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（現在は正式にClaude Agent SDKと名称変更）は、PythonおよびTypeScriptのライブラリで、あなたのアプリケーション内でClaudeを自律型エージェントとして実行できます。プロンプトを与えると、ファイルの読み取り、コマンドの実行、コードの編集、タスク完了までの反復処理をすべて自動で行います。ツールループを記述する必要も、ストリーミングの配管を管理する必要もありません。

このガイドでは、開発者が始めるために必要なすべてをカバーします：インストール、コアの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実行、ウェブ検索などをカバーしており、実装は不要です。
セッションにより、エージェントは完全なコンテキストを保持したまま複数の呼び出しにわたって作業を再開できます。
フックを使用すると、特定のライフサイクルポイントでツール呼び出しを検証、ログ記録、またはブロックできます。
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における自動コードレビュー、リファクタリング、テスト生成
ファイルの読み取り・変更、スクリプトの実行、代理でのウェブ検索を行うエージェント
コーディネーターが専門ワーカーにサブタスクを委任するマルチエージェントパイプライン
プロンプトに答えるだけでなく、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
# plus standard AWS credentials

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
# plus GOOGLE_CLOUD_PROJECT and gcloud credentials

# Microsoft Azure AI Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
# plus Azure credentials

ステップ2：最初のエージェントクエリを実行する

SDK全体は単一の関数 query() を中心に構築されています。プロンプトとオプションを受け取り、メッセージイベントの非同期イテレータを返します。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="List all Python files 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: "List all Python files in this directory",
  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	現在の情報をウェブ検索する
WebFetch	ウェブページのコンテンツを取得して解析する
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="Review this codebase for security issues and code smell",
    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="Refactor auth.py to use dataclasses",
        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 auth.ts to use interfaces",
  options: {
    permissionMode: "acceptEdits",
    hooks: {
      PostToolUse: [{ matcher: "Edit|Write", hooks: [logFileChange] }]
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

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

ステップ5：セッションで作業を再開する

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

セッションを再開するには、SystemMessageのinitイベントからsession_idを取得し、それをresumeに渡します：

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

async def main():
    session_id = None

    # First query: read and analyze the codebase
    async for message in query(
        prompt="Read the authentication module and identify all external dependencies",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
    ):
        if isinstance(message, SystemMessage) and message.subtype == "init":
            session_id = message.data["session_id"]

    # Second query: continue with full context from the first
    async for message in query(
        prompt="Now check if any of those dependencies have known vulnerabilities",
        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="Review this codebase: use the security-auditor agent for auth files and the style-checker agent for everything else",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "security-auditor": AgentDefinition(
                    description="Specialist in authentication and authorization security.",
                    prompt="Audit auth-related code for OWASP Top 10 vulnerabilities. Be specific about line numbers and risk severity.",
                    tools=["Read", "Glob", "Grep"],
                ),
                "style-checker": AgentDefinition(
                    description="Code style and maintainability reviewer.",
                    prompt="Check code for naming conventions, complexity, and documentation gaps.",
                    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="Open https://example.com and describe the page structure",
        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="Review all changed Python files in this PR for correctness and test coverage gaps. Output a JSON report.",
        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 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