Claude Agent SDKとは？使い方・料金【2026年8月】

Claude Agent SDKとは、Anthropicが公式提供するAIエージェント自社実装ライブラリです。もともとは「Claude Code SDK」という名前でしたが、2025年9月29日に「Claude Agent SDK」へ改名されました。Claude Codeを動かしているのと同じツール実行・エージェントループ・コンテキスト管理を、PythonとTypeScriptから直接プログラムできます。2026年8月時点でGitHub starsはPython版8,006・TypeScript版1,723（Anthropic公式リポジトリ調べ）、npmの週間ダウンロード数は約1,298万件です。

この記事の要点:

• 要点1: 「Claude Code SDK」は現在の正式名称ではありません。2025年9月29日にAnthropicが「Claude Agent SDK」へ改名しており、パッケージ名・オプション型名も変更されています（詳細は後述）
• 要点2: 2026年8月時点でSonnet 5（$2/$10・per 1Mトークン）が本番実装の新しいスイートスポットに加わりました。長文脈（1Mトークン）でも追加料金はかかりません
• 要点3: OpenAI Agents SDK・LangGraph・AWS Bedrock AgentCoreとの使い分け基準に加え、Anthropicホスティング型の「Managed Agents」との関係も整理しています

対象読者: AIエージェントの自社実装を検討中のエンジニア・DX推進担当・開発責任者
読了後にできること: Claude Agent SDKのPython/TypeScriptコードを動かして、最初のエージェントを5分で起動できる。旧「Claude Code SDK」と何が違うのか、Claude Pro/Maxのサブスクで動くのかを人に説明できる

「AIエージェントを自社で実装したいけど、どのSDKを選べばいいかわからない」

企業向けAI研修をしていると、この質問を本当によくいただきます。2026年に入ってからOpenAI、Anthropic、AWS、LangChainがそれぞれエージェントSDKをリリースまたは大幅アップデートし、「どれを使えばいいのか」という混乱が一気に増した印象があります。

先日も、DX推進担当の方から「Anthropicのドキュメントを見たら旧Claude Code SDKが消えていてClaude Agent SDKになっていた。移行が必要なのか、そもそも何が変わったのか教えてほしい」というご相談を受けました。名前が変わっただけなのか、機能的に別物なのか、確かにわかりづらいですよね。

この記事では、Claude Agent SDKの最新仕様（2026年8月時点）を、公式ドキュメント・公式ブログ・GitHub CHANGELOGを直接確認しながら解説します。コピペして動くPython/TypeScriptのサンプルコード、主要SDKとの比較表、Managed Agentsとの使い分け、自社実装で踏みがちな落とし穴も全部まとめています。

AIエージェント開発の技術選定、ぜひこの記事を判断材料にしてください。

Claude Agent SDKとは何か — まず5分で動かしてみる

Claude Agent SDKは、Anthropicが公開しているAIエージェント実装ライブラリです。「旧SDK」という言い方をしましたが、実態は名称変更＋機能大幅追加です。Claude Codeを動かしているのと同じツール実行ループ・コンテキスト管理・ファイル読み書き・Bash実行を、Pythonまたは TypeScript のコードから直接プログラムできます。

公式ドキュメントの説明を引用すると「Build AI agents that autonomously read files, run commands, search the web, edit code, and more」。ファイル読み込み、コマンド実行、ウェブ検索、コード編集が全てビルトインで使えるのが最大の特徴です。自分でツール実行ループを実装する必要がありません。対応言語はPythonとTypeScriptのみで、2026年8月時点でJava等の公式SDKはありません（後述の比較表を参照）。

インストールと最初のエージェント（Python）

pip install claude-agent-sdk

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="このディレクトリにあるPythonファイルを全て列挙して、各ファイルの役割を1行で説明してください",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob", "Read"]),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

これだけです。エージェントが自分でGlobでファイルを探し、Readで内容を読み、結果をまとめて返してきます。ツールの実行ループは全部SDKが内部で処理します。

インストールと最初のエージェント（TypeScript）

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

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

