Claude Agent SDKとは何か — 初心者向け完全ガイド【Python/TypeScript対応】

Last updated at 2026-02-23Posted at 2026-02-23

Claude Agent SDKは、Claudeに「手足」を与えるライブラリです。ファイルの読み書き、コマンド実行、Web検索などをClaudeが自律的に行えるようになります。

このSDKを使うと、自律的に動くAIエージェントを驚くほど短いコードで作れます。ツール呼び出しのループ処理やエラーハンドリングはSDKが内部で処理するため、開発者は「何をさせたいか」をプロンプトで書くだけです。数行のPythonやTypeScriptで、ファイルを読み書きし、バグを修正し、Web検索で最新情報を取得するエージェントが動き始めます。

# たった3行で自律エージェントが動く
async for message in query(prompt="auth.pyのバグを見つけて修正して"):
    if hasattr(message, "result"):
        print(message.result)  # Claudeが自分でファイルを読み、修正し、結果を報告する

この記事では、Agent SDKの仕組み・始め方・主要機能を、初めて触る方にもわかるように解説します。

Agent SDKの位置づけ

Claudeで何かを作る方法は3つあります。

方法	何ができるか	誰向けか
Claude.ai / アプリ	チャット、ファイル添付、Web検索	全ユーザー
Anthropic Client SDK	APIを直接呼び出してプロンプトを送る	開発者
Claude Agent SDK	Claudeが自分でファイル操作・コマンド実行・検索を行う	エージェントを作りたい開発者

Client SDKは「APIとの通信ライブラリ」です。ツールを使わせたいなら、ツール定義・呼び出し・結果の返却ループを自分で書く必要があります。

Agent SDKは「Claude Codeと同じ能力をライブラリとして使えるもの」です。ツール実行ループは内部で自動的に回るため、プロンプトを渡すだけでClaudeが自律的にタスクを完了します。

# Client SDK — ツールループを自分で書く
response = client.messages.create(...)
while response.stop_reason == "tool_use":
    result = your_tool_executor(response.tool_use)
    response = client.messages.create(tool_result=result, ...)

# Agent SDK — プロンプトを渡すだけ
async for message in query(prompt="auth.pyのバグを修正して"):
    print(message)

内部アーキテクチャ — CLIをサブプロセスで動かしている

Agent SDKは、内部でClaude Code CLIをサブプロセスとして起動します。Anthropic APIを直接呼ぶのではなく、CLIを経由する構造です。

あなたのPythonコード
  └─ Claude Agent SDK (claude-agent-sdk)
       └─ SubprocessCLITransport
            └─ Claude Code CLI（サブプロセス）
                 └─ Anthropic API

CLIはパッケージに同梱されているため、別途インストールする必要はありません。pip install claude-agent-sdk（またはnpm install @anthropic-ai/claude-agent-sdk）だけで動きます。

認証方法 — APIキーだけでなくサブスクリプションも使える

公式ドキュメントではAPIキーによる認証が案内されていますが、内部的にClaude Code CLIを使っている構造上、Pro/Maxサブスクリプションのブラウザログイン認証でも動作します。

方法1: APIキー（従量課金）

export ANTHROPIC_API_KEY=your-api-key

Anthropic Consoleでキーを取得し、環境変数にセットします。使った分だけ課金されます。

方法2: サブスクリプション（定額課金）

Claude Pro ($20/月) やMax ($100/月) に加入している場合、Claude Code CLIのブラウザログイン認証がそのまま使えます。ターミナルでclaudeコマンドを実行してログイン済みであれば、Agent SDKもその認証を引き継ぎます。

環境変数ANTHROPIC_API_KEYが設定されている場合、サブスクリプション認証よりもAPIキーが優先されます。サブスクリプションで使いたい場合は、ANTHROPIC_API_KEYを設定しないでください。

方法3: クラウドプロバイダー経由

Amazon Bedrock、Google Vertex AI、Microsoft Azure AI Foundryの認証情報でも利用できます。企業の既存クラウド契約をそのまま使えるのが利点です。

# Amazon Bedrock
export CLAUDE_CODE_USE_BEDROCK=1

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1

# Microsoft Azure AI Foundry
export CLAUDE_CODE_USE_FOUNDRY=1

対応LLMプロバイダー一覧

Agent SDKは内部でClaude Code CLIを使っているため、Claude Codeが対応しているLLMプロバイダーはすべて利用できます。Anthropic公式のClaude以外のモデルも、Anthropic Messages API互換のエンドポイントを経由して動作します。

公式サポート（Anthropicモデル）

