Agent SDK の基本

Agent SDK は、Claude Code と同じツール・エージェントループ・コンテキスト管理を Python と TypeScript のライブラリとして使えるようにしたものです。自分のアプリの中でエージェントを動かすときの入口になるページです。

• 組み込みツール・フック・サブエージェント・MCP・権限・セッションなど、Claude Code の機能をコードから使えます
• query() が返すメッセージのストリームを読んで、進捗や最終結果を取り出します
• settingSources で、CLAUDE.md・スキル・フックなどのファイルベースの設定を読み込むかを決めます
• ターン数と費用の上限、モデル、環境変数、作業ディレクトリは options で指定します
• セッションは SDK のセッションと入出力、ツールと権限は SDK のツール・権限・拡張、運用は SDK の本番運用、型の一覧は SDK の API リファレンス を見てください

ほかの Claude の道具との違い#

Python と TypeScript 以外の言語から同じループを使うには、CLI を -p と --output-format json 付きでサブプロセスとして起動します（ヘッドレス実行）。

Claude Code から使える機能#

導入する#

必要なのは Node.js 18 以上、または Python 3.10 以上と、Anthropic のアカウントです。

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

# Python（uv）
uv add claude-agent-sdk

# Python（pip。仮想環境を有効にしてから）
pip install claude-agent-sdk

どちらの SDK も Claude Code のネイティブバイナリを同梱するので、通常は Claude Code を別に入れる必要はありません。例外は次のとおりです。

• pip がプラットフォーム別の wheel でなくソース配布物を入れた場合（例：ARM64 の Windows）は、バイナリが同梱されません。Claude Code を別途インストールします（インストールとログイン）。Python SDK は PATH から見つけます
• TypeScript SDK はバイナリを npm の optional dependencies で入れます。npm ci --omit=optional のように省くとバイナリが入りません。省かずに入れ直すか、ネイティブ版を入れて pathToClaudeCodeExecutable にパスを指定します

API キーは、エージェントを動かすシェルの環境変数 ANTHROPIC_API_KEY に入れます。SDK は .env を自動では読まないので、必要なら dotenv などで先に読み込みます。

export ANTHROPIC_API_KEY=your-api-key

サードパーティのプロバイダー経由でも認証できます（詳しくは Bedrock・Vertex AI・Foundry）。

Not logged in や Invalid API key が出たら、エージェントを動かすシェルで ANTHROPIC_API_KEY が設定されているかを確かめます（エラー一覧）。

最初のエージェント#

query() はエージェントループを起動する入口です。非同期イテレーターを返すので、Claude が作業するあいだのメッセージを順に受け取れます。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def main():
    async for message in query(
        prompt="utils.py をレビューし、クラッシュするバグを直して",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],  # 自動承認するツール
            permission_mode="acceptEdits",           # ファイル編集を自動承認
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")

asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "utils.py をレビューし、クラッシュするバグを直して",
  options: {
    allowedTools: ["Read", "Edit", "Glob"], // 自動承認するツール
    permissionMode: "acceptEdits",          // ファイル編集を自動承認
  },
})) {
  if (message.type === "assistant" && message.message?.content) {
    for (const block of message.message.content) {
      if ("text" in block) console.log(block.text);
      else if ("name" in block) console.log(`Tool: ${block.name}`);
    }
  } else if (message.type === "result") {
    console.log(`Done: ${message.subtype}`);
  }
}

実行は TypeScript なら npx tsx agent.ts、Python なら uv run agent.py か python agent.py です。既存の CommonJS プロジェクトでは、トップレベルの await を使うためファイル名を agent.mts にします。

• 絞り込まずに全メッセージを見ると、初期化メッセージや内部状態も含まれます（デバッグ向け）
• ライブ表示が要らない用途（バックグラウンドジョブや CI）は、メッセージをまとめて受け取れます（SDK のセッションと入出力）

ツールの組み合わせの目安です。

エージェントループの仕組み#

