SDK の API リファレンス

Agent SDK の TypeScript 版（@anthropic-ai/claude-agent-sdk）と Python 版（claude-agent-sdk）の API を、辞書として引けるようにまとめたページです。関数・主要な型・オプションの全フィールド・メッセージの型・フックの型・ツールの入力・サンドボックスの設定を表にしています。使い方は Agent SDK の基本、セッションと入出力は SDK のセッションと入出力、ツール・権限・フックは SDK のツール・権限・拡張 にあります。

• 入口は query()。TypeScript は Query オブジェクト、Python は非同期イテレーターを返す
• 設定は TypeScript が Options、Python が ClaudeAgentOptions（名前は camelCase と snake_case で対応する）
• 結果メッセージの subtype と total_cost_usd が、成否と費用の見積もりを持つ
• TypeScript の SDK バージョンは同梱の Claude Code のバージョンに合わせて進み（v0.3.191 が Claude Code v2.1.191 を同梱）、機能ごとの要件は表の説明にある

インストール#

• TypeScript は、パッケージマネージャーが optional dependencies を飛ばすと Native CLI binary for <platform>-<arch> not found を投げます。libc のフィールドを適用しない Yarn 1.x では、Linux で glibc と musl の両方のパッケージが入ります（v0.2.141 以降の SDK は正しいほうを起動します）
• TypeScript のルートのエントリは zod と @modelcontextprotocol/sdk の自前のコピーを持ちます。/core のエントリはそれらを自分の node_modules から読みます。1つのプロセスでは、ルートか /core のどちらか一方だけから読み込みます（両方だと SDK のクラスと状態が2つできる）
• 単一の実行ファイルへのコンパイルは、bun build --compile の場合に起動の失敗の原因が違います（Agent SDK の基本 の「CLI の起動」）

関数#

TypeScript#

startup() と prewarm() の詳しいところです。

• startup()：アプリの起動時などに早めに呼び、プロンプトが決まったら返り値の .query() を呼ぶと、サブプロセスの起動と初期化を待たずに済みます。作業ディレクトリがまだ分からないなら prewarm() を使います
• prewarm()：予備のプロセスは、options.cwd があればそこで、なければ Claude Code の設定ディレクトリの下の私用の一時ディレクトリで待ちます。予備1つがおよそ 230〜260 MB のメモリを使います。options に resume・continue・forkSession があると投げます。claim で設定できないもの（mcpServers・hooks・canUseTool・settingSources・systemPrompt・plugins など）は予備の寿命の間固定なので、組み合わせごとに予備を1つ持ちます

tool() の引数です。

createSdkMcpServer() のオプションです。

セッション関数のオプションと戻り値です。

SDKSessionInfo のプロパティです。

SessionMessage のプロパティです。

resolveSettings() のオプションと戻り値です。

戻り値の ResolvedSettings は、effective（統合後の設定）・provenance（各キーを与えたソース）・sources（ソースごとの生の設定。優先度の低い順）を持ちます。MDM のソースは読みますが、policyHelper は実行せず、サーバー管理の設定は取得しません。

Python#

tool() の入力スキーマは、簡単な型の対応（{"text": str, "count": int, "enabled": bool}、推奨）か、複雑な検証のための JSON Schema 形式（type・properties・required・minimum など）です。

Python の SDKSessionInfo のプロパティです。

Python の SessionMessage は、type（"user" か "assistant"）・uuid・session_id・message（生の内容）・parent_tool_use_id・parent_agent_id（Python Agent SDK 0.2.140 以降）を持ちます。

query() と ClaudeSDKClient の違い（Python）#

チャット画面のような対話的なアプリや、次の動作が Claude の応答に依存するときは ClaudeSDKClient を使います。

ClaudeSDKClient のメソッド#

TypeScript の Options#

query() に渡す設定です（既定の列の「CLI の既定」は、CLI が決める値）。

systemPrompt の形です。

詳しい使い方は SDK のツール・権限・拡張 の「システムプロンプト」にあります。

遅い API 応答・止まった API 応答を扱う#

