Claude Agent SDK の基本的な使い方を学ぶ

npm install @anthropic-ai/claude-agent-sdk zod
export ANTHROPIC_API_KEY=sk-ant-...

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

const response = query({
  prompt: "TypeScript で配列の重複を除く最短のコードを 1 行で。説明は不要。",
  options: {
    tools: [],
    settingSources: [],
    maxTurns: 1,
  },
});

for await (const message of response) {
  if (message.type === "assistant") {
    for (const block of message.message.content) {
      if (block.type === "text") console.log(block.text);
    }
  }
  if (message.type === "result" && message.subtype === "success") {
    console.log("cost:", message.total_cost_usd);
  }
}

for await (const message of response) {
  switch (message.type) {
    case "system":
      // セッション開始時に 1 回だけ。有効なツール一覧とモデルが分かる
      if (message.subtype === "init") {
        console.log(`model=${message.model} tools=${message.tools.length}個`);
      }
      break;

    case "assistant":
      for (const block of message.message.content) {
        if (block.type === "tool_use") {
          console.log(`[tool_use] ${block.name} ${JSON.stringify(block.input)}`);
        }
      }
      break;

    case "user":
      // ツール実行結果はユーザーターンとして戻ってくる
      break;

    case "result":
      console.log(`[result] ${message.subtype}`);
      break;
  }
}

const MAX_TURNS = 1;
let toolCalls = 0;
let sessionId = "";

try {
  const response = query({
    prompt: "このディレクトリの .ts ファイルを列挙して、行数の合計を報告して。",
    options: {
      tools: ["Bash", "Read", "Glob"],
      allowedTools: ["Bash", "Read", "Glob"],
      settingSources: [],
      maxTurns: MAX_TURNS,
      maxBudgetUsd: 0.5,
      effort: "low",
    },
  });

  for await (const message of response) {
    if (message.type === "system" && message.subtype === "init") {
      sessionId = message.session_id;
    }

    if (message.type === "assistant") {
      // assistant メッセージは content ブロックごとに 1 通流れてくる
      for (const block of message.message.content) {
        if (block.type === "tool_use") {
          console.log(`[tool_use ${++toolCalls}] ${block.name}`);
        }
      }
    }

    if (message.type === "result") {
      console.log(`[result] subtype=${message.subtype}`);
      console.log(`  num_turns  : ${message.num_turns}`);
      console.log(`  stop_reason: ${message.stop_reason}`);
      console.log(`  cost       : $${message.total_cost_usd.toFixed(4)}`);

      if (message.subtype === "success") {
        console.log(`  result     : ${message.result}`);
      } else if (message.subtype === "error_max_turns") {
        console.log(`  → resume ${sessionId} で続きから再開できる`);
      }
    }
  }
} catch (error) {
  // エラー result を受け取った後に投げられる。上の分岐は既に走っている
  console.log(`[catch] ${error instanceof Error ? error.message : String(error)}`);
}

if (message.type === "system" && message.subtype === "compact_boundary") {
  const m = message.compact_metadata;
  console.log(`[compact] ${m.trigger} ${m.pre_tokens} -> ${m.post_tokens}`);
}

options: {
  model: "claude-opus-5",              // "opus" / "sonnet" / "haiku" のエイリアスも可
  effort: "low",                       // low | medium | high | xhigh | max
  thinking: { type: "adaptive", display: "summarized" },

  systemPrompt: {
    type: "preset",
    preset: "claude_code",
    append: "回答は必ず日本語で、3行以内にまとめること。",
  },

  cwd: "/path/to/workdir",
  tools: ["Read", "Write", "Bash"],
  allowedTools: ["Read", "Write"],
  settingSources: [],

  maxTurns: 10,
  maxBudgetUsd: 0.5,
}

env: { ...process.env, CLAUDE_AGENT_SDK_CLIENT_APP: "my-app/1.0" }

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