プロンプトを受けた Claude が、ツールを呼び、結果を受け取り、ツール呼び出しのない応答を出すまで繰り返します。この1周が1ターンです。ターンの間は呼び出し側にメッセージが流れるだけで、制御は戻りません。

1. SDK がプロンプトを送り、セッション情報の SystemMessage を返す
2. Claude がツールを呼ぶ応答を出す（AssistantMessage）
3. SDK がツールを実行し、結果を UserMessage として返す
4. 2〜3 を繰り返し、ツール呼び出しのない応答が出たらループが終わる
5. 最後の AssistantMessage に続けて、最終結果の ResultMessage が来る

メッセージの種類#

• init 以外の SystemMessage は、TypeScript では SDKMessage の中で別々の型になります
• SessionStart や Setup のフックが走ると、そのライフサイクルメッセージが init より前に届きます
• ResultMessage のあとに prompt_suggestion などのシステムイベントが少し届くことがあるので、結果で break せず最後まで読みます
• 判定は、Python は isinstance()、TypeScript は type 文字列です。TypeScript の AssistantMessage と UserMessage は API のメッセージを .message に持つので、内容は message.message.content にあります
• 進捗は AssistantMessage、最終結果だけなら ResultMessage、リアルタイム表示は include_partial_messages / includePartialMessages を有効にして StreamEvent を使います

ツールの実行と権限#

組み込みツールは Claude Code と同じです。

タスク管理のツールが標準で付かないモデルでは、TaskCreate と TaskUpdate は有効にしたときだけ使えます。

許可は3つのオプションで決まります。

"Bash(npm *)" のようなルールで、特定のコマンドだけを許可することもできます。拒否されたツールは、拒否のメッセージがツール結果として Claude に返り、Claude は別の手を試すか、できないと報告します。

読み取り専用のツール（Read・Glob・Grep・読み取り専用と印を付けた MCP ツール）は並列に動き、状態を変えるもの（Edit・Write・Bash）は順番に動きます。自作ツールは既定で順番です。並列にするにはアノテーションの readOnlyHint を設定します。

権限モード#

ターンと費用の上限#

• 上限に達すると、ResultMessage の subtype が error_max_turns か error_max_budget_usd になります
• 費用の上限はサブエージェントの分も数えます。上限に達すると新しいサブエージェントは Budget limit reached で失敗し、動いているバックグラウンドのサブエージェントも止まります（この動作は Claude Code v2.1.217 以降）
• ストリーミング入力では、ターンが上限で終わっても待機中のメッセージは新しいターンで処理され、ターン数は数え直されます。費用の合計はメッセージをまたいで積算され、/clear で数え直されます
• max_turns の 0 は上限なしと同じです。max_budget_usd の 0 は CLI が起動時に不正な値として拒否します

effort#

effort は推論の深さの指定です。対応していないモデルもあります。未指定なら Claude Code が決めます（モデル・effort・fast mode）。

effort は拡張思考（extended thinking）とは別の機能で、片方だけを使うことも両方を使うこともできます。サブエージェントごとに上書きするには AgentDefinition の effort を使います。

コンテキストと圧縮#

コンテキストはターンをまたいで積み上がります。システムプロンプト・ツール定義・会話履歴・ツールの入出力が含まれ、変わらない部分はプロンプトキャッシュされます（コンテキストとプロンプトキャッシュ）。

• 上限に近づくと自動で圧縮され、古い履歴が要約されます。system で subtype が compact_boundary のメッセージが流れます
• 圧縮で初期のプロンプトの指示は失われうるので、守らせたい規則は CLAUDE.md に書きます
• 圧縮の動きは、CLAUDE.md に要約時に残すものを書く、PreCompact フック（trigger は manual か auto）でトランスクリプトを保存する、/compact をプロンプトとして送って手動で起こす、の3通りで調整できます

