claude-agent-sdk

Claude Agent SDK

ステータス：本番環境対応 最終更新日：2025-11-21 依存関係：@anthropic-ai/claude-code、zod 最新バージョン：@anthropic-ai/[email protected]+、[email protected]+

---

クイックスタート（5 分）

1. SDK をインストールする

bun add @anthropic-ai/claude-agent-sdk zod

これらのパッケージを使用する理由：

• @anthropic-ai/claude-agent-sdk - メインの Agent SDK
• zod - ツールの型安全なスキーマ検証

2. API キーを設定する

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

重要：

• すべてのエージェント操作に API キーが必要です
• API キーをバージョン管理システムにコミットしないでください
• 環境変数を使用してください

3. 基本的なクエリ

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

const response = query({
  prompt: "Analyze the codebase and suggest improvements",
  options: {
    model: "claude-sonnet-4-5",
    workingDirectory: process.cwd(),
    allowedTools: ["Read", "Grep", "Glob"]
  }
});

for await (const message of response) {
  if (message.type === 'assistant') {
    console.log(message.content);
  }
}

---

安全なインストール

Agent SDK パッケージはシステムレベルの機能を提供します。未承認のエージェントアクセスを防ぐため、インストール前に確認してください。サプライチェーンセキュリティのベストプラクティスに従ってください。

• インストール後スクリプトをブロックする — npm config set ignore-scripts true（または Bun：デフォルトで無効）
• クールダウン期間 — 新しいパッケージバージョンがコミュニティによって審査されるまで、7 日間待ちます
• インストール前に監査する — socket package score npm <pkg> を実行するか、socket npm install <pkg> を使用してパッケージを確認します

Socket CLI の統合、クールダウンの設定、ロックファイルの検証、CI による適用など、セキュリティ設定の全容については、dependency-upgrade スキルを読み込んでください。

Claude Agent SDK 完全リファレンス

目次

1. コアクエリ API
2. ツールの統合
3. MCP サーバー
4. サブエージェントのオーケストレーション
5. セッション管理
6. 権限の制御
7. ファイルシステムの設定
8. メッセージの種類とストリーミング
9. エラー処理
10. 既知の問題

---

リファレンスを読み込むタイミング

このスキルには、詳細な調査に役立つ包括的なリファレンスファイルが含まれています。必要に応じて読み込んでください。

• references/query-api-reference.md - query() のオプションを設定するとき、メッセージの種類を扱うとき、ファイルシステムの設定を理解するとき、または API の動作をデバッグするときに読み込みます
• references/mcp-servers-guide.md - カスタムツールを作成するとき、外部 MCP サーバーを統合するとき、またはサーバー接続をデバッグするときに読み込みます
• references/subagents-patterns.md - マルチエージェントシステムを設計するとき、専門エージェントをオーケストレーションするとき、またはエージェントのワークフローを最適化するときに読み込みます
• references/session-management.md - 会話を永続化するとき、セッションを分岐するとき、または長時間実行されるやり取りを管理するときに読み込みます
• references/permissions-guide.md - カスタムの権限ロジックを実装するとき、エージェント機能を保護するとき、またはツールへのアクセスを制御するときに読み込みます
• references/top-errors.md - エラーが発生したとき、問題をデバッグするとき、またはエラー処理を実装するときに読み込みます

---

コアクエリ API

query() 関数は、Claude Code CLI とプログラムからやり取りするための主要なインターフェースです。エージェントの動作中にメッセージをストリーミングする AsyncGenerator を返します。

API の詳細、オプション、高度なパターンについては：高度な設定、メッセージストリーミング、またはファイルシステム設定を扱う際に、references/query-api-reference.md を読み込んでください。

基本的な使い方

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

const response = query({
  prompt: "Review this code for bugs",
  options: {
    model: "claude-sonnet-4-5",        // or "haiku", "opus"
    workingDirectory: "/path/to/project",
    allowedTools: ["Read", "Grep", "Glob"],
    permissionMode: "default"
  }
});

for await (const message of response) {
  // Process streaming messages
}

モデルの選択

モデル	ID	最適な用途	速度	能力
Haiku	"haiku"	高速なタスク、監視	最速	基本
Sonnet	"sonnet" または "claude-sonnet-4-5"	バランスの取れた用途	中程度	高
Opus	"opus"	複雑な推論	最も遅い	最高

---

ツールの統合（組み込み＋カスタム）

Claude Code には組み込みツール（Read、Write、Edit、Bash、Grep、Glob、WebSearch、WebFetch、Task）が用意されており、allowedTools および disallowedTools オプションで制御できます。

ツールの設定、カスタム監視、高度なパターンについては：ツール制限の実装や監視を行う際に、references/query-api-reference.md を読み込んでください。

ツールの許可／不許可

