Claude Agent SDK

ファイルの読み取り、コマンドの実行、コードの編集、ウェブ検索など、様々な機能を持つ自律型AIエージェントを構築します。このSDKはClaudeコードを支える同じツール、エージェントループ、およびコンテキスト管理を提供します。

コアコンセプト

重要な設計原則：Claudeにコンピュータを与える。bashコマンドの実行、ファイルの編集、ファイルの作成、ファイルの検索といったツールを提供することで、Claudeは人間がデジタルタスクに取り組むのと同じように機能できます。

エージェントループパターン

効果的なエージェントは、このフィードバックループに従います：コンテキスト収集 → アクション実行 → 作業検証 → 繰り返し

┌─────────────────────────────────────────────────────┐
│                    AGENT LOOP                       │
├─────────────────────────────────────────────────────┤
│  1. GATHER CONTEXT                                  │
│     - Read files, search codebase                   │
│     - Use subagents for parallel information        │
│     - Query external APIs via MCP                   │
│                                                     │
│  2. TAKE ACTION                                     │
│     - Execute tools (Read, Write, Edit, Bash)       │
│     - Generate and run code                         │
│     - Call external services                        │
│                                                     │
│  3. VERIFY WORK                                     │
│     - Run linters, tests, type checkers             │
│     - Visual feedback (screenshots)                 │
│     - LLM-as-judge for fuzzy validation             │
│     - Apply deterministic rules                     │
└─────────────────────────────────────────────────────┘

クイックスタート

インストール

npm install -g @anthropic-ai/claude-code
npm install @anthropic-ai/claude-agent-sdk
export ANTHROPIC_API_KEY=your-api-key

最小限のエージェント（TypeScript）

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

async function main() {
  for await (const message of query({
    prompt: "What files are in this directory?",
    options: {
      model: "opus",
      allowedTools: ["Glob", "Read"],
      maxTurns: 250
    }
  })) {
    if (message.type === "assistant") {
      for (const block of message.message.content) {
        if ("text" in block) console.log(block.text);
      }
    }
  }
}
main();

最小限のエージェント（Python）

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="What files are in this directory?",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"])
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

リファレンスドキュメント

詳細な実装パターンについては、以下を参照してください：

• api_reference.md：完全なAPI、オプション、フック、サブエージェント、V2 API
• PATTERNS.md：コードレビュー、リサーチ、自動化、チャットパターン
• TOOLS.md：組み込みツールとMCP統合
• PRODUCTION.md：デプロイメント、サンドボックス、セキュリティ、監視

スクリプト

• create_agent.ts：テンプレートから新しいエージェントプロジェクトを生成

組み込みツール

ツール	目的
Read	作業ディレクトリ内の任意のファイルを読み取る
Write	新しいファイルを作成する
Edit	既存ファイルの正確な編集を実行する
Bash	ターミナルコマンドを実行する
Glob	パターンでファイルを検索する
Grep	正規表現でファイル内容を検索する
WebSearch	ウェブを検索する
WebFetch	ウェブページを取得してパースする
Task	並列処理用にサブエージェントをスポーンする

ユースケース別エージェントタイプ

コードレビューエージェント: allowedTools: ["Read", "Glob", "Grep"] ファイル自動化エージェント: allowedTools: ["Read", "Write", "Edit", "Bash", "Glob"] リサーチエージェント: allowedTools: ["WebSearch", "WebFetch", "Read", "Write"] マルチエージェントオーケストレータ: allowedTools: ["Read", "Glob", "Grep", "Task"]

主要なオプション

options: {
  model: "opus" | "sonnet" | "haiku",  // Model selection
  maxTurns: 250,                        // Max agent iterations
  allowedTools: [...],                  // Tools available to agent
  permissionMode: "default" | "acceptEdits" | "bypassPermissions",
  systemPrompt: "...",                  // Custom system instructions
  settingSources: ["project"],          // Load skills from .claude/skills/
  outputFormat: { type: "json_schema", schema: {...} }  // Structured output
}

メッセージストリームタイプ

for await (const message of query({...})) {
  switch (message.type) {
    case "system":    // Session init, available tools
    case "assistant": // Claude's responses and tool calls
    case "result":    // Final result with cost info
  }
}

各パターンを使う時機

シンプルなタスク、単一ファイル：基本的なツールを使った直接クエリ 複雑な分析：構造化出力スキーマを追加 大規模なコードベース：並列検索用にサブエージェントを使用 外部統合：カスタムツール用にMCPサーバーを追加 本番環境へのデプロイ：監査とガードレール用にフックを追加

検証戦略

1. リント/型チェック：コード生成後に実行
2. ビジュアルフィードバック：UI作業用のスクリーンショットレンダリング
3. 決定論的ルール：特定の条件をチェックするフック
4. LLM-as-judge：出力品質を評価するサブエージェント

コンテキストエンジニアリング

ファイルシステムはコンテキストに取り込むことが できる 情報を表現します：

• プロジェクトレベルの指示には CLAUDE.md を使用
• エージェンティック検索用にデータフォルダを整理
• 大きなファイルに対して grep/tail をClaudeに使わせる
• コンテキストを分離して要約を返すにはサブエージェントを使用