# Summary instructions
When summarizing this conversation, always preserve:
- The current task objective and acceptance criteria
- File paths that have been read or modified
- Test results and error messages

長く動かすときの工夫です。

• サブエージェントに小作業を任せる。親のコンテキストは要約の分しか増えない
• ツールを絞る。サブエージェントの tools で最小限にする
• MCP サーバーの費用に注意する。ツール検索が無効、または先読みに戻った場合は、全ツールのスキーマが毎リクエストに入る
• 単純な作業は effort を "low" にする

結果の扱い#

• result は success のときだけあるので、先に subtype を見ます
• どの subtype も total_cost_usd・usage・num_turns・session_id を持ちます。Python では total_cost_usd・usage・model_usage が省略可能な型なので None を確かめます
• セッションがクラッシュすると、費用が 0 のままの error_during_execution が最後に出てプロセスが終わります。stop_reason は null です
• usage はメインのループだけです。サブエージェントを含む全体の集計は modelUsage（Python は model_usage）を使います（SDK の本番運用）
• stop_reason は end_turn・max_tokens・refusal などです。拒否の検出は stop_reason が "refusal" かどうかで見ます

ループに使えるフック#

フックは自分のアプリのプロセスで動くので、コンテキストを消費しません。PreToolUse で拒否するとツールは実行されず、Claude に拒否のメッセージが返ります。Python に無いイベントが TypeScript にはあります（SDK のツール・権限・拡張）。

まとめの例#

import { query } from "@anthropic-ai/claude-agent-sdk";

