3行でいうと

  • 公式は、層を分けて説明しています。Messages API（と各言語のクライアントSDK）は、モデルを呼ぶ窓口で、道具を使う繰り返しは自分で書きます。Agent SDKは、Claude Codeの道具とループをライブラリにしたものです。Managed Agentsは、その実行をAnthropicの側で動かす仕組みで、ベータ版です。
  • Agent SDKは、中で claude のプログラムを別のプロセスとして起動します。普通のAPIの呼び出しとは違い、1つの会話が1つの長く生きるプロセスと、手元のディスクの状態に結びつきます。置き場所、状態の保存、複数の利用者の分離を、先に設計する必要があります。
  • 自分の製品に組み込むときは、認証、権限、隔離、費用、名前の出し方に、公式が書いた決まりがあります。たとえば、第三者の製品でclaude.aiのログインを提供することは、事前の承認がない限り認められていません。

この記事は、実際に使って確かめた記録ではありません。運営者はClaude Codeを入れていますが、使い心地はこの記事には書いていません。この記事は、2026年10月16日に公式ドキュメントを読んでまとめたものです。コードは、公式ページの例を読んで写したもので、実行していません。ベータ版の機能や上限の数字は、変わることがあります。法律や契約の助言ではありません。

先に結論

前提：層を分けて見る

公式の「Agent SDK overview」の比較表を並べ直します。

やりたいこと 公式が挙げる道 得られるもの
Claude Codeのエージェントを、自分が運用するプロセスの中に埋め込む Agent SDK Claude Codeの道具、権限、セッション、フックを持つライブラリ
端末で対話しながら開発する、単発の作業を頼む Claude Code CLI 日常の対話向けの端末の画面
自分のコードからClaude APIを直接呼ぶ クライアントSDK APIへの直接のアクセス。道具を使う繰り返しは自分で書く（ベータの「ツールランナー」も選べる）
Anthropicの側でエージェントを動かす Managed Agents 管理されたクラウドの砂場（サンドボックス）か、自社の砂場で動く、ホスト型のエージェント

クライアントSDKは、公式の一覧では、Python、TypeScript、C#、Go、Java、PHP、Rubyの7言語です。公式は、これらは自分でリクエストを送り、応答を処理するもの、と説明しています。

Claude API（Messages API）とは

Claude APIは https://api.anthropic.com のREST（Webの標準的なやりとり）のAPIです。会話の中心は POST /v1/messages で、公式は、テキストや画像を含む入力メッセージのリストを送ると、モデルが会話の次のメッセージを作って返す窓口、と説明しています。

公式のAPIの概要によると、リクエストのヘッダーは次のとおりです。

呼び出しの例は次の形です（上のヘッダーの表に合わせた例で、API概要のページには、curlの例が見つかりませんでした）。モデル名は変わりやすいので <モデルID> に置き換えました。

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "<モデルID>",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello, Claude"}
    ]
  }'

応答は Message というオブジェクトで、content（TextBlock や ToolUseBlock などの並び）と、usage（トークンの使用量）などが入ります。止まった理由は stop_reason に入り、公式のページには、end_turn、max_tokens、stop_sequence、tool_use、pause_turn、refusal、model_context_window_exceeded が挙がっています。各値の意味の説明は、読んだページにはありませんでした。ここは僕らの読みですが、tool_use は「モデルが道具の呼び出しを求めて止まった」という名前で、その実行と結果の返却を、Messages APIでは自分のコードが担当します。

SDKは、認証のヘッダーや anthropic-version を自動で付けます。

Agent SDKは何をしているのか

ループを持ってくる

公式のagent loopのページによると、SDKは、Claude Codeと同じ実行のループを動かします。プロンプトを受け取り、Claudeが応答し、道具の呼び出しがあれば実行して結果を戻し、道具の呼び出しがなくなるまで繰り返し、最後に結果のメッセージを返します。1周が「ターン」です。

呼び出しは query() です。公式のクイックスタートの最小の例（Python）は次の形です。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],  # Auto-approve these tools
            permission_mode="acceptEdits",  # Auto-approve file edits
        ),
    ):
        print(message)


asyncio.run(main())

上は、公式の例の表示部分を print に置き換えた短縮版で、実行はしていません。

ループを制御する主な設定は、max_turns（TypeScriptでは maxTurns）、max_budget_usd、permission_mode、allowed_tools、disallowed_tools、effort です。終わり方は、結果の subtype（success、error_max_turns、error_max_budget_usd など）で分かります。

中で別のプロセスが動く

公式のホスティングのページが強調するのは、ここです。query() を呼ぶと、SDKは別の claude のプロセスを起動し、標準入出力でやり取りします。そのプロセスが、シェル、作業フォルダ、セッションの記録を持ちます。1つのエージェントのセッションは1つのプロセスです。同時に10のセッションを動かすなら、10のプロセスが動きます。

状態は、既定では、コンテナのディスクに置かれます。公式は3つを挙げています。セッションの記録（~/.claude/projects/、または CLAUDE_CONFIG_DIR の下）、CLAUDE.mdのメモリ、作業フォルダの成果物です。コンテナの再起動や別のマシンへの移動で、これらは残りません。セッションの記録を別の場所に残すには、SessionStore というアダプターを設定します。ただし、これが写すのはセッションの記録だけで、CLAUDE.mdや作業フォルダのファイルは、別の方法で保存する必要がある、と書かれています。

