Claude Agent SDK実践ガイド — 移行手順・Subagents・Hooks・Skillsで構築する本番AIエージェント

# TypeScript
npm uninstall @anthropic-ai/claude-code
npm install @anthropic-ai/claude-agent-sdk

# Python
pip uninstall claude-code-sdk
pip install claude-agent-sdk

# プロジェクト全体で一括置換
find src -name '*.ts' -exec sed -i '' \
  's/@anthropic-ai\/claude-code/@anthropic-ai\/claude-agent-sdk/g' {} +

// Before
import { query } from '@anthropic-ai/claude-code';

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

const q = query({
  prompt: 'プロジェクトのREADMEを生成して',
  options: {
    model: 'sonnet',
    maxTurns: 30,
    cwd: process.cwd(),
    permissionMode: 'bypassPermissions',
    allowedTools: ['Bash', 'Read', 'Write', 'Edit', 'Glob', 'Grep'],
  },
});

for await (const msg of q) {
  if (msg.type === 'result' && msg.subtype === 'success') {
    console.log(msg.result);
    console.log(`Cost: $${msg.total_cost_usd}`);
  }
}

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, AgentDefinition

agents = {
    "researcher": AgentDefinition(
        description="Web検索でトレンドと技術情報を調査する",
        tools=["WebSearch", "WebFetch", "Write"],
        prompt="あなたはリサーチャーです。指定されたトピックについてWeb検索で情報を収集し、findings.mdに調査結果をまとめてください。",
        model="haiku"
    ),
    "implementer": AgentDefinition(
        description="調査結果に基づいてコードを実装する",
        tools=["Read", "Write", "Edit", "Bash", "Glob"],
        prompt="あなたは実装担当です。findings.mdを読み、仕様に沿ってコードを実装してください。",
        model="sonnet"
    ),
    "reviewer": AgentDefinition(
        description="実装コードのレビューと改善提案を行う",
        tools=["Read", "Glob", "Grep", "Bash"],
        prompt="あなたはコードレビュアーです。実装されたコードの品質・セキュリティ・パフォーマンスを評価してください。",
        model="sonnet"
    ),
}

options = ClaudeAgentOptions(
    permission_mode="bypassPermissions",
    system_prompt="あなたはリードエージェントです。researcher→implementer→reviewerの順にタスクを委譲してください。",
    allowed_tools=["Agent"],  # Agentツールでサブエージェントを呼び出す
    agents=agents,
    model="sonnet"
)

import { query } from '@anthropic-ai/claude-agent-sdk';
import type { HookJSONOutput } from '@anthropic-ai/claude-agent-sdk';

const q = query({
  prompt: 'プロジェクトをリファクタリングして',
  options: {
    model: 'sonnet',
    maxTurns: 50,
    permissionMode: 'bypassPermissions',
    allowedTools: ['Bash', 'Read', 'Write', 'Edit', 'Glob', 'Grep'],
    hooks: {
      PreToolUse: [
        {
          matcher: 'Bash',
          hooks: [
            async (input: any): Promise<HookJSONOutput> => {
              const command: string = input.tool_input?.command || '';

              // 危険なコマンドをブロック
              if (command.includes('rm -rf') || command.includes('DROP TABLE')) {
                return {
                  decision: 'block',
                  stopReason: `危険なコマンドを検出: ${command}`,
                  continue: false,
                };
              }
              return { continue: true };
            },
          ],
        },
      ],
      PostToolUse: [
        {
          matcher: null, // 全ツールにマッチ
          hooks: [
            async (input: any): Promise<HookJSONOutput> => {
              // 全ツール実行を監査ログに記録
              console.log(JSON.stringify({
                timestamp: new Date().toISOString(),
                tool: input.tool_name,
                duration_ms: input.duration_ms,
              }));
              return { continue: true };
            },
          ],
        },
      ],
    },
  },
});

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

const dbServer = createSdkMcpServer({
  name: 'database',
  version: '1.0.0',
  tools: [
    tool(
      'search_products',
      '商品データベースを検索する',
      {
        keyword: z.string().describe('検索キーワード'),
        limit: z.number().optional().describe('取得件数（デフォルト10）'),
      },
      async (args) => {
        const results = await db.query(
          'SELECT * FROM products WHERE name LIKE ?',
          [`%${args.keyword}%`]
        );
        return {
          content: [{ type: 'text', text: JSON.stringify(results) }],
        };
      }
    ),
  ],
});

const q = query({
  prompt: '最新のワイヤレスイヤホンを検索して比較表を作って',
  options: {
    model: 'sonnet',
    maxTurns: 20,
    mcpServers: { database: dbServer },
    allowedTools: [
      'mcp__database__search_products', // mcp__{server名}__{tool名}
      'Write',
    ],
  },
});

// Before: CLI spawn方式（claude-runner.ts）
const child = spawn('claude', ['-p', '--dangerously-skip-permissions'], {
  cwd: workDir,
  env: getCleanEnv(),
  stdio: ['pipe', 'pipe', 'pipe'],
});
child.stdin.write(prompt);
child.stdin.end();

let output = '';
child.stdout.on('data', (chunk) => { output += chunk.toString(); });
child.stderr.on('data', (chunk) => {
  // レート制限はstderrの文字列パターンマッチで検出...
});

// After: Agent SDK方式
import { query } from '@anthropic-ai/claude-agent-sdk';

const q = query({
  prompt,
  options: {
    cwd: workDir,
    model: 'sonnet',
    maxTurns: 30,
    permissionMode: 'bypassPermissions',
    allowedTools: ['Bash', 'Read', 'Write', 'Edit', 'WebSearch', 'WebFetch'],
  },
});

for await (const msg of q) {
  if (msg.type === 'assistant' && msg.message) {
    for (const block of msg.message.content) {
      if (block.type === 'tool_use') {
        log.info(`Tool: ${block.name}`);
      }
    }
  }
  if (msg.type === 'result' && msg.subtype === 'success') {
    return { output: msg.result, cost: msg.total_cost_usd };
  }
}

const abortController = new AbortController();

const q = query({
  prompt: '...',
  options: { abortController },
});

// タイムアウト時の安全な中断
setTimeout(() => abortController.abort(), 10 * 60 * 1000);