Agent SDKのサンプル集 — TypeScript/Pythonの実例

最初に動かす1本はどれか

最小のエージェントを1つ動かした経験がないなら、デモやCookbookに進む前にAgent SDK入門が先です。サンプルファイルのバグを見つけて直す最小エージェントを、PythonとTypeScriptの両方で組めます。

経験があるなら、本記事は「次に何を作るか」を決める地図になります。TypeScriptのアプリケーションはGitHubのclaude-agent-sdk-demosに、PythonのレシピはClaude CookbookのAgent SDKシリーズに、実行可能な形で公開されています。作りたいものに近い実装を読みに行くほうが、汎用ドキュメントを順に読むより早く手が動きます。

TypeScriptデモ8本の動かし方と選び方

claude-agent-sdk-demosにはローカル開発向けのデモが8本あります。READMEの前提はBun(またはNode.js 18以降)とAnthropicのAPIキーです。手順は、リポジトリをクローンして使いたいデモのディレクトリに入り、そこのREADMEに従うだけです。

git clone https://github.com/anthropics/claude-agent-sdk-demos.git
cd claude-agent-sdk-demos
cd hello-world   # email-agent や excel-demo などデモ名のディレクトリ

セットアップ手順はデモごとのディレクトリに専用のものがあるので、クローンしたルートで一括して準備するのではなく、使うデモのREADMEから始めます。

デモごとの学べる内容は次のとおりです。

Hello World V2のAPIは名前にunstable_が付いており、安定版として固定された仕様ではありません。コードを写して使うときは、SDKのバージョンを固定しておくと崩れにくくなります。

Pythonで学ぶレシピ集(Claude Cookbook)

Python向けの実例は、Claude CookbookのAgent SDKシリーズです。各レシピはPythonノートブックで、前のレシピの上に新しい概念を積む連作になっています。入口は「one-liner research agent」です。

動かす前の準備

最初のレシピの前提は、Python 3.11以上とAnthropicのAPIキー、そしてasync/awaitに慣れていることです。依存関係のインストールは次の1行です。

pip install -U claude-agent-sdk python-dotenv

APIキーは.envファイルにANTHROPIC_API_KEY=...の形で書き、ノートブックの先頭でload_dotenv()を呼んで読み込みます。SDK自体は.envを自動で読まないため、この1行が抜けるとNot logged inやInvalid API keyのような認証エラーになります。レシピのコードはMODEL = "claude-opus-4-6"でモデルを固定しています。

最小構成のone-liner research agent

入口のレシピが示す最小構成は次のとおりです。

from claude_agent_sdk import ClaudeAgentOptions, query
 
messages = []
async for msg in query(
    prompt="Research the latest trends in AI agents and give me a brief summary and relevant citiations links.",
    options=ClaudeAgentOptions(model=MODEL, allowed_tools=["WebSearch"]),
):
    print_activity(msg)
    messages.append(msg)

query()は単発の、会話の記憶を持たない呼び出しを作ります。allowed_tools=["WebSearch"]でWeb検索が承認なしで許可され、検索クエリの組み立てから結果の統合までをClaudeが自律的に進めます。

コード中のprint_activityはレシピ側の共通ユーティリティで、Claudeがいま何をしているかを画面に出します。同じモジュールのget_activity_text()を使うと、表示用の文字列をログ出力や監視の処理に渡せます。レシピは処理をresearch_agent/agent.pyのsend_query()にまとめており、display_result=Falseを渡すと結果のテキストだけが返ります。既定のTrueはノートブックに整形して表示します。

query()とClaudeSDKClientの使い分け

レシピはone-liner research agentに、次の3つの改善を段階的に加えていきます。

3つを組み合わせると、会話状態・システムプロンプト・複数ツールを同時に使うクライアントになります。

from claude_agent_sdk import ClaudeSDKClient
 
RESEARCH_SYSTEM_PROMPT = """You are a research agent specialized in AI.
When providing research findings:
- Always include source URLs as citations
- Format citations as markdown links: [Source Title](URL)
- Group sources in a "Sources:" section at the end of your response"""
 
async with ClaudeSDKClient(
    options=ClaudeAgentOptions(
        model=MODEL,
        cwd="research_agent",
        system_prompt=RESEARCH_SYSTEM_PROMPT,
        allowed_tools=["WebSearch", "Read"],
        max_buffer_size=10 * 1024 * 1024,  # 画像を扱うため10MBへ引き上げ
    )
) as research_agent:
    await research_agent.query("Analyze the chart in research_agent/projects_claude.png")
    async for msg in research_agent.receive_response():
        print_activity(msg)

画像を渡すと出るバッファエラー

この発展形で実際につまずきやすいのがmax_buffer_sizeです。既定値は1MB(1,048,576バイト)で、画像はメッセージ内でBase64エンコードされます。ディスク上で200KB程度の画像でも270KB以上に膨らみ、メッセージ全体のオーバーヘッドも加わって、既定値を超えることがあります。超えると次のエラーで止まります。