const canUseTool: CanUseTool = async (toolName, input) => {
  if (toolName === "Bash") {
    const command = String((input as { command?: string }).command ?? "");

    if (/\brm\b|\bsudo\b/.test(command)) {
      return {
        behavior: "deny",
        message: "破壊的なコマンドはこのエージェントでは禁止されています。",
        interrupt: true,
      };
    }

    // 入力を書き換えて通すことも出来る
    return {
      behavior: "allow",
      updatedInput: { ...(input as Record<string, unknown>), timeout: 10_000 },
    };
  }
  return { behavior: "allow" };
};

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

const getWeather = tool(
  "get_weather",
  "指定した都市の現在の天気を返す",
  {
    city: z.string().describe("都市名。例: Tokyo"),
    unit: z.enum(["celsius", "fahrenheit"]).default("celsius"),
  },
  async ({ city, unit }) => {
    const temp = unit === "celsius" ? 22 : 72;
    return { content: [{ type: "text", text: `${city} は晴れ、${temp}度です。` }] };
  },
  { annotations: { readOnlyHint: true, openWorldHint: true } },
);

const shopServer = createSdkMcpServer({
  name: "shop",
  version: "1.0.0",
  tools: [getWeather],
});

const response = query({
  prompt: "東京の天気を調べて、雨でなければ SKU-123 を 2 個カートに入れて。",
  options: {
    mcpServers: { shop: shopServer },
    tools: [],
    allowedTools: ["mcp__shop__get_weather", "mcp__shop__add_to_cart"],
  },
});

const preToolUse: HookCallback = async (input) => {
  if (input.hook_event_name !== "PreToolUse") return {};

  const command = String((input.tool_input as { command?: string })?.command ?? "");
  if (command.includes("curl") || command.includes("wget")) {
    return {
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "deny",
        permissionDecisionReason: "外部ネットワークアクセスは禁止です。",
      },
    };
  }
  return {};
};

const response = query({
  prompt: "...",
  options: {
    hooks: {
      PreToolUse: [{ matcher: "Bash", hooks: [preToolUse] }],
    },
  },
});

const agents: Record<string, AgentDefinition> = {
  explorer: {
    description: "コードベースを横断的に検索して、該当箇所のパスと概要だけを返す。",
    prompt: "あなたはコード探索の専門家です。path:line 形式で最大 10 件まで報告してください。",
    tools: ["Read", "Grep", "Glob"],
    model: "haiku",
    effort: "low",
    maxTurns: 10,
  },
  reviewer: {
    description: "変更内容をレビューして、問題点を重大度順に指摘する。",
    prompt: "あなたは厳格なコードレビュアーです。",
    tools: ["Read", "Grep"],
    model: "inherit",
    omitClaudeMd: true,
  },
};

// 1 回目
let sessionId = "";
for await (const message of query({ prompt: "私の好きな言語は Go です。" })) {
  if (message.type === "system" && message.subtype === "init") {
    sessionId = message.session_id;
  }
}

// 2 回目: 文脈が残っている
for await (const message of query({
  prompt: "私の好きな言語は何でしたか？",
  options: { resume: sessionId },
})) { /* ... */ }

// 3 回目: 分岐。元のセッションは無傷のまま別ラインを作る
for await (const message of query({
  prompt: "代わりに Rust を使うとしたら、と仮定して続けて。",
  options: { resume: sessionId, forkSession: true },
})) { /* ... */ }

const ReportSchema = z.object({
  language: z.string(),
  fileCount: z.number().int(),
  findings: z.array(z.object({
    severity: z.enum(["low", "medium", "high"]),
    summary: z.string(),
  })),
});

const response = query({
  prompt: "src ディレクトリを調べて、構成と気づいた点をレポートして。",
  options: {
    outputFormat: {
      type: "json_schema",
      schema: z.toJSONSchema(ReportSchema) as Record<string, unknown>,
    },
  },
});

for await (const message of response) {
  if (message.type === "result" && message.subtype === "success") {
    const parsed = ReportSchema.safeParse(message.structured_output);
    if (parsed.success) console.log(parsed.data.findings);
  }
}

await conversation.setPermissionMode("acceptEdits");
await conversation.setModel("claude-sonnet-5");
await conversation.interrupt();
const usage = await conversation.getContextUsage({ detail: "summary" });
conversation.close();