Claude Agent SDK入門：Pythonで読み取り専用エージェントを作る¶

対象 / ポイント

対象: PythonでClaudeへファイル調査やツール利用を任せたい開発者

ポイント:

現在のPythonパッケージ名は claude-agent-sdk、import名は claude_agent_sdk である
1回の処理は query()、複数ターンやカスタムツールは ClaudeSDKClient が基本になる
最初はRead、Grep、Globだけを許可し、書き込み権限を後から追加する

Claude Agent SDKは、Claude Codeと同系統のエージェントループ、ファイルツール、権限、セッションをアプリケーションへ組み込むSDKだ。 Python版はPython 3.10以上に対応し、必要なClaude Code CLIをパッケージへ同梱するため、別インストールは必須ではない。¹

旧記事やサンプルにある anthropic-agent-sdk、AgentSDK、agent.run() は現在のPython APIではない。ここでは公式READMEに沿った最小構成から始める。

1. 環境を作る¶

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

Windows PowerShellでは有効化だけを読み替える。

.venv\Scripts\Activate.ps1

直接Claude APIで認証する環境では、ANTHROPIC_API_KEY をシークレット管理から環境変数へ渡す。キーをソースコード、.env のコミット、ログへ残さない。

2. 最小の問い合わせを実行する¶

query() はメッセージを非同期ストリームとして返す。

import anyio
from claude_agent_sdk import ResultMessage, query


async def main() -> None:
    async for message in query(prompt="2 + 2 は？"):
        if isinstance(message, ResultMessage):
            print(message.result)


anyio.run(main)

ストリームには初期化、Claudeの出力、ツール利用、最終結果が順に流れる。 ResultMessage は最後のイベントで、result のほか使用量、コスト、セッションIDを持つ。¹

3. 読み取り専用のコード調査へ広げる¶

最初の実用例では、書き込みとシェルを渡さない。

import anyio
from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query


async def main() -> None:
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Grep", "Glob"],
        max_turns=6,
    )

    prompt = """
    このプロジェクトの認証処理を調べる。
    実装ファイル、設定、テストを根拠として、
    ログインからセッション確立までを要約する。
    ファイルは変更しない。
    """

    async for message in query(prompt=prompt, options=options):
        if isinstance(message, ResultMessage):
            if message.is_error:
                raise RuntimeError(message.result or "Agent run failed")
            print(message.result)
            print(f"cost_usd={message.total_cost_usd}")


anyio.run(main)

allowed_tools は利用可能なツールを絞る。書き込みやシェルを追加した場合、利用可能にすることと自動承認することは別であり、permission_mode や can_use_tool で承認境界を設計する。²

`query()` と `ClaudeSDKClient` の使い分け¶

API	状態	向く用途
`query()`	呼び出し単位	1回の調査、独立したバッチ処理
`ClaudeSDKClient`	開いている間は複数ターンを保持	対話UI、途中指示、カスタムツール、継続セッション

query() は短い処理を関数として呼ぶ場合に単純である。同じ文脈へ追加入力する、実行途中に介入する、SDK内MCPツールを使う場合は ClaudeSDKClient を選ぶ。²

カスタムツールの考え方¶

Python関数をそのまま自由実行させるのではなく、@tool で入力スキーマを定義し、create_sdk_mcp_server でインプロセスMCPサーバーとして渡す。

ツールを設計するときは次を守る。

読み取りと更新を別ツールにする
自由文1項目ではなく、対象IDと操作を型付きで定義する
外部送信、削除、公開にはアプリケーション側の承認を置く
入力、結果、失敗を監査ログへ記録する
ツールの例外を成功メッセージへ変換しない

SDKがエージェントループを提供しても、外部APIの認可と副作用の責任はアプリケーション側に残る。

本番化前のチェック¶

作業ディレクトリを限定する¶

SDKの組み込みツールは、実行プロセスのファイルシステムへ作用する。専用ワークツリー、コンテナ、一時ディレクトリを使い、ホームディレクトリ全体を作業範囲にしない。

上限を置く¶

max_turns、タイムアウト、API側の予算、同時実行数を制限する。 ResultMessage の使用量と total_cost_usd を保存し、失敗時も計測する。

結果を検証する¶

エージェントの最終文をそのまま次の更新処理へ渡さない。 JSON Schema、件数照合、静的解析、テストなど、成果物に合う検査を挟む。

秘密を分離する¶

APIキーをプロンプトやファイルへ書かず、ツール実行時に必要な最小スコープで注入する。ログからAuthorizationヘッダーと個人情報を除外する。

よくあるエラー¶

`No matching distribution found`¶

Pythonのバージョンとパッケージ名を確認する。

python --version
python -m pip install --upgrade claude-agent-sdk

古いサンプルのimportが失敗する¶

現在は from claude_agent_sdk import ... を使う。旧Claude Code SDKからはクラス名とメッセージ型に破壊的変更があるため、公式READMEのmigration節を確認する。¹

ツールが承認待ちになる¶

allowed_tools と承認モードは別である。まずツールを絞り、書き込みを無条件承認する前に can_use_tool やhooksで許可条件を実装する。

まとめ¶

pip install claude-agent-sdk で導入し、claude_agent_sdk からimportする
1回の処理は query()、継続対話やカスタムツールは ClaudeSDKClient を使う
Read、Grep、Globから始め、書き込みとBashは別途承認する
作業範囲、ターン、コスト、副作用をアプリケーション側で制限する

短いコードで動くことは導入の利点だが、安全なエージェントは行数では決まらない。ツールを狭くし、実行結果を検証し、失敗時に止められる構造まで含めて最小実装と考える。