Python SDK を使う

段	達成したと言える状態
1. 触る	仮想環境に `claude-agent-sdk` を入れ、`query()` でメッセージを非同期イテレータとして受け取れた
2. 入れる	単発なら `query()`、継続する会話なら `ClaudeSDKClient` と、用途で選び分けている
3. 効かせる	`ResultMessage` の `subtype` と `model_usage` を読み、`interrupt()` 後のバッファ処理まで含めて実装できる

何のためのものか

Python 用 Agent SDK。query() による単発クエリと、ClaudeSDKClient による複数ターンの会話の 2 本立て。

触る

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() は新しいセッションを作り、メッセージを非同期イテレータとして返す。

入れる

2 つの入口を用途で選ぶ。

	`query()`	`ClaudeSDKClient`
セッション	デフォルトで新規作成	同一セッションを再利用
会話	単一のやり取り	同一コンテキストで複数のやり取り
割り込み	非対応	対応
会話の継続	`continue_conversation` または `resume` で手動	自動

ClaudeSDKClient は async context manager として使え、セッション中に set_permission_mode() / set_model() を呼べる。MCP の状態確認（get_mcp_status()）や再接続（reconnect_mcp_server()）もここから。

よく使う ClaudeAgentOptions は allowed_tools / disallowed_tools / system_prompt / permission_mode / max_turns / max_budget_usd / can_use_tool / hooks / agents あたり。

効かせる

結果の読み方を決める。 ResultMessage.subtype は "success" / "error_during_execution" / "error_max_turns" / "error_max_budget_usd" など。usage はトップレベルのループのみで、subagent を含む全体は model_usage を見る（請求明細ではなく見積もり）
型のアクセス方法が 2 種類ある。 @dataclass の型（ResultMessage、AgentDefinition など）は属性アクセス、TypedDict の型（ThinkingConfigEnabled、McpStdioServerConfig など）は辞書のキーアクセス
ファイルの巻き戻しが要るなら enable_file_checkpointing=True を立てて rewind_files()

落とし穴

interrupt() の後はバッファが残る。 中断されたタスクのメッセージ（ResultMessage を含む）が残るので、新しいクエリの応答を読む前に receive_response() でドレインする
メッセージイテレーション中の break は asyncio のクリーンアップに問題を起こしうる
ストリーミング入力モードでは model_usage と total_cost_usd がターンを跨いで累積される。 合算せず最新の result を読む
非推奨の項目がある（max_thinking_tokens → thinking、debug_stderr → stderr）
Transport クラスは低レベル内部 API で、将来インターフェースが変わりうる

Python SDK を使う

どこまで来たら使えたと言えるか

何のためのものか

触る

入れる

効かせる

落とし穴

根拠と前後