Claude Agent SDK 入門|AI エージェントを業務システムに組み込む実装ガイド
この記事でわかること
- Claude Agent SDK が解決する問題: Anthropic API 直叩き / LangChain と何が違うか
- 最小実装: 30 行で動く CLI Agent (TypeScript / Python)
- Tool Use と MCP の組み合わせ方: 自社ツールを Agent に持たせる手順
- 本番運用での注意: タイムアウト・コスト・無限ループ対策
- 似た仕組み (LangGraph, Semantic Kernel) との設計思想の違い
なぜ Claude Agent SDK が必要だったのか
Claude を「エージェント」(自律的にツールを使ってタスクを完遂する AI) として動かすには、Anthropic API の messages.create を 何度も往復 する必要があります。具体的には:
- ユーザー質問を投げる
- Claude が「Tool X を使いたい」と返す
- Tool X を実行して結果を得る
- 結果を Claude に渡す
- Claude が次の Tool または最終回答を返す
- 4-5 を繰り返す
この ループ・ツール定義・エラーハンドリング・コンテキスト管理・無限ループ防止 を全て自分で書くのは大変。Anthropic は 2025-26 年に Claude Agent SDK をリリースし、これを SDK 標準で提供するようにしました。
30 行 Hello Agent (TypeScript)
npm i @anthropic-ai/agent-sdk
import { Agent, defineTool } from "@anthropic-ai/agent-sdk";
const calc = defineTool({
name: "calculator",
description: "数式を計算する。例: 2 + 2 * 3",
inputSchema: {
type: "object",
properties: { expr: { type: "string" } },
required: ["expr"],
},
execute: async ({ expr }) => ({ result: eval(expr) }), // demo only
});
const agent = new Agent({
model: "claude-sonnet-4-6",
systemPrompt: "あなたは計算アシスタント。calculator tool を使って答える。",
tools: [calc],
maxIterations: 5,
});
const response = await agent.run("100 + 200 * 3 はいくつ?");
console.log(response.finalText);
これで動くエージェントが完成。agent.run() 内部で:
- messages.create で Claude に質問送信
- Claude が「calculator を使う」と返す
- SDK が calc.execute を自動呼出
- 結果を Claude に返す
- Claude が「答えは 700 です」と返す
- 終了
Tool Use と MCP の組み合わせ
局所 tool は SDK の defineTool
シンプルな関数 (上記 calculator のような) は SDK 内で defineTool するのが早い。
社内ツールは MCP として実装
社内 DB / Slack / GitHub などは MCP サーバーとして書いて、Agent SDK から接続するのが再利用性高い設計です:
import { Agent, addMcpServer } from "@anthropic-ai/agent-sdk";
const agent = new Agent({
model: "claude-sonnet-4-6",
systemPrompt: "あなたは社内データ分析アシスタント。",
mcpServers: [
{
name: "company-db",
command: "npx",
args: ["tsx", "/srv/mcp/company-db-server.ts"],
},
{
name: "slack",
command: "npx",
args: ["-y", "@modelcontextprotocol/server-slack"],
env: { SLACK_BOT_TOKEN: process.env.SLACK_TOKEN! },
},
],
maxIterations: 10,
});
await agent.run("先週の売上を集計して #sales-report に投稿して");
MCP 入門 で MCP サーバー実装を扱っています。Agent SDK と組み合わせて初めて Agent SDK の真価が出ます。
LangChain / LangGraph との違い
| 観点 | Anthropic API 直叩き | Claude Agent SDK | LangChain | LangGraph |
|---|---|---|---|---|
| ベンダー | Claude 専用 | Claude 専用 | マルチモデル | LangChain 系 |
| Tool ループ | 自前実装 | 標準提供 | 抽象化あり | DAG / state machine |
| MCP 統合 | 自前 | 標準 | コミュニティ拡張 | コミュニティ拡張 |
| Prompt Caching | 自前で TTL 管理 | SDK 自動 | 一部対応 | 対応 |
| 複雑なワークフロー | 自前 | maxIterations のみ | チェーン | グラフ DSL |
| マルチエージェント | 自前 | 単純な並列はあり | サブエージェント | 標準サポート |
選び方の指針:
- Claude 中心 + シンプルな tool 利用: Agent SDK が最短
- 複数モデル混在 (Claude + GPT + Gemini): LangChain
- 複雑なワークフロー (条件分岐・人間レビュー挟む): LangGraph
- 本格的なマルチエージェント協調: LangGraph or 自前
本番運用の落とし穴
1. タイムアウト
Tool 呼出を含む 1 ループは 5-15 秒、最大 60 秒以上になることも。HTTP API として公開するなら fastify / express の timeout を 120s 以上 に設定。Cloudflare Workers (30s 制限) には収まらないので注意。
2. コスト
Claude Sonnet で 1 セッション $0.1-$1。社内エージェントなら問題ないが、エンドユーザー向けに開放するなら maxIterations + max_tokens で上限管理 が必須。月額予算 ÷ 想定セッション数 で 1 セッションの予算を逆算するのが定石。
3. 無限ループ
maxIterations を必ず設定 (デフォルト 10 だが、本番は 5-7 に絞ることが多い)。Tool が常に同じ結果を返すと Claude が「もう一回 Tool を使う」を繰り返します。Tool 結果に「変わらないよ」シグナルを返す設計も併用。
4. ロギング
各ループの user / assistant / tool_use / tool_result を全て記録。本番障害時の調査に必須。SDK には built-in logger があるが、構造化ログ (JSON) で外部に流すのが推奨。
5. プロンプトキャッシュ
enablePromptCaching: true でシステムプロンプト + tool 定義をキャッシュ。同じ Agent を多数のリクエストで使うなら 50-90% コスト削減。
どこから手を動かすか
公式チュートリアル (docs.claude.com/agent-sdk) で概念を読む → 30 行 Hello Agent → 簡単な Tool 1 つ → MCP 接続 → ループ制御、の順で手を動かすのが効率的。
次の手を動かす: 本サイトの AIエージェント活用実践編 で Claude Agent SDK + MCP の公開カリキュラムを確認できます。無料マークの付いた教材は登録なしで閲覧でき、学習記録の保存・演習の提出にはGoogleログインが必要です。プランの提供状況は 料金ページ で確認してください。 先に試したい場合は バイブコーディング実践編 全 40 レッスンを無料受講できます。
関連ガイド:
- MCP 入門 — Agent SDK と組み合わせる Model Context Protocol
- Claude Code 入門 — Agent SDK と Claude Code の使い分け
- Claude Code チュートリアル — 5 つの実例タスク
- バイブコーディングとは — AI ペアプロの基礎
- Claude Code vs Cursor 比較 — Agent SDK 周辺ツールの比較
- Claude Code vs GitHub Copilot 比較 — Copilot Workspace との対比
- Claude Code セキュリティガイド — Agent 本番運用のセキュリティ統制
- Anthropic Academy と AI研修 LMS の比較 — 公式講座と日本語演習の選び方
まとめ
- Claude Agent SDK は Claude 専用に Tool ループ / MCP / ロギングを標準化
- 30 行で動く Hello Agent、defineTool で関数を tool 化
- 社内ツールは MCP サーバーで実装、Agent SDK から接続が再利用性高い
- LangChain は多モデル対応、LangGraph は複雑ワークフロー、Agent SDK は Claude 専用最短
- 本番運用は timeout / コスト上限 / maxIterations / ロギング / prompt caching の 5 点を必ず設定
関連するガイド
- Claude Code 入門|公式ドキュメントには載っていない実務の使い方【2026年版】Claude Code の始め方を、CLI のインストールからプロジェクトへの導入、安全な使い方、レビュー文化との折り合い、有料プラン課金タイ…
- Claude Code チュートリアル|最初の 1 時間で実務に効く 5 タスク【2026年版】Claude Code を実際のリポジトリに入れて、最初の 1 時間で何ができるかを 5 つの実例タスクで解説。バグ修正・テスト追加・リファク…
- MCP (Model Context Protocol) 入門|Claude を社内ツールに繋ぐ実践ガイドAnthropic が提唱する MCP (Model Context Protocol) を、設計思想・実装手順・社内ツール連携の実例で解説。…
- Claude Code vs Cursor 徹底比較|実務で 6ヶ月使った判断軸【2026年版】Claude Code (CLI) と Cursor (エディタ) を、対話粒度・速度・料金・安全性・組織導入の 5 軸で実機比較。両方を半年…
- Claude Code vs GitHub Copilot 徹底比較|2026年の使い分け実践ガイドClaude Code と GitHub Copilot の違いを、対話粒度・補完速度・タスク完遂力・組織導入・コストの 5 軸で実機比較。C…
- Claude Code セキュリティガイド|法人の社内導入ガードレール5項目と規約テンプレ【2026年版】Claude Code を法人で社内導入する際の「最低限のガードレール5項目」を、(1) ファイルアクセス、(2) コマンド実行、(3) 認証…
関連する AI 研修コース・事例
このガイドで解説した内容を、提出物・採点ルーブリック付きの実装演習で 実務レベルまで定着させるためのコースと、国内外の AI 活用事例を見るための入口です。
- バイブコーディング実践編 (vibe_practice)Claude Code を業務コードに使うときの安全設定・許可コマンド・ ログ管理を、提出物付き40レッスンで学習。現在の無料公開教材は登録なしで閲覧できます。
- AIエージェント活用実践編 (agent_practice)Claude Agent SDK と MCP で AI を働かせる実装演習。 Claude Code に慣れた次のステップ。
- サイバーセキュリティ基礎 (cybersec_basic)AI を業務に取り入れる際の社内ガードレール・情報統制と一緒に学ぶ 実務者向けセキュリティ 40 レッスン。
- AI 活用事例集KDDI・SAP・freee・メルカリ等、国内外の企業 AI 導入実例を業種別に確認。
- AI研修 コース一覧一般社員・経営者・実装担当の目的に合わせて、無料範囲と公開状態を確認。