Claude Agent SDK入門: Claude Codeをアプリに組み込む実装パターン

Claude Codeを「ターミナルで相談する道具」から、社内ツールやCIに組み込む実行基盤へ広げたいなら、見るべき対象は現在の Claude Agent SDK です。

以前のサンプルでは @anthropic-ai/claude-code や Claude Code SDK という名前で説明されている記事もあります。しかし2026年6月時点の公式ドキュメントでは、TypeScriptは @anthropic-ai/claude-agent-sdk、Pythonは claude-agent-sdk が案内されています。公式のAgent SDK overviewとMigration Guideを基準に、古い記事や生成AIの回答をそのまま信じないほうが安全です。

この記事では、Claude Agent SDKを使って「ファイルを読む、検索する、必要なら編集する、テストを走らせる、結果を返す」エージェントを実務で作る手順を整理します。単なるAPI呼び出しではなく、権限、作業ディレクトリ、MCP、コスト、失敗時の止め方まで含めて設計するのがポイントです。

まず何が変わったのか

Claude Agent SDKは、Claude Codeのエージェントループをアプリケーションから使うためのSDKです。エージェントループとは、モデルが「次にどの道具を使うか」を判断し、ファイル読取、検索、編集、コマンド実行などの結果を見ながら複数ステップで目的に近づく流れです。

公式ドキュメント上の大事な現在地は次の通りです。

観点	現在の実務判断
TypeScriptパッケージ	@anthropic-ai/claude-agent-sdk を使う
Pythonパッケージ	claude-agent-sdk を使う
CLIとの違い	CLIは人が対話する入口、SDKは自分のアプリやCIから呼ぶ入口
Client SDKとの違い	Client SDKはツール実行ループを自前実装、Agent SDKはClaude Codeの組み込みツールとループを使う
注意点	権限を広げるほど便利だが、誤編集や危険なBashも起きやすい

TypeScript SDKはプラットフォーム別のClaude Codeバイナリをオプション依存として含むため、通常はClaude Code CLIを別途入れなくても動きます。ただし、パッケージマネージャがoptional dependenciesを飛ばす設定だと、ネイティブバイナリが見つからないエラーになります。この場合は依存の入れ方を見直すか、別途インストールした claude のパスを pathToClaudeCodeExecutable に渡します。

セットアップ: 最小構成をコピペで作る

まずはNode.jsのプロジェクトとして作ります。ここではTypeScriptで、tsx を使ってすぐ実行できる形にします。

mkdir claude-agent-sdk-demo
cd claude-agent-sdk-demo
npm init -y
npm install @anthropic-ai/claude-agent-sdk zod
npm install -D typescript tsx @types/node

package.json を次のように整えます。

{
  "type": "module",
  "scripts": {
    "audit": "tsx src/read-only-audit.ts",
    "runbook": "tsx src/runbook-agent.ts",
    "fix": "tsx src/safe-fix.ts"
  },
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "latest",
    "zod": "latest"
  },
  "devDependencies": {
    "@types/node": "latest",
    "tsx": "latest",
    "typescript": "latest"
  }
}

APIキーは環境変数で渡します。記事やリポジトリに直書きしないでください。

export ANTHROPIC_API_KEY="sk-ant-..."

Windows PowerShellなら次の形です。

$env:ANTHROPIC_API_KEY = "sk-ant-..."

最初の確認用に src/read-only-audit.ts を作ります。allowedTools を Read、Glob、Grep に絞っているので、ファイル編集やBash実行はしません。

import { query } from "@anthropic-ai/claude-agent-sdk";

const prompt = [
  "このリポジトリを読み取り専用で確認してください。",
  "TODOコメント、古い依存、テストが薄い箇所を探し、",
  "優先度順に箇条書きで返してください。",
].join("\n");