Fatal error in message reader: Failed to decode JSON: JSON message exceeded maximum buffer size of 1048576 bytes

対処はClaudeAgentOptionsのmax_buffer_sizeを引き上げることです。レシピは画像や大きめのツール出力を扱う用途で10MBを例示し、大きな文書を処理するならさらに上げるとしています。あわせて、フルサイズの画像が本当に必要か(説明文や縮小サムネイルで足りないか)の見直しと、バッファエラーの監視も挙げています。

次のレシピと応用先

one-liner research agentの次は「chief of staff agent」で、専門のサブエージェントを束ねる構成、フックとカスタムコマンドによる統制、相手に合わせた出力スタイルの切り替えへ進みます。単発のリサーチから複数エージェントへ移る段差は、ここで越えることになります。

競合分析や技術トラブルシューティング、投資リサーチ、文献レビューのように、入力の時点で答えが手元にないタスクには、同じ土台がそのまま使えます。

用途から選ぶ早見表

作りたいものが決まっているなら、次の対応でデモ・レシピを絞れます。

自分のプロジェクトに組み込む前に確認すること

• 本番デプロイを前提にしない: claude-agent-sdk-demosのREADMEはローカル開発専用で、本番や大規模利用はしないよう明記しています。認証・エラー処理・レート制限などは自分のアプリケーション側で用意します
• 認証はAPIキーが基本: デモのREADMEが前提に挙げるのはAnthropicのAPIキーです。SDKはAmazon BedrockやGoogle CloudのAgent Platformなど、サードパーティのプロバイダー経由の認証にも対応しています。claude.aiのログインやレート制限を第三者の製品として提供することは、事前の承認がない限り認められていません
• ランタイムを揃える: TypeScriptデモはBun(またはNode.js 18以降)が前提です。Pythonレシピは、最初のレシピがPython 3.11以上を求めます。SDKのホスティング解説ではPython 3.10以上と書かれており、ページごとに下限が異なります。レシピを動かすなら厳しいほうに合わせるのが無難です
• ClaudeAgentOptionsの破壊的変更: 旧SDK時代のコード例をそのまま持ち込むと動かないことがあります。命名や既定動作の変更点はAgent SDK移行ガイドにまとめています
• 並列実行は観測性を先に入れる: Cookbookのレシピはprint_activityでツール呼び出しを画面に出すだけです。複数のSDKサブプロセスをコンテナで並列に動かすなら、OpenTelemetryのOTEL_*環境変数をコンテナ側に持たせると、query()ごとのトレース・メトリクス・ログを収集基盤に流せます。トレースだけはCLAUDE_CODE_ENHANCED_TELEMETRY_BETAも必要です

デモを常駐サービスに寄せるときの制約

Research Agentのように調査者を並列で立てる構成や、Simple Chat Appのようにセッションを持つ構成を、手元から常駐サービスへ移すと、デモでは表に出なかった制約が出てきます。SDKのホスティング解説は、次の点を挙げています。

• セッションは自動では終わりません。トップレベルのタイムアウトがないため、max_turns(TypeScriptではmaxTurns)でツール呼び出しの往復回数に上限を付けます
• 大量のサブエージェントを一度に並列起動するとレート制限に当たることがあります。仕事を小さなバッチに分けて投入するのが対処です
• 会話の記録はコンテナのローカルディスクに置かれ、再起動やスケールダウンで失われます。再開したいセッションはSessionStoreアダプターで耐久性のある保存先に写します
• 1エージェントあたり1 GiBのRAM、5 GiBのディスク、1 CPUが起動直後の目安です。メモリは会話が長くなるほど増えるため、同時実行数は実際のセッション長で測って決めます

よくある質問

Claude Code本体の使い方との違いは何か

Claude Code CLIは対話的なターミナル利用や単発タスクの実行に向いた製品です。Agent SDKはそのエージェントループを自分のプロセスに組み込むためのライブラリで、対話端末を介さずアプリケーションから直接呼び出します。CLIとしての使い方はClaude Codeの基礎ガイドにまとめています。

PythonとTypeScript以外の言語から使えるか

SDKはPythonとTypeScriptの2言語です。それ以外の言語で同じエージェントループを動かすなら、CLIをサブプロセスとして-pフラグと--output-format json付きで呼び出す方法がSDKの概要に載っています。

Managed Agentsとはどう違うか

Managed Agentsはエージェントループ自体をAnthropicがホストするサービスで、セッションはAnthropic管理のクラウドサンドボックスか、自前のサンドボックスで動きます。Agent SDKは自分が運用するプロセスの中で動かす点が違います。

まとめ

写すときに固定したいのは2点です。unstable_v2_*を使うHello World V2はSDKのバージョンを固定し、Pythonレシピは下限が高いほう(3.11以上)に実行環境を合わせます。この2点を決めてから、作りたいものの形に近い1本を選ぶと、動かなくなったときの原因を切り分けやすくなります。