Agent SDK の概要
Claude Code をライブラリとして使用して、本番環境対応の AI エージェントを構築します
ファイルを自動的に読み取り、コマンドを実行し、ウェブを検索し、コードを編集するなど、さらに多くのことができる AI エージェントを構築します。Agent SDK は、Claude Code を強化する同じツール、エージェントループ、およびコンテキスト管理を提供し、Python と TypeScript でプログラム可能です。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Find and fix the bug in auth.py",
options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
):
print(message) # Claude reads the file, finds the bug, edits it
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Find and fix the bug in auth.ts",
options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
console.log(message); // Claude reads the file, finds the bug, edits it
}
Agent SDK には、ファイルの読み取り、コマンドの実行、コードの編集用の組み込みツールが含まれているため、ツール実行を実装することなく、エージェントはすぐに動作を開始できます。クイックスタートに進むか、SDK で構築された実際のエージェントを探索してください。
はじめに
SDK をインストールします
npm install @anthropic-ai/claude-agent-sdk
pip install claude-agent-sdk
Python パッケージには Python 3.10 以降が必要です。pip が No matching distribution found for claude-agent-sdk と報告する場合、インタープリターは 3.10 より古いバージョンです。macOS または Linux では python3 --version を実行するか、Windows では py --version を実行してバージョンを確認してください。
API キーを設定します
Console から API キーを取得し、環境変数として設定します。
export ANTHROPIC_API_KEY=your-api-key
SDK はサードパーティ API プロバイダーを介した認証もサポートしています。
- Amazon Bedrock:
CLAUDE_CODE_USE_BEDROCK=1環境変数を設定し、AWS 認証情報を構成します - Claude Platform on AWS:
CLAUDE_CODE_USE_ANTHROPIC_AWS=1とANTHROPIC_AWS_WORKSPACE_IDを設定し、AWS 認証情報を構成します - Google Vertex AI:
CLAUDE_CODE_USE_VERTEX=1環境変数を設定し、Google Cloud 認証情報を構成します - Microsoft Azure:
CLAUDE_CODE_USE_FOUNDRY=1環境変数を設定し、Azure 認証情報を構成します
詳細については、Bedrock、Claude Platform on AWS、Vertex AI、または Azure AI Foundry のセットアップガイドを参照してください。
最初のエージェントを実行します
この例は、組み込みツールを使用して現在のディレクトリ内のファイルをリストするエージェントを作成します。
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())
import { query } from "@anthropic-ai/claude-agent-sdk";
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);
}
構築する準備はできていますか？ クイックスタートに従って、数分でバグを見つけて修正するエージェントを作成します。
機能
Claude Code を強力にするすべてのものが SDK で利用可能です。
エージェントは、ファイルの読み取り、コマンドの実行、コードベースの検索をすぐに実行できます。主要なツールは次のとおりです。
| ツール | 機能 |
|---|---|
| Read | 作業ディレクトリ内の任意のファイルを読み取ります |
| Write | 新しいファイルを作成します |
| Edit | 既存ファイルに正確な編集を加えます |
| Bash | ターミナルコマンド、スクリプト、git 操作を実行します |
| Monitor | バックグラウンドスクリプトを監視し、各出力行をイベントとして反応します |
| Glob | パターン（**/*.ts、src/**/*.py）でファイルを検索します |
| Grep | 正規表現でファイルコンテンツを検索します |
| WebSearch | 現在の情報をウェブで検索します |
| WebFetch | ウェブページコンテンツを取得して解析します |
| AskUserQuestion | 複数選択オプション付きで、ユーザーに明確化の質問をします |
この例は、コードベースで TODO コメントを検索するエージェントを作成します。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Find all TODO comments and create a summary",
options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Find all TODO comments and create a summary",
options: { allowedTools: ["Read", "Glob", "Grep"] }
})) {
if ("result" in message) console.log(message.result);
}
エージェントライフサイクルの重要なポイントでカスタムコードを実行します。SDK hooks はコールバック関数を使用して、エージェントの動作を検証、ログ、ブロック、または変換します。
利用可能な hooks: PreToolUse、PostToolUse、Stop、SessionStart、SessionEnd、UserPromptSubmit など。
この例は、すべてのファイル変更を監査ファイルにログします。
import asyncio
from datetime import datetime
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher
async def log_file_change(input_data, tool_use_id, context):
file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
with open("./audit.log", "a") as f:
f.write(f"{datetime.now()}: modified {file_path}\n")
return {}
async def main():
async for message in query(
prompt="Refactor utils.py to improve readability",
options=ClaudeAgentOptions(
permission_mode="acceptEdits",
hooks={
"PostToolUse": [
HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
]
},
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
import { query, HookCallback } from "@anthropic-ai/claude-agent-sdk";
import { appendFile } from "fs/promises";
const logFileChange: HookCallback = async (input) => {
const filePath = (input as any).tool_input?.file_path ?? "unknown";
await appendFile("./audit.log", `${new Date().toISOString()}: modified ${filePath}\n`);
return {};
};
for await (const message of query({
prompt: "Refactor utils.py to improve readability",
options: {
permissionMode: "acceptEdits",
hooks: {
PostToolUse: [{ matcher: "Edit|Write", hooks: [logFileChange] }]
}
}
})) {
if ("result" in message) console.log(message.result);
}
特定のサブタスクを処理するために特化したエージェントを生成します。メインエージェントが作業を委譲し、サブエージェントが結果を報告します。
特化した指示を持つカスタムエージェントを定義します。サブエージェントは Agent ツール経由で呼び出されるため、allowedTools に Agent を含めて、それらの呼び出しを自動承認します。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition
async def main():
async for message in query(
prompt="Use the code-reviewer agent to review this codebase",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep", "Agent"],
agents={
"code-reviewer": AgentDefinition(
description="Expert code reviewer for quality and security reviews.",
prompt="Analyze code quality and suggest improvements.",
tools=["Read", "Glob", "Grep"],
)
},
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Use the code-reviewer agent to review this codebase",
options: {
allowedTools: ["Read", "Glob", "Grep", "Agent"],
agents: {
"code-reviewer": {
description: "Expert code reviewer for quality and security reviews.",
prompt: "Analyze code quality and suggest improvements.",
tools: ["Read", "Glob", "Grep"]
}
}
}
})) {
if ("result" in message) console.log(message.result);
}
サブエージェントのコンテキスト内からのメッセージには parent_tool_use_id フィールドが含まれており、どのメッセージがどのサブエージェント実行に属しているかを追跡できます。
Model Context Protocol を介して外部システムに接続します。データベース、ブラウザ、API、および数百以上。
この例は、Playwright MCP サーバーを接続して、エージェントにブラウザ自動化機能を提供します。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Open example.com and describe what you see",
options=ClaudeAgentOptions(
mcp_servers={
"playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}
}
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Open example.com and describe what you see",
options: {
mcpServers: {
playwright: { command: "npx", args: ["@playwright/mcp@latest"] }
}
}
})) {
if ("result" in message) console.log(message.result);
}
エージェントが使用できるツールを正確に制御します。安全な操作を許可し、危険な操作をブロックするか、機密アクションの承認を要求します。
この例は、コードを分析できるが変更できない読み取り専用エージェントを作成します。allowed_tools は Read、Glob、および Grep を事前承認します。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Review this code for best practices",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep"],
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Review this code for best practices",
options: {
allowedTools: ["Read", "Glob", "Grep"]
}
})) {
if ("result" in message) console.log(message.result);
}
複数の交換にわたってコンテキストを維持します。Claude は読み取ったファイル、実行した分析、および会話履歴を記憶します。後でセッションを再開するか、異なるアプローチを探索するためにフォークします。
この例は、最初のクエリからセッション ID をキャプチャし、その後、完全なコンテキストで続行するために再開します。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage, ResultMessage
async def main():
session_id = None
# First query: capture the session ID
async for message in query(
prompt="Read the authentication module",
options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"]),
):
if isinstance(message, SystemMessage) and message.subtype == "init":
session_id = message.data["session_id"]
# Resume with full context from the first query
async for message in query(
prompt="Now find all places that call it", # "it" = auth module
options=ClaudeAgentOptions(resume=session_id),
):
if isinstance(message, ResultMessage):
print(message.result)
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
let sessionId: string | undefined;
// First query: capture the session ID
for await (const message of query({
prompt: "Read the authentication module",
options: { allowedTools: ["Read", "Glob"] }
})) {
if (message.type === "system" && message.subtype === "init") {
sessionId = message.session_id;
}
}
// Resume with full context from the first query
for await (const message of query({
prompt: "Now find all places that call it", // "it" = auth module
options: { resume: sessionId }
})) {
if ("result" in message) console.log(message.result);
}
Claude Code の機能
SDK はまた Claude Code のファイルシステムベースの構成をサポートしています。デフォルトオプションでは、SDK は作業ディレクトリの .claude/ と ~/.claude/ からこれらを読み込みます。どのソースを読み込むかを制限するには、オプションで setting_sources（Python）または settingSources（TypeScript）を設定します。
| 機能 | 説明 | 場所 |
|---|---|---|
| Skills | Claude が自動的に使用するか、/name で呼び出す特化した機能 |
.claude/skills/*/SKILL.md |
| Commands | レガシー形式のカスタムコマンド。新しいカスタムコマンドには skills を使用してください | .claude/commands/*.md |
| Memory | プロジェクトコンテキストと指示 | CLAUDE.md または .claude/CLAUDE.md |
| Plugins | skills、エージェント、hooks、および MCP サーバーで拡張 | plugins オプション経由でプログラム的に |
Agent SDK と他の Claude ツールを比較します
Claude Platform は Claude で構築するための複数の方法を提供しています。Agent SDK がどのように適合するかは次のとおりです。
Anthropic Client SDK は直接 API アクセスを提供します。プロンプトを送信し、ツール実行を自分で実装します。Agent SDK は、組み込みツール実行を備えた Claude を提供します。
Client SDK では、ツールループを実装します。Agent SDK では、Claude がそれを処理します。
# Client SDK: You implement the tool loop
response = client.messages.create(...)
while response.stop_reason == "tool_use":
result = your_tool_executor(response.tool_use)
response = client.messages.create(tool_result=result, **params)
# Agent SDK: Claude handles tools autonomously
async for message in query(prompt="Fix the bug in auth.py"):
print(message)
// Client SDK: You implement the tool loop
let response = await client.messages.create({ ...params });
while (response.stop_reason === "tool_use") {
const result = yourToolExecutor(response.tool_use);
response = await client.messages.create({ tool_result: result, ...params });
}
// Agent SDK: Claude handles tools autonomously
for await (const message of query({ prompt: "Fix the bug in auth.ts" })) {
console.log(message);
}
同じ機能、異なるインターフェース。
| ユースケース | 最適な選択 |
|---|---|
| インタラクティブな開発 | CLI |
| CI/CD パイプライン | SDK |
| カスタムアプリケーション | SDK |
| 1 回限りのタスク | CLI |
| 本番環境の自動化 | SDK |
多くのチームは両方を使用しています。日常的な開発には CLI、本番環境には SDK を使用します。ワークフローはそれらの間で直接変換されます。
Managed Agents はホストされた REST API です。Anthropic がエージェントとサンドボックスを実行し、アプリケーションがイベントを送信して結果をストリーミングで返します。Agent SDK は、独自のプロセス内でエージェントループを実行するライブラリです。
| Agent SDK | Managed Agents | |
|---|---|---|
| 実行場所 | ユーザーのプロセス、ユーザーのインフラストラクチャ | Anthropic 管理インフラストラクチャ |
| インターフェース | Python または TypeScript ライブラリ | REST API |
| エージェントが動作する場所 | ユーザーのインフラストラクチャ上のファイル | セッションごとの管理サンドボックス |
| セッション状態 | ユーザーのファイルシステム上の JSONL | Anthropic ホスト型イベントログ |
| カスタムツール | インプロセス Python または TypeScript 関数 | Claude がツールをトリガーします。ユーザーが実行して結果を返します |
| 最適な用途 | ローカルプロトタイピング、ユーザーのファイルシステムとサービスで直接動作するエージェント | サンドボックスまたはセッションインフラストラクチャを運用する必要のない本番環境エージェント、長時間実行および非同期セッション |
一般的なパスは、Agent SDK でローカルにプロトタイプを作成してから、本番環境用に Managed Agents に移行することです。
変更ログ
SDK の更新、バグ修正、および新機能の完全な変更ログを表示します。
- TypeScript SDK: CHANGELOG.md を表示
- Python SDK: CHANGELOG.md を表示
バグの報告
Agent SDK でバグまたは問題が発生した場合：
- TypeScript SDK: GitHub で問題を報告
- Python SDK: GitHub で問題を報告
ブランドガイドライン
Claude Agent SDK を統合するパートナーの場合、Claude ブランドの使用はオプションです。製品で Claude を参照する場合：
許可されています：
- 「Claude Agent」（ドロップダウンメニューに推奨）
- 「Claude」（既に「Agents」というラベルが付いたメニュー内の場合）
- 「{YourAgentName} Powered by Claude」（既存のエージェント名がある場合）
許可されていません：
- 「Claude Code」または「Claude Code Agent」
- Claude Code ブランドの ASCII アートまたは Claude Code を模倣する視覚要素
製品は独自のブランドを維持し、Claude Code または任意の Anthropic 製品のように見えるべきではありません。ブランドコンプライアンスに関する質問については、Anthropic 営業チームに連絡してください。
ライセンスと利用規約
Claude Agent SDK の使用は、Anthropic の商用利用規約によって管理されます。これは、Claude Agent SDK を使用して、独自のカスタマーおよびエンドユーザーに利用可能にする製品およびサービスを強化する場合を含みます。ただし、特定のコンポーネントまたは依存関係が、そのコンポーネントの LICENSE ファイルに示されているように異なるライセンスの対象である場合を除きます。