はじめに

2025年9月、AnthropicはClaude Sonnet 4.5と同時に、Claude Agent SDKを正式にリリースしました。このSDKは、Claude Codeを駆動しているagent harnessをベースに構築されており、開発者が驚くほど少ないコードで本格的なAIエージェントを構築できるようになっています。

実際に検証してみると、公式ドキュメントにある最もシンプルな例では、わずか数行でClaude Code相当のエージェントが作れることがわかりました。

https://docs.claude.com/en/docs/claude-code/sdk/migration-guide

import anyiofrom claude_agent_sdkimport queryasyncdefmain():asyncfor messagein query(prompt="What is 2 + 2?"):print(message)anyio.run(main)

これだけです。もちろん、これは最小限の例ですが、ツールの追加や会話の継続も驚くほど簡単に実現できます。本記事では、実際にカスタムツールを持つ数学計算エージェントを作成し、その仕組みを詳しく解説していきます。

Claude Agent SDKとは何か

Claude Agent SDKは、元々「Claude Code SDK」という名前でしたが、2025年9月に現在の名称に変更されました。この改名は、SDKの適用範囲がコーディングタスクに留まらず、様々な種類のエージェント構築に対応できることを反映しています。

公式ドキュメントによれば、このSDKは「Claude Codeを駆動するagent harnessの上に構築されている」とのことです。つまり、Anthropic自身が本番環境で使用している技術を、そのまま開発者に提供しているということになります。

主な機能

このSDKが提供する機能は以下の通りです：

• 自動コンテキスト管理：会話が長くなっても、SDKが自動的にコンテキストを圧縮し、トークン制限に達しないよう調整します
• 豊富なツールエコシステム：ファイル操作、コード実行、Web検索など、すぐに使えるツールが用意されています
• カスタムツールの追加：データベースやAPIと連携する独自のツールを簡単に追加できます

準備

Claude Agent SDKはPythonとTypeScript/JavaScriptの両方で利用できます。本記事ではPythonを使用しますが、TypeScriptでも同様の機能が利用可能です。

Python版：

# SDKのインストール（Python 3.10以上が必要）pipinstall claude-agent-sdk# 環境変数の設定exportANTHROPIC_API_KEY="your-api-key-here"

TypeScript版：

# SDKのインストール（Node.js 18以上が必要）npminstall @anthropic-ai/claude-agent-sdk

Anthropic APIキーはClaude Consoleから取得できます。

計算エージェント実装してみる

では、実際にカスタムツールを持つエージェントを作成してみましょう。今回は、加算、乗算、累乗、階乗の4つの計算ツールを持つ数学エージェントを実装します。

以下のコードはすべてmath_agent.py という1つのファイルにまとめて記述します。各セクションのコードを順番に紹介していきますので、最後に実行方法を説明します。

必要なモジュールのインポート

まず、必要なライブラリをインポートします：

import anyioimport mathfrom claude_agent_sdkimport(    tool,    create_sdk_mcp_server,    ClaudeSDKClient,    ClaudeAgentOptions,    AssistantMessage,    TextBlock,    ToolUseBlock,)

ツール定義

Claude Agent SDKでは、@toolデコレータを使うだけでカスタムツールを定義できます。

import mathfrom claude_agent_sdkimport tool　@tool("add","2つの数を足す",{"a":float,"b":float})asyncdefadd_tool(args):"""加算ツール"""    result= args["a"]+ args["b"]return{"content":[{"type":"text","text":str(result)}]}@tool("multiply","2つの数を掛ける",{"a":float,"b":float})asyncdefmultiply_tool(args):"""乗算ツール"""    result= args["a"]* args["b"]return{"content":[{"type":"text","text":str(result)}]}@tool("power","累乗計算",{"base":float,"exponent":float})asyncdefpower_tool(args):"""累乗ツール"""    result= args["base"]** args["exponent"]return{"content":[{"type":"text","text":str(result)}]}@tool("factorial","階乗計算",{"n":int})asyncdeffactorial_tool(args):"""階乗ツール"""    n=int(args["n"])if n<0:return{"content":[{"type":"text","text":"負の数の階乗は計算できません"}]}    result= math.factorial(n)return{"content":[{"type":"text","text":str(result)}]}

ツール定義は非常にシンプルです。ツール名、説明、入力パラメータの型を指定し、関数本体で実際の処理を記述するだけです。

ツールをSDKに登録

次に、定義したツールをSDKに登録します。

from claude_agent_sdkimport create_sdk_mcp_serverserver= create_sdk_mcp_server(    name="math-tools",    version="1.0.0",    tools=[add_tool, multiply_tool, power_tool, factorial_tool])

create_sdk_mcp_serverは、定義したツールをClaudeが呼び出せる形式にまとめる関数です。ここではツールのリストを渡すだけで、複雑な設定は必要ありません。

内部的にはModel Context Protocol（MCP）という仕組みが使われていますが、SDKがすべて処理してくれるため、開発者はMCPの詳細を理解する必要はありません。また、外部プロセスとして実行する必要がなく、アプリケーションと同じプロセス内で動作するため、デプロイも簡単です。

エージェント設定

まず、エージェントの動作を制御するオプションを設定します。

