Claude Code Agent SDKは、プログラム可能なエージェントループを提供します。これが良いニュースです。
より重要なのは、SDKが提供しないものです。
SDKは、ほとんどの本番ワークフローが必要とする現実世界のケイパビリティ層、つまりライブ検索・画像生成・動画生成・アーティファクトストレージ・公開機能を提供しません。SDKが与えるのはシェルとオーケストレーション層です。より強力なエージェントを求めるなら、その背後にあるランタイムも必要です。
この違いが重要なのは、SDK解説記事の多くが「エージェントの起動方法」で止まってしまうからです。本番チームが気にするのは次の問いです：そのエージェントは本当に仕事を完遂できるのか？
このガイドでは両面を取り上げます。Claude Code Agent SDKが得意とすること、そしてエージェントがファイルの読み書きやbash実行以上のことをする必要があるときに、AnyCap のようなケイパビリティランタイムがどこで活躍するかを解説します。
Claude Code Agent SDKとは？
Claude Code Agent SDKは、Anthropicが提供するPythonおよびTypeScriptのツールキットで、Claude Codeスタイルのエージェント動作を自社アプリケーションに組み込むためのものです。
次のように考えてください：
- Claudeモデル = 推論
- Agent SDK = プログラム可能なエージェントループ
- ケイパビリティランタイム = メディア・検索・ストレージ・公開のための欠けた実行層
SDKは、これまで自分で構築しなければならなかったコアなオーケストレーション作業を担います：
- 計画と反復的な実行
- ファイルアクセスと編集
- シェル実行
- ツール呼び出し
- MCPインテグレーション
- サブエージェントパターン
これだけで多くのカスタム接続コードを置き換えられます。ただし、本番スタック全体のほんの一部にすぎません。
素のClaude APIとの違い
| 機能 | Claude API | Claude Code Agent SDK |
|---|---|---|
| エージェントループ | 自分で構築 | 組み込み済み |
| ファイルアクセス | なし | 付属 |
| シェル実行 | なし | 付属 |
| ツールオーケストレーション | 手動 | 付属 |
| MCPサポート | 手動 | 付属 |
| サブエージェントパターン | 手動 | 実装が容易 |
コードレビューワーカー・CI自動化・リポジトリアシスタントを構築しているなら、SDKはループを手動で組むよりも大きな進歩です。
ただし、その境界を理解しておくべきです。ツールインターフェースを持っているだけで、完全なケイパビリティランタイムに魔法のようになるわけではありません。
インストールとセットアップ
前提条件
- Python 3.10+ または Node.js 20+
- Anthropic APIキー またはClaude Codeアクセス
- ランタイムサーフェスとして Claude Code CLI がインストール済みであること
Claude Code CLIのインストール
npm install -g @anthropic-ai/claude-code
Agent SDKのインストール
Python
pip install claude-agent-sdk
TypeScript
npm install @anthropic-ai/claude-agent-sdk
認証
claude login
はじめてのエージェント
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="You are a careful code reviewer.",
tools=[read_file, list_files],
model="claude-sonnet-4-20250514"
)
result = agent.run("Review ./src for security issues")
print(result.output)
ここがSDKの真骨頂です。ツールを定義してタスクを渡せば、エージェントループが探索と反復を担当します。
コアコンセプト
1. エージェントループ
Task → Plan → Tool Call → Observe → Re-plan → Final Answer
このループがSDKの本質的な価値です。毎回の処理を手動で配線する必要をなくします。
2. サブエージェント
サブエージェントを使えば、一つの長いコンテキストに詰め込まず、作業を分割できます。
agent = Agent(
system_prompt="You are a tech lead reviewing a codebase.",
tools=["task"]
)
並列ディレクトリレビュー・分割調査・大規模コードベースに活用できます。
3. MCPサポート
SDKはMCP互換ツールと通信でき、内部API・データベース・専門サービスに役立ちます。
agent = Agent(
mcp_servers=[
{
"command": "npx",
"args": ["-y", "@anthropic-ai/mcp-server-filesystem"],
"env": {"ALLOWED_DIRECTORIES": "/project"}
}
]
)
ただし、多くのガイドが見落とすニュアンスがあります：MCPはプロトコル層であり、ケイパビリティ戦略の全体ではありません。 エージェントがより幅広いクロスファンクショナルなツールサーフェスを必要とする場合は、関連性のない5つの個別インテグレーションではなく、ケイパビリティランタイムを選ぶべきです。
本番運用での考慮事項
コスト管理
ルーティンな作業には低コストのモデルを使用し、max_turnsを設定し、大規模な並列作業は肥大化したセッションではなくサブエージェントに委ねましょう。
コンテキスト管理
プロンプトを簡潔に保ち、不要なファイルの読み込みを避け、セッションが長くなった場合は中間結果を要約しましょう。
権限
エージェントのファイルアクセスと外部インテグレーションを、必要最小限のスコープに制限してください。
よくあるエラーと対処法
OverloadedError
指数バックオフでリトライしてください。
import time
from claude_agent_sdk import OverloadedError
def run_with_retry(agent, prompt, max_retries=3):
for attempt in range(max_retries):
try:
return agent.run(prompt)
except OverloadedError:
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt)
ContextLengthExceededError
作業をサブタスクに分割し、一枚岩的な実行ではなくサブエージェントを使いましょう。
MaxTurnsReached
タスクが明確に範囲限定されている場合のみ max_turns を増やしてください。そうでなければ、ワークフローを分解してください。
権限エラー
エージェントが実際に必要とするディレクトリとインテグレーションのみを展開してください。
Agent SDKがまだ提供しないもの
これが本番ワークフローで最も重要な部分です。
Claude Code Agent SDKができること：
- ファイルの読み書き
- シェルコマンドの実行
- ツール呼び出しのオーケストレーション
- 反復的なエージェントループの管理
SDKが単独では提供しない、欠けたケイパビリティ層：
- ライブWeb検索
- AI画像生成
- 動画生成
- クラウドストレージと共有
- Web公開
これが、多くのチームがデモでは印象的でも実運用では不完全なエージェントを抱える理由です。エージェントはローンチページについて美しく推論できますが、追加インフラなしにはヒーロー画像の生成・最終アーティファクトの保存・成果物の公開ができません。
AnyCap が果たす役割
AnyCap は、Claudeベースのエージェントが経由して実行できるケイパビリティランタイムとして理解するのが最も適切です。
層を分離すると、アーキテクチャはよりシンプルになります：
- Claudeモデル → 考える
- Claude Code Agent SDK → オーケストレーション
- AnyCap CLI → クロスファンクショナルなケイパビリティの実行
- AnyCap skill → CLIの効果的な使い方をエージェントに教える
ケイパビリティランタイムのインストール
curl -fsSL https://anycap.ai/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
anycap login
スキル層の追加
npx -y skills add anycap-ai/anycap -a claude-code
これにより、エージェントは以下のような一貫したケイパビリティサーフェスを使用できます：
anycap search "latest competitor pricing"
anycap image generate "product hero image"
anycap video generate "10-second launch teaser"
anycap drive upload ./report.pdf
anycap page publish ./launch-brief.md
「エージェントループを構築した」と「仕事を実際に完遂できるエージェントを構築した」の違いがそこにあります。
Agent SDKを使うべきタイミング
次のものが必要な場合にAgent SDKを使用してください：
- 製品または自動化内のプログラムによるエージェント
- 再現可能なコードレビューワーカー
- CI/CD内のリポジトリアシスタント
- 反復的なエージェントループが必要なバックグラウンドタスク
エージェントが調査・メディア生成・ファイル配信・出力公開も必要な場合は、ケイパビリティランタイムを並行して使用してください。
まとめ
Claude Code Agent SDKは、オーケストレーション問題を解決するという点で強力です。開発者がゼロから構築することを強いる代わりに、Claude Codeのループのプログラム可能なバージョンを提供します。
ただし、これはあくまでもシェルと調整層にすぎません。
エージェントが現実世界と関わる必要がある場合、つまり最新情報の検索・クリエイティブアセットの生成・出力の保存・結果の公開が必要な場合は、欠けたケイパビリティ層も必要です。
これが、SDKが単独でできることをチームが過大評価しないための思考モデルです。
SDKはエージェントをプログラム可能にします。
ケイパビリティランタイムは、エージェントをコードを超えて役立つものにします。
次に読むべき記事
- Claude Codeチュートリアル：ゼロから最初のセッションまで（2026） — 完全なセットアップガイド、CLAUDE.md設定、AnyCap統合
- Claude CodeでAI画像を生成する方法（2026） — Claude CodeエージェントにAI画像生成を追加する
- Claude Code Web検索の修正：4つの解決策 — 権限エラーと「Did 0 searches」バグを修正する
- なぜClaude Codeは実際のワークフローにWeb検索が必要なのか — コーディングエージェントにライブWebアクセスが必要な理由
- ターミナルエージェント比較：Claude Code vs Codex vs Windsurf — 主要なターミナルネイティブAIコーディングエージェントを比較