Agent SDK リファレンス — Python

概要

Python 用 Agent SDK の API リファレンス。query() による単発クエリと ClaudeSDKClient による複数ターンの会話を提供する。

仕様

インストール

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

システム Python への直接 pip install は、最近の Debian / Ubuntu / Homebrew Python では error: externally-managed-environment で失敗する

`query()` と `ClaudeSDKClient` の選択

機能	`query()`	`ClaudeSDKClient`
セッション	デフォルトで新規作成	同一セッションを再利用
会話	単一のやり取り	同一コンテキストで複数のやり取り
接続	自動管理	手動制御
ストリーミング入力	対応	対応
割り込み（interrupt）	非対応	対応
Hooks	対応	対応
カスタムツール	対応	対応
会話の継続	`continue_conversation` または `resume` で手動	自動
ユースケース	単発タスク	継続的な会話

主要関数

`query()`

新しいセッションを作成し、メッセージを非同期イテレータとして返す。

async def query(
    *,
    prompt: str | AsyncIterable[dict[str, Any]],
    options: ClaudeAgentOptions | None = None,
    transport: Transport | None = None
) -> AsyncIterator[Message]

prompt: 文字列またはストリーミングモード用の非同期イテラブル
options: ClaudeAgentOptions（省略時はデフォルト設定）
transport: カスタムトランスポート（省略時はローカルサブプロセス）

`tool()`

MCP ツールを定義するデコレータ。

@tool("greet", "Greet a user", {"name": str})
async def greet(args: dict[str, Any]) -> dict[str, Any]:
    return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]}

input_schema: 簡易型マッピング（{"text": str, "count": int}）または JSON Schema 形式を指定可能
annotations: ToolAnnotations（readOnlyHint、destructiveHint、idempotentHint、openWorldHint 等）を指定可能。mcp.types から再エクスポートされている

`create_sdk_mcp_server()`

インプロセス MCP サーバーを作成する。

def create_sdk_mcp_server(
    name: str,
    version: str = "1.0.0",
    tools: list[SdkMcpTool[Any]] | None = None
) -> McpSdkServerConfig

返り値は ClaudeAgentOptions.mcp_servers に渡す

`list_sessions()`

過去のセッション一覧を取得する。同期関数。

def list_sessions(
    directory: str | None = None,
    limit: int | None = None,
    offset: int = 0,
    include_worktrees: bool = True
) -> list[SDKSessionInfo]

directory 省略時は全プロジェクトのセッションを返す
結果は last_modified 降順

`get_session_messages()`

過去セッションのメッセージを取得する。同期関数。

def get_session_messages(
    session_id: str,
    directory: str | None = None,
    limit: int | None = None,
    offset: int = 0
) -> list[SessionMessage]

`get_session_info()`

セッション ID でメタデータを取得する。同期関数。セッションが見つからなければ None を返す。

`rename_session()`

セッションのタイトルを変更する。同期関数。繰り返し呼び出し可能で、最新のタイトルが有効。

`tag_session()`

セッションにタグを設定する。None でクリア。同期関数。

`ClaudeSDKClient`

複数のやり取りにわたるセッションを維持するクラス。async context manager として使用可能。

メソッド	説明
`connect(prompt)`	Claude に接続（オプションで初期プロンプト）
`query(prompt, session_id)`	ストリーミングモードで新しいリクエストを送信
`receive_messages()`	全メッセージを非同期イテレータで受信
`receive_response()`	`ResultMessage` を含むまでメッセージを受信
`interrupt()`	割り込みシグナルを送信（ストリーミングモードのみ）
`set_permission_mode(mode)`	セッション中にパーミッションモードを変更
`set_model(model)`	セッション中にモデルを変更。`None` でデフォルトにリセット
`rewind_files(user_message_id)`	指定メッセージ時点のファイル状態に復元。`enable_file_checkpointing=True` が必要
`get_mcp_status()`	全 MCP サーバーのステータスを取得
`reconnect_mcp_server(server_name)`	失敗/切断された MCP サーバーへの再接続
`toggle_mcp_server(server_name, enabled)`	MCP サーバーの有効/無効を切り替え
`stop_task(task_id)`	実行中のバックグラウンドタスクを停止
`get_server_info()`	セッション ID やケイパビリティを含むサーバー情報を取得
`disconnect()`	切断

`ClaudeAgentOptions`

主要なフィールド:

