Anthropic の Agent SDK は、Claude Code をターミナル用アシスタントから、自分のワークフローに組み込めるプログラム可能で自動化可能な AI エージェントへと変えます。このガイドでは、インストール、エージェントループ、ツール連携、MCP サーバー、サブエージェントのオーケストレーション、そして本番運用で埋めるべき機能ギャップまで、すべてを解説します。
Claude Code Agent SDK とは？
Claude Code Agent SDK は、Claude Agent SDK や Claude Code SDK とも呼ばれ、Claude を搭載した自律型 AI エージェントを構築するための Anthropic の Python および TypeScript ライブラリです。Claude Code CLI を支えるのと同じエージェントループ、ツールシステム、サンドボックス実行環境をラップし、それを自分のコードから呼び出せる SDK として提供します。
この SDK は、AI エージェントを単なる対話型ではなく、プログラム可能にするという Anthropic の 2026 年初頭の取り組みの一環として公開されました。
Claude API を直接使う場合との違い
| 機能 | Claude API | Claude Agent SDK |
|---|---|---|
| エージェントループ | 自分で構築 | 内蔵: 計画 → 実行 → 観測 → 繰り返し |
| ファイルシステムアクセス | なし | ファイルの読み取り、書き込み、編集 |
| シェル実行 | なし | サンドボックス内で Bash コマンドを実行 |
| ツール呼び出し | 手動で関数定義 | 内蔵ツール + MCP サーバー対応 |
| サブエージェント | 利用不可 | 並列エージェントワーカーを起動 |
| コンテキスト管理 | 手動 | 自動圧縮と要約 |
現在 Claude API を使っていて、手動のツール処理を伴うエージェントループを自前実装しているなら、Agent SDK は何百行ものボイラープレートを置き換えます。
インストールとセットアップ
前提条件
- Python 3.10+ または TypeScript/Node.js 20+
- Anthropic API キー または Claude Code Pro/Max/Enterprise サブスクリプション
- Claude Code CLI のインストール済み環境。SDK はこれをランタイムとして使います
ステップ 1: Claude Code CLI をインストール
npm install -g @anthropic-ai/claude-code
または claude.ai/download のネイティブインストーラーを使ってください。
ステップ 2: Agent SDK をインストール
Python:
pip install claude-agent-sdk
TypeScript:
npm install @anthropic-ai/claude-agent-sdk
ステップ 3: 認証する
claude login
OAuth フローに従ってください。API キーはローカルに保存され、SDK が自動で利用します。
最初のエージェント: バグ発見器
以下は、ディレクトリ内のバグをスキャンする最小構成の Python エージェントです。
from claude_agent_sdk import Agent, tool
@tool
def read_file(path: str) -> str:
"""ファイルを読み取り、その内容を返します。"""
with open(path, 'r') as f:
return f.read()
@tool
def list_files(directory: str = ".") -> list:
"""ディレクトリ内のすべてのファイルを一覧表示します。"""
import os
return os.listdir(directory)
agent = Agent(
system_prompt="あなたはコードレビュアーです。バグを見つけ、修正案を提案してください。",
tools=[read_file, list_files],
model="claude-sonnet-4-20250514"
)
result = agent.run("./src のコードをセキュリティ問題の観点でレビューしてください")
print(result.output)
内部で何が起きているか
- エージェントがタスクを受け取り、システムプロンプトを読みます
- コードベースを把握するために
list_files("./src")を呼び出します - 各ソースファイルに対して
read_file(path)を呼び出します - Claude の推論能力でコードを分析します
- 行番号と修正提案を含む結果を返します
SDK がループ全体を処理するので、plan-act-observe のロジックを自分で書く必要はありません。
コア概念
エージェントループ
タスク → 計画 → ツール呼び出し → 結果を観測 → 再計画 → ... → 最終回答
各イテレーションで:
- Claude が次に何をするかを決める
- 必要に応じてツールを呼び出す
- ツール出力を受け取る
- 続行するか終了するかを判断する
SDK は、古いターンを要約する圧縮処理とサブエージェント委譲により、コンテキストウィンドウの制限を自動で管理します。
ツールと tool デコレータ
ツールは、エージェントに公開する関数です。SDK にはいくつかの内蔵ツールがあります。
# 内蔵のファイル操作。自動で利用可能
agent = Agent(
tools=["read", "write", "edit", "glob", "grep", "bash", "task"]
)
カスタムツールは @tool デコレータを使います。
from claude_agent_sdk import tool
@tool
def search_docs(query: str, max_results: int = 5) -> str:
"""指定したクエリで社内ドキュメントを検索します。"""
# 検索の実装
return results
agent = Agent(tools=[search_docs])
サブエージェント: 並列処理
サブエージェントを使うと、独立した Claude インスタンスを並列作業用に起動できます。
agent = Agent(
system_prompt="あなたはコードベースをレビューするテックリードです。",
tools=["task"] # サブエージェント起動を有効化
)
result = agent.run("""
./frontend/ と ./backend/ を並列でレビューしてください。
各ディレクトリにサブエージェントを使い、その後で結果をまとめてください。
""")
サブエージェントは分離されたコンテキストで実行され、独立して結果を返します。これが Claude Code 自体の大規模操作の扱い方です。
MCP サーバー連携
SDK は Model Context Protocol サーバー、つまりエージェントにツールを提供する外部サービスをサポートします。
agent = Agent(
mcp_servers=[
{
"command": "npx",
"args": ["-y", "@anthropic-ai/mcp-server-filesystem"],
"env": {"ALLOWED_DIRECTORIES": "/project"}
}
]
)
MCP サーバーは、データベースアクセス、API 連携、サードパーティサービスなどを追加できます。
Agent SDK でできないことと、そのギャップの埋め方
Claude Code Agent SDK は、エージェントにファイルアクセス、シェル実行、コード操作を提供します。ですが、5 つの大きな機能ギャップがあります。
1. 画像生成
エージェントは画像 API を呼ぶコードを書くことはできますが、画像を直接生成したり見ることはできません。UI を作る、デザインを試作する、ドキュメントを作成するエージェントにとって、これは実際の制約です。
解決策: 画像生成を扱う機能ランタイムをエージェントに与えてください。設定を 1 行加えるだけで、テキストから画像を生成し、デザインを反復し、結果を埋め込めます。
2. 動画生成
動画はさらに手が届きません。エージェントは ffmpeg コマンドを書くことはできますが、新しい動画コンテンツを生成することはできません。
3. 根拠付きのウェブ検索
Claude Code エージェントは curl や fetch API を使えますが、根拠や引用付きの意味論的なウェブ検索はできません。これは、リサーチエージェント、コンテンツエージェント、最新情報を必要とするワークフローで重要です。
4. クラウドストレージとファイル共有
SDK のファイルシステムアクセスはローカルのみです。成果物を保存する、人間とファイルを共有する、セッションをまたいでデータを保持する必要があるなら、クラウドストレージが必要です。
5. 公開とデプロイ
エージェントが成果物を作れても、それをオンラインに公開するには、ウェブページ、共有可能なレポート、デプロイ済みアプリなど、別のインフラが必要です。
ワンコマンドの解決策
5 つの別々の MCP サーバーを、それぞれ独自の API キー、保守負担、トークンオーバーヘッド付きで設定する代わりに、画像生成、動画、ウェブ検索、クラウドストレージ、公開を 1 つのエンドポイントにまとめた 機能ランタイム を使えます。
たとえば AnyCap は、画像生成、動画、ウェブ検索、クラウドストレージ、ページ公開という 5 つの機能を 1 つの CLI で提供するため、設定にかかる時間は数時間ではなく数分で済みます。
本番運用での考慮事項
コンテキストウィンドウ管理
Agent SDK はコンテキスト圧縮を自動で処理しますが、100 ターン以上続く長時間稼働のエージェントでは、次を推奨します。
- サブエージェントを使う 大きな並列タスクでは、順次処理よりもサブエージェントを使う
- システムプロンプトを簡潔に保つ システムプロンプト内の各トークンは毎ターンのオーバーヘッドになる
- 大きなファイルをコンテキストに読み込まない ツールが要約を返せるならその方がよい
コスト管理
SDK を使った典型的なエージェントセッションのコストは、タスクの複雑さに応じて 0.50 ドルから 3.00 ドル程度です。コストを抑えるには:
max_turnsを設定して暴走ループを防ぐ- 単純なサブエージェントには Haiku、メインエージェントには Sonnet を使う
- Anthropic のコンソールダッシュボードで使用量を監視する
セキュリティ
SDK はコマンドをサンドボックス内で実行しますが、それでも次は守るべきです。
ALLOWED_DIRECTORIESでファイルシステムアクセスを制限する- 本番エージェントに認証情報や
.envファイルへのアクセスを与えない - 非対話モードではエージェントの動作を確認する
Claude Code SDK と Claude Agent SDK: 違いは何か？
これらの用語はしばしば同じ意味で使われますが、区別があります。
| Claude Code SDK | Claude Agent SDK | |
|---|---|---|
| 範囲 | Claude Code とやり取りするための低レベル API | より高レベルなエージェントフレームワーク |
| Python パッケージ | claude-agent-sdk の一部 |
主なインターフェースは claude-agent-sdk |
| ユースケース | Claude Code セッションのプログラム制御 | 自律エージェントの構築 |
| ドキュメント | code.claude.com/docs/en/agent-sdk | code.claude.com/docs/en/agent-sdk/overview |
実際には、ほとんどの開発者が Agent SDK を入口として使います。低レベルの SDK API は、カスタムセッション管理のような高度な用途向けです。
Claude Code CLI ではなく Agent SDK を使うべき場面
| シナリオ | 使うもの |
|---|---|
| 対話型コーディングセッション | Claude Code CLI |
| 単発のコードレビュー | Claude Code CLI |
| 自動化された PR レビューパイプライン | Agent SDK |
| 定期実行のデータ処理 | Agent SDK |
| CI/CD 連携 | Agent SDK |
| 多段階のリサーチエージェント | Agent SDK |
| Claude の上に製品を作る | Agent SDK |
目安はシンプルです。コマンドを打つなら CLI。Claude を呼び出すコードを書くなら SDK です。
まとめ
Claude Code Agent SDK は、Claude をターミナルの相棒からプログラム可能なエージェントランタイムへと変えます。内蔵のファイル操作、シェルアクセス、サブエージェントのオーケストレーション、MCP サーバー対応により、エージェント基盤の重い部分を担います。
ただし、ファイルを読むだけで bash を実行するだけのエージェントは、半分しか完成していません。ウェブ検索、画像や動画の生成、成果物のクラウド保存、結果の公開までできるエージェントを作るには、機能レイヤーが必要です。SDK はエージェントに頭脳を与え、AnyCap のような機能ランタイムは目、手、そして声を与えます。