async function main() {
  for await (const message of query({
    prompt: "このディレクトリにあるPythonファイルを全て列挙して、各ファイルの役割を1行で説明してください",
    options: { allowedTools: ["Bash", "Glob", "Read"] }
  })) {
    if ("result" in message) console.log(message.result);
  }
}

main();

TypeScript版はnpm install @anthropic-ai/claude-agent-sdkだけで動きます。Claude Code CLIのネイティブバイナリがオプション依存として同梱されているので、Claude Codeを別途インストールする必要はありません。

なお、APIキーの設定は環境変数1行です。

export ANTHROPIC_API_KEY=your-api-key

AIエージェントの基本概念や導入ステップについては、AIエージェント導入完全ガイドで体系的にまとめています。エージェントの使い方からセキュリティ設計まで網羅しています。

Claude Code SDKとClaude Agent SDKの違い（名称変更の経緯）

「claude code sdk」で検索して旧名称のページが見当たらず戸惑う方が今でも少なくないようです。Claude Code SDKとClaude Agent SDKは別物ではなく、同じライブラリの旧名称と新名称です。

Anthropicは2025年9月29日公開の公式ブログ記事で改名を発表しました。原文は次の一文です。

“To reflect this broader vision, we’re renaming the Claude Code SDK to the Claude Agent SDK.”

背景は、Claude Codeを動かすエージェントハーネスが、コーディング支援の枠を超えてリサーチ・動画作成・メモ取りなど非コーディング用途にも広く使われるようになったことです。単なる呼び方の変更ではなく「コーディングツールのSDK」から「汎用エージェント基盤のSDK」への再定義、という位置付けです。

改名にともなうパッケージ名・型名の主な変更点は次の通りです（公式移行ガイドより）。

もう1つ地味に効くのがシステムプロンプトのデフォルト挙動です。旧SDKはデフォルトでClaude Code相当のシステムプロンプトを読み込んでいましたが、Claude Agent SDK（v0.1.0以降）はデフォルトで最小限のシステムプロンプトになりました。旧挙動が必要な場合はsystem_prompt（TypeScriptはsystemPrompt）に{"type": "preset", "preset": "claude_code"}を明示的に指定してください。

旧パッケージ（claude-code-sdk / @anthropic-ai/claude-code）は環境によっては引き続きインストールできる場合がありますが、新規プロジェクトで使う理由はありません。既存プロジェクトで旧パッケージを使っている場合は、公式の移行ガイドに沿ってclaude-agent-sdk / @anthropic-ai/claude-agent-sdkへ切り替えてください。

Claude Agent SDKの使い方｜インストール〜最初のエージェント起動（2026年8月最新）

ここでは公式Quickstart（2026年8月時点）に沿って、環境構築から最初のエージェントが動くまでの手順をまとめます。前提はNode.js 18以上またはPython 3.10以上です。

Python版のセットアップ（uv推奨）

uvなら依存管理・仮想環境を自動でやってくれます（公式Quickstart推奨）。

uv init
uv add claude-agent-sdk

pip + venvでも問題ありません。

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

TypeScript版のセットアップ

npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

"type": "module"はトップレベルawaitを使うための設定です。CommonJSのままにしたい場合は、ファイル拡張子を.mtsにすれば変換なしで動きます。

APIキーの設定

export ANTHROPIC_API_KEY=your-api-key

SDKは実行プロセスの環境変数からキーを読みます。.envファイルは自動で読み込まれないので、必要であればdotenv等で自分で読み込む処理を入れてください。

最初のエージェント — バグ修正エージェント

公式Quickstartのサンプルは、コードのバグを自動で見つけて直すエージェントです。

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