ホスティングの数字と型（公式のhostingページ、10月16日時点）
  • 4つのセッションの型：1つの作業ごとにコンテナを作って捨てる「ephemeral」。長く動かし続ける「long-running」。使うときだけ起こして SessionStore から復元する「hybrid」。1つのコンテナに複数のエージェントを入れる「multi-agent」。hybridでは、SessionStore がないと、停止とともに記録が消えます。
  • 目安の資源：エージェント1つあたり、メモリ1GiB、ディスク5GiB、CPU 1つが、起動直後の出発点です。上限ではなく、会話が長いほどメモリは増える、と書かれています。
  • 観測：OpenTelemetryの環境変数（CLAUDE_CODE_ENABLE_TELEMETRY=1 など）で、トレースなどを出せます。プロンプトの本文は、既定では含まれません。
  • 上限の弱点：セッション全体のタイムアウトはありません。maxTurns で抑えます。サブエージェントごとの総実行時間の期限もありません（出力が止まったことを見張る CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS はありますが、総実行時間の期限ではない、と書かれています）。
  • 複数の利用者を同じコンテナで扱うとき：settingSources: []（Pythonは setting_sources=[]）、CLAUDE_CODE_DISABLE_AUTO_MEMORY=1、利用者ごとの CLAUDE_CONFIG_DIR、利用者ごとの作業フォルダ cwd を、公式は組み合わせて示しています。

Claude Codeを組み込むときに先に決める5つ

1. 認証：誰の鍵で、誰の請求か

SDKのクイックスタートは、APIキー（ANTHROPIC_API_KEY）を、SDKを動かすプロセスの環境変数に置く、と案内しています。Amazon Bedrock、Google CloudのAgent Platform、Microsoft Foundryの環境変数でも動きます。

そのうえで、公式のoverviewとクイックスタートには、同じ注意書きがあります。第三者の開発者が、自分の製品でclaude.aiのログインや使用枠を提供することについて、公式は「does not allow third party developers to offer claude.ai login」と書いています（overviewの原文の一部）。事前に承認を受けた場合は別で、それ以外はAPIキーの方法を使うよう案内されています。

2. 権限：承認する人がいない場所での既定

権限のモードは、default、acceptEdits、plan、dontAsk、auto、bypassPermissions などです。公式は、bypassPermissions を、CIやコンテナのような、隔離された環境でだけ使うよう書いています。TypeScriptでは allowDangerouslySkipPermissions: true も必要で、Unixでroot権限のときは使えません。

3. 隔離：エージェントが何に触れてよいか

公式のsecure deploymentのページは、エージェントが、処理する内容（ファイル、Webページ、利用者の入力）に含まれる指示や、モデルの誤りで、意図しない動きをするかもしれない、という前提で書かれています（プロンプトインジェクション）。対策として、最小権限、多層の防御、そして鍵をエージェントの外に置く「プロキシ方式」を挙げています。プロキシ方式は、エージェントの外に中継を置き、そこが鍵を付けて送るので、エージェント自身は鍵を見ない、という形です。ANTHROPIC_BASE_URL でClaudeへのリクエストを中継に向けられます。隔離の技術として、サンドボックスのランタイム、コンテナ、gVisor、仮想マシンが、強さと手間の比較つきで並んでいます。

4. 費用：推計は請求ではない

費用の追跡のページは、total_cost_usd などの欄は、手元の価格表から計算した推計で、請求の根拠ではないと明記しています。価格の改定やSDKが知らないモデルなどで、ずれることがあります。正確な請求はUsage and Cost APIかConsoleの利用ページで見る、エンドユーザーへの請求には使わない、とあります。サブエージェントの使用量は total_cost_usd と modelUsage には含まれますが、usage には含まれません。ホスティングのページは、トークンの費用はコンテナの費用より、普通は桁違いに大きいと書いています。

5. 製品の名前とライセンス

overviewのブランドのガイドラインでは、「Claude Agent」や「{自分のエージェント名} Powered by Claude」などが許されます。「Claude Code」や「Claude Code Agent」という名前、Claude Codeを思わせる絵や飾りは許されません。自分の製品が、Anthropicの製品に見えないようにする、とあります。ライセンスは、Anthropicの商用利用規約（Commercial Terms of Service）に従う、と書かれています。顧客向けのサービスでも同じです。

Managed Agentsという3つ目の道

公式のManaged Agentsのページは、あらかじめ作られた、設定できるエージェントの実行環境を、管理されたインフラで動かすもの、と説明しています。長く続く作業や非同期の作業向けで、プロンプトのキャッシュと会話の圧縮（compaction）を内蔵します。状態は「ベータ」で、動作が変わることがあります。

主な概念は、Agent、Environment（動く場所）、Session、Events（アプリとエージェントのメッセージ）です。使うにはClaude APIキーと、ベータ用のヘッダー managed-agents-2026-04-01 が要ります（SDKは自動で付けます）。

注意点として、公式は、Managed Agentsは状態を保持する（セッション、会話の履歴、砂場の状態、出力がサーバー側に保存される）仕組みで、現時点ではゼロデータ保持やHIPAAのBAAの対象外、と書いています。

見立て（ここからは僕らの見立てです）

気をつけること

出典