Anthropic API の messages.create を直叩きするのと何が違う?

Agent SDK は (1) tool use の往復ループ、(2) tool error のハンドリング、(3) コンテキスト管理、(4) MCP 統合、(5) ロギングを標準提供します。直叩きでもこれらは実装可能ですが、SDK は best practice をデフォルトで持つので、最初から本番品質に近いコードが書けます。

LangChain と LangGraph と何が違う?

LangChain は OpenAI / Anthropic / Cohere など多モデル対応の抽象化レイヤ、LangGraph はマルチエージェント / ワークフロー設計用 DSL です。Claude Agent SDK は Claude 専用に最適化されており、Claude の prompt caching / extended thinking / vision をフルに使えます。マルチモデル対応が必要なら LangChain、Claude 中心なら Agent SDK が手数が少ないです。

本番運用で一番ハマるのは?

タイムアウトとコストです。ツール呼出を含む対話ループは 30-60 秒かかることもあり、HTTP リクエストの timeout 設定で切れる事故が多いです。また、Claude Sonnet でも 1 セッション $0.1-$1 になるため、月額予算と max_iterations の組合せで上限を設定するのが必須です。

MCP と組み合わせるメリットは?

MCP サーバーを作れば、その tool は Claude Code / Claude Desktop / Agent SDK 全てから等しく使えます。Agent SDK 内で fn として書くと再利用性がなくなるため、社内ツールは MCP として実装、Agent SDK は MCP サーバーを呼ぶだけ、というアーキテクチャがクリーンです。

extended thinking はいつ有効化すべき?

数学・複雑なロジック・多段推論が必要なときだけ。タスク決定や実装量産では逆に遅くなります。コスト的にも extended thinking は通常 3-5 倍かかるので、user-facing なエージェントでは原則無効、バックグラウンドの分析ジョブでは有効、と使い分けると効率的です。

ツール呼出のセキュリティで一番大事なのは?

(1) ツール側で認証情報を保持し Agent に渡さない (MCP と同じ原則)、(2) write 系操作は dry-run モードを実装、(3) 呼出ログを必ず取る、(4) 削除系 / 課金系 / 認証系の tool は確認プロンプトを挟む、の 4 点。Claude が暴走するより、Tool の実装ミスで暴走する方が現実には多いです。

実装力を効率的に身につけるには?

公式ドキュメント (docs.claude.com) で概念を読む → 自分で 30 行 Hello Agent → 簡単な Tool を 1 つ実装 → MCP 接続 → 本番ループ制御、の順で手を動かすのが効率的です。本サイトのバイブコーディング実践編に Agent SDK の章があり、提出物テンプレ + 採点ルーブリック付きの演習で定着できます。

Claude Agent SDK 入門｜AI エージェントを業務システムに組み込む実装ガイド

公開: 2026-05-09

この記事でわかること

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 の組み合わせを 10 章 46 レッスンで解説しています (有料 Pro プラン)。LP 公開前のため近日中の公開予定。先に試したい場合はバイブコーディング実践編で MCP の章を 4 週間限定無料で受講できます。

まとめ

Claude Agent SDK は Claude 専用に Tool ループ / MCP / ロギングを標準化
30 行で動く Hello Agent、defineTool で関数を tool 化
社内ツールは MCP サーバーで実装、Agent SDK から接続が再利用性高い
LangChain は多モデル対応、LangGraph は複雑ワークフロー、Agent SDK は Claude 専用最短
本番運用は timeout / コスト上限 / maxIterations / ロギング / prompt caching の 5 点を必ず設定