async def main():
    async for message in query(
        prompt="utils.pyのバグを確認し、クラッシュの原因になる問題があれば修正してください。",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")

asyncio.run(main())

TypeScript版もmessage.typeで判定する同じ構造で書けます（具体例は次章のサンプルコードを参照）。Python実行はuv run agent.py、TypeScript実行はnpx tsx agent.tsです。動いたら、次章以降で機能（フック・サブエージェント・MCP）を広げていってください。

Claude Agent SDKの主要機能5つ — 実装例つき

公式ドキュメントとCHANGELOGを読んで確認した、2026年8月時点での主要機能を実装例つきで解説します。

機能1: ビルトインツール — ファイル読み書き・コマンド実行がすぐ使える

Claude Agent SDKには以下のツールが標準搭載されています。

実際に研修先でよく使うのがコードベース調査エージェントです。こんな感じで書くと、TODOコメントを全部まとめてくれます。

async for message in query(
    prompt="コードベース全体からTODOコメントを探し、優先度別に整理してください",
    options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
):
    if hasattr(message, "result"):
        print(message.result)

ポイントはallowed_toolsで許可するツールを明示的に指定すること。不要なツールを渡さないのがセキュリティのベストプラクティスです。

機能2: フック — エージェントの動作に介入する

v0.1.74で大幅強化されたのがフック機能です。エージェントがツールを使う前後・セッション開始終了・ユーザープロンプト送信など、ライフサイクルの各ポイントでカスタムコードを実行できます。

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):
    """ファイル変更をaudit.logに記録するフック"""
    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 block_sensitive_files(input_data, tool_use_id, context):
    """本番設定ファイルへの書き込みをブロックするフック"""
    file_path = input_data.get("tool_input", {}).get("file_path", "")
    if "production" in file_path or ".env.prod" in file_path:
        return {"decision": "deny", "reason": "本番設定ファイルへの書き込みは禁止されています"}
    return {}

