Claude Agent SDK vs API vs Claude Code：使い分けパターン

#実務（デリバリー）視点での決定的な違い

公式ドキュメントには各ツールの概要が明確に書かれていますが、実際に顧客へシステムを**「選定・構築・納品する」**立場から見ると、以下の2つの問いに集約されます。

1. エージェントループ（Harness）は誰が書くか？ ―― 「Claudeがツール呼び出しを決定 → こちらでツールを実行 → 結果をClaudeに返却 → Claudeが次のアクションを決定」というループ処理と、会話が長くなった際の文脈（コンテキスト）管理システムを指します。これを「ハーネス（制御機構）」と呼びます。
2. 実行インフラ（Deployment）は誰が用意するか？ ―― プロセス、サーバー、サンドボックス、セッション状態の保存先などです。これを「デプロイメント（実行環境）」と呼びます。

これら2つの軸で整理すると、以下のようになります。

• Claude API（Tool Runner機能を含むMessages API）―― ツールを定義し、SDK（または開発者自身）がループを回し、自社サーバーでホストします。組み込みのツールやサンドボックスはありません。最も「魔法（ブラックボックス）が少ない」レベルであり、開発者がすべてを制御できる代わりに、すべてを自分で組み立てる必要があります。
• Claude Agent SDK ―― Claude Codeのエンジンをライブラリ（Pythonの claude_agent_sdk、TypeScriptの @anthropic-ai/claude-agent-sdk）としてパッケージ化したものです。エージェントループ、コンテキスト管理、および強力な組み込みツール群（Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetchなど）が最初から揃っています。開発者はプロンプトと設定を用意するだけで動かせますが、実行環境自体は**自社プロセス内（セルフホスト）**になります。
• Claude Code ―― SDKと同じハーネスを使用しますが、ターミナルから操作する対話型CLIツールです。機能はAgent SDKと同等ですが、インターフェースが異なります。
• Managed Agents ―― Anthropicがハーネスとデプロイメントの両方を管理します。Anthropicのインフラ上でエージェントループが動作し、セッションごとにサンドボックス環境が自動生成されます。開発者はREST経由でイベントを送り、結果を受け取るだけです。

ここで最も混同しやすいのが、「Agent SDK」と「Claude APIのTool Runner機能」は別物という点です。Tool Runner（anthropic / @anthropic-ai/sdk 内の client.beta.messages.tool_runner）は、自分が定義した独自のツールに対して単純なループ処理を肩代わりするだけの薄いヘルパー機能に過ぎず、組み込みツールやファイルシステムへのアクセス権は持ちません。一方、Agent SDK（claude-agent-sdk）は、Claude Codeのシステムそのものです。これらは異なるパッケージであり、動作するレイヤーも異なります。

「開発者による管理・制御」から「Anthropicへの委ね（利便性）」へのグラデーション：

下に行くほど、開発者は管理コスト（最初はエージェントループ、最終的にはインフラ全体）をAnthropicに任せることができ、制御性と引き換えに利便性を得られます。

#選定の前に：そのタスクは本当に「エージェント」が必要か？

これは最も見落とされがちな問いです。自律的にツールを呼び出して複数ステップを処理するエージェントは、通常のシングルリクエストと比較して莫大なトークンを消費し、動作の予測可能性も低くなります。私は、以下の4つの条件すべてを満たす場合にのみ、タスクを「エージェント」化します。

• 複数ステップが必要で、事前にフローを完全には定義できない ―― 「PDFからタイトルを抽出する」ような作業ではなく、「この設計書をもとにPR（プルリクエスト）を作成する」ようなケース。
• コストに見合う ―― エージェント化に伴うコストや遅延（レイテンシ）を上回る価値がアウトプットにある。
• Claudeの得意分野である ―― モデルが本来の実力を発揮できる種類のタスクである。
• 失敗してもリカバリー可能である ―― テスト、レビュー、ロールバックなど、エラーを検知して元に戻せる仕組みがある。

これらのうち1つでも欠けている場合は、よりシンプルなアプローチ（分類、要約、データ抽出などの通常のClaude APIリクエスト、またはコード側でフローを制御するプログラム的なワークフロー）にダウングレードすべきです。紹介記事ではあまり触れませんが、実案件のデリバリーにおいて最もコストを削減できるアドバイスは、**「SQLクエリ1本で解決する作業に、わざわざAIエージェントを持ち込まないこと」**です。

#デリバリーシナリオ別の決定マトリクス

私がプロジェクトの技術選定を行う際、実際に使っているマトリクスです。技術的な機能比較ではなく、**「デリバリー状況（納品シナリオ）」**をメインの軸に据えています。なぜなら、最終的な意思決定で最も重要なのは「自分がプロジェクトを離れた後、誰が運用するのか」であり、「機能の多さ」ではないからです。

要約すると、**「自社インフラで動かす社内自動化 ＝ Agent SDK」「製品への組み込みと制御 ＝ Claude API」「手元でのクイックな対話 ＝ Claude Code」「インフラの運用負荷をゼロに ＝ Managed Agents」**となります。

