Claude Agent SDK（TypeScript）実践ガイド — CLI spawn から SDK ネイティブへ、自律エージェント構築の全手順

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

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

for await (const message of query({ prompt: "Hello!" })) {
  if (message.type === "assistant") console.log(message.content);
}

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

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

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

// 1ターン目
let sessionId: string | undefined;
for await (const msg of query({
  prompt: "src/index.ts を読んで問題を指摘して",
  allowedTools: ["Read", "Glob", "Grep"],
  permissionMode: "bypassPermissions",
})) {
  if (msg.type === "system" && "sessionId" in msg) sessionId = msg.sessionId;
  if (msg.type === "result") console.log(`Cost: $${msg.total_cost_usd}`);
}

// 2ターン目（セッション継続）
for await (const msg of query({
  prompt: "指摘した問題を修正して",
  resume: { sessionId: sessionId!, mode: "continue" },
  allowedTools: ["Read", "Edit", "Bash"],
  permissionMode: "bypassPermissions",
})) {
  if (msg.type === "assistant") console.log(msg.content);
}

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

// TypeScript 5.2+ の await using で自動クリーンアップ
await using session = unstable_v2_createSession({
  allowedTools: ["Read", "Edit", "Bash", "Glob"],
  permissionMode: "bypassPermissions",
});

// 1ターン目
await session.send("src/index.ts を読んで問題を指摘して");
for await (const msg of session.stream()) {
  if (msg.type === "assistant") console.log(msg.content);
}

// 2ターン目 — セッションID管理不要
await session.send("指摘した問題を修正して");
for await (const msg of session.stream()) {
  if (msg.type === "result") console.log(`Cost: $${msg.total_cost_usd}`);
}

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

const result = await unstable_v2_prompt("package.json の依存関係を一覧して", {
  allowedTools: ["Read"],
  permissionMode: "bypassPermissions",
});
console.log(result.total_cost_usd);

マルチターン会話が必要？
├─ No → unstable_v2_prompt()（ワンショット）
└─ Yes → セッションフォーク（分岐）が必要？
    ├─ Yes → V1 query() + forkSession()（V1 一択）
    └─ No → 本番の安定性を最優先？
        ├─ Yes → V1 query() + resume
        └─ No → V2 createSession()（開発体験が最良）

const options = {
  prompt: "...",
  settingSources: ["project"],  // .claude/settings.json + CLAUDE.md を読み込む
};

1. Hooks（PreToolUse）       → ブロック可。最優先
2. disallowedTools           → bypassPermissions でも有効。絶対拒否
3. permissionMode            → default / acceptEdits / bypassPermissions / dontAsk
4. allowedTools              → 事前承認リスト（制限リストではない）
5. canUseTool コールバック    → プログラム的な動的判定

// Read 以外のツールを拒否する場合の正しい設定
const options = {
  permissionMode: "dontAsk",
  allowedTools: ["Read", "Glob", "Grep"],
  disallowedTools: ["Edit", "Write", "Bash", "NotebookEdit"],
};

// パターン1: 読み取り専用エージェント（コードレビュー等）
const readOnly = {
  permissionMode: "dontAsk" as const,
  allowedTools: ["Read", "Glob", "Grep"],
  disallowedTools: ["Edit", "Write", "Bash"],
};

// パターン2: 編集許可（ビルド・テスト付き）
const editAllowed = {
  permissionMode: "bypassPermissions" as const,
  allowedTools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"],
  disallowedTools: ["NotebookEdit"],
};

// パターン3: フル権限 + コスト上限
const fullAccess = {
  permissionMode: "bypassPermissions" as const,
  maxBudgetUsd: 5.0,
  maxTurns: 20,
};

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

for await (const msg of query({
  prompt: "最新のissueを確認して",
  mcpServers: {
    github: {
      type: "stdio",
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-github"],
      env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN! },
    },
    "remote-search": {
      type: "http",
      url: "https://search.example.com/mcp",
    },
  },
  allowedTools: ["mcp__github__*"],  // ワイルドカードで一括許可
  permissionMode: "bypassPermissions",
})) {
  if (msg.type === "assistant") console.log(msg.content);
}

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

const searchTool = tool(
  "search_docs",
  "社内ドキュメントを検索する",
  { query: z.string().describe("検索クエリ") },
  async ({ query }) => {
    const results = await searchInternalDocs(query);
    return { content: [{ type: "text", text: JSON.stringify(results) }] };
  },
  { annotations: { readOnlyHint: true } }
);

const mcpServer = createSdkMcpServer({
  name: "internal-tools",
  version: "1.0.0",
  tools: [searchTool],
});

for await (const msg of query({
  prompt: "認証フローのドキュメントを検索して要約して",
  mcpServers: { "internal-tools": mcpServer },
  allowedTools: ["mcp__internal-tools__*"],
  permissionMode: "bypassPermissions",
})) {
  if (msg.type === "assistant") console.log(msg.content);
}

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

async function autoFixAgent(projectDir: string, task: string) {
  await using session = unstable_v2_createSession({
    cwd: projectDir,
    systemPrompt: `あなたはシニアエンジニアです。与えられたタスクに対して、
コードの読み取り→問題特定→修正→ビルド確認を自律的に行ってください。
修正後は必ず npm run build で動作確認すること。`,
    allowedTools: ["Read", "Edit", "Write", "Bash", "Glob", "Grep"],
    permissionMode: "bypassPermissions",
    maxTurns: 15,
    maxBudgetUsd: 2.0,
  });

  await session.send(task);

  for await (const msg of session.stream()) {
    switch (msg.type) {
      case "assistant":
        // アシスタントの応答をストリーム出力
        if (typeof msg.content === "string") process.stdout.write(msg.content);
        break;
      case "result":
        // 完了 or エラー
        console.log("\n--- 実行完了 ---");
        console.log(`ステータス: ${msg.subtype}`);
        console.log(`コスト: $${msg.total_cost_usd}`);
        console.log(`ターン数: ${msg.num_turns}`);
        console.log(`所要時間: ${msg.duration_ms}ms`);

        if (msg.subtype === "error_max_turns") {
          console.warn("最大ターン数に到達。タスクが複雑すぎる可能性あり。");
        }
        if (msg.subtype === "error_max_budget_usd") {
          console.warn("コスト上限に到達。maxBudgetUsd の引き上げを検討。");
        }
        break;
    }
  }
}

// 使用例
await autoFixAgent(
  "/path/to/project",
  "TypeScript のビルドエラーを修正して、全テストが通るようにして"
);

判断フロー:
┌─ マルチターン会話が必要？ ──── Yes ──→ SDK
├─ ツール権限の細かい制御が必要？ ─ Yes ──→ SDK
├─ コスト追跡・上限設定が必要？ ── Yes ──→ SDK
├─ MCP カスタムツールを使う？ ─── Yes ──→ SDK
└─ すべて No ──────────────────────────→ CLI spawn で十分