CLI のサブプロセスは、API のタイムアウトと停滞の検出を制御するいくつかの環境変数を読みます。TypeScript は env に、Python は ClaudeAgentOptions.env に渡します。

ANTHROPIC_BASE_URL の向こうのゲートウェイが keep-alive の ping で応答を開けたままにしているあいだ、includePartialMessages（Python は include_partial_messages）を設定したホストは ping のストリームイベントを受け取り続けます。これは沈黙でタイムアウトとするのでなく、生存の合図として読みます（v2.1.257 より前は、最後の本物のストリームイベントの5分後に止まった）。

Python の ClaudeAgentOptions#

データクラスです。stderr や env は、TypeScript の Options と動きが違う点があります（env は継承した環境の上に重なる）。

Python のシステムプロンプトの型です。

設定ソースと型#

settingSources を省くと、user・project・local を読みます。組み合わせたときの優先順位（高い順）は、local・project・user です。agents・allowedTools・settings などのプログラムのオプションは、user・project・local のファイルの設定を上書きし、管理ポリシーの設定はプログラムのオプションより優先されます。

AgentDefinition#

Python の AgentDefinition はデータクラスで、omitClaudeMd を持ちません。フィールド名は通信の形に合わせて camelCase のままで、ClaudeAgentOptions の snake_case と違います。

CanUseTool と権限の結果#

TypeScript の CanUseTool は (toolName, input, options) => Promise<PermissionResult | null> です。

• コールバックは通常 PermissionResult を返します。null を返してよいのは、アプリが自前の経路で control_response を送り済みで、requestId を返してあるときだけです。ほかの場合に null を返すと、ツール呼び出しは無期限にブロックされたままになります（requestId と null の返しは Claude Code v2.1.199 以降）
• PermissionResult は { behavior: "allow"; updatedInput?; updatedPermissions?; toolUseID? } か { behavior: "deny"; message; interrupt?; toolUseID? } です

Python の CanUseTool は (tool_name, input_data, context) -> PermissionResult で、context は ToolPermissionContext です。

Python の戻り値は PermissionResultAllow(behavior="allow", updated_input, updated_permissions) と PermissionResultDeny(behavior="deny", message="", interrupt=False) です。

PermissionUpdate#

type は "addRules"・"replaceRules"・"removeRules"・"setMode"・"addDirectories"・"removeDirectories" のどれかです。

ThinkingConfig#

display（"summarized" か "omitted"）は、思考のテキストを返すかを決めます。Claude Opus 4.7 以降の API の既定は "omitted" なので、思考の内容を受け取るには "summarized" を指定します。Python の ThinkingConfig は TypedDict で、実行時は普通の辞書です（config["budget_tokens"] のように読む）。

MCP サーバーの設定#

プラグインの設定#

ToolConfig（TypeScript）#

askUserQuestion.previewFormat（'markdown' か 'html'）が、AskUserQuestion の選択肢の preview フィールドを有効にし、内容の形式を決めます。未設定なら、Claude はプレビューを出しません。

SandboxSettings#

SandboxNetworkConfig（サンドボックスされた Bash のコマンドに効き、WebFetch ツールは制限しません。WebFetch は権限ルールで制御します）です。

SandboxFilesystemConfig（TypeScript）は allowWrite・denyWrite・denyRead（どれもファイルパスのパターンの string[]、既定 []）です。

サンドボックスの外での実行（allowUnsandboxedCommands）は、モデルが入力に dangerouslyDisableSandbox: true を設定して求め、その要求は既存の権限の仕組みに戻るので、canUseTool のハンドラーが呼ばれて、独自の認可の判断を実装できます。excludedCommands の項目は、モデルを介さずに、呼び出しをサンドボックスの外に出します。

Query オブジェクトのメソッド（TypeScript）#

query() が返す Query は、AsyncGenerator<SDKMessage, void> を拡張します。

applyFlagSettings() の効き方です。

