Claude Agent SDK: エージェントの構築方法（2026）

TL;DR

• Claude Agent SDK は、自分のコード内で AI エージェントを構築するための Anthropic のライブラリです — Claude Code を支えるのと同じエージェントエンジンが、Python (3.10+) 向けの claude-agent-sdk および TypeScript 向けの @anthropic-ai/claude-agent-sdk として公開されています。
• 2025 年後半に `claude-code-sdk` から名称変更 されました。チュートリアルに ClaudeCodeOptions と書かれている場合、それは古い情報です — 現在のクラスは ClaudeAgentOptions です。
• ファイルツール、Bash、Web 検索、@tool によるカスタムツール、MCP サーバー（Jira や Shopify を接続する方法）、サブエージェント、フック、権限など、完全なエージェントループを無料で利用できます。支払うのは Claude API トークン分だけです。
• Anthropic Messages API と通信するため、ANTHROPIC_BASE_URL でゲートウェイを指定できます — 私たちは [Velokey](https://api.velokey.ai) の /v1/messages エンドポイントでテストし、クレジット課金の 1 つのキーで動作することを確認しました。

今は誰もがエージェントを作っていますが、多くのガイドは 10 行のクイックスタートで終わってしまいます。この記事ではその先を扱います。よくある Node の罠を避けてインストールする方法、Jira や Shopify のような実際のツールを接続する方法、実行に実際いくらかかるのか、そしてゲートウェイ経由でルーティングする方法です。さっそく見ていきましょう。

Claude Agent SDKとは何か？

Claude Agent SDKは、Claude Codeの内部で動作しているものと同じ自律型エージェントループを、自分のアプリケーションに提供するライブラリです。ファイルの読み書き、コマンドの実行、Web検索、ツールの呼び出しを、ツール呼び出しループを手書きすることなく行えます。AnthropicはPythonおよびTypeScript向けに提供しており、公式ドキュメントによれば、Claude上で本番環境向けエージェントを構築するためにサポートされている方法です。

ほとんどの人が見落としがちな重要な背景があります。以前はClaude Code SDKと呼ばれていました。Anthropicは2025年後半に、コーディングツールだけでなく*あらゆる*エージェントを構築するためのものだと示すため、名称をClaude Agent SDKに変更しました。パッケージ、import、そして中核となる1つのクラスがすべて変更されました — claude-code-sdkはclaude-agent-sdkになり、ClaudeCodeOptionsはClaudeAgentOptionsになりました。多くのブログ記事やStack Overflowの回答はいまだに古い名前を参照しているため、importが失敗する場合、通常はそれが理由です。

内部的には、SDKはClaude Code CLIをサブプロセスとしてラップします。PythonまたはTypeScriptのコードはSDKと通信し、SDKは同梱されたCLIを駆動し、CLIがClaudeと通信します。このアーキテクチャが重要である理由は2つあり、後で触れます。CLIはNodeバイナリであるため（Python SDKであってもNodeをインストールしておく必要があります）、またCLIはシステムプロンプトに対して積極的なプロンプトキャッシュを行うためです（これによりコスト計算が変わります）。

Claude Agent SDK をインストールして使用するには？

Claude Agent SDK を PyPI（または npm）からインストールし、API キーを設定して、query() を呼び出します — 動作するエージェントは約 ten lines です。Python は 3.10 以降が必要です:

pip install claude-agent-sdk
export ANTHROPIC_API_KEY="sk-ant-..."

最小構成のワンショットエージェントは次のとおりです。query() はメッセージの async iterator を返します:

import anyio
from claude_agent_sdk import query

async def main():
    async for message in query(prompt="List the Python files in this repo and summarize each."):
        print(message)

anyio.run(main)

インタラクティブまたはマルチターンの用途では、ClaudeSDKClient を使用し、ClaudeAgentOptions で設定します:

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

options = ClaudeAgentOptions(
    system_prompt="You are a careful code-review assistant.",
    allowed_tools=["Read", "Grep", "Glob"],
    permission_mode="acceptEdits",
    max_turns=10,
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Review auth.py for security issues.")
    async for msg in client.receive_response():
        print(msg)

ten-line quickstart には載っていない、つまずきやすいインストール時の注意点が 2 つあります:

Claude Agent SDK で何を構築できますか？

ファイルアクセス、コマンド実行、またはツール利用を必要とするあらゆるエージェントを構築できます — コードレビュー担当から、カスタマーサポートのトリアージ担当、データパイプラインのオペレーターまで。SDK は 5 つの構成要素を提供し、設計全体の主眼は、エージェントに何を許可するかを制御することにあります。

カスタムツールは最も扱いやすい部分です。関数をデコレートすると、エージェントがそれを直接呼び出せます — 別プロセスも、ネットワークホップも不要です。

from claude_agent_sdk import tool

@tool("get_order", "Look up an order by ID", {"order_id": str})
async def get_order(args):
    order = db.fetch(args["order_id"])
    return {"content": [{"type": "text", "text": str(order)}]}

フックと権限は、デモを無人で実行できるものに変える要素です。PreToolUse フックは、危険なパターンに一致する Bash コマンドをブロックできます。permission_mode は、エージェントが承認のために一時停止するか、編集を自動承認するかを決定します。本番環境では、ほとんどのチームが厳格な allowed_tools リストから始め、エージェントへの信頼が高まるにつれて範囲を広げます — これは、何でも許可するクイックスタートとは逆です。

6 つ目の構成要素、そして単一のエージェントが遅くなったときに人々が頼るものが、サブエージェントです。SDK は、スコープを限定したサブタスクを処理するために、独自のコンテキストを持つ新しいサブエージェントを生成し、その結果を返すことができます — Claude Code はこれを使ってファイル全体に処理を展開します。これは、「複数のことを並行して処理できるか」や「メインコンテキストがいっぱいになるのをどう防ぐか」に対する組み込みの答えです。ノイズの多い作業（10 個のファイルを読む、テストマトリクスを実行するなど）をサブエージェントに委任することで、メインエージェントは集中を保てます。セッションのフォークは、進行中の会話を分岐させるための関連テクニックです。

Jira または Shopify を Claude Agent SDK と統合するにはどうすればよいですか？

Jira、Shopify、または任意の外部システムは、その MCP server を ClaudeAgentOptions の mcp_servers に追加することで統合します。SDK には Jira 専用のコードはなく、オープンな Model Context Protocol を使用し、Atlassian と Shopify はどちらも MCP servers を提供しています。これは、最もよくある統合に関する質問（「Jira/Shopify を Claude Agent SDK に接続するにはどうすればよいか」）への答えです。特別なコネクタはなく、MCP server を登録してその tools を許可します。

パターンはどちらも同じです。SDK に MCP server（ローカルコマンドまたはリモート URL）を指定し、それが公開する tools を許可します。

options = ClaudeAgentOptions(
    mcp_servers={
        "jira": {
            "command": "npx",
            "args": ["-y", "@atlassian/mcp-server-jira"],
            "env": {"JIRA_API_TOKEN": os.environ["JIRA_API_TOKEN"]},
        }
    },
    allowed_tools=["mcp__jira__search_issues", "mcp__jira__create_issue"],
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Find open bugs assigned to me and summarize them.")
    async for msg in client.receive_response():
        print(msg)

サーバーブロックを @shopify/mcp-server（Shopify トークン付き）に差し替えれば、同じ agent で orders を読み取ったり products を更新したりできます。正しく設定すべき点は 2 つあります。tool 名は mcp__<server>__<tool> という規則に従うため、allowed_tools のエントリは完全に一致している必要があります。また、各 MCP server には env 内にそれぞれ独自の認証情報が必要です。agent が tool を利用できないと言う場合、ほとんどの場合は名前の不一致またはトークンの欠落であり、SDK のバグではありません。

ベンダーがローカルコマンドではなくリモート MCP server をホストしている場合は、command/args ではなく URL で登録します — {"jira": {"url": "https://mcp.atlassian.com/v1/sse"}} — すると SDK はネットワーク経由で接続します。ローカル（stdio）サーバーは開発ではよりシンプルで、トークンを自分のマシン上に保持できます。リモート（URL）サーバーは何もインストールせずに済みます。どちらの場合でも、allowed_tools とサーバーごとの認証情報に関するルールは同じです。

ゲートウェイ経由で Claude Agent SDK を実行するには？

ANTHROPIC_BASE_URL をゲートウェイのルートに設定すると、SDK は api.anthropic.com の代わりにすべてのリクエストをそこへ送信します。コード変更は不要です。SDK は標準の Anthropic 環境変数に従うため、Anthropic Messages API (/v1/messages) を公開している任意のバックエンドで動作します。たとえば、企業プロキシ、地域ブリッジ、統合ゲートウェイなどです。

これは、Anthropic 互換の /v1/messages エンドポイントを公開している [Velokey](https://api.velokey.ai) に対してテストしました。そこへのライブリクエストは、標準的な Messages レスポンス（stop_reason: end_turn、Anthropic 形式の usage）を返しました。これは SDK が期待するものと完全に一致します。

export ANTHROPIC_BASE_URL="https://api.velokey.ai"
export ANTHROPIC_API_KEY="sk-your-velokey-key"
# then run your agent as usual — set the model to one Velokey serves:

options = ClaudeAgentOptions(
    model="claude-sonnet-5",      # or claude-opus-4-8
    allowed_tools=["Read", "Grep"],
    max_turns=8,
)

そもそもなぜエージェントをゲートウェイ経由でルーティングするのでしょうか？別個の Anthropic アカウント、ティア、30 日保持設定を用意する代わりに 1 つのキーで済み、上限を設定できるクレジットベースの課金が使え、同じキーで [Claude Opus 4.8](/model/claude-opus-4-8)、[Claude Sonnet 5](/model/claude-sonnet-5)、および他の場所で使う可能性のあるモデルにもアクセスできます。プロキシが x-api-key ヘッダーの代わりに bearer token を要求する場合は、ANTHROPIC_API_KEY ではなく ANTHROPIC_AUTH_TOKEN を設定してください。これは、OpenAI 互換ツールをゲートウェイに向けるのと同じドロップインの考え方です。OpenAI 形式での同等手順については、Qwen CLI guide を参照してください。

Claude Agent SDK のコストはいくらですか？

SDK 自体は無料でオープンソースです — 支払うのは、エージェントが消費する Claude API トークンの料金であり、エージェントはそのトークンを大量に消費します。各ターンで増え続ける会話が再送信され、各ツール結果がコンテキストに戻され、たった 1 件の「このバグを修正して」というタスクでも 10 ターン以上実行されることがあります。ここがコスト面での意外な点です。コードは 10 行でも、トークン請求額はエージェントがどれだけ探索するかに応じて増えていきます。

コストを抑えるためのレバーは 3 つあり、そのうち最大のものは SDK に組み込まれています。

最後の行は理論上の話ではなく実際のものです。私たちのテストリクエストでは、レスポンスに数万の cache_read_input_tokens が報告されており、大きなシステムプロンプトが各ターンで再課金されるのではなく、入力価格のおよそ 10 分の 1 でキャッシュから提供されたことを意味します。これが、エージェントのコストがターン数から想像するほど過酷にならない主な理由です。モデルごとの詳しいトークン計算については、Claude API pricing guide を参照してください。エージェントを組み込む前に Claude モデルへの単一呼び出しを動かしてみたい場合は、how to call Claude with an API key で基本を説明しています。

よくある質問

Claude Agent SDK とは何ですか？

これは、Claude Code を支えるものと同じ自律型エージェントループを使用して、Python または TypeScript で AI エージェントを構築するための Anthropic 公式ライブラリです。ツール呼び出しループ、ファイル操作、コマンド実行、MCP 連携を代わりに処理してくれるため、オーケストレーションではなく、目標とツールを書くことに集中できます。支払うのは Claude API トークンの料金だけです。

Claude Agent SDK は Claude Code SDK と同じものですか？

はい — 名称変更されたバージョンです。Anthropic は 2025 年後半に claude-code-sdk を claude-agent-sdk に改名し、ClaudeCodeOptions は ClaudeAgentOptions になりました。機能は引き継がれており、変更されたのはパッケージ名とクラス名だけです。チュートリアルが古い名前をインポートしている場合、それは改名以前のものであり、現在のパッケージではインポートに失敗します。

Claude Agent SDK はどうやってインストールしますか？

Python 3.10+ では pip install claude-agent-sdk を、TypeScript では npm install @anthropic-ai/claude-agent-sdk を実行し、その後 ANTHROPIC_API_KEY を設定します。SDK はバンドルされた Claude Code CLI をサブプロセスとして駆動するため、Python パッケージであっても Node.js のインストールが必要です — Node がないことが、最も一般的なインストール失敗の原因です。

Jira や Shopify を Claude Agent SDK エージェントに接続するにはどうすればよいですか？

ベンダーの MCP サーバーを ClaudeAgentOptions の mcp_servers に追加し、そのツールを許可します。Atlassian (Jira) と Shopify はどちらも MCP サーバーを公開しているため、独自コネクタを書く必要はありません — API トークンでサーバーを登録し、そのツール（allowed_tools 内で mcp__<server>__<tool> という名前）を列挙します。

Claude Agent SDK はゲートウェイやプロキシで動作しますか？

はい。ANTHROPIC_BASE_URL 環境変数を尊重するため、コード変更なしで Anthropic Messages API（/v1/messages）を公開している任意のバックエンドにルーティングされます。Velokey の Anthropic 互換エンドポイントに対してライブリクエストを検証しました。x-api-key プロキシには ANTHROPIC_API_KEY を、ベアラートークン方式のものには ANTHROPIC_AUTH_TOKEN を使用してください。

Claude Agent SDK はどのモデルを使用しますか？

指定したエンドポイントを通じて Claude モデルを使用します — デフォルトでは Anthropic の最新モデルで、model オプションにより特定のもの（たとえば claude-sonnet-5 や claude-opus-4-8）を設定できます。ゲートウェイ経由では、そのゲートウェイが提供する任意の Claude モデルを選択できるため、通常のエージェント実行により安価なモデルを使うのに便利です。

Claude Agent SDK は無料ですか？

SDK は無料でオープンソースですが、エージェントの実行には Claude API トークンの料金がかかり、複数ターンのエージェントループではそれらをすぐに消費します。通常作業にはより安価なモデルを選び、max_turns を設定し、ツールアクセスを制限することで支出を管理してください — そして組み込みのプロンプトキャッシュを活用してください。これは、繰り返されるシステムプロンプトを入力価格のおよそ 10 分の 1 で提供します。