プロバイダー	設定方法	備考
Anthropic（直接）	`ANTHROPIC_API_KEY`を設定	標準的な使い方
Anthropic（サブスクリプション）	Claude Code CLIにブラウザログイン	Pro/Maxプランが必要
Amazon Bedrock	`CLAUDE_CODE_USE_BEDROCK=1`	AWS IAM認証。既存のAWS契約を利用可能
Google Vertex AI	`CLAUDE_CODE_USE_VERTEX=1`	Google Cloud認証。GCPプロジェクトが必要
Microsoft Azure AI Foundry	`CLAUDE_CODE_USE_FOUNDRY=1`	APIキーまたはMicrosoft Entra ID認証

サードパーティモデル（Anthropic API互換エンドポイント）

以下のプロバイダーは、Anthropic Messages API互換のエンドポイントを提供しており、ANTHROPIC_BASE_URLを差し替えるだけでAgent SDKから利用できます。

プロバイダー	主なモデル	入力/出力価格 (per 1Mトークン)	設定例
Zhipu AI (智谱)	GLM-4.6, GLM-4.7	$0.60 / $2.20	Coding Plan $3/月〜
DeepSeek	DeepSeek V3.2	$0.28 / $0.42	最安クラス
Alibaba (阿里云)	Qwen3-Coder	$0.22 / $0.95	Anthropic互換エンドポイント
MiniMax	MiniMax-M2, M2.5	$0.30 / $1.20	Coding Plan $10/月〜
Moonshot AI	Kimi K2, K2.5	$0.14 / $2.49	プロンプトキャッシング対応

設定は共通で、~/.claude/settings.jsonに以下のような環境変数を指定します。

~/.claude/settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "your-api-key"
  }
}

Anthropic公式のClaudeモデルと比較すると、サードパーティモデルはコストが最大98%安くなります。ただしツール利用の精度やエージェントとしての安定性はモデルによって差があるため、本番利用の前に十分なテストを推奨します。

ゲートウェイ・プロキシ経由（500以上のモデル）

APIゲートウェイやプロキシを使うと、Anthropic API互換エンドポイントを持たないモデル（OpenAI GPT、Google Geminiなど）もAgent SDKから利用できます。

ゲートウェイ	特徴	設定例
OpenRouter	500以上のモデルに統一APIでアクセス。Claude Code統合の公式ガイドあり	`ANTHROPIC_BASE_URL=https://openrouter.ai/api`
LiteLLM	ローカルプロキシとして動作。100以上のプロバイダーに対応。使用量追跡やコスト管理機能つき	`ANTHROPIC_BASE_URL=http://localhost:4000/anthropic`

OpenRouterの設定例

export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="your-openrouter-key"
export ANTHROPIC_API_KEY=""  # 空にする（Anthropic直接認証を無効化）

ローカルモデル（Ollama）

Ollamaを使えば、完全無料・完全オフラインでAgent SDKを動かせます。Ollama v0.14以降はAnthropic Messages API互換のエンドポイントをネイティブで提供しています。

Ollamaの設定例

export ANTHROPIC_BASE_URL="http://localhost:11434"
export ANTHROPIC_AUTH_TOKEN="ollama"
export ANTHROPIC_API_KEY=""

Ollamaで動作確認が取れている主なモデルは以下の通りです。

GLM-4.7 Flash — 128kコンテキスト。速度とコストのバランスが良い
Qwen3-Coder 30B — オープンソースのコーディングモデルとして高精度
DeepSeek V3.2 — 低コストで幅広いタスクに対応
Devstral 2 Small (24B) — Python・複雑なロジックに強い

Claude Codeのシステムプロンプトは約16,000トークンと大きいため、ローカル実行にはNVIDIA GPU 16GB以上のVRAMまたはApple Silicon 32GB以上のメモリが推奨されます。メモリ不足の場合、量子化モデル（q4_K_Mなど）を使うことで動作可能になる場合があります。

インストールと最初の一歩

Python

pip install claude-agent-sdk

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="このディレクトリにあるファイルを一覧表示して",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"])
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

TypeScript

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

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

for await (const message of query({
  prompt: "このディレクトリにあるファイルを一覧表示して",
  options: { allowedTools: ["Bash", "Glob"] }
})) {
  if ("result" in message) console.log(message.result);
}

どちらも数行でエージェントが動きます。allowed_toolsで使用可能なツールを制限することで、安全性を確保できます。

2つのAPI — `query()` と `ClaudeSDKClient`

Agent SDKには2つのインターフェースがあります。用途に応じて使い分けます。

`query()` — 単発のタスク向け

呼び出すたびに新しいセッションが作られます。前回の会話は記憶しません。