from claude_agent_sdkimport ClaudeSDKClient, ClaudeAgentOptionsoptions= ClaudeAgentOptions(    model="claude-haiku-4-5",# 使用するモデル    permission_mode="bypassPermissions",# テスト用：ツールを自動承認    mcp_servers={"math": server},# 先ほど作成したツールサーバー    allowed_tools=[# 使用を許可するツール"mcp__math-tools__add","mcp__math-tools__multiply","mcp__math-tools__power","mcp__math-tools__factorial",])

modelには使用したいClaudeのモデルを指定します。allowed_toolsで許可するツールを明示的にリストアップすることで、エージェントが使用できる機能を制御できます。

AIとの対話実装

次に、実際にClaudeと対話するためのループを実装します。

asyncdefmain():asyncwith ClaudeSDKClient(options=options)as client:whileTrue:# ユーザー入力を受け取る            user_input=input("\n💬 あなた: ").strip()if user_input.lower()in["exit","quit","終了"]:break# Claudeにクエリを送信await client.query(user_input)# ストリーミングでレスポンスを受信print("🤖 Claude: ", end="", flush=True)asyncfor messagein client.receive_response():ifisinstance(message, AssistantMessage):for blockin message.content:ifisinstance(block, TextBlock):# テキスト応答を表示print(block.text, end="", flush=True)elifisinstance(block, ToolUseBlock):# ツール呼び出しを表示（デバッグ用）print(f"\n   🔧 [{block.name}]{block.input}", end="", flush=True)print()# エージェントを起動if __name__=="__main__":    anyio.run(main)

ポイント：

1. client.query(user_input)：ユーザーの質問をClaudeに送信します
2. client.receive_response()：Claudeからの応答をストリーミングで受け取ります
3. AssistantMessage：Claudeからのメッセージには、テキスト（TextBlock）とツール呼び出し（ToolUseBlock）の両方が含まれる可能性があります
4. ストリーミング：応答が生成されるたびにリアルタイムで表示されるため、待ち時間が短く感じられます

ClaudeSDKClientを使用することで、セッションの継続性が保たれ、会話の文脈を維持したまま複数ターンの対話が可能になります。

エージェントの起動方法

上記のコードをすべてmath_agent.py というファイルに保存し、以下のコマンドで実行します：

# 必要なパッケージのインストールpipinstall claude-agent-sdk anyio# エージェントの起動python math_agent.py

起動すると、以下のようなプロンプトが表示され、対話が開始されます：

💬 あなた:

ここに質問を入力すると、Claudeが応答を返してくれます。終了する場合はexit、quit、または終了 と入力してください。

実行結果

実装したエージェントを起動すると、以下のような対話が可能になります。

エージェントは自己紹介をし、「Claude Code へようこそ」と言っています。まさに、自分専用のClaude Codeを作成できたわけです。

ReActパターンの実現

このエージェントの興味深い点は、ReAct（Reasoning and Acting）パターンを自然に実現していることです。ReActとは、「思考（Reasoning）→ 行動（Acting）→ 観察（Observation）」を繰り返すエージェントの動作パターンです。

実際の動作を見てみましょう。

ユーザーからの複雑なリクエスト「7 × 8を計算して、そして14の階乗を計算してください。二つの結果を最後足し算してください。別々でツールを呼び出してください」に対して、エージェントは以下のように動作しています：

1. 思考：「7 × 8を計算して、14の階乗を計算して、その後、二つの結果を足します。別々にツールを呼び出します」
2. 行動1：multiplyツールを呼び出し →観察：結果は56
3. 行動2：factorialツールを呼び出し →観察：結果は87178291200
4. 行動3：addツールを呼び出し →観察：結果は87178291256

最終的に、エージェントは3つのツールを適切な順序で使用し、正しい答えを導き出しています。このような複雑なタスクの分解と実行が、コードの追加なしに自動的に行われることは驚くべきことです。

さらに、エージェントは自分が持っているツールについても理解しています。

「数学計算について、どんなツールを持っていますか？」という質問に対して、エージェントは自分の能力を正確に列挙し、使用例まで提示しています。

実装時の推奨事項

エラーハンドリング

本番環境で使用する場合は、より詳細なエラーハンドリングを実装することが推奨されます。

try:asyncwith ClaudeSDKClient(options=options)as client:# ... エージェントのロジックexcept KeyboardInterrupt:print("\nユーザーによる中断")except Exceptionas e:print(f"\nエラー:{type(e).__name__}:{e}")

権限モードの設定

今回の例ではpermission_mode="bypassPermissions"を使用していますが、これはテスト用の設定です。本番環境では、適切な権限管理を実装することが重要です。

マルチエージェント対応

Claude Agent SDKは、subagents（サブエージェント）を使った複数エージェントの編成もサポートしています。Orchestrator-Workerパターンを使用することで、複数の専門化されたエージェントを並列実行し、それぞれが独立したコンテキストウィンドウを持つことができます。

これにより、大規模なタスクを複数の小さなタスクに分割し、効率的に処理することが可能になります。ただし、今回の実装では単一エージェントに焦点を当てています。

注意点

Claude Agent SDKは基本的にClaude向けに最適化されているため、他のLLMとの互換性は限定的です。マルチモデル対応が必要な場合は、OpenAI Agents SDKやLangChainなどの汎用フレームワークの方が適している場合もあります。

まとめ

Claude Agent SDKは、最小限のコードで本格的なAIエージェントを構築できる強力なツールです。@toolデコレータによる簡潔なツール定義、create_sdk_mcp_serverによる簡単な統合、そしてClaudeSDKClientによるストリーミング対話の実現は、開発体験を大幅に向上させます。

ReActパターンの自然な実現や、自動コンテキスト管理といった高度な機能が、開発者の負担なく提供されることは、まさに「ClaudeCodeを数行で作る」という表現に相応しいと言えるでしょう。

所感として、このSDKはAIエージェント開発の新しい標準になる可能性を秘めています。ただし、適用範囲や制約を理解した上で、プロジェクトの要件に合わせて活用することが重要です。今後も、このSDKの進化とコミュニティの成長に注目していきたいと思います。