Claude Agent SDK完全ガイド【TypeScript/Python】｜query()・セッション管理・ストリーミング・カスタムツール・サブエージェントの実装方法

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

# TypeScript用の型定義は同梱されています

pip install claude-agent-sdk

# Python 3.10以上が必要
python --version

ANTHROPIC_API_KEY=sk-ant-xxxxx

# Bedrock を使う場合
# CLAUDE_CODE_USE_BEDROCK=1
# AWS_REGION=us-east-1

# Vertex AI を使う場合
# CLAUDE_CODE_USE_VERTEX=1
# ANTHROPIC_VERTEX_PROJECT_ID=your-project-id

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

async function main() {
  const messages = [];

  // query() は非同期イテレータを返す
  for await (const message of query({
    prompt: "package.json を読んで、依存パッケージの概要を教えてください",
    options: {
      maxTurns: 10,         // エージェントの最大ターン数
      permissionMode: "acceptEdits",  // ファイル編集を自動承認
    },
  })) {
    messages.push(message);

    // メッセージの種類に応じて処理
    if (message.type === "assistant") {
      for (const block of message.message.content) {
        if (block.type === "text") {
          console.log(block.text);
        }
      }
    }
  }
}

main().catch(console.error);

import asyncio
from claude_agent_sdk import query, ClaudeCodeOptions

async def main():
    messages = []

    async for message in query(
        prompt="package.json を読んで、依存パッケージの概要を教えてください",
        options=ClaudeCodeOptions(
            max_turns=10,
            permission_mode="acceptEdits",
        ),
    ):
        messages.append(message)

        if message.type == "assistant":
            for block in message.message.content:
                if block.type == "text":
                    print(block.text)

asyncio.run(main())

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

for await (const message of query({
  prompt: "src/ 以下のTypeScriptファイルを読んで改善提案をしてください",
  options: {
    permissionMode: PermissionMode.DEFAULT,
    // ツール使用前に呼ばれるコールバック
    canUseTool: async (toolName, toolInput) => {
      // 読み取り専用ツールは自動承認
      if (toolName === "Read" || toolName === "Glob" || toolName === "Grep") {
        return true;
      }
      // Bash は内容を確認してから承認
      if (toolName === "Bash") {
        const cmd = toolInput.command as string;
        const isSafe = !cmd.includes("rm") && !cmd.includes("sudo");
        if (!isSafe) {
          console.log(`ブロック: ${cmd}`);
          return false;
        }
        return true;
      }
      // その他（Write/Edit等）は確認
      console.log(`承認が必要: ${toolName} ${JSON.stringify(toolInput)}`);
      return false;
    },
  },
})) {
  // ...
}

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeCodeOptions

async def main():
    # ClaudeSDKClient はセッションIDを内部管理する
    async with ClaudeSDKClient(
        options=ClaudeCodeOptions(permission_mode="acceptEdits")
    ) as client:
        # 1ターン目: コードを読む
        await client.query("src/app.ts の構造を分析してください")
        response1 = await client.receive_response()
        print("分析結果:", response1.text)

        # 2ターン目: 同じコンテキストで続ける
        await client.query("その中でリファクタリングが必要な箇所はどこですか？")
        response2 = await client.receive_response()
        print("改善提案:", response2.text)

asyncio.run(main())

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

// セッションIDを保存しておく
let savedSessionId: string | undefined;

// 1回目の実行
for await (const message of query({ prompt: "バグを調査してください" })) {
  if (message.type === "result") {
    savedSessionId = message.sessionId;
  }
}

// 前回セッションを再開
for await (const message of query({
  prompt: "発見したバグを修正してください",
  options: {
    resume: savedSessionId,  // 前回の調査結果を引き継ぐ
  },
})) {
  // ...
}

// 別アプローチを試す（セッションを分岐）
for await (const message of query({
  prompt: "別の方法で同じバグを修正してください",
  options: {
    forkSession: savedSessionId,  // 同じ調査結果から分岐
  },
})) {
  // ...
}

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

for await (const event of query({
  prompt: "README.md の内容をもとに詳しいドキュメントを生成してください",
  options: {
    includePartialMessages: true,  // ストリーミングを有効化
  },
})) {
  // ストリームイベントの種類で分岐
  if (event.type === "content_block_delta") {
    if (event.delta.type === "text_delta") {
      // テキストをリアルタイムに出力
      process.stdout.write(event.delta.text);
    }
  } else if (event.type === "content_block_stop") {
    console.log(); // ブロック終了時に改行
  } else if (event.type === "result") {
    console.log(`
完了。コスト: $${event.cost_usd}`);
  }
}

import asyncio
import sys
from claude_agent_sdk import query, ClaudeCodeOptions