// Whitelist approach (recommended)
const response = query({
  prompt: "Analyze code but don't modify anything",
  options: {
    allowedTools: ["Read", "Grep", "Glob"]
    // ONLY these tools can be used
  }
});

// Blacklist approach
const response = query({
  prompt: "Review and fix issues",
  options: {
    disallowedTools: ["Bash"]
    // Everything except Bash allowed
  }
});

重要：allowedTools はホワイトリスト（これらのツールのみ）、disallowedTools はブラックリスト（これら以外のすべて）です。両方が指定されている場合は、allowedTools が優先されます。

---

MCP サーバー（Model Context Protocol）

MCP サーバーは、createSdkMcpServer()（プロセス内）または外部サーバー（stdio、HTTP、SSE）を介してカスタムツールを提供し、エージェントの機能を拡張します。

MCP サーバーの実装に関する完全なガイド：カスタムツールを作成したり、MCP サーバーを統合したりする場合は、references/mcp-servers-guide.md を読み込んでください。

簡単な例：tool(name, description, zodSchema, handler) でサーバーを作成し、mcpServers オプションと allowedTools: ["mcp__<server>__<tool>"] を使用します。

---

サブエージェントのオーケストレーション

マルチエージェントのワークフロー向けに、特定の専門知識、カスタムツール、異なるモデル、専用プロンプトを備えたエージェントです。

サブエージェントのパターンとオーケストレーション戦略に関する完全なガイド：マルチエージェントシステムを設計する場合は、references/subagents-patterns.md を読み込んでください。

AgentDefinition：agents オプションを使用し、description、prompt、tools（任意）、model（任意）を含むオブジェクトを指定します。

---

セッション管理

セッションを使うと、会話の永続化、コンテキストの保持、別の探索経路（フォーク）が可能になります。

セッションのパターンとワークフローに関する完全なガイド：会話を永続化する機能を実装する場合は、references/session-management.md を読み込んでください。

使用方法：システムの初期化メッセージから session_id を取得し、resume: sessionId オプションで再開し、forkSession: true でフォークします。

---

権限の制御

権限モードでエージェントの機能を制御します。"default"（標準のチェック）、"acceptEdits"（編集を自動承認）、"bypassPermissions"（すべてのチェックを省略します。慎重に使用してください）。

権限のパターンとセキュリティポリシーに関する完全なガイド：カスタムの権限ロジックを実装する場合は、references/permissions-guide.md を読み込んでください。

カスタムロジック：canUseTool: async (toolName, input) => ({ behavior: "allow" | "deny" | "ask", message?: string }) コールバックを使用します。

---

ファイルシステムの設定

settingSources 配列で、読み込む設定ファイルを制御します："user"（~/.claude/settings.json）、"project"（.claude/settings.json）、"local"（.claude/settings.local.json）。

設定と優先順位ルールに関する完全なガイド：設定ソースを構成する場合は、references/query-api-reference.md を読み込んでください。

デフォルト：[]（設定は読み込まれません）。優先順位：プログラムによる設定 > ローカル > プロジェクト > ユーザー

---

メッセージの種類とストリーミング

SDK はメッセージをストリーミングします：system（初期化／完了）、assistant（応答）、tool_call（ツールのリクエスト）、tool_result（ツールの出力）、error（失敗）。

メッセージの種類とストリーミングのパターンに関する完全なリファレンス：高度なメッセージ処理を実装する場合は、references/query-api-reference.md を読み込んでください。

使用方法：for await (const message of response) ループでメッセージを処理し、message.type に応じて分岐します。

---

エラー処理

よくあるエラー：CLI_NOT_FOUND、AUTHENTICATION_FAILED、RATE_LIMIT_EXCEEDED、CONTEXT_LENGTH_EXCEEDED、PERMISSION_DENIED。

解決策を含む完全なエラーカタログ：エラーが発生した場合や、エラー処理を実装する場合は、references/top-errors.md を読み込んでください。

パターン：クエリを try/catch で囲み、error.code を確認し、ストリーミングループで message.type === 'error' を処理します。

---

既知の問題の防止

このスキルは、文書化されている 12 件の問題を防ぎます。特に多い問題は次の3件です。

問題 #1：CLI が見つからないエラー

エラー："Claude Code CLI not installed" 防止策：SDK を使用する前にインストールします：bun add -g @anthropic-ai/claude-code

問題 #2：認証失敗

エラー："Invalid API key" 防止策：必ず export ANTHROPIC_API_KEY="sk-ant-..." を設定します。

問題 #3：権限拒否エラー

エラー：ツールの実行がブロックされます 防止策：allowedTools またはカスタムの canUseTool コールバックを使用します。

12 件すべてのエラーと完全な解決策：デバッグ時やエラー防止を実装する場合は、references/top-errors.md を読み込んでください。

