Claude Agent SDKで自律型AIエージェントを構築する実践ガイド — CLI spawn方式からの移行で得られる型安全性とストリーミング制御

import { spawn } from "child_process";

const child = spawn("claude", ["-p", "--dangerously-skip-permissions"], {
  cwd,
  env: getCleanEnv(),
  stdio: ["pipe", "pipe", "pipe"],
});

let stdout = "";
let stderr = "";
child.stdout.on("data", (data) => { stdout += data.toString(); });
child.stderr.on("data", (data) => { stderr += data.toString(); });
child.stdin.write(prompt);
child.stdin.end();

child.on("close", (exitCode) => {
  const rateLimited = isRateLimited(exitCode, stderr, stdout);
  // 文字列パースでレート制限を判定...
});

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

for await (const message of query({
  prompt: "プロジェクトのビルドエラーを修正して",
  options: {
    cwd: "/path/to/project",
    permissionMode: "bypassPermissions",
    allowDangerouslySkipPermissions: true,
  },
})) {
  if (message.type === "result") {
    console.log(message.subtype); // "success" | "error_max_turns" | ...
  }
}

npm install @anthropic-ai/claude-agent-sdk

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

for await (const message of query({
  prompt: "Hello, Agent SDK!",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code" },
    settingSources: ["project"],
    permissionMode: "bypassPermissions",
    allowDangerouslySkipPermissions: true,
    cwd: process.cwd(),
  },
})) {
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
  if (message.type === "result") {
    console.log("Cost:", message.cost_usd);
  }
}

systemPrompt: { type: "preset", preset: "claude_code" }

settingSources: ["user", "project", "local"]

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

const slackNotifyTool = tool(
  "notify_slack",
  "Slackチャンネルにメッセージを送信する",
  {
    channel: z.string().describe("送信先チャンネル名"),
    message: z.string().describe("メッセージ本文"),
  },
  async ({ channel, message }) => {
    await fetch(process.env.SLACK_WEBHOOK_URL!, {
      method: "POST",
      body: JSON.stringify({ text: `[${channel}] ${message}` }),
    });
    return { content: [{ type: "text", text: "通知完了" }] };
  }
);

const customServer = createSdkMcpServer({
  name: "my-tools",
  version: "1.0.0",
  tools: [slackNotifyTool],
});

options: {
  agents: {
    "code-reviewer": {
      description: "コード品質レビュー専門エージェント",
      prompt: "コード品質を分析し、改善点を提案してください。",
      tools: ["Read", "Glob", "Grep"],
      model: "haiku",
      maxTurns: 10,
    },
    "builder": {
      description: "ビルド・テスト実行エージェント",
      prompt: "プロジェクトをビルドし、テストを実行してください。",
      tools: ["Read", "Bash", "Edit"],
      model: "sonnet",
    },
  },
}

const controller = new AbortController();

// 10分でタイムアウト
setTimeout(() => controller.abort(), 10 * 60 * 1000);

for await (const msg of query({
  prompt: "全テストを実行して結果を報告して",
  options: { abortController: controller },
})) {
  switch (msg.type) {
    case "assistant":
      // エージェントの応答テキストをSlackに中継
      await notifySlack(`Agent: ${JSON.stringify(msg.message.content).slice(0, 200)}`);
      break;
    case "result":
      await notifySlack(`完了: ${msg.subtype}, コスト: $${msg.cost_usd}`);
      break;
  }
}

// 1回目: セッション開始
let sessionId: string;
for await (const msg of query({ prompt: "package.jsonを確認して" })) {
  if (msg.type === "system" && msg.subtype === "init") {
    sessionId = msg.sessionId;
  }
}

// 2回目: セッション継続
for await (const msg of query({
  prompt: "さっき確認した依存関係を最新に更新して",
  options: { resume: sessionId },
})) {
  // 前回のコンテキストを保持した状態で実行
}