# ファイルを読んで要約するだけの単発タスク
async for message in query(
    prompt="README.mdを読んで要約して",
    options=ClaudeAgentOptions(allowed_tools=["Read"])
):
    if hasattr(message, "result"):
        print(message.result)

適しているケース:

スクリプトやCI/CDパイプラインでの一回限りのタスク
前後の文脈が不要な独立した処理

`ClaudeSDKClient` — 対話・継続タスク向け

1つのセッションで複数のやり取りができます。Claudeが前の会話を覚えています。

async with ClaudeSDKClient() as client:
    # 最初の質問
    await client.query("auth.pyを読んで")
    async for message in client.receive_response():
        print(message)

    # フォローアップ — 「それ」が何か理解してくれる
    await client.query("そのファイルのバグを修正して")
    async for message in client.receive_response():
        print(message)

ClaudeSDKClientでしか使えない機能もあります。

機能	`query()`	`ClaudeSDKClient`
会話の継続	毎回リセット	コンテキスト保持
中断（interrupt）	非対応	対応
フック	非対応	対応
カスタムツール	非対応	対応

組み込みツール一覧

Agent SDKにはClaude Codeと同じツールが組み込まれています。ツール実行の実装は不要で、allowed_toolsに名前を指定するだけで使えます。

ツール	機能
`Read`	ファイルを読む（画像・PDFも可）
`Write`	新しいファイルを作成する
`Edit`	既存ファイルを部分的に書き換える
`Bash`	ターミナルコマンドを実行する
`Glob`	パターンでファイルを検索する（`*/.py`など）
`Grep`	正規表現でファイル内容を検索する
`WebSearch`	Webで最新情報を検索する
`WebFetch`	Webページの内容を取得して分析する
`Task`	サブエージェントを起動して委譲する
`AskUserQuestion`	ユーザーに質問して確認する

# 読み取り専用のコードレビューエージェント
options = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep"],
    permission_mode="bypassPermissions"
)

allowed_toolsを絞ることで「読み取り専用エージェント」「ファイル編集可能エージェント」などを簡単に作り分けられます。

主要機能

サブエージェント

メインのエージェントから専門エージェントを呼び出し、タスクを委譲できます。allowed_toolsにTaskを含め、agentsで定義します。

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep", "Task"],
    agents={
        "code-reviewer": AgentDefinition(
            description="コード品質とセキュリティのレビュー専門家",
            prompt="コード品質を分析し、改善点を提案してください。",
            tools=["Read", "Glob", "Grep"]
        )
    }
)

メインエージェントが判断してcode-reviewerにタスクを振り、結果を受け取ります。

MCP（Model Context Protocol）連携

MCPサーバーを接続すると、外部サービスとの連携が可能になります。

options = ClaudeAgentOptions(
    mcp_servers={
        "playwright": {
            "command": "npx",
            "args": ["@playwright/mcp@latest"]
        }
    }
)

データベース、ブラウザ、GitHubなど、MCPサーバーが存在するサービスならすべて接続できます。

フック

ツール実行の前後にカスタム処理を挟めます。監査ログの記録や危険な操作のブロックに使います。

async def block_dangerous_commands(input_data, tool_use_id, context):
    command = input_data.get("tool_input", {}).get("command", "")
    if "rm -rf /" in command:
        return {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "permissionDecisionReason": "危険なコマンドをブロックしました"
            }
        }
    return {}

options = ClaudeAgentOptions(
    hooks={
        "PreToolUse": [
            HookMatcher(matcher="Bash", hooks=[block_dangerous_commands])
        ]
    }
)

利用可能なフックイベントは以下の通りです。

PreToolUse — ツール実行前
PostToolUse — ツール実行後
UserPromptSubmit — プロンプト送信時
Stop — 実行停止時
SubagentStop — サブエージェント停止時
PreCompact — コンテキスト圧縮前

セッション管理

セッションIDを保存しておけば、後から会話を再開できます。

session_id = None

# 最初のクエリでセッションIDを取得
async for message in query(
    prompt="認証モジュールを読んで",
    options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"])
):
    if hasattr(message, "subtype") and message.subtype == "init":
        session_id = message.session_id

# セッションを再開 — 前回の文脈がそのまま使える
async for message in query(
    prompt="それを呼び出している箇所を探して",
    options=ClaudeAgentOptions(resume=session_id)
):
    if hasattr(message, "result"):
        print(message.result)

カスタムツール（インプロセスMCPサーバー）

@toolデコレータでカスタムツールを定義し、インプロセスMCPサーバーとして動かせます。別プロセスを管理する必要がなく、同一Pythonプロセス内で動作します。

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool("add", "2つの数値を足す", {"a": float, "b": float})
async def add(args):
    return {
        "content": [{"type": "text", "text": f"合計: {args['a'] + args['b']}"}]
    }