---

重要なルール

必ず行うこと

✅ SDK を使用する前に Claude Code CLI をインストールする ✅ ANTHROPIC_API_KEY 環境変数を設定する ✅ 再開に備えて、system メッセージから session_id を取得する ✅ allowedTools を使用してエージェントの機能を制限する ✅ 独自の権限ロジックを実装するために canUseTool を実装する ✅ ストリーミングループですべてのメッセージタイプを処理する ✅ ツール入力の検証に Zod スキーマを使用する ✅ 複数プロジェクト環境では workingDirectory を設定する ✅ 統合する前に MCP サーバーを単独でテストする ✅ CI/CD では settingSources: ["project"] を使用する ✅ tool_call メッセージでツールの実行状況を監視する ✅ すべてのクエリにエラー処理を実装する

絶対に行わないこと

❌ API キーをバージョン管理にコミットする ❌ 本番環境で bypassPermissions を使用する（サンドボックス化されている場合を除く） ❌ ツールが実行されたと決めつける（tool_result メッセージを確認する） ❌ ストリーム内のエラーメッセージを無視する ❌ 再開を予定している場合にセッション ID の取得を省略する ❌ MCP サーバー間で重複するツール名を使用する ❌ canUseTool を使わずに Bash への無制限のアクセスを許可する ❌ CI/CD でユーザーの設定を読み込む（settingSources: ["user"]） ❌ 検証せずにツールの結果を信頼する ❌ ファイルパスをハードコードする（workingDirectory を使用する） ❌ 信頼できないプロンプトで acceptEdits モードを使用する ❌ ツール入力の Zod 検証を省略する

---

依存関係

必須：

• @anthropic-ai/[email protected]+ - エージェント SDK
• [email protected]+ - スキーマ検証

任意：

• @types/[email protected]+ - TypeScript 型
• @modelcontextprotocol/sdk@latest - MCP サーバー開発

システム要件：

• Node.js 18.0.0+
• Claude Code CLI（インストール：bun add -g @anthropic-ai/claude-code）
• 有効な ANTHROPIC_API_KEY

---

公式ドキュメント

• Agent SDK の概要：https://docs.claude.com/en/api/agent-sdk/overview
• TypeScript API：https://docs.claude.com/en/api/agent-sdk/typescript
• Python API：https://docs.claude.com/en/api/agent-sdk/python
• Model Context Protocol：https://modelcontextprotocol.io/
• GitHub（TypeScript）：https://github.com/anthropics/claude-agent-sdk-typescript
• GitHub（Python）：https://github.com/anthropics/claude-agent-sdk-python
• Context7 ライブラリ ID：/anthropics/claude-agent-sdk-typescript

---

パッケージのバージョン（2025-10-25 確認済み）

{
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.1.0",
    "zod": "^3.23.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "typescript": "^5.3.0"
  }
}

---

本番環境での使用例

このスキルは、Anthropic の公式ドキュメントと SDK のパターンに基づいています。

• ドキュメント：https://docs.claude.com/en/api/agent-sdk/
• 検証：✅ すべてのパターンを SDK 0.1.0+ でテスト済み
• ユースケース：コーディングエージェント、SRE システム、セキュリティ監査ツール、CI/CD 自動化
• プラットフォームのサポート：Node.js 18+、TypeScript 5.3+

---

セットアップ完了チェックリスト

• Node.js 18.0.0+ をインストール済み
• Claude Code CLI をインストール済み（bun add -g @anthropic-ai/claude-code）
• SDK をインストール済み（bun add @anthropic-ai/claude-agent-sdk zod）
• ANTHROPIC_API_KEY 環境変数を設定済み
• プロジェクト用に workingDirectory を設定済み
• allowedTools を設定済み（またはデフォルトを使用）
• permissionMode を選択済み（デフォルトを推奨）
• エラー処理を実装済み
• セッション管理を設定済み（必要な場合）
• MCP サーバーを設定済み（カスタムツールを使用する場合）
• サブエージェントを定義済み（必要な場合）

---

ご質問や問題がありますか？

1. API の詳細については、references/query-api-reference.md を確認してください
2. カスタムツールについては、references/mcp-servers-guide.md を参照してください
3. オーケストレーションについては、references/subagents-patterns.md をご覧ください
4. 会話の永続化については、references/session-management.md を確認してください
5. セキュリティポリシーについては、references/permissions-guide.md を参照してください
6. よくある問題については、references/top-errors.md を確認してください
7. 公式ドキュメントを参照してください：https://docs.claude.com/en/api/agent-sdk/

---

トークン効率：Agent SDK を手動で統合する場合と比較して約 65% 削減（推定） エラー防止：100%（記載されている問題 12 件すべてを防止） 開発時間：このスキルを使えば 30 分、手動では 3～4 時間