• effortLevel は労力のレベル名を受け、"ultracode"（xhigh の労力で ultracode をオン）も受けます。TypeScript では { ultracode: true, effortLevel: "xhigh" } を渡します。ultracode のキーだけなら、いまの労力のレベルのまま ultracode をオンにします
• 値は、query() の settings オプションが起動時に設定したものの上に統合される、フラグ設定の層に書かれます。続けて呼ぶと、最上位のキーが浅く統合されます（permissions を2回目に渡すと、前の permissions のオブジェクト全体が置き換わる）
• キーを消すには null を渡します。多くのキーは、起動時の settings、続いて優先度の低いソースの値に戻ります。model を消すと、設定ファイルが model を設定していても、Claude Code の既定のモデルに戻ります。effortLevel: null はモデルの既定の労力、agent: null は次のターンからエージェントなし、ultracode: null は ultracode をオフにします。undefined は JSON のシリアライズで落ちるので効果がありません
• Python に同等のメソッドはありません

updateSettings() の効き方です。

どちらも文字列の値で、ほかのキーを持つ要求・リモートの通信路で動くセッション・名指ししたソースを settingSources が除いているセッションでは拒否されます。キーの削除はできません。

WarmQuery は query(prompt)（1回だけ呼べる）と close() を持ち、AsyncDisposable なので await using が使えます。SpareProcess は claim({ prompt, options })・claimed・exited・close() を持ちます。claim では options.cwd が必須で、additionalDirectories・model・permissionMode・maxThinkingTokens・settings・appendSystemPrompt・title・agents・env のセッション用のトークンも指定できます。claimed が option_not_applied で始まるメッセージで拒否されたときは、model か maxThinkingTokens が効かないまま動いています。それ以外の拒否では、プロンプトは動いていないので、query() でセッションを始めます。

メッセージの型#

TypeScript の SDKMessage#

query() が返すメッセージのユニオンです。主な型です。

ほかに、ユニオンには SDKSessionStateChangedMessage・SDKNotificationMessage・SDKMemoryRecallMessage・SDKElicitationCompleteMessage・SDKAPIRetryMessage・SDKMirrorErrorMessage が含まれます。

SDKAssistantMessageError は、'authentication_failed'・'oauth_org_not_allowed'・'account_on_hold'・'billing_error'・'rate_limit'・'overloaded'・'invalid_request'・'model_not_found'・'server_error'・'max_output_tokens'・'cloud_credential_error'・'unknown' のどれかです。

• 'model_not_found'：選んだモデルが存在しないか、アカウントやデプロイで使えない
• 'overloaded'：サーバーが満杯で API が 529 を返した（'rate_limit' は、自分の割り当てに対する 429）
• 'account_on_hold'：アカウントが保留中
• 'cloud_credential_error'：Claude Code が、動いているマシンで使える AWS か Google Cloud の認証情報を得られず、クラウドのプロバイダーへリクエストが届かなかった。多くは、クラウドのサインインがそのマシンで期限切れか未完了（認証情報のサービスが一時的に届かないときも同じ値）

aborted は、中断か中止でアシスタントメッセージがストリームの完了前に切れたとき true です（stop_reason がなく、内容が単語の途中で終わることがある。Agent SDK v0.3.214 以降）。timestamp は、メッセージの内容の生成が終わった時刻（ISO 8601）で、そのマシンの時計に由来するので表示専用に使い、順序には使いません。

SDKUserMessage のフィールドです。

SDKResultMessage のフィールド#

成功（subtype: "success"）と、エラー（"error_max_turns"・"error_during_execution"・"error_max_budget_usd"・"error_max_structured_output_retries"）の2つの形があります。

startup_failure_reason の値は次の17個です。CLAUDE_CODE_STARTUP_FAILURE_RESULTS=1 を env に入れると、すべての値でこの結果を受け取れます。入れないと、結果が書かれるのは worktree_unverified・worktree_resume_refused（worktree へ戻せない再開）と、バックグラウンドのセッションが持つ会話を continue しようとして拒まれた session_held_by_background だけで、ほかは標準エラーと 0 以外の終了で終わります。

fast_mode_disabled_reason のコードです。

SDKSystemMessage（init）のフィールド#

Python のメッセージ#

