なぜ Agent SDK か
- 年に入り、Anthropic は Claude Agent SDK（旧 Claude Code SDK）を正式に「エージェント基盤」として位置付け直した。`@anthropic-ai/agent-sdk` (TS) と `anthropic-agent` (Python) の両言語で提供され、subagent / tool / hook / MCP の 4 概念で構築する。Claude Code が内部的に使っているのと同じ仕組みを、自社プロダクトに組み込めるのが要点である。
ベース構成
```ts import { query } from "@anthropic-ai/agent-sdk";
const result = await query({ prompt: "顧客の最新請求を要約して", model: "claude-opus-4-7", systemPrompt: "あなたは経理アシスタント。日本語で答えること。", mcpServers: { db: { command: "node", args: ["./mcp/db-readonly.js"] } }, hooks: { PreToolUse: ["./hooks/audit.sh"], Stop: ["./hooks/notify-slack.sh"] } }); ```
Subagent 分割
主エージェント（プランナー）と子エージェント（実装担当）を分けると、コンテキスト汚染を防ぎつつ並列性を出せる。子エージェントは独立したコンテキストで起動するため、トークン使用量も予測しやすい。社内 R&D ではコードレビュー系のエージェントを「セキュリティ」「パフォーマンス」「保守性」の 3 並列に分けて統合する構成で安定運用している。
Hook の使い方
PreToolUse, PostToolUse, Stop, Notification, UserPromptSubmit などのライフサイクルフックがある。本番運用では:
- PreToolUse: 監査ログ記録、危険なコマンドの拒否
- PostToolUse: 出力ファイルの自動 lint / format
- Stop: 未完了タスクの検出（get-shit-done パターン）
- Notification: Slack 通知（許可待ちなど）
MCP の役割
社内 DB、社内ナレッジ、特定 SaaS への接続を MCP サーバとして外出しすることで、エージェント本体は薄く保てる。MCP サーバは別プロセスのため、再起動・差し替えが容易で、複数エージェントから共有もできる。
ガードレール
- Tool 単位の allowlist
- 出力前の Llama Guard 3 / Claude Guard でのフィルタ
- ツール呼び出し回数の上限と暴走検出
- センシティブなツール（DB 書き込み、メール送信）はヒト承認をフックでブロッキング
観測
OpenTelemetry の `agent.run`、`agent.tool_call`、`agent.subagent` という 3 種の span をデフォルトで吐かせ、Langfuse / Honeycomb で可視化。失敗パターンの統計が取りやすくなる。
まとめ
Claude Agent SDK は「Claude Code の中身を自社プロダクトに移植する」ことを楽にする SDK で、subagent + hook + MCP の組み合わせが本番運用の安定性を決める。テンプレ的な構成を社内で標準化し、各案件はそれをカスタマイズする方針が早い立ち上げにつながる。