claude-agent-sdk

Claude Agent SDK - 構造化出力とエラー防止ガイド

パッケージ: @anthropic-ai/[email protected]（2025年11月21日） 破壊的変更: v0.1.45 - 構造化出力（2025年11月）、v0.1.0 - デフォルトのシステムプロンプトなし、settingSources が必須

---

v0.1.45 以降の新機能（2025年11月）

主な機能：

1. 構造化出力（v0.1.45、2025年11月14日）

• JSON スキーマ検証 - 応答が正確なスキーマに一致することを保証します
• outputFormat パラメーター - JSON スキーマまたは Zod で出力構造を定義します
• 検証済みの結果にアクセス - message.structured_output 経由でアクセスします
• ベータヘッダーが必須：structured-outputs-2025-11-13
• 型安全性 - Zod スキーマによる完全な TypeScript 型推論

例：

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

const schema = z.object({
  summary: z.string(),
  sentiment: z.enum(['positive', 'neutral', 'negative']),
  confidence: z.number().min(0).max(1)
});

const response = query({
  prompt: "Analyze this code review feedback",
  options: {
    model: "claude-sonnet-4-5",
    outputFormat: {
      type: "json_schema",
      json_schema: {
        name: "AnalysisResult",
        strict: true,
        schema: zodToJsonSchema(schema)
      }
    }
  }
});

for await (const message of response) {
  if (message.type === 'result' && message.structured_output) {
    // Guaranteed to match schema
    const validated = schema.parse(message.structured_output);
    console.log(`Sentiment: ${validated.sentiment}`);
  }
}

2. プラグインシステム（v0.1.27）

• plugins 配列 - ローカルのプラグインパスを読み込みます
• カスタムプラグインのサポート - エージェントの機能を拡張します

3. フックシステム（v0.1.0 以降）

• イベント駆動型コールバック - PreToolUse、PostToolUse、Notification、UserPromptSubmit
• セッションイベントフック - エージェントの動作を監視および制御します

4. その他のオプション

• fallbackModel - 失敗時にモデルを自動的に切り替えます
• maxThinkingTokens - 拡張思考の予算を制御します
• strictMcpConfig - MCP 設定を厳密に検証します
• continue - 新しいプロンプトで再開します（resume とは異なります）
• permissionMode: 'plan' - 計画ワークフロー用の新しい権限モード

📚 ドキュメント: https://platform.claude.com/docs/en/agent-sdk/structured-outputs

---

Claude Agent SDK 完全リファレンス

目次

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

---

コア Query API

主なシグネチャ：

query(prompt: string | AsyncIterable<SDKUserMessage>, options?: Options)
  -> AsyncGenerator<SDKMessage>

重要なオプション：

• outputFormat - 構造化 JSON スキーマ検証（v0.1.45 以降）
• settingSources - ファイルシステム設定の読み込み（'user'|'project'|'local'）
• canUseTool - カスタム権限ロジックのコールバック
• agents - プログラムによるサブエージェント定義
• mcpServers - MCP サーバーの設定
• permissionMode - 'default'|'acceptEdits'|'bypassPermissions'|'plan'

---

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

ツールの制御：

• allowedTools - 許可リスト（優先されます）
• disallowedTools - 拒否リスト
• canUseTool - カスタム権限コールバック（「権限の制御」セクションを参照）

組み込みツール： Read、Write、Edit、Bash、Grep、Glob、WebSearch、WebFetch、Task、NotebookEdit、BashOutput、KillBash、ListMcpResources、ReadMcpResource

---

MCP サーバー（Model Context Protocol）

サーバーの種類：

• プロセス内 - tool() 定義を使った createSdkMcpServer()
• 外部 - stdio、HTTP、SSE トランスポート

ツールの定義：

tool(name: string, description: string, zodSchema, handler)

ハンドラーの戻り値：

{ content: [{ type: "text", text: "..." }], isError?: boolean }

外部 MCP サーバー（stdio）