calculator = create_sdk_mcp_server(
    name="calculator",
    tools=[add]
)

options = ClaudeAgentOptions(
    mcp_servers={"calc": calculator},
    allowed_tools=["mcp__calc__add"]
)

カスタムツールの名前は mcp__{サーバー名}__{ツール名} の形式でallowed_toolsに指定します。

権限制御

permission_modeで安全レベルを設定できます。

モード	動作
`default`	標準的な権限チェック
`acceptEdits`	ファイル編集を自動承認
`plan`	計画のみ、実行はしない
`bypassPermissions`	すべての権限チェックをバイパス

さらに細かく制御したい場合は、can_use_toolコールバックで個別のツール呼び出しごとに許可・拒否を判定できます。

async def custom_permission(tool_name, input_data, context):
    # /system/ 以下への書き込みをブロック
    if tool_name == "Write" and input_data.get("file_path", "").startswith("/system/"):
        return PermissionResultDeny(message="システムディレクトリへの書き込みは禁止")
    return PermissionResultAllow(updated_input=input_data)

options = ClaudeAgentOptions(can_use_tool=custom_permission)

構造化出力

JSONスキーマを指定すると、エージェントの最終出力をそのスキーマに従った構造化データとして受け取れます。

options = ClaudeAgentOptions(
    output_format={
        "type": "json_schema",
        "schema": {
            "type": "object",
            "properties": {
                "summary": {"type": "string"},
                "files_changed": {"type": "array", "items": {"type": "string"}},
                "risk_level": {"type": "string", "enum": ["low", "medium", "high"]}
            },
            "required": ["summary", "files_changed", "risk_level"]
        }
    }
)

CLAUDE.md との連携

プロジェクトのCLAUDE.mdをAgent SDKから読み込むことも可能です。setting_sourcesに"project"を含めます。

options = ClaudeAgentOptions(
    system_prompt={"type": "preset", "preset": "claude_code"},
    setting_sources=["project"],  # CLAUDE.md を読み込む
    allowed_tools=["Read", "Write", "Edit"]
)

setting_sourcesを省略すると、ファイルシステム上の設定は一切読み込まれません。SDKアプリケーションの分離のためにこれがデフォルトです。

実用例: コードレビューエージェント

ここまでの機能を組み合わせて、簡単なコードレビューエージェントを作ってみます。

import asyncio
from claude_agent_sdk import (
    query, ClaudeAgentOptions, AgentDefinition,
    AssistantMessage, TextBlock, ResultMessage
)

async def code_review(target_dir: str):
    options = ClaudeAgentOptions(
        system_prompt="あなたはシニアソフトウェアエンジニアです。コードレビューを行ってください。",
        allowed_tools=["Read", "Glob", "Grep", "Task"],
        permission_mode="bypassPermissions",
        cwd=target_dir,
        agents={
            "security-reviewer": AgentDefinition(
                description="セキュリティの観点からコードをレビューする専門家",
                prompt="OWASP Top 10を中心にセキュリティ上の問題を指摘してください。",
                tools=["Read", "Glob", "Grep"]
            )
        }
    )

    async for message in query(
        prompt="srcディレクトリのPythonファイルをレビューして。セキュリティ面はsecurity-reviewerに委譲して。",
        options=options
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text)
        elif isinstance(message, ResultMessage):
            print(f"\n完了 (コスト: ${message.total_cost_usd:.4f})")

asyncio.run(code_review("/path/to/project"))

メインエージェントがコード品質をレビューし、セキュリティ関連のチェックはサブエージェントに委譲する構成です。

旧SDKからの移行

以前のclaude-code-sdkパッケージは非推奨です。claude-agent-sdkに移行してください。

# 旧パッケージを削除して新パッケージをインストール
pip uninstall claude-code-sdk
pip install claude-agent-sdk

# 旧: from claude_code_sdk import ClaudeCodeOptions
# 新:
from claude_agent_sdk import ClaudeAgentOptions

詳細な移行手順は公式の移行ガイドを参照してください。

まとめ

項目	内容
Agent SDKとは	Claude Codeの能力をライブラリとして使えるようにしたもの
内部動作	Claude Code CLIをサブプロセスとして起動
認証	APIキー、Pro/Maxサブスクリプション、クラウドプロバイダー
2つのAPI	`query()`（単発）と`ClaudeSDKClient`（対話的）
組み込みツール	Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, Task
拡張方法	カスタムツール、MCPサーバー、サブエージェント、フック

参考リンク

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up