Message は UserMessage・AssistantMessage・SystemMessage・ResultMessage・StreamEvent・RateLimitEvent・ConversationResetMessage のユニオンです。

• AssistantMessageError は、"authentication_failed"・"billing_error"・"rate_limit"・"invalid_request"・"server_error"・"unknown" です。CLI は max_output_tokens などの、このリストにない値も出し、SDK は値をそのまま渡すので、リスト外の文字列は unknown と同じに扱います
• ResultMessage は全バリアントを1つの形にならしたデータクラスで、subtype に当たらないフィールドは None です。is_error は、error_* では常に True、subtype="success" では、最後のモデルのリクエストが失敗したとき True です。result は success のテキスト。success かつ is_error=True のときは、API のエラー文字列が入る（空のこともある）。errors は error_* のときだけ。terminal_reason の "aborted_streaming" と "aborted_tools" は、ターンが完了前に中断されたことを示します（interrupt() や権限のコールバックが原因になる）
• RateLimitInfo は、status（"allowed"・"allowed_warning"・"rejected"）・resets_at・rate_limit_type（"five_hour"・"seven_day"・"seven_day_opus"・"seven_day_sonnet"・"overage"）・utilization（0.0〜1.0）・overage_status・overage_resets_at・overage_disabled_reason・raw を持ちます
• TaskUsage は total_tokens・tool_uses・duration_ms です。CLI が長い MCP ツールの呼び出しをバックグラウンドへ移すと、その呼び出しのツール結果にはプレースホルダーだけが入り、本当の結果は TaskNotificationMessage に届きます。resource_links はデータクラスにフィールドがないので message.data.get("resource_links") で読みます

コンテンツブロック（Python）#

ContentBlock は、これらと ServerToolUseBlock・ServerToolResultBlock のユニオンです。

使用量の型#

ModelUsage（TypeScript の costUSD などはクライアント側の見積もり。Python は同じ camelCase のキーを持つ TypedDict で、claude_agent_sdk.types からインポートする）です。

Python の usage の辞書のキーは、input_tokens・output_tokens・cache_creation_input_tokens・cache_read_input_tokens です（メインのエージェントのループだけ）。TypeScript の Usage（BetaUsage）は、これらに加えて cache_creation（ephemeral_5m_input_tokens と ephemeral_1h_input_tokens）・server_tool_use・service_tier・speed・inference_geo・iterations・output_tokens_details（thinking_tokens を持つ。v0.3.228 以降）・fallback_credit（null になりうる。入るかは、インストールした @anthropic-ai/sdk（0.115.0 で追加）による）を持ちます。TypeScript の NonNullableUsage は、fallback_credit を除くすべての null になりうるフィールドを null にならない形にしたものです。サブエージェントの結果（Agent の出力）の usage に fallback_credit が入るのは、TypeScript SDK v0.3.285 以降・Python SDK v0.2.162 以降（Claude Code v2.1.285 を同梱）です。output_tokens が正式な合計で、思考の内訳は観測用です。

ThinkingConfig 以外の補助の型（TypeScript）#

SDKMessageOrigin の kind は次の7つです。

SDKControl*Response には、SDKControlInitializeResponse・SDKControlInterruptResponse・SDKControlGetContextUsageResponse・SDKControlReadFileResponse・SDKControlReloadPluginsResponse・SDKControlReloadSkillsResponse・SDKControlReloadOutputStylesResponse・SDKControlMcpReadResourceResponse があります。

SDKControlInitializeResponse には、任意の sdk_mcp_manifests_parked（サーバー名 → "parked"・"already_connected"・"protocol_version_mismatch"・"malformed"・"not_honoured"）が加わりました。リクエスト側の sdkMcpServerManifests と、この応答の sdk_mcp_manifests_parked は、createSdkMcpServer() で作ったプロセス内の SDK MCP サーバーのためのもので、アプリが設定したり読んだりするものではありません。

フックの型#

HookEvent#

TypeScript は次の33種類です。Python は PreToolUse・PostToolUse・PostToolUseFailure・UserPromptSubmit・Stop・SubagentStop・PreCompact・Notification・SubagentStart・PermissionRequest の10種類だけです（イベントごとの対応は SDK のツール・権限・拡張 の表）。