async def main():
    async for event in query(
        prompt="README.md の内容をもとに詳しいドキュメントを生成してください",
        options=ClaudeCodeOptions(include_partial_messages=True),
    ):
        if event.type == "content_block_delta":
            if event.delta.type == "text_delta":
                sys.stdout.write(event.delta.text)
                sys.stdout.flush()
        elif event.type == "result":
            print(f"
完了。コスト: ${event.cost_usd}")

asyncio.run(main())

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

for await (const message of query({
  prompt: "GitHub のissue一覧を取得して、優先度順に並べてください",
  options: {
    mcpServers: {
      // GitHub MCP サーバー
      github: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN ?? "",
        },
      },
      // Playwright MCP サーバー（UI自動化）
      playwright: {
        command: "npx",
        args: ["@playwright/mcp@latest"],
      },
    },
  },
})) {
  // ...
}

import asyncio
import os
from claude_agent_sdk import query, ClaudeCodeOptions, MCPServerConfig

async def main():
    async for message in query(
        prompt="GitHub のissue一覧を取得して、優先度順に並べてください",
        options=ClaudeCodeOptions(
            mcp_servers={
                "github": MCPServerConfig(
                    command="npx",
                    args=["-y", "@modelcontextprotocol/server-github"],
                    env={"GITHUB_PERSONAL_ACCESS_TOKEN": os.environ["GITHUB_TOKEN"]},
                ),
            }
        ),
    ):
        pass  # メッセージ処理

asyncio.run(main())

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

// サブエージェントの定義
const testAgent: AgentDefinition = {
  name: "test-runner",
  description: "テストを実行して結果を報告するエージェント",
  prompt: "指定されたファイルのテストを実行し、失敗したテストの詳細を報告してください",
  options: {
    allowedTools: ["Bash", "Read"],  // 使用できるツールを制限
    permissionMode: "acceptEdits",
  },
};

const codeReviewAgent: AgentDefinition = {
  name: "code-reviewer",
  description: "コードレビューを行うエージェント",
  prompt: "コードを読んでバグ・セキュリティ問題・改善点を報告してください",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
  },
};

// メインエージェントにサブエージェントを使わせる
for await (const message of query({
  prompt: `src/ のコードをレビューし、問題があればテストを実行して確認してください。
           code-reviewer と test-runner エージェントを活用してください`,
  options: {
    allowedTools: ["Agent", "Read", "Bash"],  // Agent ツールを許可
    subagents: [testAgent, codeReviewAgent],
  },
})) {
  if (message.type === "assistant") {
    for (const block of message.message.content) {
      if (block.type === "text") {
        console.log(block.text);
      }
    }
  }
}

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

async function reviewPR(prNumber: string) {
  // 変更差分を取得
  const diff = execSync(`git diff origin/main...HEAD`).toString();

  const reviewComments: string[] = [];

  for await (const message of query({
    prompt: `以下のPR差分をレビューしてください。
    バグ・セキュリティ問題・パフォーマンス問題・コードスタイルの指摘を
    箇条書きでまとめてください。

    ${diff}`,
    options: {
      maxTurns: 5,
      allowedTools: ["Read", "Glob"],  // 関連ファイルの参照のみ許可
    },
  })) {
    if (message.type === "assistant") {
      for (const block of message.message.content) {
        if (block.type === "text") {
          reviewComments.push(block.text);
        }
      }
    }
  }

  return reviewComments.join("
");
}

import asyncio
import glob
from claude_agent_sdk import query, ClaudeCodeOptions

async def refactor_files(pattern: str, instruction: str):
    """指定パターンに一致するファイルを一括リファクタリング"""
    files = glob.glob(pattern, recursive=True)
    print(f"{len(files)}ファイルをリファクタリングします...")

    for file_path in files:
        print(f"処理中: {file_path}")

        async for message in query(
            prompt=f"{file_path} を以下の方針でリファクタリングしてください:
{instruction}",
            options=ClaudeCodeOptions(
                max_turns=5,
                permission_mode="acceptEdits",
                allowed_tools=["Read", "Edit"],  # 読み取りと編集のみ
            ),
        ):
            if message.type == "result":
                print(f"  完了 (コスト: ${message.cost_usd:.4f})")
                break

asyncio.run(refactor_files(
    "src/**/*.py",
    "型アノテーションを追加し、docstringをGoogle形式に統一してください"
))

#!/usr/bin/env node
import { query } from "@anthropic-ai/claude-agent-sdk";

// コマンドライン引数からタスクを受け取る
const task = process.argv.slice(2).join(" ");

if (!task) {
  console.error("使い方: npx my-agent <タスクの説明>");
  process.exit(1);
}

(async () => {
  process.stdout.write("エージェント実行中...
");

  for await (const message of query({
    prompt: task,
    options: {
      maxTurns: 20,
      permissionMode: "acceptEdits",
    },
  })) {
    if (message.type === "assistant") {
      for (const block of message.message.content) {
        if (block.type === "text") {
          console.log(block.text);
        }
      }
    } else if (message.type === "result") {
      console.log(`
実行時間: ${message.duration_ms}ms | コスト: $${message.cost_usd}`);
    }
  }
})();