Claude Agent SDK 使用説明

Claude Agent SDKを使用すると、ファイルを自律的に読み取り、コマンドを実行し、Web検索を行い、コードを編集するなどのAI Agentを構築できます。

Claude Agent SDKは、Claude Codeを駆動するツール、Agentループ、コンテキスト管理機能を、プログラマブルなPythonおよびTypeScriptライブラリとして公開します。

簡単に言うと、これはClaude Codeをライブラリとして使用するSDKです。自身のアプリケーション、CIパイプライン、自動化スクリプトに組み込んで、複雑なタスクを自律的に完了できるAI Agentを構築できます。

コア機能

SDKにはファイルの読み取り、コマンドの実行、コードの編集を行うツールが組み込まれているため、Agentがツール実行ロジックを自ら実装する必要はなく、すぐに作業を開始できます。主な機能は次のとおりです。

機能 説明
組み込みツール ファイルの読み書き、ターミナルコマンド、コード編集、Web検索など
Hooks ツール呼び出しの前後にカスタムロジックを実行
サブエージェント（Subagents） 大きなタスクを分解し、独立したサブエージェントに並行して実行させる
MCPサーバー データベース、ブラウザ、外部APIなどに接続
権限制御 Agentが何をできるか、いつユーザーの承認が必要かを細かく制御
セッション管理（Sessions） コンテキストを保持するマルチターン対話Agentを構築

前提条件

  • Node.js 18+（TypeScript）またはPython 3.10+
  • 1つのAnthropicアカウント、APIキーを取得します（ここで登録）

ステップ1：SDKをインストール

TypeScript

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

TypeScript SDKは、お使いのプラットフォームに適したClaude Codeバイナリをオプションの依存関係として同梱するため、Claude Codeを個別にインストールする必要はありません。

Python

# 使用 pip
pip install claude-agent-sdk

# 或使用 uv（推荐）
uv add claude-agent-sdk

注意：Claude Code CLIはパッケージと一緒に自動的にインストールされるため、個別のインストールは不要です！SDKはデフォルトで同梱のCLIを使用します。

システムレベルのインストールや特定のバージョンを使用したい場合は、ClaudeAgentOptions(cli_path="/path/to/claude")パスを指定できます。

ステップ2：APIキーを設定

からClaude ConsoleAPIキーを取得し、プロジェクトディレクトリに作成します.envファイル：

ANTHROPIC_API_KEY=your-api-key-here

または環境変数として直接設定します：

export ANTHROPIC_API_KEY=your-api-key-here

サードパーティクラウドプラットフォームのサポート

SDKはサードパーティのAPIプロバイダーによる認証もサポートしています：Amazon Bedrock（CLAUDE_CODE_USE_BEDROCK=1環境変数を設定し、AWS認証情報を構成）、Google Vertex AI（CLAUDE_CODE_USE_VERTEX=1）、Microsoft Azure（CLAUDE_CODE_USE_FOUNDRY=1）。

⚠️ 重要：事前にAnthropicの承認を得ない限り、サードパーティの開発者はClaude Agent SDKに基づいて構築された製品でclaude.aiへのログインやレート制限を提供することはできません。ドキュメントに記載されているAPIキー認証方式を使用してください。

ステップ3：最初のAgentを実行

次の例では、現在のディレクトリ内のファイルを一覧表示するAgentを作成します：

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())

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: { allowedTools: ["Bash", "Glob"] },
  })) {
    if ("result" in message) {
      console.log(message.result);
    }
  }
}

main();

実践：バグを自動修正するAgentを構築

以下では、完全な例を通してAgent SDKのコアな使い方を示します。

バグのあるファイルを準備

作成するutils.py、意図的に仕込んだ2つのバグが含まれています：

例

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)   # Bug: 空リストのときに0で除算

def get_user_name(user):
    return user["name"].upper()   # Bug: userがNoneのときにTypeErrorが発生

Agentを作成

作成するagent.py：

例

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def main():
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],  # 使用を許可するツール
            permission_mode="acceptEdits",            # ファイル編集を自動承認
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)          # Claudeの推論プロセス
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}") # 呼び出し中のツール
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")  # 最終結果

asyncio.run(main())

実行

python agent.py

実行後にutils.py、Agentが自律的に次の操作を完了したことがわかります：

  1. 読み取りたutils.pyファイル
  2. 分析コードロジックを分析し、クラッシュを引き起こす可能性のあるエッジケースを特定しました
  3. 編集ファイルを編集し、堅牢なエラーハンドリングを追加しました