フィールド	型	デフォルト	説明
`allowed_tools`	`list[str]`	`[]`	自動承認するツール。他のツールは制限されない
`disallowed_tools`	`list[str]`	`[]`	ブロックするツール
`system_prompt`	`str \| SystemPromptPreset \| SystemPromptFile \| None`	`None`	システムプロンプト
`mcp_servers`	`dict[str, McpServerConfig] \| str \| Path`	`{}`	MCP サーバー設定
`permission_mode`	`PermissionMode \| None`	`None`	パーミッションモード
`continue_conversation`	`bool`	`False`	前回セッションの会話を継続
`resume`	`str \| None`	`None`	特定セッション ID の会話を再開
`max_turns`	`int \| None`	`None`	最大ターン数
`max_budget_usd`	`float \| None`	`None`	最大予算（USD）
`model`	`str \| None`	`None`	使用するモデル
`fallback_model`	`str \| None`	`None`	フォールバックモデル
`cwd`	`str \| Path \| None`	`None`	作業ディレクトリ
`can_use_tool`	`CanUseTool \| None`	`None`	ツール使用許可コールバック
`hooks`	`dict[HookEvent, list[HookMatcher]] \| None`	`None`	フックの設定
`agents`	`dict[str, AgentDefinition] \| None`	`None`	サブエージェント定義
`thinking`	`ThinkingConfig \| None`	`None`	Thinking 設定
`effort`	`EffortLevel \| None`	`None`	推論の努力レベル
`enable_file_checkpointing`	`bool`	`False`	ファイルチェックポイント
`load_timeout_ms`	`int`	`60_000`	読み込みタイムアウト（ms）
`task_budget`	`TaskBudget \| None`	`None`	タスクバジェット

サブエージェントの出力と追加ディレクトリ

既定では、サブエージェントの tool_use と tool_result ブロックだけがメッセージストリームに出る。 forward_subagent_text（既定 False）を True にすると、サブエージェントのテキストと thinking ブロックも転送される
add_dirs の各項目は Claude Code へ --add-dir として渡される。 project の setting source が有効な場合、そのディレクトリの skill・command・subagent も読み込まれる

型の注意点

@dataclass で定義された型（ResultMessage、AgentDefinition、TextBlock 等）は属性アクセス: msg.result
TypedDict で定義された型（ThinkingConfigEnabled、McpStdioServerConfig、SyncHookJSONOutput 等）はランタイムでは辞書。キーアクセスが必要: config["budget_tokens"]

メッセージ型

Message = (
    UserMessage
    | AssistantMessage
    | SystemMessage
    | ResultMessage
    | StreamEvent
    | RateLimitEvent
    | ConversationResetMessage
)

ResultMessage.subtype: "success" / "error_during_execution" / "error_max_turns" / "error_max_budget_usd" / "error_max_structured_output_retries"
ResultMessage.terminal_reason: "completed" / "max_turns" / "api_error" / "aborted_streaming" / "aborted_tools" 等
ResultMessage.usage: トップレベルエージェントループのみ。サブエージェントのトークンは含まない。全体のトークン計測には model_usage を使う
ResultMessage.model_usage: メインループ、サブエージェント、compaction 等を含む累積値。パーミッション分類器やトークンカウントリクエストは除外。請求明細ではなく見積もりとして扱う
AssistantMessageError: "authentication_failed" / "billing_error" / "rate_limit" / "invalid_request" / "server_error" / "unknown"。CLI はこのリテラル外の値（例: max_output_tokens）も返す可能性がある

制約・注意点

interrupt() 後、中断されたタスクのメッセージ（ResultMessage を含む）がバッファに残る。新しいクエリのレスポンスを読む前に receive_response() でドレインする必要がある
メッセージイテレーション中に break で早期終了すると asyncio のクリーンアップに問題が発生する可能性がある
max_thinking_tokens は非推奨。代わりに thinking を使う
debug_stderr は非推奨。代わりに stderr を使う
Transport クラスは低レベル内部 API であり、将来のリリースでインターフェースが変更される可能性がある
ストリーミング入力モードでは model_usage と total_cost_usd はターンを跨いで累積される。最新の result を読み取る（合算しない）

Agent SDK リファレンス — Python

概要

仕様

インストール

query() と ClaudeSDKClient の選択

主要関数

query()

tool()

create_sdk_mcp_server()

list_sessions()

get_session_messages()

get_session_info()

rename_session()

tag_session()

ClaudeSDKClient

ClaudeAgentOptions