const response = query({
  prompt: "List files and analyze Git history",
  options: {
    mcpServers: {
      // Filesystem server
      "filesystem": {
        command: "npx",
        args: ["@modelcontextprotocol/server-filesystem"],
        env: {
          ALLOWED_PATHS: "/Users/developer/projects:/tmp"
        }
      },
      // Git operations server
      "git": {
        command: "npx",
        args: ["@modelcontextprotocol/server-git"],
        env: {
          GIT_REPO_PATH: "/Users/developer/projects/my-repo"
        }
      }
    },
    allowedTools: [
      "mcp__filesystem__list_files",
      "mcp__filesystem__read_file",
      "mcp__git__log",
      "mcp__git__diff"
    ]
  }
});

外部 MCP サーバー（HTTP/SSE）

const response = query({
  prompt: "Analyze data from remote service",
  options: {
    mcpServers: {
      "remote-service": {
        url: "https://api.example.com/mcp",
        headers: {
          "Authorization": "Bearer your-token-here",
          "Content-Type": "application/json"
        }
      }
    },
    allowedTools: ["mcp__remote-service__analyze"]
  }
});

MCP ツールの命名規則

形式: mcp__<server-name>__<tool-name>

重要：

• サーバー名とツール名は設定と一致している必要があります
• 区切り文字には二重アンダースコア（__）を使います
• allowedTools 配列に含めます

例： mcp__weather-service__get_weather、mcp__filesystem__read_file

---

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

AgentDefinition 型

type AgentDefinition = {
  description: string;        // When to use this agent
  prompt: string;             // System prompt for agent
  tools?: string[];           // Allowed tools (optional)
  model?: 'sonnet' | 'opus' | 'haiku' | 'inherit';  // Model (optional)
}

フィールドの詳細：

• description: エージェントを使用するタイミング（メインエージェントが委任に使用します）
• prompt: システムプロンプト（役割を定義し、メインのコンテキストを引き継ぎます）
• tools: 使用可能なツール（省略すると、メインエージェントから引き継ぎます）
• model: モデルの上書き（haiku/sonnet/opus/inherit）

使用方法：

agents: {
  "security-checker": {
    description: "Security audits and vulnerability scanning",
    prompt: "You check security. Scan for secrets, verify OWASP compliance.",
    tools: ["Read", "Grep", "Bash"],
    model: "sonnet"
  }
}

---

セッション管理

オプション：

• resume: sessionId - 前のセッションを続行します
• forkSession: true - セッションから新しいブランチを作成します
• continue: prompt - 新しいプロンプトで再開します（resumeとは異なります）

セッションのフォークパターン（独自の機能）：

// Explore alternative without modifying original
const forked = query({
  prompt: "Try GraphQL instead of REST",
  options: {
    resume: sessionId,
    forkSession: true  // Creates new branch, original session unchanged
  }
});

セッション ID の取得：

for await (const message of response) {
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id;  // Save for later resume/fork
  }
}

---

権限管理

権限モード：

type PermissionMode = "default" | "acceptEdits" | "bypassPermissions" | "plan";

• default - 標準の権限チェック
• acceptEdits - ファイル編集を自動承認します
• bypassPermissions - すべてのチェックをスキップします（CI/CD でのみ使用してください）
• plan - 計画モード（v0.1.45 以降）

カスタム権限ロジック

const response = query({
  prompt: "Deploy application to production",
  options: {
    permissionMode: "default",
    canUseTool: async (toolName, input) => {
      // Allow read-only operations
      if (['Read', 'Grep', 'Glob'].includes(toolName)) {
        return { behavior: "allow" };
      }

      // Deny destructive bash commands
      if (toolName === 'Bash') {
        const dangerous = ['rm -rf', 'dd if=', 'mkfs', '> /dev/'];
        if (dangerous.some(pattern => input.command.includes(pattern))) {
          return {
            behavior: "deny",
            message: "Destructive command blocked for safety"
          };
        }
      }

      // Require confirmation for deployments
      if (input.command?.includes('deploy') || input.command?.includes('kubectl apply')) {
        return {
          behavior: "ask",
          message: "Confirm deployment to production?"
        };
      }

      // Allow by default
      return { behavior: "allow" };
    }
  }
});

canUseTool コールバック

type CanUseToolCallback = (
  toolName: string,
  input: any
) => Promise<PermissionDecision>;

type PermissionDecision =
  | { behavior: "allow" }
  | { behavior: "deny"; message?: string }
  | { behavior: "ask"; message?: string };

