Claude Agent SDK（旧Claude Code SDK）：PythonおよびTypeScriptガイド

主なポイント
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 バックエンドを超えてモデル選択とコスト管理の選択肢を得られます。サブスクリプションと API の比較については、Claude API 価格とサブスクリプションプランをご覧ください。

このガイドでは、開発者が始めるために必要なすべてを網羅します：インストール、コアAPI query()、組み込みツール、フック、セッション、サブエージェント、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 が対話的に使用するのと同じツール、推論ループ、コンテキスト管理を公開しますが、ライブラリとしてインポートして独自のコードから呼び出せます。プロジェクトレベルのルールとスコープについては、Claude Code ルールと CLAUDE.md をご覧ください。

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 認証情

# Micosoft 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 フィルドを持つメッセージ）— エジェントの最終応答
subtype === "init" の SystemMessage — 後で再開するための 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 や WebFectch を追します。

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()}: modified {file_path}\n")
    return {}

async def main():
    async for message in query(
        prompt="auth.py をデーカラスを使用するようにリファクリング",
        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: "auth.ts をインターフェースを使用するようにリファクタリング",
  options: {
    permissionMode: "acceptEdits",
    hooks: {
      PostToolUse: [{ matcher: "Edit|Write", hooks: [logFileChange] }]
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

PreToolUse フックが { block: true } を返すと、ツール呼び出しを完全に防止します — 自動コンテキストで「ファイルを決して削除しない」のようなポリシーを強制するのに役立ちます。

ステップ5: セッションを使用した作業の再開

セッションは、エージェントの完全なコンテキスト（読み取ったファイル、見つけた内容、会話履歴）を複数の query() 呼び出しにわたって保持します。これにより、長いタスクをステップに分割したり、中断された作業を続行したりできます。

セッションを再開するには、SystemMessage 初期化イベントから 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: Run automated code review
  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 はホスト型 REST API で、Anthropic が自社インフラでエージェントを実行します。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 Agent SDK（旧Claude Code SDK）：PythonおよびTypeScriptガイド

主なポイント

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 SDK を使用するために Claude Code CLI をインストールする必要がありますか？

Claude Agent SDK は Anthropic の Claude 以外のモデルを使用できますか？

Agent SDK と Claude Managed Agents の違いは何ですか？

Claude Agent SDK はストリーミング出力をサポートしていますか？

Agent SDK を Amazon Bedrock や Vertex AI で使用できますか？

最初に読むべき anthropic claude agent sdk のドキュメントは？

おすすめ記事

Product

RESOURCES

Partners

Company

主なポイント

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 SDK を使用するために Claude Code CLI をインストールする必要がありますか？

Claude Agent SDK は Anthropic の Claude 以外のモデルを使用できますか？

Agent SDK と Claude Managed Agents の違いは何ですか？

Claude Agent SDK はストリーミング出力をサポートしていますか？

Agent SDK を Amazon Bedrock や Vertex AI で使用できますか？

最初に読むべき anthropic claude agent sdk のドキュメントは？

おすすめ記事

関連記事

Product

RESOURCES

Partners

Company