- 主なポイント
- Claude Code SDK とは？
- Claude Code SDK vs. Anthropic Client SDK：使い分け
- Claude Agent SDK のインストール
- ステップ 1：認証の構成
- ステップ 2：最初のエージェントクエリを実行する
- ステップ 3：allowedTools で権限を制御する
- ステップ 4：フックを使用してライフサイクルを制御する
- ステップ 5：セッションで作業を再開する
- ステップ 6：サブエージェントにタスクを委任する
- ステップ 7：MCP 経由で外部システムに接続する
- モデルバックエンドとして Novita AI を使用する
- CI/CD パイプラインでの Claude Code SDK
- トラブルシューティング
- FAQ
- おすすめ記事
Claude Code SDK は、Anthropic のエージェント SDK リリースに伴い Claude Agent SDK と改名されました。アプリケーション内で自律型コーディングエージェントを実行するための Python および TypeScript ライブラリです。ファイル読み取り、コマンド実行、コード編集、ツール呼び出し、マルチステップの反復処理を、手動でツールループを構築することなく処理します。Novita AI の Anthropic 互換エンドポイントを使用すれば、同じ SDK でサポートされているオープンウェイトモデルも実行でき、デフォルトの Anthropic バックエンド以外にもモデル選択とコスト管理の選択肢が広がります。
このガイドでは、開発者が始めるために必要なすべての情報を網羅します：インストール、中核となる query() API、組み込みツール、フック、セッション、サブエージェント、MCP 統合、そして Novita AI の LLM API をモデルバックエンドとして使用する方法について説明します。
主なポイント
- Claude Code SDK は現在 Claude Agent SDK と呼ばれています（Python は
claude-agent-sdk、TypeScript は@anthropic-ai/claude-agent-sdk）。 - 単一の
query()関数で、Anthropic Client SDK で必要だった手動のツール実行ループを置き換えます。 - 組み込みツールはファイル読み取り、編集、bash 実行、Web 検索などをカバーしており、実装は不要です。
- セッションにより、エージェントは完全なコンテキストを保持したまま複数の呼び出しにわたって作業を再開できます。
- フックを使用すると、特定のライフサイクルポイントでツール呼び出しを検証、ログ記録、またはブロックできます。
- Novita AI の Anthropic 互換エンドポイント（
https://api.novita.ai/anthropic）を使用すると、同じ SDK コードで高品質なオープンウェイトモデルを利用できます。
Claude Code SDK とは？
Claude Code SDK は、Claude Code のエージェント機能へのプログラムインターフェースです。Claude Code CLI が対話的に使用するものと同じツール、推論ループ、コンテキスト管理を公開していますが、ライブラリとしてインポートして独自のコードから呼び出せます。
Anthropic は 4.6 世代からこれを Claude Agent SDK に改名しましたが、元の検索語「claude code sdk」は依然としてその機能を正確に表しています。つまり、Claude Code の上に位置し、ソフトウェア内でエージェントタスクを自動化する SDK 層です。
適している用途：
- CI/CD における自動コードレビュー、リファクタリング、テスト生成
- ファイルの読み取り・変更、スクリプト実行、または代理での Web 検索を行うエージェント
- コーディネーターが専門ワーカーにサブタスクを委任するマルチエージェントパイプライン
- Claude に自律的なマルチステップアクションを実行させたい（単なるプロンプト応答ではない）ワークフロー
適していない用途： すべてのメッセージを直接制御したり、単一呼び出しで構造化出力を得たり、チャット UI 用にストリーミング応答が必要な場合は、Anthropic Client SDK の方が適切です。
Claude Code SDK vs. Anthropic Client SDK：使い分け
両方の SDK は Claude 上に構築されていますが、解決する問題が異なります。
| Claude Agent SDK | Anthropic Client SDK | |
|---|---|---|
| ツール実行 | Claude が自律的に処理 | ツールループを自分で実装 |
| インターフェース | query() が非同期イテレーターを返す |
client.messages.create() がレスポンスオブジェクトを返す |
| 組み込みツール | Read, Write, Edit, Bash, Grep, Glob, WebSearch など | なし — すべてのツールを自分で定義・実行 |
| セッション | 組み込み — セッション ID で再開 | 手動 — 会話履歴を自分で管理 |
| 最適な用途 | エージェントパイプライン、CI/CD、ファイル操作 | チャットアプリ、構造化出力、きめ細かい制御 |
Claude にどのファイルを読み取るべきか判断させ、自律的に編集させたい場合：Agent SDK。Claude に特定のプロンプトに応答させ、処理する値を返させたい場合：Client SDK。
Claude Agent SDK のインストール
Python（Python 3.10 以上が必要）：
pip install claude-agent-sdk
TypeScript / Node.js：
npm install @anthropic-ai/claude-agent-sdk
TypeScript パッケージには、プラットフォーム用のネイティブ Claude Code バイナリがオプションの依存関係としてバンドルされています。Claude Code を別途インストールする必要はありません。
インストール前に Python バージョンを確認するには：
python3 --version # macOS/Linux
py --version # Windows
pip が No matching distribution found for claude-agent-sdk と報告した場合、Python インタープリターが 3.10 より古いことを意味します。
ステップ 1：認証の構成
Anthropic API キーを環境変数として設定します：
export ANTHROPIC_API_KEY=your-api-key
SDK は、クラウドプロバイダー経由でルーティングするチーム向けに、Amazon Bedrock、Google Vertex AI、Azure AI Foundry もサポートしています：
# Amazon Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
# 標準の AWS 認証情報も必要
# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
# GOOGLE_CLOUD_PROJECT と gcloud 認証情報も必要
# Microsoft Azure AI Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
# Azure 認証情報も必要
ステップ 2：最初のエージェントクエリを実行する
SDK の表面全体は、単一の関数 query() を中心に構築されています。プロンプトとオプションを受け取り、メッセージイベントの非同期イテレーターを返します。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="このディレクトリ内のすべての Python ファイルを一覧表示してください",
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: "このディレクトリ内のすべての Python ファイルを一覧表示してください",
options: { allowedTools: ["Bash", "Glob"] }
})) {
if ("result" in message) console.log(message.result);
}
イテレーターはいくつかのメッセージタイプを生成します。最も有用な2つは次のとおりです：
ResultMessage（またはresultフィールドを持つメッセージ）— エージェントの最終応答SystemMessage、subtype === "init"— 後で再開するためのsession_idを保持
ステップ 3：allowedTools で権限を制御する
SDK には事前実装されたツールが同梱されています。エージェントが使用できるツールを宣言すると、Claude が実行を処理します。
| ツール | 機能 |
|---|---|
| Read | 作業ディレクトリ内の任意のファイルを読み取る |
| Write | 新しいファイルを作成する |
| Edit | 既存のファイルに的を絞った編集を行う |
| Bash | シェルコマンド、スクリプト、git 操作を実行する |
| Glob | パターンでファイルを検索する（**/*.ts、src/**/*.py） |
| Grep | 正規表現でファイル内容を検索する |
| WebSearch | 最新情報を Web 検索する |
| WebFetch | Web ページの内容を取得して解析する |
| Monitor | バックグラウンドスクリプトを監視し、出力行に反応する |
| AskUserQuestion | タスク途中でユーザーに確認質問をする |
| Agent | 定義済みのサブエージェントを呼び出す |
Bash + Read + Edit の組み合わせは、ほとんどの自動コードタスクに十分です。エージェントが外部データを必要とする場合は、WebSearch または WebFetch を追加します。
allowed_tools（Python）/ allowedTools（TypeScript）は、プロンプトなしで特定のツールを事前承認します。ツールセットを制限することで、エージェントが意図せず実行できる操作も制限できます — 自動パイプラインに役立つガードレールです。
読み取り専用のコードレビューエージェント：
from claude_agent_sdk import query, ClaudeAgentOptions
async for message in query(
prompt="このコードベースをセキュリティ問題とコードの臭いについてレビューしてください",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep"],
),
):
if hasattr(message, "result"):
print(message.result)
完全な編集エージェント（ファイル書き込みを事前承認）：
options=ClaudeAgentOptions(
allowed_tools=["Read", "Write", "Edit", "Bash"],
permission_mode="acceptEdits",
)
permission_mode="acceptEdits" は、対話的なプロンプトなしでファイル編集を自動承認します。これは CI で実行する場合に必須です。
ステップ 4：フックを使用してライフサイクルを制御する
フックを使用すると、エージェントの実行における定義されたポイントでカスタムコードを実行できます。アクションのログ記録、入力の検証、危険な操作のブロック、外部状態の更新などが可能です。
利用可能なフックイベント： PreToolUse、PostToolUse、PostToolUseFailure、UserPromptSubmit、Stop、SubagentStop、SubagentStart、PreCompact、Notification、PermissionRequest
この例では、エージェントがファイルを編集または作成するたびに監査ログを書き込みます：
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().isoformat()}: {file_path} を変更しました\n")
return {}
async def main():
async for message in query(
prompt="auth.py を dataclass を使用するようにリファクタリングしてください",
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()}: ${filePath} を変更しました\n`);
return {};
};
for await (const message of query({
prompt: "auth.ts をインターフェースを使用するようにリファクタリングしてください",
options: {
permissionMode: "acceptEdits",
hooks: {
PostToolUse: [{ matcher: "Edit|Write", hooks: [logFileChange] }]
}
}
})) {
if ("result" in message) console.log(message.result);
}
{ block: true } を返す PreToolUse フックは、ツール呼び出しを完全に防止します — 自動化されたコンテキストで「ファイルを削除しない」などのポリシーを強制するのに役立ちます。
ステップ 5：セッションで作業を再開する
セッションは、エージェントの完全なコンテキスト（読み取ったファイル、発見した内容、会話履歴）を複数の query() 呼び出しにわたって保持します。これにより、長いタスクをステップに分割したり、中断された作業を続行したりできます。
セッションを再開するには、SystemMessage の init イベントから session_id を取得し、それを resume に渡します：
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage, ResultMessage
async def main():
session_id = None
# 最初のクエリ：コードベースを読み取って分析
async for message in query(
prompt="認証モジュールを読み取り、すべての外部依存関係を特定してください",
options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
):
if isinstance(message, SystemMessage) and message.subtype == "init":
session_id = message.data["session_id"]
# 2番目のクエリ：最初のクエリの完全なコンテキストで続行
async for message in query(
prompt="それらの依存関係に既知の脆弱性があるかどうかを確認してください",
options=ClaudeAgentOptions(
resume=session_id,
allowed_tools=["Read", "Bash", "WebSearch"],
),
):
if isinstance(message, ResultMessage):
print(message.result)
asyncio.run(main())
2番目のプロンプトは「それらの依存関係」を使用しています — これは、セッションが最初の呼び出しからのコンテキストを保持しているためにのみ意味を持つ参照です。resume がないと、Claude は何を参照しているのか理解できません。
ステップ 6：サブエージェントにタスクを委任する
サブエージェントは、メインエージェントが Agent ツールを介して呼び出せる専門エージェントです。メインエージェントが調整役を務め、サブエージェントが集中的な作業を行います。結果はメインコンテキストに戻ります。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition
async def main():
async for message in query(
prompt="このコードベースをレビューしてください：認証ファイルには security-auditor エージェントを、その他すべてには style-checker エージェントを使用してください",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep", "Agent"],
agents={
"security-auditor": AgentDefinition(
description="認証と認可のセキュリティ専門家。",
prompt="認証関連のコードを OWASP Top 10 の脆弱性について監査してください。行番号とリスク重大度を具体的に示してください。",
tools=["Read", "Glob", "Grep"],
),
"style-checker": AgentDefinition(
description="コードスタイルと保守性のレビュアー。",
prompt="命名規則、複雑性、ドキュメントの不足についてコードを確認してください。",
tools=["Read", "Glob"],
),
},
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
サブエージェントの呼び出しを事前承認するには、allowed_tools に "Agent" を含めます。サブエージェントからのメッセージには parent_tool_use_id フィールドが含まれるため、どの出力がどのサブエージェントからのものかを追跡できます。
ステップ 7：MCP 経由で外部システムに接続する
Model Context Protocol（MCP）を使用すると、カスタムツールを作成せずに、データベース、ブラウザ、内部 API などの外部機能をエージェントに追加できます。エージェントは MCP ツールを組み込みツールと同様に扱います。
この例では、Playwright MCP サーバーを介してブラウザ自動化を追加します：
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="https://example.com を開いて、ページ構造を説明してください",
options=ClaudeAgentOptions(
mcp_servers={
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
mcp_servers オプションは、MCP 仕様に従う任意のサーバーを受け入れます。コミュニティ MCP レジストリ github.com/modelcontextprotocol/servers には、Postgres、Puppeteer、Slack、GitHub、ファイルシステムバリアントなど、数百の統合がリストされています。
モデルバックエンドとして Novita AI を使用する
Claude Agent SDK はデフォルトで Anthropic の API を使用しますが、コードを変更せずに、Novita AI の Anthropic 互換エンドポイントを指定してコスト効率の高いオープンウェイトモデルを使用できます。
Novita AI のエンドポイントは Anthropic API 形式をミラーリングしています：
https://api.novita.ai/anthropic
エージェントを実行する前に、次の2つの環境変数を設定します：
export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_API_KEY="your-novita-api-key"
既存の query() 呼び出しは変更なしで動作します。SDK は自動的に ANTHROPIC_BASE_URL を読み取ります。
Novita AI は、Kimi K2.5、GLM 5.2、MiniMax M2.1、Qwen 3.5 など、このエンドポイントからアクセス可能な幅広いモデルをホストしています。数千のタスクを実行するエージェントパイプラインを構築するチームにとって、トークンあたりのコスト差は大きくなる可能性があります。最新のモデルカタログと価格については、Novita AI LLM API を参照してください。
エージェントを分離されたサンドボックスインフラストラクチャにデプロイする必要がある場合（エージェントがホストのファイルシステムに触れないようにするエージェントコード実行に有用）、Novita Agent Sandbox は、Claude Agent SDK 上に構築されたエージェント向けに特別に設計された E2B 互換の実行環境を提供します。
CI/CD パイプラインでの Claude Code SDK
SDK の permission_mode="acceptEdits" と allowed_tools の制限により、CI でエージェントを無人実行することが実用的です。一般的な GitHub Actions のパターン：
- name: 自動コードレビューを実行
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
python review_agent.py
ここで review_agent.py は次のような内容です：
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="この PR で変更されたすべての Python ファイルを、正当性とテストカバレッジのギャップについてレビューしてください。JSON レポートを出力してください。",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep", "Bash"],
permission_mode="acceptEdits",
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
リポジトリに書き戻すエージェント（自動リファクタリング、ドキュメント生成）の場合は、変更が git に到達する前に検証する PostToolUse フックと組み合わせます。
トラブルシューティング
No matching distribution found for claude-agent-sdk
Python バージョンが 3.10 未満です。python3 --version を実行して、必要に応じてアップグレードしてください。
ANTHROPIC_API_KEY is not set
SDK は環境変数を必要とします。実行前にシェルまたは .env ファイルでエクスポートしてください。
TypeScript エージェントが完了前に終了する
イテレーターのループ全体を await していることを確認してください。SDK はプロセスが終了する前にすべてのメッセージイベントを処理する必要があります。
エージェントが予期しないツールを使用する
allowed_tools を使用してツールセットを明示的に制限してください。指定しない場合、エージェントはすべての組み込みツールにアクセスできます。
サブエージェントのメッセージが出力に表示されない
parent_tool_use_id が設定されているメッセージをフィルタリングして、メインエージェントとは別にサブエージェントの出力を特定してください。
セッションが正しく再開されない
最初のクエリの開始時に、subtype === "init" の SystemMessage から session_id を取得してください。結果メッセージからではないことに注意してください。
FAQ
Claude Code SDK と Anthropic SDK の違いは何ですか？
Claude Agent SDK（旧 Claude Code SDK）は、ツール実行を自動的に処理する自律型エージェントを提供します。Anthropic Client SDK は、ツールループを自分で実装する必要がある生の API アクセスを提供します。エージェントパイプラインには Agent SDK を、正確な制御が必要な直接モデル呼び出しには Client SDK を使用してください。
claude-agent-sdk に必要な Python バージョンは？
Python 3.10 以降です。Python 3.9 以前ではパッケージはインストールされません。
TypeScript SDK を使用するには Claude Code CLI をインストールする必要がありますか？
いいえ。@anthropic-ai/claude-agent-sdk パッケージは、独自のネイティブ Claude Code バイナリをオプションの依存関係としてバンドルしています。
Claude Agent SDK は Anthropic の Claude 以外のモデルも使用できますか？
ANTHROPIC_BASE_URL を https://api.novita.ai/anthropic などの Anthropic 互換エンドポイントに設定することで、そのプロバイダーがホストする任意のモデル（Kimi、GLM、MiniMax、Qwen のオープンウェイトモデルを含む）を使用できます。
Agent SDK は Claude Managed Agents とどう違うのですか？
Managed Agents は、Anthropic が自社インフラストラクチャでエージェントを実行するホスト型 REST API です。Agent SDK は、独自のプロセス内で、独自のファイルシステム上でエージェントループを実行するライブラリです。Agent SDK はローカル開発や、プライベートファイルやサービスにアクセスする必要があるエージェントに適しています。
Claude Agent SDK はストリーミング出力をサポートしていますか？
query() 関数は、エージェントが作業するにつれてメッセージを生成する非同期イテレーターを返します。これにより、最終的な回答の前に中間結果が表示されるストリーミングのような動作が得られます。
Agent SDK を Amazon Bedrock や Vertex AI で使用できますか？
はい。Bedrock の場合は CLAUDE_CODE_USE_BEDROCK=1 と AWS 認証情報を、Vertex AI の場合は CLAUDE_CODE_USE_VERTEX=1 と Google Cloud 認証情報を設定してください。
最初に読むべき anthropic claude agent sdk のドキュメントは？
公式ドキュメントは code.claude.com/docs/en/agent-sdk/overview にあります。クイックスタートから始め、動作するエージェントができたらセッションとフックのガイドを読んでください。
おすすめ記事
- Claude Code CLI ドキュメント：セットアップ、スラッシュコマンド、LLM API 統合
- Vercel AI SDK：AI アプリケーション構築のための完全開発者ガイド
- Novita Sandbox で Claude Agent SDK をデプロイおよびホストする方法
情報源：2026年7月3日確認：Claude Agent SDK ドキュメント、Novita AI LLM API