例：

// Block all file writes
canUseTool: async (toolName, input) => {
  if (toolName === 'Write' || toolName === 'Edit') {
    return { behavior: "deny", message: "No file modifications allowed" };
  }
  return { behavior: "allow" };
}

// Require confirmation for specific files
canUseTool: async (toolName, input) => {
  const sensitivePaths = ['/etc/', '/root/', '.env', 'credentials.json'];
  if ((toolName === 'Write' || toolName === 'Edit') &&
      sensitivePaths.some(path => input.file_path?.includes(path))) {
    return {
      behavior: "ask",
      message: `Modify sensitive file ${input.file_path}?`
    };
  }
  return { behavior: "allow" };
}

// Log all tool usage
canUseTool: async (toolName, input) => {
  console.log(`Tool requested: ${toolName}`, input);
  await logToDatabase(toolName, input);
  return { behavior: "allow" };
}

---

ファイルシステムの設定

設定ソース：

type SettingSource = 'user' | 'project' | 'local';

• user - ~/.claude/settings.json（グローバル）
• project - .claude/settings.json（チームで共有）
• local - .claude/settings.local.json（Git の追跡対象外のオーバーライド）

デフォルト： 設定は読み込まれません（settingSources: []）

設定の優先順位

複数のソースを読み込む場合、設定は次の順序（優先度の高い順）でマージされます。

1. プログラムによるオプション（query()に渡されるもの） - 常に優先されます
2. ローカル設定（.claude/settings.local.json）
3. プロジェクト設定（.claude/settings.json）
4. ユーザー設定（~/.claude/settings.json）

例：

// .claude/settings.json
{
  "allowedTools": ["Read", "Write", "Edit"]
}

// .claude/settings.local.json
{
  "allowedTools": ["Read"]  // Overrides project settings
}

// Programmatic
const response = query({
  options: {
    settingSources: ["project", "local"],
    allowedTools: ["Read", "Grep"]  // ← This wins
  }
});

// Actual allowedTools: ["Read", "Grep"]

ベストプラクティス： 一貫した動作を実現するには、CI/CD でsettingSources: ["project"]を使用してください。

---

メッセージタイプとストリーミング

メッセージタイプ：

• system - セッションの初期化／完了（session_idを含みます）
• assistant - エージェントの応答
• tool_call - ツール実行リクエスト
• tool_result - ツール実行結果
• error - エラーメッセージ
• result - 最終結果（v0.1.45 以降はstructured_outputを含みます）

ストリーミングパターン：

for await (const message of response) {
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id;  // Capture for resume/fork
  }
  if (message.type === 'result' && message.structured_output) {
    // Structured output available (v0.1.45+)
    const validated = schema.parse(message.structured_output);
  }
}

---

エラー処理

エラーコード：

エラーコード	原因	解決策
CLI_NOT_FOUND	Claude Code がインストールされていません	インストールします：npm install -g @anthropic-ai/claude-code
AUTHENTICATION_FAILED	API キーが無効です	ANTHROPIC_API_KEY 環境変数を確認してください
RATE_LIMIT_EXCEEDED	リクエストが多すぎます	バックオフを伴う再試行を実装してください
CONTEXT_LENGTH_EXCEEDED	プロンプトが長すぎます	セッションの圧縮を使用し、コンテキストを減らしてください
PERMISSION_DENIED	ツールがブロックされました	permissionMode と canUseTool を確認してください
TOOL_EXECUTION_FAILED	ツールエラー	ツールの実装を確認してください
SESSION_NOT_FOUND	セッション ID が無効です	セッション ID を確認してください
MCP_SERVER_FAILED	サーバーエラー	サーバーの設定を確認してください

---

既知の問題の防止

このスキルは、記録されている12 件の問題を防止します。

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

エラー：「Claude Code CLI がインストールされていません」 発生源：SDK には Claude Code CLI が必要です 発生理由：CLI がグローバルにインストールされていません 防止策：SDK の使用前にインストールします：npm install -g @anthropic-ai/claude-code

問題 #2：認証エラー