#実案件で直面する「落とし穴」

• Agent SDKの実行コードは驚くほどシンプルです。 本質的には query(prompt, options) を呼び出してメッセージのストリームを受け取るだけです。しかし、「動かすのが簡単」であることと「プロダクション（本番環境）で運用できる」ことは全く別物です（詳細は後述のチェックリストを参照）。
• 認証制限：サードパーティ製品に claude.ai の個人アカウントでログインさせることはできません。 アプリケーションにAgent SDKを組み込む場合、APIキー（またはAmazon Bedrock / Google Vertex AIなど）を使用する必要があります。これは、ユーザーやセッションごとのトークン費用が発生することを意味するため、プロジェクトの初期段階から利用コストの計測と設計を行っておく必要があります。プロジェクトの終盤になってから気づくのでは遅すぎます。
• セッションの永続化：Agent SDKでは、セッション状態がローカルのファイルシステム上にJSONL形式で保存されます。 セッションの再開（Resume）や分岐（Fork）には非常に便利ですが、納品する際には「誰がこれをバックアップし、誰がクリーンアップし、保存期間はどうするか」という運用ルールを決める必要があります。Managed Agentsでは、この状態管理はAnthropicがホストするイベントログに保存されるため、利便性と制御のトレードオフになります。
• ブランド・商標の制約：Agent SDKを使って構築した製品に、「Claude Code」という名称やブランディングを使用することはできません。 細かい点に見えるかもしれませんが、顧客向けUIのデザインを作成する前に合意しておくべき重要なポイントです。

#AIエージェント本番導入チェックリスト

適切なツールを選ぶことはスタートラインに過ぎません。一般的なテックブログやニュース記事では語られない、真の課題は「コストの暴走やエージェントの暴走を防ぎながら、いかに本番環境で安全に運用するか」です。Agent SDKやClaude Codeを採用する場合、私は以下の6つの観点でチェックを行います。

1. ツールの最小権限の原則（Least-privilege）： allowed_tools（Python）または allowedTools（TS）で必要なツールだけを明示的に指定し、不要なツールは disallowed_tools で確実に遮断します。ファイルの読み取り専用エージェントであれば、絶対に Bash や Edit は有効にしないでください。これは設定の好みの問題ではなく、セキュリティ境界の設計そのものです。

2. トークンコストの天井設定： エージェントループは通常のAPIリクエストよりも遙かに多くのトークンを消費します。ステップ数の上限を設定し、タスクごとに適切なモデルを選択（すべての工程で最上位モデルを使わない）、固定されたシステムプロンプトにはPrompt Cachingを適用してコストを抑制します。

3. 非可逆なアクションにおけるHuman-in-the-loop： ファイルの削除、コードのプッシュ、外部APIの呼び出しなど、後戻りできない操作を行う前には、PreToolUse フックを挟んでユーザーに承認を求める仕組みを実装します。permission_mode を適切に設定し、自動実行の度合いをコントロールします。

4. 可観測性（Observability）の確保： PostToolUse フックを利用して、ファイルの修正やコマンド実行の履歴を監査ログ（Audit Log）として記録します。問題が発生した際に、「エージェントが何をしたのか」を推測するのではなく、ログから即座に追跡できるようにします。

5. 顧客ごとの認証と課金（Billing）の分離： APIキーはサーバーサイドで管理し、ユーザーごとの消費費用を初期段階から追跡します。これは将来的な価格設定や運用保守のコスト計算において、極めて重要なデータになります。

6. 納品・運用の引き継ぎ計画： 自分が開発から離れた後、誰がこのエージェントを保守するのか？セッションのJSONLファイルはどこに保存され、モデルの価格改定時の負担はどうするのか、APIキーの管理者は誰か？これらの問いにすべて回答できて初めて、エージェントの実装は本当の意味で「完了」したと言えます。

#おわりに

Claude Agent SDK、Claude API、Claude Codeは優劣の関係ではなく、委ねるグラデーションのスペクトラムに位置しています。上に行けば行くほど（制御ループ、そしてインフラ全体を）Anthropicに委ねることになり、引き換えに開発効率と手軽さを得られます。正しい選定とは、状況に合わせた適切なステップを選択することであり、常に「本当にエージェントが必要か？」という問いから始め、「納品後に誰が運用するのか？」という問いで終わることです。

さらに深く知りたい方は、Claudeプラットフォーム構築の全体像を解説したClaude Platform 101、Messages APIとツール利用の基礎を扱うBuilding with the Claude API、ターミナルでの開発効率を最大化するClaude Code 101、そしてAgent SDKでも再利用されているIntroduction to Subagentsをご参照ください。学習ロードマップ全体は [/learn/claude?lang=ja] にまとめられています。

Nguyễn Phúc Nguyên Châu
Delivery Manager
ベトナム・日本市場向けに14年のデリバリー経験（Web・システム・AI自動化）