PreToolUse・PostToolUse・PostToolUseFailure・PostToolBatch・Notification・UserPromptSubmit・UserPromptExpansion・SessionStart・SessionEnd・Stop・StopFailure・SubagentStart・SubagentStop・PreCompact・PostCompact・PreModelSwitch・PostModelSwitch・PermissionRequest・PermissionDenied・Setup・TeammateIdle・TaskCreated・TaskCompleted・Elicitation・ElicitationResult・ConfigChange・DirectoryAdded・WorktreeCreate・WorktreeRemove・InstructionsLoaded・CwdChanged・FileChanged・MessageDisplay

コールバックとマッチャー#

フックの入力#

どのフックの入力にも共通のフィールドがあります。

TypeScript のイベントごとの入力の型は、PreToolUseHookInput（tool_name・tool_input・tool_use_id・mcp_server?）・PostToolUseHookInput・PostToolUseFailureHookInput・PostToolBatchHookInput・PermissionDeniedHookInput・NotificationHookInput・UserPromptSubmitHookInput・UserPromptExpansionHookInput・SessionStartHookInput・SessionEndHookInput・StopHookInput・StopFailureHookInput・SubagentStartHookInput・SubagentStopHookInput・PreCompactHookInput・PostCompactHookInput・PreModelSwitchHookInput・PostModelSwitchHookInput・PermissionRequestHookInput・SetupHookInput・TeammateIdleHookInput・TaskCreatedHookInput・TaskCompletedHookInput・ElicitationHookInput・ElicitationResultHookInput・ConfigChangeHookInput・InstructionsLoadedHookInput・DirectoryAddedHookInput・WorktreeCreateHookInput・WorktreeRemoveHookInput・CwdChangedHookInput・FileChangedHookInput・MessageDisplayHookInput です。Python は、PreToolUseHookInput・PostToolUseHookInput・PostToolUseFailureHookInput・UserPromptSubmitHookInput・StopHookInput・SubagentStopHookInput・PreCompactHookInput・NotificationHookInput・SubagentStartHookInput・PermissionRequestHookInput を持ちます。

フックの出力#

HookJSONOutput は、同期の出力（SyncHookJSONOutput）か非同期の出力（AsyncHookJSONOutput）です。

hookSpecificOutput のイベントごとのフィールドです（Python の型は PreToolUse・PostToolUse・PostToolUseFailure・UserPromptSubmit・Notification・SubagentStart・PermissionRequest）。

ツールの入力#

組み込みツールの入力の型です。TypeScript は @anthropic-ai/claude-agent-sdk/sdk-tools から型を読み込めます。Python の説明は、ツールの入出力の型の節にあります。

次のツールにも入力と出力の型があります。Workflow・TodoWrite・TaskCreate・TaskUpdate・TaskGet・TaskList・ExitPlanMode・EnterPlanMode・ListMcpResources（ツール名 ListMcpResourcesTool）・ReadMcpResource（ReadMcpResourceTool）・ReadMcpResourceDir（ReadMcpResourceDirTool）・RefreshMcpTools・EnterWorktree・ExitWorktree・CronCreate・CronDelete・CronList・ScheduleWakeup・RemoteTrigger・PushNotification・ReportFindings・Artifact・Projects・ShowOnboardingRolePicker、動的な MCP のツール（mcp__<server>__<tool> の形）です（ツール一覧は ツール一覧）。

• TaskOutput は Claude Code v2.1.277 で、TaskOutputInput の型とともに削除されました。まだ TaskOutput を名指しする disallowedTools や deny ルールは、警告なしに無視されます
• 実験的な REPL ツールは v2.1.275 で削除されました（v2.1.274 までは env の CLAUDE_CODE_REPL=1 で有効にできた）

エラー型（Python）#