エラー：「API キーが無効です」 発生源：ANTHROPIC_API_KEY が未設定または正しくありません 発生理由：環境変数が設定されていません 防止策：必ずexport ANTHROPIC_API_KEY="sk-ant-..."を設定してください

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

エラー：ツールの実行がブロックされました 発生源：permissionModeの制限 発生理由：権限によってツールの使用が許可されていません 防止策：allowedToolsまたはカスタムcanUseToolコールバックを使用してください

問題 #4：コンテキスト長の上限超過

エラー：「プロンプトが長すぎます」 発生源：入力がモデルのコンテキストウィンドウを超えています 発生理由：大規模なコードベース、長時間の会話 防止策：SDK は自動で圧縮しますが、必要に応じてコンテキストを減らしてください

問題 #5：ツール実行のタイムアウト

エラー：ツールが応答しません 発生源：ツールの実行に時間がかかっています 発生理由：ツールの実行時間が長すぎます（デフォルトでは 5 分超） 防止策：ツールの実装にタイムアウト処理を組み込んでください

問題 #6：セッションが見つからない

エラー：「セッション ID が無効です」 発生源：セッションの有効期限が切れているか、無効です 発生理由：セッション ID が正しくないか、古すぎます 防止策：systemの初期化メッセージからsession_idを取得してください

Issue #7: MCP サーバーの接続に失敗

エラー：サーバーが応答しません 原因：サーバーが起動していないか、設定が誤っています 発生理由：コマンド／URLが正しくない、またはサーバーがクラッシュした 予防策：MCP サーバーを単独でテストし、コマンド／URLを確認します

Issue #8: サブエージェントの定義エラー

エラー：AgentDefinition が無効です 原因：必須フィールドがありません 発生理由：description または prompt がありません 予防策：必ず description フィールドと prompt フィールドを含めます

Issue #9: 設定ファイルが見つからない

エラー：「設定を読み取れません」 原因：設定ファイルが存在しません 発生理由：settingSources に存在しないファイルが含まれています 予防策：sources に含める前にファイルの存在を確認します

Issue #10: ツール名の衝突

エラー：ツール名が重複しています 原因：同じ名前のツールが複数あります 発生理由：2つの MCP サーバーが同じツール名を定義しています 予防策：一意のツール名を使用し、サーバー名を接頭辞として付けます

Issue #11: Zod スキーマの検証エラー

エラー：ツールの入力が無効です 原因：入力が Zod スキーマと一致しません 発生理由：エージェントが誤ったデータ型を指定しました 予防策：.describe() を使用して、説明的な Zod スキーマを作成します

Issue #12: ファイルシステムのアクセス許可が拒否されました

エラー：パスにアクセスできません 原因：ファイルシステムへのアクセスが制限されています 発生理由：パスが workingDirectory の範囲外にあるか、アクセス許可がありません 予防策：workingDirectory を正しく設定し、ファイルのアクセス許可を確認します

---

公式ドキュメント

• Agent SDK の概要: https://platform.claude.com/docs/en/api/agent-sdk/overview
• TypeScript API: https://platform.claude.com/docs/en/api/agent-sdk/typescript
• 構造化出力: https://platform.claude.com/docs/en/agent-sdk/structured-outputs
• GitHub（TypeScript）: https://github.com/anthropics/claude-agent-sdk-typescript
• CHANGELOG: https://github.com/anthropics/claude-agent-sdk-typescript/blob/main/CHANGELOG.md

---

トークン効率：

• スキルなしの場合：約12,000トークン（MCP のセットアップ、権限のパターン、セッションのフォーク、構造化出力、エラー処理）
• スキルありの場合：約3,600トークン（v0.1.45 以降の機能、エラー予防、高度なパターンに特化）
• 削減率：約70%（約8,400トークン）

予防できるエラー：解決策を明記した12件の文書化済みの問題 主な価値：構造化出力（v0.1.45 以降）、セッションのフォーク、canUseTool のパターン、settingSources の優先順位、MCP の命名、エラーコード

---

最終確認日：2025-11-22 | スキルのバージョン：2.0.0 | 変更点：v0.1.45 の構造化出力、プラグイン、フック、新しいオプションを追加。チュートリアル／基本的な例（約750行）を削除。知識のギャップ、エラー予防、高度なパターンに特化。