let sessionId: string | undefined;
try {
  for await (const message of query({
    prompt: "auth モジュールのテスト失敗の原因を見つけて直して",
    options: {
      allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep"],
      settingSources: ["project"], // CLAUDE.md・スキル・フックを読み込む
      maxTurns: 30,                // 暴走の防止
      effort: "high",
    },
  })) {
    if (message.type === "system" && message.subtype === "init") {
      sessionId = message.session_id; // 再開用に保存
    }
    if (message.type === "result") {
      if (message.subtype === "success") console.log(message.result);
      else console.log(`Stopped: ${message.subtype}`);
      console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`);
    }
  }
} catch (error) {
  console.log(`Session ended with an error: ${error}`);
}

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def run_agent():
    try:
        async for message in query(
            prompt="auth モジュールのテスト失敗の原因を見つけて直して",
            options=ClaudeAgentOptions(
                allowed_tools=["Read", "Edit", "Bash", "Glob", "Grep"],
                setting_sources=["project"],
                max_turns=30,
                effort="high",
            ),
        ):
            if isinstance(message, ResultMessage):
                if message.subtype == "success":
                    print(message.result)
                else:
                    print(f"Stopped: {message.subtype}")
                if message.total_cost_usd is not None:
                    print(f"Cost: ${message.total_cost_usd:.4f}")
    except Exception as error:
        print(f"Session ended with an error: {error}")

asyncio.run(run_agent())

オプションを組み立てる#

query() は options を受け取ります（TypeScript は Options、Python は ClaudeAgentOptions）。どのフィールドも省略可能で、省略した分は SDK の既定で動きます。全フィールドは SDK の API リファレンス にあります。

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "このリポジトリの未完了の TODO を要約して",
  options: {
    model: "claude-sonnet-5",
    allowedTools: ["Read", "Glob", "Grep"],
    maxTurns: 8,
    cwd: "/path/to/repo",
  },
})) {
  if (message.type === "result" && message.subtype === "success" && !message.is_error) {
    console.log(message.result);
  }
}

import asyncio
from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query

async def main():
    options = ClaudeAgentOptions(
        model="claude-sonnet-5",
        allowed_tools=["Read", "Glob", "Grep"],
        max_turns=8,
        cwd="/path/to/repo",
    )
    async for message in query(prompt="このリポジトリの未完了の TODO を要約して", options=options):
        if isinstance(message, ResultMessage) and not message.is_error:
            print(message.result)

asyncio.run(main())

設定ファイルの読み込み#

モデル#

• model を指定しないと、設定や環境変数で決まるモデル、なければ Claude Code の既定のモデルで始まります（モデル・effort・fast mode）。値はエイリアスでも完全なモデル名でも構いません
• fallbackModel / fallback_model に予備のモデルを指定すると、本命が過負荷や利用不可のときに切り替わります。各ユーザーターンの頭で本命を再試行します。カンマ区切りで複数指定でき、TypeScript では model と同じ値を指定すると起動時にエラーになります
• temperature・top_p・max_tokens に相当するフィールドはありません。代わりに effort や費用の上限を使います

環境変数#

env は、セッションを動かす Claude Code プロセスの環境変数です。

env を指定しなければ、どちらも自分の環境を引き継ぎます。

const options = {
  env: { ...process.env, ANTHROPIC_BASE_URL: "https://gateway.example.com" },
};

options = ClaudeAgentOptions(
    env={"ANTHROPIC_BASE_URL": "https://gateway.example.com"},
)

Claude Code が読む変数は 環境変数一覧 にあります。

作業ディレクトリ#

• cwd を指定すると、そのディレクトリでセッションが動きます。未指定ならプロセスの作業ディレクトリです
• cwd を変える API はありません。別のディレクトリで動かすには、別のセッションを始めます
• Claude Code は cwd から、読み込むプロジェクトの設定とフック、スキルの探索先、セッションの保存先を決めます
• 作業ディレクトリの外のファイルに触らせるには additionalDirectories（Python は add_dirs）を使います。許可されるのはファイルへのアクセスで、設定の読み込みではありません

セッション中の設定変更#

ストリーミング入力で始めたセッションは、動いている間にモデルと権限モードを切り替えられます。TypeScript は query() が返すオブジェクトのメソッド、Python は ClaudeSDKClient のメソッドです。

機能ごとのオプション#

関連は SDK のセッションと入出力（resume・forkSession・sessionStore・outputFormat・enableFileCheckpointing）と SDK のツール・権限・拡張（そのほか）です。

Claude Code の機能を読み込む#

settingSources を省略すると、query() は Claude Code の CLI と同じファイルベースの設定を読みます。user・project・local の設定、CLAUDE.md、.claude/ のスキル・エージェント・コマンドです。何も読ませたくないときは settingSources: [] を渡し、プログラムで指定したものだけで動かします。

for await (const message of query({
  prompt: "auth モジュールをリファクタリングして",
  options: {
    settingSources: ["user", "project"], // ~/.claude/ と <cwd>/.claude/
    allowedTools: ["Read", "Edit", "Bash"],
  },
})) { /* ... */ }

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],
    allowed_tools=["Read", "Edit", "Bash"],
)

省略は ["user", "project", "local"] と同じです。プロジェクトの settings.json とフックは <cwd>/.claude/ だけから読み、親ディレクトリへはさかのぼりません。

settingSources が制御しないもの#

CLAUDE.md の読み込み場所#

全レベルが加算で効き、優先順位の決まりはありません。矛盾すると Claude の解釈次第なので、矛盾しない書き方にするか、特定のファイルに優先を明記します。CLAUDE.md を使わずに systemPrompt で文脈を渡すこともできます。対話の Claude Code と SDK で同じ文脈を共有したいときに CLAUDE.md が向きます（CLAUDE.md とメモリ）。

スキルとフック#

• スキルは settingSources 経由でファイルシステムから見つかります。skills を省略すると、見つかったユーザーとプロジェクトのスキルが有効で、Skill ツールが使えます。"all"・スキル名のリスト・[]（全部無効）を渡せます。skills を指定すると Skill ツールが allowedTools に自動で加わります。tools を明示するなら "Skill" を含めます
• スキルは .claude/skills/<name>/SKILL.md のファイルとして作ります。プログラムから登録する API はありません（スキル）
• フックには、settings.json に書くファイルシステムのフックと、query() に渡すコールバック（プログラム）の2種類があり、並んで動きます

コールバックは {} を返すと許可です。拒否するには hookSpecificOutput に permissionDecision: "deny" と permissionDecisionReason を入れます。理由は Claude にツール結果として返ります。SessionStart・SessionEnd・TeammateIdle・TaskCompleted などは TypeScript だけのイベントです。

async def audit_bash(input_data, tool_use_id, context):
    command = input_data.get("tool_input", {}).get("command", "")
    if "rm -rf" in command:
        return {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "permissionDecisionReason": "Destructive command blocked",
            }
        }
    return {}

目的から機能を選ぶ#

有効にした機能は、どれもコンテキストを使います。

旧 Claude Code SDK からの移行#

Claude Code SDK は Claude Agent SDK に改名されました。

手順は、旧パッケージをアンインストールし（npm uninstall @anthropic-ai/claude-code、pip uninstall -y claude-code-sdk）、新しいものを入れ、インポートを書き換えます。package.json・requirements.txt・pyproject.toml に旧名が残っていれば置き換えます（package.json はバージョン範囲も更新します）。

// 旧: import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

# 旧: from claude_code_sdk import query, ClaudeCodeOptions
from claude_agent_sdk import query, ClaudeAgentOptions

v0.1.0 からの破壊的変更です。

• Python の ClaudeCodeOptions は ClaudeAgentOptions に改名されました
• SDK は、既定では Claude Code のシステムプロンプトを使いません（最小のシステムプロンプトで動きます）。以前の動きにするには systemPrompt: { type: "preset", preset: "claude_code" }（Python は system_prompt={"type": "preset", "preset": "claude_code"}）を指定します。自作の文字列を渡すこともできます（システムプロンプトの変更）
• settingSources の既定は、v0.1.0 で一時的にファイルシステム設定を読まない形に変わったあと元に戻っているので、移行の作業は要りません。現在は省略すると user・project・local を読みます。分離するなら [] を渡します。CI/CD・デプロイしたアプリ・テスト環境・マルチテナントでは分離が特に重要です

エラーの対処#

機能ごとの症状は各機能のページにあります。ここでは CLI の起動と終了、構造化出力のエラーを扱います。次の表は、症状の行き先です。

CLI の起動#

起動できない場合の共通の対処です。

• パスが claude の実行ファイルそのものを指し、実行権限があるか確かめる
• 独自のパスが要らなければ cli_path（Python）か pathToClaudeCodeExecutable（TypeScript）を外し、同梱のものを使わせる
• 同梱のバイナリがコンテナで失敗するなら、イメージのビルド時に SDK を入れ直すか、実行するアーキテクチャ用にイメージを作り直す（アーキテクチャや libc の不一致、実行権限の欠落が多い）

CLI の終了#

ResultError は ProcessError のサブクラスなので、別々に扱うなら except ResultError を先に書きます。claude-agent-sdk 0.2.140 より前は、エラー結果での終了を普通の Exception として送出していました。

構造化出力が空#

subtype が success でも、structured_output が Python で None、TypeScript で undefined になることがあります。実行は終わっても、検証済みの出力が無い状態です（例：満たせないスキーマ）。アプリ側では失敗として扱い、subtype が success であることと structured_output があることの両方を確かめてから使います。スキーマが正しいはずなのに繰り返すなら、充足可能かを確かめ、単純にして通してから、制約を1つずつ戻します（SDK のセッションと入出力）。

例とデモ#

• クイックスタートで、バグを見つけて直すエージェントを作れます
• claude-agent-sdk-demos のリポジトリに、最小の Hello World から、メールクライアントやマルチエージェントの調査システムまで、手元で動かせるデモがあります
• Claude Cookbook の Agent SDK シリーズは、1行の調査エージェントから多段のマルチエージェントへ進む Python ノートブックの連続した教材です。OpenAI Agents SDK からの移行レシピもあります