コアコンセプトの解説

関数 — Agentループの入口

queryはAgentループを作成する主要なエントリポイントであり、非同期イテレータを返すため、async forを使用して、Claudeが作業中に生成するメッセージをリアルタイムにストリーミング取得します。ループはClaudeがタスクを完了するか、エラーに遭遇すると終了します。SDKがオーケストレーション（ツール実行、コンテキスト管理、リトライ）を担当するため、あなたはこのメッセージストリームを消費するだけでよいのです。

各イテレーションは1つのメッセージを生成します。それらは次のいずれかです：

  • Claudeの推論プロセス
  • ツール呼び出し
  • ツール呼び出しの結果
  • 最終結果

ツール（Tools）— Agentが何をできるかを制御

ツール構成 Agentの機能
Read, Glob, Grep 読み取り専用分析
Read, Edit, Glob コードの分析と修正
Read, Edit, Bash, Glob, Grep 完全自動化
加えてWebSearch Web検索機能を追加

権限モード（Permission Modes）— 人間の監督の度合いを制御

モード 動作 適用シーン
acceptEdits ファイル編集を自動承認し、その他の操作は確認が必要 信頼された開発ワークフロー
dontAsk 拒否allowedTools以外のすべての操作 ロックされた無人Agent
auto（TypeScriptのみ） モデル分類子が各ツール呼び出しを自動承認/拒否 安全策付きの自律Agent
bypassPermissions プロンプトなしで全てのツールを直接実行 サンドボックス化されたCI環境
default 提供が必要canUseToolコールバックによる承認処理 カスタム承認フロー

Agentの動作をカスタマイズ

Web検索を追加

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "WebSearch"],
    permission_mode="acceptEdits"
)

カスタムシステムプロンプトを追加

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob"],
    permission_mode="acceptEdits",
    system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines.",
)

ターミナルコマンドの実行を許可

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"],
    permission_mode="acceptEdits"
)
# 可以尝试：
# prompt="Write unit tests for utils.py, run them, and fix any failures"

プロジェクト設定（CLAUDE.mdなど）を読み込み

SDKはClaude Codeと同じ基盤上に構築されており、SDK Agentは同じファイルシステムベースの機能にアクセスできます：プロジェクト説明（CLAUDE.mdとrules）、スキル、Hooksなど。デフォルトではSDKはファイルシステム設定を一切読み込みません。

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit"],
    # "user" 从 ~/.claude/ 加载，"project" 从 ./.claude/ 加载
    setting_sources=["user", "project"],
)

エラーハンドリング

from claude_agent_sdk import (
    ClaudeSDKError,      # 基础错误
    CLINotFoundError,    # Claude Code 未安装
    CLIConnectionError,  # 连接问题
    ProcessError,        # 进程失败
    CLIJSONDecodeError,  # JSON 解析失败
)

try:
    async for message in query(prompt="Hello"):
        pass
except CLINotFoundError:
    print("请先安装 Claude Code")
except ProcessError as e:
    print(f"进程失败，退出码：{e.exit_code}")
except CLIJSONDecodeError as e:
    print(f"响应解析失败：{e}")

Agent SDK vs. 他のClaudeツール

Agent SDK Client SDK（Messages API） Claude Code CLI
使用方法 Python/TypeScriptライブラリ HTTP API呼び出し ターミナルCLIツール
ツール実行 組み込み、自動実行 手動実装が必要 組み込み、対話式
適用シーン 自主エージェントの構築、アプリケーション統合 一般的なLLM呼び出し 直接的なコーディング支援
状態管理 ステートフル、セッション対応 ステートレス ステートフル、対話型

SDK機能比較表

SDKはClaude Codeのファイルシステムベースの設定もサポートしています。これらの機能を使用するには、オプションで設定する必要がありますsetting_sources=["project"]（Python）またはsettingSources: ['project']（TypeScript）。

機能 説明 場所
Skills（スキル） Markdownで定義された専門能力 .claude/skills/*/SKILL.md
Slash Commands 一般的なタスク用のカスタムコマンド .claude/commands/*.md
Memory（メモリ） プロジェクトコンテキストと指示 CLAUDE.md
Plugins（プラグイン） を通じてpluginsオプション拡張 コードによる設定
その他の拡張