• 単発の query() がエラーの結果で終わると、最後の結果メッセージのあとで ResultError が送出されます。Python Agent SDK 0.2.140 より前は、ClaudeSDKError のサブクラスでない普通の Exception を送出していました
• ResultError は subtype・errors（なければ空のリスト）・result・api_error_status・terminal_reason・session_id・data（結果の生のペイロード）を持ちます。失敗を見分けるには、subtype より先に terminal_reason を見ます。最後のリクエストが API エラーで失敗したときは、Claude Code は subtype を "success"、原因を terminal_reason（例："api_error"）で報告します
• ProcessError より先に ResultError を捕まえます

try:
    async for message in query(prompt="Hello"):
        print(message)
except CLINotFoundError:
    print("Claude Code CLI not found")
except ResultError as e:
    if e.terminal_reason == "api_error":
        print(f"API request failed: {e}")
    else:
        print(f"Query ended with an error result ({e.terminal_reason or e.subtype}): {e}")
except ProcessError as e:
    print(f"Process failed with exit code: {e.exit_code}")
except CLIJSONDecodeError as e:
    print(f"Failed to parse response: {e}")

そのほか#

• Python の SdkMcpTool は、name・description・input_schema・handler・annotations を持つデータクラスです
• Python の ToolAnnotations は、title・readOnlyHint（既定 False）・destructiveHint（既定 True）・idempotentHint（既定 False）・openWorldHint（既定 True）・maxResultSizeChars（Claude Code がツールのテキスト結果を、ファイルに保存せず会話にインラインで残す文字数の上限。最大 500,000）を持ち、camelCase でも snake_case でも書けます（snake_case と型付きの maxResultSizeChars は Python Agent SDK 0.2.140 以降）。TypeScript の ToolAnnotations は MCP SDK の型で、title と4つのヒントを持ちます。どれも、セキュリティの判断に頼ってはいけないヒントです
• Python の Transport は、独自の通信路（リモートの接続など）で Claude のプロセスとやり取りするための抽象クラスです。connect()・write(data)・read_messages()・close()・is_ready()・end_input() を実装します。低水準の内部 API で、インターフェースは今後のリリースで変わりえます
• Python の TaskBudget は {"total": <int>}、ToolsPreset は {"type": "preset", "preset": "claude_code"}、McpStatusResponse は mcpServers に McpServerStatus のリストを持ちます
• Python の McpServerStatus は、name・status（"connected"・"failed"・"needs-auth"・"pending"・"disabled"）・serverInfo（name と version）・error・config・scope・tools（name・description・annotations）を持ちます

削除された TypeScript の V2 セッション API#

試験的な V2 のセッション API（unstable_v2_createSession()・unstable_v2_resumeSession()・unstable_v2_prompt()、SDKSession と SDKSessionOptions の型）は、TypeScript Agent SDK 0.3.142 で削除され、もうサポートされません。移行するには、query() と、それが受け取るセッションのオプションを使います。複数ターンの会話には AsyncIterable<SDKUserMessage> を渡し、保存済みのセッションを続けるには options.resume を使います（SDK のセッションと入出力）。

V2 は、非同期ジェネレーターと yield の調整を要らなくした試験的な API でした。ターンごとに send() と stream() の組を呼ぶ形です。

• 0.2.x が V2 を含む最後のバージョンです。パッケージのバージョンは 0.2.x から直接 0.3.142 へ飛んだので、削除のバージョンと下のピン留めは、同じ境目を指しています。V2 に対応した最後のリリースを入れるには、npm install @anthropic-ai/claude-agent-sdk@0.2 で major と minor を固定します
• セッションは await using（TypeScript 5.2 以降）か、session.close() で閉じます
• V2 は V1 のすべての機能に対応していませんでした。セッションの分岐（forkSession オプション）と、一部の高度なストリーミング入力のパターンは V1 の SDK が必要でした
• 0.2.x 以前のコードを保守する人向けの参照です

// V1（現在）で同じことをする：1回きりの問い合わせ
import { query } from "@anthropic-ai/claude-agent-sdk";

const q = query({ prompt: "What is 2 + 2?", options: { model: "claude-opus-4-7" } });
for await (const msg of q) {
  if (msg.type === "result" && msg.subtype === "success") console.log(msg.result);
}