async def main():
    async for message in query(
        prompt="コードをリファクタリングしてください",
        options=ClaudeAgentOptions(
            permission_mode="acceptEdits",
            hooks={
                "PostToolUse": [
                    HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
                ],
                "PreToolUse": [
                    HookMatcher(matcher="Write", hooks=[block_sensitive_files])
                ]
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

v0.1.74以降ではdefer決定（承認の先送り）とupdatedToolOutput（ツール出力をモデルに渡す前に書き換える）も追加されました。企業向けの監査ログ・アクセス制御の実装に使えます。

機能3: サブエージェント — 並列・専門分担でスループットを上げる

Anthropicはサブエージェントを「メインエージェントが集中した子タスクを処理する専門エージェントを生成する」と説明しています。allowedToolsにAgentを含めると使えます。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="code-reviewerエージェントを使ってこのコードベースをレビューしてください",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "code-reviewer": AgentDefinition(
                    description="コード品質・セキュリティの専門レビュアー",
                    prompt="コードの品質を分析し、改善提案をしてください。セキュリティリスクも確認すること。",
                    tools=["Read", "Glob", "Grep"],
                )
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

サブエージェントのメッセージにはparent_tool_use_idフィールドが付くので、どのサブエージェントから来たメッセージかをトラッキングできます。大規模なコードベース解析・複数ファイルの並列処理に効きます。

Claude Code Sub-Agentsの詳細な使い方（並列タスク委任・実装パターン）についてはClaude Code Sub-Agents完全ガイド、業務での並列活用イメージはサブエージェント完全ガイド｜AIエージェント並列活用の仕組みと業務例も参照してください。

機能4: MCP（Model Context Protocol）— 外部システムと接続する

MCPはデータベース・ブラウザ・外部APIをエージェントに接続するためのプロトコルです。Claude Agent SDKはMCPをネイティブサポートしています。2026年8月時点でPython SDKにはインプロセスのSDK MCPサーバー向けにMCP 2.x対応も追加されています。

# Playwright MCPでブラウザ操作エージェントを作る例
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="example.comを開いて、メインコンテンツを要約してください",
        options=ClaudeAgentOptions(
            mcp_servers={
                "playwright": {
                    "command": "npx",
                    "args": ["@playwright/mcp@latest"]
                }
            }
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Slack・GitHub・データベースなど、数百のMCPサーバーが公開されています。独自認証コードを書かなくても外部サービスと連携できるのが実務上の大きな利点です。自社でMCPサーバーを構築する場合の実装パターンはMCP Server構築完全ガイド2026、Claude CodeでのMCP設定・運用はClaude Code MCP完全ガイド2026で詳しく解説しています。

機能5: セッション継続 — 長いタスクを分割して処理する

v0.1.73で追加されたEager Session Flushingにより、セッションのリアルタイム書き出しが可能になりました。複数回のqueryを通じてコンテキストを保持できます。

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

async def main():
    session_id = None

    # 第1回のクエリ — セッションIDを取得
    async for message in query(
        prompt="認証モジュールを読んで、ざっくり説明してください",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"]),
    ):
        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),
    ):
        if isinstance(message, ResultMessage):
            print(message.result)

asyncio.run(main())

コンテキストが保持されるので、「それ」「さっきの関数」のような自然な会話ができます。長時間のタスクを段階的に処理するときに重宝します。

主要エージェントSDK比較 — Claude・OpenAI・LangGraph・Bedrock AgentCoreの使い分け表

2026年時点で主要なエージェントSDKは4つに集約されています（Claude Agent SDKの列は2026年8月時点で再確認、他社SDKの列は公式で確認できた項目のみ更新）。

どれを選ぶか — ユースケース別の推奨

正直に言うと、Claude Agent SDKはLangGraphほどグラフ構造を可視化できないし、OpenAI Agents SDKのように最新トレーシングが内蔵されているわけでもありません。ただ「Claudeを使う」と決めているなら、公式SDKで一番ドキュメントが整っていて、公式サポートも受けやすい。そこが最大の利点です。

他のAIエージェントプラットフォーム（Salesforce Agentforce）との比較についてはSalesforce Agentforce完全ガイドも参考になります。ノーコードアプローチとSDKアプローチの違いがわかります。

料金体系と実際のコスト — 1エージェント実行でいくらかかるか

Claude Agent SDKの料金は「使用モデルのAPIトークン料金と同じ」です。SDK固有の追加料金は基本的にありません。Managed Agents（後述）を使う場合はトークン料金に加えてセッション実行時間の課金（1セッション時間あたり$0.08）が発生します。

2026年8月時点のモデル別料金（per 1Mトークン）

旧モデル（Opus 4.7: $5/$25、Sonnet 4.6: $3/$15）も引き続き利用できますが、単価が下がったSonnet 5から検討するのが基本です。なお、Opus 4.7以降とMythos Previewは新しいトークナイザーを採用しており、旧モデル比で体感トークン数が増えることがある点は公式資料でも触れられています（Sonnet 5・Sonnet 4.6・Haiku 4.5は旧来のまま）。

重要なポイントが2つあります。

まず、長文脈（1Mトークン）でも追加料金はかかりません。この仕様はClaude 4.6以降のモデルとClaude Mythos Previewが対象で、2026年8月時点でも維持されています。90万トークンのリクエストも9,000トークンのリクエストも、1トークンあたりの単価は同じです。大規模コードベース解析で使いやすくなりました。

次に、バッチ処理は50%オフになります。リアルタイム性が不要なタスク（夜間のコード解析・一括ドキュメント生成等）はバッチAPIで半額です（Managed Agentsのセッション実行にはこのバッチ割引は適用されません）。

実際のコスト感（Autoolize社の実績データ）

• 中規模コードベースのバグ修正エージェント: $0.05〜$0.50/実行（Sonnet 4.6）
• リサーチエージェント（Web検索込み、複数ファイル読み込み）: $0.20〜$1.00/実行
• 日次バッチ（5,000〜50,000リクエスト/日）: Sonnet 4.6で月額$450〜$4,500相当

上記はSonnet 4.6時代の実績値です。2026年8月時点のSonnet 5（$2/$10）に置き換えると単価ベースで約3分の1コストダウンする計算になります（単価のみの試算・実際は変動します）。

コスト最適化のポイントはallowed_toolsを絞ることです。不要なツールを渡すとエージェントが余計な探索をして無駄なトークンを消費します。本番環境では必要最小限のツールセットを渡しましょう。

実装例 — よくあるユースケース4パターン

研修や顧問先での実装支援で「これが一番わかりやすい」と言われるパターンをまとめます。

パターン1: コードレビューエージェント（read-only・安全）

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def code_review_agent(repo_path: str):
    """
    指定リポジトリのコードをレビューするread-onlyエージェント
    Write系ツールを渡さないことで安全性を担保
    """
    async for message in query(
        prompt=f"""
        {repo_path} のコードをレビューしてください。
        以下の観点で確認し、問題点をMarkdownでまとめること:
        1. セキュリティリスク（SQLインジェクション・XSS・認証不備等）
        2. パフォーマンス問題（N+1クエリ・不要なループ等）
        3. コードの可読性・保守性
        4. テスト不足

        問題点は重要度（CRITICAL/HIGH/MEDIUM/LOW）を付けて列挙すること。
        不足している情報があれば最初に質問してください。
        """,
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep"],  # Write系は渡さない
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(code_review_agent("./src"))

パターン2: ドキュメント自動生成エージェント

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def doc_generator_agent():
    """
    コードを読んでAPIドキュメントを自動生成するエージェント
    """
    async for message in query(
        prompt="""
        src/ ディレクトリのPythonファイルを全て読んで、
        docs/api-reference.md に APIリファレンスを生成してください。

        形式:
        - 各モジュール・関数・クラスをMarkdownで記述
        - 引数・戻り値の型と説明
        - 使用例（コードブロック付き）
        - 各関数の副作用・注意点

        仮定した点は必ず"仮定"と明記してください。
        """,
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Write"],
            permission_mode="acceptEdits",
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(doc_generator_agent())

パターン3: 複数ファイルの並列処理（TypeScript版）

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

async function translateDocuments(files: string[]) {
  // 複数エージェントを並列起動して複数ファイルを同時処理
  const promises = files.map(async (file) => {
    const messages: string[] = [];
    for await (const message of query({
      prompt: `${file} を日本語に翻訳し、${file.replace('.en.md', '.ja.md')} として保存してください。
      専門用語は英語のまま（日本語で括弧説明を付ける）。
      翻訳時に補足した情報があれば訳注として追記すること。`,
      options: {
        allowedTools: ["Read", "Write"],
        permissionMode: "acceptEdits"
      }
    })) {
      if ("result" in message) messages.push(message.result as string);
    }
    return { file, result: messages.join("n") };
  });

  const results = await Promise.all(promises);
  results.forEach(({ file, result }) => {
    console.log(`完了: ${file}`);
    console.log(result);
  });
}

// 10ファイルを並列処理
translateDocuments([
  "docs/getting-started.en.md",
  "docs/api-reference.en.md",
  "docs/troubleshooting.en.md",
  // ... 他のファイル
]);

パターン4: セキュリティ監査エージェント（フック付き）

import asyncio
import json
from datetime import datetime
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher

security_findings = []

async def capture_security_finding(input_data, tool_use_id, context):
    """Bashコマンドの実行を全てログに記録するフック"""
    command = input_data.get("tool_input", {}).get("command", "")
    security_findings.append({
        "timestamp": datetime.now().isoformat(),
        "command": command,
        "tool_use_id": tool_use_id
    })
    return {}

async def security_audit_agent():
    async for message in query(
        prompt="""
        このリポジトリのセキュリティ監査を実施してください:
        1. .env ファイルや secrets ファイルが git に含まれていないか確認
        2. ハードコードされたAPIキー・パスワードがないか検索
        3. 依存関係に既知の脆弱性がないか確認（pip audit または npm audit）
        4. ファイルパーミッションの問題がないか確認

        発見した問題は重大度別に分類して報告すること。
        数字と固有名詞は根拠を添えてください。
        """,
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Bash"],
            hooks={
                "PostToolUse": [
                    HookMatcher(matcher="Bash", hooks=[capture_security_finding])
                ]
            }
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

    # 監査ログを保存
    with open("./security-audit-log.json", "w") as f:
        json.dump(security_findings, f, ensure_ascii=False, indent=2)
    print(f"n監査ログ保存完了: {len(security_findings)} コマンドを記録")

asyncio.run(security_audit_agent())

Claude Agent SDK vs 生のAnthropicクライアントSDK — どちらを使うべきか

「Claude Agent SDKじゃなくて、普通のanthropicパッケージじゃダメなの？」という質問も研修でよく受けます。整理します。

Anthropicクライアントライブラリ（anthropicパッケージ）を使うべき場面:

• チャットボット・QA・テキスト生成など、ツール実行を伴わないシンプルな用途
• ツールループを自分で細かく制御したい（カスタムロジックが複雑な）場合
• 他のLLMも組み合わせて使う場合

Claude Agent SDKを使うべき場面:

• ファイル操作・コマンド実行・ウェブ検索などのツール実行が必要なエージェント
• CI/CDパイプライン・本番自動化
• カスタムアプリケーションへのClaude Code機能の組み込み
• 複数のサブエージェントを並列で動かしたい場合

公式ドキュメントにある比較が端的で分かりやすいです。

# クライアント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, **params)

# Agent SDK: Claudeが自律的にツールを処理する
async for message in query(prompt="auth.pyのバグを修正して"):
    print(message)

エージェントに「自律的にファイルを読んで考えて実行してほしい」なら迷わずAgent SDKです。

【要注意】よくある失敗パターンと回避策

企業向けAI研修やエージェント実装支援の現場で実際に見てきた失敗パターンを紹介します。

失敗1: allowed_toolsを渡さずにエージェントを動かす

❌ よくある間違い

# allowed_tools を指定しないと、デフォルトで全ツールが使用可能になる
async for message in query(prompt="認証システムを修正してください"):
    print(message)

⭕ 正しいアプローチ

# 必要最小限のツールだけ渡す
async for message in query(
    prompt="認証システムを修正してください",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Grep"],  # Bashは渡さない（コマンド実行させない）
    )
):
    print(message)

なぜ重要か: 不必要なツールを渡すと、エージェントが意図しない操作（rm -rf等）を実行するリスクがあります。本番環境では最小権限の原則を徹底してください。

失敗2: 本番DBに直接つないでエージェントを動かす

❌ よくある間違い: ステージング環境なしにいきなり本番DBの認証情報をエージェントに渡す

⭕ 正しいアプローチ: ステージングで十分テストしてから本番へ。本番で使う場合もread-onlyユーザーのみ渡す。フックでDELETE/DROP文を検知して拒否する実装を入れる。

実際に顧問先で見たケースですが、「動作確認のつもり」でエージェントに本番DB接続情報を渡したら、エージェントが自分でデータ整理を始めて数千件のレコードを削除しようとしました。フックで止まりましたが、フックを入れていなければアウトでした。

失敗3: セッションをまたぐコンテキストの想定ミス

❌ よくある間違い

# session_idなしで2回目を呼ぶと前回の会話を全く覚えていない
first_result = await run_query("認証モジュールを読んでください")
second_result = await run_query("さっき読んだ部分のバグを直してください")  # NG: さっき読んだ = ?

⭕ 正しいアプローチ

# session_id を取得して resume で引き継ぐ
session_id = get_session_id_from_first_run()
second_result = await run_query("さっき読んだ部分のバグを直してください", resume=session_id)  # OK

なぜ重要か: デフォルトではqueryを呼ぶたびに新しいセッションが始まります。前回の会話を参照させたい場合は必ずresume=session_idを指定してください。

失敗4: Opus 4.7でSDKバージョンが古い

❌ エラー: thinking.type.enabled API error

⭕ 対策: Opus 4.7はAgent SDK v0.1.111以上が必要です（TypeScript版は v0.2.111以上）。エラーが出たらpip install --upgrade claude-agent-sdkを実行してください。

pip install --upgrade claude-agent-sdk
# または
npm install @anthropic-ai/claude-agent-sdk@latest

Bedrock・Vertex AI・Azure対応 — クラウド別の設定方法

Claude Agent SDKはAnthropicのAPIだけでなく、主要クラウドプロバイダー経由でも使えます。

Amazon Bedrock経由

export CLAUDE_CODE_USE_BEDROCK=1
# AWS認証情報を設定（~/.aws/credentials または 環境変数）
export AWS_DEFAULT_REGION=us-east-1

# あとは通常通りqueryを呼ぶだけ
import asyncio
from claude_agent_sdk import query

async def main():
    async for message in query(prompt="Bedrockでエージェントを動かす"):
        print(message)

asyncio.run(main())

Bedrockの料金はAnthropicのAPIと同じレートです。2026年8月時点の公式情報では、リージョンを固定するリージョナルエンドポイントを使う場合、グローバルエンドポイント比で約10%のプレミアムが加算されます。なお2026年にはAWS Marketplace経由のCCU（Claude Consumption Unit、1CCU=$0.01）課金となる「Claude Platform on AWS」も追加されています（環境変数CLAUDE_CODE_USE_ANTHROPIC_AWS=1 / ANTHROPIC_AWS_WORKSPACE_ID）。通常のBedrock経由とは請求方式が異なります。

Google Vertex AI経由

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-central1
export ANTHROPIC_VERTEX_PROJECT_ID=your-project-id

# Google Cloud認証
gcloud auth application-default login

Microsoft Foundry経由（旧Azure AI Foundry）

export CLAUDE_CODE_USE_FOUNDRY=1
export AZURE_ENDPOINT=https://your-endpoint.openai.azure.com
export AZURE_API_KEY=your-azure-api-key

Microsoft側のサービス名は「Azure AI Foundry」から「Microsoft Foundry」へ名称が変わっていますが、環境変数名CLAUDE_CODE_USE_FOUNDRY自体は変わっていません。

AWSはIAM管理・監査ログ・VPC内閉域が必要なエンタープライズ向け。GCPはVertex AIの他サービスとの統合が必要な場合。Microsoft Foundryは既存のMicrosoftエコシステムに乗っている場合に選ぶのが自然です。

Managed Agents との使い分け — 自前運用か、Anthropicホスティングか

Managed Agents（Claude Managed Agents）は、AnthropicがエージェントとサンドボックスをホスティングするREST APIサービスです。2026年8月時点でベータ提供で、リクエストにはmanaged-agents-2026-04-01ベータヘッダーが必要です（Agent SDK経由で利用する場合はSDKが自動で付与します）。Agent SDKとどう違うか整理します。

一般的なパスは「Agent SDKでローカルプロトタイプ → 本番はManaged Agentsに移行」です。どちらもAnthropicのClaudeモデルを使うので、コード変更は最小限で済みます。Managed Agentsは「Agent」「Environment」「Session」「Events」という4つの概念で構成されています。機微情報を扱う用途では、ZDR/HIPAA BAA未対応という制約を導入前に必ず確認してください。

料金の詳しいシミュレーションはClaude Managed Agents料金完全解説、セキュリティ設計はClaude Managed Agentsセキュリティ解説、API仕様の詳細はManaged Agents API解説で詳しく解説しています。

あわせて読みたい: OpenAIのSDKとの比較については、OpenAI Agents SDK完全ガイド2026も参考にしてください。Handoffs・Guardrails・Tracing・GPT-5.5対応の実装詳細を解説しています。

よくある質問（FAQ）

Claude Agent SDKは無料で使える？

SDK自体（Pythonのclaude-agent-sdk、TypeScriptの@anthropic-ai/claude-agent-sdk）はどちらもインストール自体は無料です。ただし実行時にはAnthropic APIのトークン従量課金がかかります。「SDKは無料、実行のたびにAPI利用料がかかる」というのが実態です。料金の目安は本記事の「料金体系と実際のコスト」を参照してください。

Claude CodeのサブスクでSDKは動く？

公式ドキュメントには「第三者の開発者が、自社製品のエンドユーザーにclaude.aiのログインやレート制限を提供することは、事前承認がない限り許可されていない（Agent SDKで構築したエージェントも対象）」という趣旨のNoteが明記されています。SDKの標準的な認証方法はAPIキー（ANTHROPIC_API_KEY環境変数）で、Claude Pro/Maxのサブスクリプションログインをそのまま自社エージェントに組み込む使い方は公式には想定されていません。個人検証を超えて業務利用する場合は、API課金前提で設計してください。

ホスティングはどうする？

自前ホスティングの場合、SDKはclaude CLIをサブプロセスとして起動する構造のため、公式ガイドではエージェント1体あたりRAM 1GiB・ディスク5GiB・CPU1コアが目安です。使い捨て型・常駐型・ハイブリッド型（アイドル時休止・SessionStoreで状態復元）・マルチエージェント型の4パターンから選びます。インフラコストはトークン費用より桁違いに小さいことが多いので、まず動かして様子を見るのが現実的です。自前インフラを持ちたくなければ、Anthropicホスティング型のManaged Agents（2026年8月時点でベータ）という選択肢もあります。

まとめ：今日から始める3つのアクション

Claude Agent SDKは「Claudeでエージェントを自社実装したい」なら現時点で最も手軽で公式サポートが手厚い選択肢です。旧名称の「Claude Code SDK」は2025年9月29日に改名されたもので、機能面では別物ではありません。2026年8月時点でPython/TypeScriptどちらもフック・サブエージェント・MCP・セッション継続が全て使え、料金面ではSonnet 5（$2/$10）という新しい選択肢も加わりました。

1. 今日やること: pip install claude-agent-sdk（またはuv add claude-agent-sdk）を実行して、この記事のパターン1（コードレビューエージェント）を手元のリポジトリで動かしてみる
2. 今週中: allowed_toolsを絞ったread-onlyエージェントで、社内のコードベース解析や定例レポート生成を自動化する
3. 今月中: フックを実装してaudit.logを出力し、エージェントの動作ログを蓄積。本番化・Managed Agentsへの移行判断の前提条件を満たす

参考・出典

• Agent SDK overview — Claude Code Docs — Anthropic公式（参照日: 2026-08-31）
• Migrate to Claude Agent SDK — Claude Code Docs — Anthropic公式（参照日: 2026-08-31）
• Hosting the Agent SDK — Claude Code Docs — Anthropic公式（参照日: 2026-08-31）
• claude-agent-sdk-python CHANGELOG — GitHub anthropics（参照日: 2026-08-30）
• claude-agent-sdk-typescript CHANGELOG — GitHub anthropics（参照日: 2026-08-30）
• Building Agents with the Claude Agent SDK — Anthropic公式ブログ（公開日: 2025-09-29／参照日: 2026-08-31）
• Pricing — Claude API Docs — Anthropic公式（参照日: 2026-08-31）
• 2026 AI Agent Framework Showdown — QubitTool（参照日: 2026-05-06）
• AIエージェント観測・評価完全ガイド：LangSmith/Langfuse/RAGAS/DeepEvalで本番品質を可視化
• AIエージェントMemory完全ガイド：Mem0/Zep/Lettaで永続記憶を実装、Core/Archival/Recall 3層モデル
• AI Voiceエージェント7強完全比較：Vapi/Retell/ElevenLabs/Deepgramほか電話AI比較
• AIカスタマーサポート7強完全比較：Decagon/Sierra/Intercom Fin等のCS AI基盤比較
• 士業のAI活用完全ガイド：税理士/社労士/弁護士/司法書士/行政書士の実践プロンプト10選
• Codex×経理 自動化プロンプト10選：経理特化10シーンで最大80%削減
• Codex×Excel自動化プロンプト10選：VBA/Apps Script/Power Query代替
• Codex×業務15選 部署別ガイド：営業/マーケ/人事/法務/経企/情シス/CSの15シーン

著者: 佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。早稲田大学法学部在学中に生成AIの可能性に魅了され、X（旧Twitter）で活用法を発信（@SuguruKun_ai、フォロワー約10万人）。100社以上の企業向けAI研修・導入支援を展開。著書『AIエージェント仕事術』（SBクリエイティブ）。SoftBank IT連載7回執筆（NewsPicks最大1,125ピックス）。

ご質問・ご相談はお問い合わせフォームからお気軽にどうぞ。

関連記事: MCP（Model Context Protocol）完全実装ガイド — Claude/Codex/Cursor統一プロトコルの実装ガイドです。

関連記事: AIエージェントセキュリティ完全ガイド｜OWASP対応 — AIエージェントのセキュリティ実装ガイドです。