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

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

選ぶべきものは、最小のエージェントを1つ動かした経験があるかどうかで変わります。まだ何も動かしていないなら、いきなりTypeScriptのデモやPythonのCookbookレシピに手を出すのは遠回りです。Agent SDK入門でサンプルファイルのバグを見つけて直す最小エージェントを組むのが最短です。セットアップからPython/TypeScript両方のコードまで一通り揃っています。

すでに最小構成を動かした経験があるなら、本記事は「次に何を作るか」を決めるための地図として使えます。TypeScriptのアプリケーションはGitHubのclaude-agent-sdk-demosリポジトリに、PythonのレシピはClaude CookbookのAgent SDKシリーズに、それぞれ実行可能な形で公開されています。

入門ガイドが1本のエージェントを最初から最後まで組み立てる手順書だとすれば、本記事はそこから先にどんな作りたいものがあるかを見取り図として並べる位置付けです。作りたいものの輪郭が見えているなら、いきなり近いデモやレシピのコードを読みに行くほうが、汎用のドキュメントを順番に読むより早く手を動かせます。

TypeScriptで動かせる実践デモ

claude-agent-sdk-demosリポジトリには、ローカル開発向けのデモアプリケーションが8本収録されています。いずれもBun(またはNode.js 18以降)とAnthropicのAPIキーがあればクローンして動かせます。

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

Python向けの実例はClaude CookbookのAgent SDKシリーズにまとまっています。1本のノートブックが単体で完結するのではなく、シンプルなリサーチエージェントから高度なマルチエージェントシステムへと段階的に発展していく連作です。入口は「one-liner research agent」で、ここから先へ進む形になっています。

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が自律的に検索クエリを組み立てて結果を統合します。

ステートレスなquery()が向くのはコンテキストを引き継がない一回限りの調査、独立したリサーチタスクの並列処理、毎回まっさらな文脈で答えさせたい場面です。逆に、前の調査結果を踏まえて掘り下げる複数ターンの調査や、初期結果を踏まえた反復的な絞り込み、持続的な文脈が要る複雑な分析には向きません。こうした場面では会話状態を保持できる構成(TypeScript側なら前述のHello World V2のSession API)に切り替える判断が必要です。

Cookbookのレシピはこの一本から、次の3つの改善を段階的に加えていく構成になっています。

1. ClaudeSDKClient による会話の記憶: ステートレスなquery()は前回の調査結果を踏まえられません。「AIスタートアップの上位はどこか」と聞いた後に「それぞれの資金調達状況は」と続けても、2回目の呼び出しは「それぞれ」が何を指すか分からないままです。ClaudeSDKClient を使い複数の呼び出しをまたいで会話履歴を保持します
2. 専門特化のためのシステムプロンプト: リサーチ領域ごとに要求される厳密さは異なります。金融分析と技術ニュースの要約では必要な水準が違うため、システムプロンプトに引用フォーマットや優先ソース、出力構造といった調査基準を書き込みます
3. Readツールによるマルチモーダル調査: 実際の調査はテキストだけで完結しません。市場レポートのグラフや技術文書の図、競合比較のスクリーンショットを扱うため、Readツールを有効にして画像やPDFを解析できるようにします

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程度に引き上げることです。あわせて、本当にフルサイズの画像を渡す必要があるか(説明文や縮小サムネイルで足りないか)を見直す、バッファエラーの発生を監視して都度調整する、という運用も推奨されています。

研究テーマ以外にも、競合分析・技術トラブルシューティング・投資リサーチ・文献レビューなど「入力の時点で答えを持っていない」タスク全般に同じ土台が使えます。

用途から選ぶ早見表

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

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

• 本番デプロイを前提にしない: claude-agent-sdk-demosはローカル開発向けの実装で、認証・エラーハンドリング・レート制限対策などが本番水準では作り込まれていません。参考にする場合も自分のアプリケーション側でこれらを補う必要があります
• APIキーの準備が前提: どのデモもAnthropicのAPIキーが必須です。claude.aiのログインやレート制限を第三者製品にそのまま提供することは許可されていないため、キー認証の構成をあらかじめ用意してください
• ランタイムの違いに注意: TypeScriptデモはBun(またはNode.js 18以降)、Pythonレシピはpip install -U claude-agent-sdk python-dotenvのようなノートブック向けの依存関係が前提です。プロジェクトのランタイムと揃っているか事前に確認します
• ClaudeAgentOptionsの破壊的変更に注意: 旧SDK時代のコード例をそのまま持ち込むと動かないことがあります。命名や既定動作の変更点はAgent SDK移行ガイドにまとめています
• コンテナ化・並列実行を検討するなら観測性を先に組み込む: デモのコードは標準出力にツール呼び出しを表示するだけですが、複数のSDKサブプロセスをコンテナで並列に動かす構成に発展させる場合、OpenTelemetryのトレース・メトリクス・ログを収集基盤にエクスポートする設定をコンテナ側の環境変数で持たせておくと、後から呼び出しごとの挙動を追跡しやすくなります

デモやレシピをそのまま動かして満足するのではなく、上記の5点を自分のユースケースに照らしてから本番寄りの設計に進めることが、公式サンプルを安全に活用する近道です。

よくある質問

TypeScriptとPythonのどちらから始めるべきか

バックエンドの実装言語に合わせるのが最も摩擦がありません。判断材料が無い場合、TypeScriptはWebアプリやチャットUIとの統合デモが厚く、PythonはCookbookのノートブック形式で概念を1つずつ積み上げて学べる点が強みです。

デモのコードをそのまま本番で使えるか

推奨されません。claude-agent-sdk-demosはAnthropicが提供するローカル開発向けのサンプルで、README自体が本番デプロイや大規模利用を想定していないと明記しています。構成や設計の参考にとどめ、認証・監視・エラー処理は自分のアプリケーションで作り込んでください。

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

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

Managed Agentsとはどう違うか

Managed Agentsはエージェント実行とサンドボックスの管理をAnthropic側が担うホスト型のREST APIで、Agent SDKとは別製品です。自分のプロセス内でエージェントループを動かしたいならAgent SDK、サンドボックスやセッション基盤を自前で持ちたくないならManaged Agentsという住み分けになります。

まとめ

Agent SDKのサンプルは、TypeScriptならクローンしてすぐ動かせるclaude-agent-sdk-demosの8本、Pythonならone-liner research agentから発展していくClaude Cookbookのレシピ、という2つの入口に分かれます。どちらもローカル開発向けの参考実装であり、本番投入には認証・エラー処理・レート制限対策・観測性を自分のアプリケーション側で補う前提です。何を作りたいかが決まっているなら、用途別の早見表から近いものを選んでコードを読むのが、ドキュメントだけを読むより早く手を動かせる近道になります。動かしてみて挙動に疑問が出たら、パッケージのバージョン差異や旧SDKからの移行漏れが原因になっていないかも合わせて確認してください。