for await (const message of query({
  prompt,
  options: {
    cwd: process.cwd(),
    allowedTools: ["Read", "Glob", "Grep"],
    maxTurns: 4,
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

実行します。

npm run audit

この段階で重要なのは「まず読み取り専用で動かす」ことです。最初から Bash や Edit を許可すると、便利さの前にリスクが見えなくなります。

実務で効く3つ以上のユースケース

Claude Agent SDKは、単発の文章生成よりも「途中で観察し、判断し、結果を確認する」仕事に向いています。Masaが記事運用と開発ワークフローに当てはめるなら、次の4つが特に現実的です。

ユースケース	使うツール	成果物	注意点
PRレビュー前の下読み	Read, Glob, Grep	リスク一覧、確認観点、追加テスト案	コメント投稿は人間確認後にする
小さな修正の自動化	Read, Edit, Bash(npm test)	差分、テスト結果、失敗時ログ	git push や削除系コマンドは禁止
障害対応の一次調査	MCPのRunbook、ログ検索ツール	仮説、関連ログ、次の確認	本番操作ツールは読み取り専用にする
多言語記事の品質監査	Read, Grep	文字化け、リンク切れ候補、CTA欠落	翻訳の自然さは最後に人が読む

関連記事として、権限設計はClaude Code権限設定ガイド、外部ツール連携はClaude Code MCPサーバーガイド、日常運用はClaude Code生産性Tipsを合わせて読むと理解しやすいです。

MCPで社内Runbookを読ませる

MCPはModel Context Protocolの略で、エージェントに外部ツールやデータソースを渡すための標準です。平たく言えば「Claudeが安全に呼べる道具の窓口」です。Claude Agent SDKでは、外部MCPサーバーだけでなく、同じプロセス内で小さなMCPツールを定義できます。公式のMCP guideにも、SDKからMCPサーバーを渡す例があります。

以下は、障害対応用のRunbookを返すだけの読み取り専用ツールです。実運用ではデータベースや社内Wikiにつなぎますが、まずはローカルのオブジェクトで動かします。

import {
  createSdkMcpServer,
  query,
  tool,
} from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const runbooks: Record<string, string> = {
  billing: "支払い失敗率、Stripe webhook、直近deployを確認する。",
  search: "index更新時刻、Algolia task status、API制限を確認する。",
  content: "CMS同期、locale別slug、OGP画像の有無を確認する。",
};

const lookupRunbook = tool(
  "lookup_runbook",
  "サービス名から運用Runbookを返す読み取り専用ツール",
  { service: z.string().min(1) },
  async ({ service }) => {
    const text = runbooks[service] ?? "該当Runbookがありません。";
    return { content: [{ type: "text", text }] };
  },
  { annotations: { readOnlyHint: true, openWorldHint: false } },
);

const runbookServer = createSdkMcpServer({
  name: "runbook",
  version: "1.0.0",
  tools: [lookupRunbook],
});

for await (const message of query({
  prompt: "contentの公開事故を調査する最初の手順を提案して。",
  options: {
    mcpServers: { runbook: runbookServer },
    allowedTools: ["mcp__runbook__lookup_runbook"],
    maxTurns: 3,
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

ここでの落とし穴は、ツール名です。MCPツールは mcp__サーバー名__ツール名 の形で許可します。lookup_runbook だけを allowedTools に入れても、SDK側では許可されません。

編集を許可するなら権限を細くする

次は、修正まで任せる例です。ただし、許可する道具をかなり狭くします。Edit は許可しますが、Bashは npm test だけを想定し、破壊的な操作は disallowedTools に明示します。公式のpermissions guideでも、ツール許可と拒否を分けて制御する考え方が示されています。

import { query } from "@anthropic-ai/claude-agent-sdk";

const prompt = [
  "src配下の小さなTypeScriptエラーを1つだけ修正してください。",
  "修正後に npm test を実行し、変更内容と結果を報告してください。",
  "大きなリファクタリングや依存追加は禁止です。",
].join("\n");

for await (const message of query({
  prompt,
  options: {
    cwd: process.cwd(),
    allowedTools: [
      "Read",
      "Glob",
      "Grep",
      "Edit",
      "Bash(npm test)",
    ],
    disallowedTools: [
      "Bash(git push)",
      "Bash(git commit)",
      "Bash(rm -rf *)",
    ],
    permissionMode: "default",
    maxTurns: 6,
  },
})) {
  if (message.type === "result") {
    console.log(message.subtype, message.result ?? "");
  }
}

このコードは「完全自動でなんでも直す」ためではありません。人間がレビューしやすい小さな差分を作り、テスト結果まで添えるための形です。編集を許可するエージェントほど、cwd、allowedTools、disallowedTools、maxTurns をセットで考えてください。

失敗例と落とし穴

1つ目の失敗は、古いパッケージ名を使うことです。検索上位の記事や古いコードに @anthropic-ai/claude-code、claude-code-sdk、ClaudeCodeOptions が出てくる場合があります。現在のAgent SDK記事として書くなら、公式のMigration Guideを確認し、ClaudeAgentOptions や @anthropic-ai/claude-agent-sdk へ寄せます。

2つ目は、Bashを広く許可することです。Bash だけを許可すると、テストだけでなく削除、deploy、git操作も候補になります。少なくとも最初は Bash(npm test) のように意図したコマンドへ狭め、deployやpushは別フローに分けます。

3つ目は、作業ディレクトリを曖昧にすることです。cwd を指定しないと、実行元プロセスの場所に依存します。CI、ローカル、バッチで動かすなら、対象リポジトリを明示しないと「隣のディレクトリを読んだ」事故が起きます。

4つ目は、Agent SDKを通常のチャットAPIのように扱うことです。Agent SDKはツール実行を含むため、時間、コスト、権限、失敗時の復旧が通常の1リクエストより重くなります。公式のcost tracking guideを確認し、usageや上限を記録する設計にしてください。

5つ目は、MCPツールの説明を雑に書くことです。説明が曖昧だと、Claudeは使うべきタイミングを判断しにくくなります。ツール名、説明、入力スキーマ、read-onlyか破壊的かの注釈を明確にします。

本番投入前のチェックリスト

• ANTHROPIC_API_KEY や外部APIトークンをログに出していない
• 最初の実行は Read, Glob, Grep だけで観察している
• 編集を許可する場合は、対象ディレクトリとコマンドを絞っている
• maxTurns を設定し、無限に近い試行を避けている
• MCPツールは読み取り専用と破壊的操作を分けている
• 結果をそのままmergeせず、差分とテストを人が確認している
• SDKの公式ドキュメントとCHANGELOGを公開前に確認している

Claude Agent SDKは強い道具ですが、記事や社内テンプレートで扱うなら「何ができるか」より「どこまで任せるか」を先に書くべきです。特に収益導線のあるメディアやSaaSでは、記事更新、CTA修正、商品リンク、計測イベントが一度に変わることがあります。運用テンプレートを整えたい場合は無料チートシートで日常コマンドを固め、実務教材やテンプレートは商品一覧へ進んでください。チームで権限、MCP、レビュー、CIまで設計するならClaude Code研修・導入相談が次の入口です。

この記事で実際に試した結果

今回の刷新では、公式のAgent SDK overview、TypeScript reference、MCP guide、permissions guide、migration guideを確認し、古い Claude Code Agent SDK 風のコードを現在の @anthropic-ai/claude-agent-sdk 形式へ置き換えました。Masaの運用目線で一番効いたのは、最初の例を読み取り専用にしたことです。いきなり編集可能なエージェントを載せるより、読者が安全に npm run audit で挙動を見られます。その上でMCP、編集、テスト実行へ段階的に進める構成にしたため、記事としても実務導入メモとしても再利用しやすくなりました。