「pip install claude-agent-sdk で本当に動くのか」「そもそも Claude Code と何が違うのか」——Claude Agent SDK を調べ始めた頃の私は、この2つで止まっていました。名前も 2025年9月に Claude Code SDK から変わったばかりで、検索すると新旧の情報が混ざって出てきます。
結論から言うと、Claude Agent SDK は「Claude Code の中身（エージェント実行基盤）を、自分の Python / TypeScript プログラムに組み込む部品セット」です。私は業務でこの SDK を使ってエージェントを実装し、本番と検証で動かしています。
本記事では、改名の経緯／Claude Code との違い／pip・npm の最小手順／料金とサブスクの SDK クレジット動向を、実演画像つきで整理します。「まず動かしたい」方はpip の最小手順から読み始めても大丈夫です。
Claude Agent SDKとは｜2025年9月にClaude Code SDKから改名
Claude Agent SDK を一言でいうと、「Claude Code がやっている自律的な動きを、ライブラリとして自分のアプリに取り付けられるようにしたもの」です。Claude Code が完成品の調理ロボットだとすれば、Agent SDK はその中のエンジンと手足を自分の厨房（アプリ）に組み付けるためのパーツ一式、という関係になります。
用語を最短で押さえておきます。「SDK」はあるサービスの機能を自分のプログラムから使うための道具箱、「CLI」はターミナルに文字で命令する操作方式（Claude Code はこれ）、「エージェントループ」は AI が「考える→道具を使う→結果を見てまた考える」を自分で繰り返す仕組みです。
この SDK は、もともと「Claude Code SDK」という名前でした。2025年9月に「Claude Agent SDK」へ改名され、いまはこちらが正式名です（出典は末尾の出典に集約）。改名の理由は、Claude Code を動かしているハーネス（エージェント実行基盤）を、コーディング専用にせず、あらゆる種類のエージェント開発に開放するためです。
なお、AI エージェントには Agent SDK 以外のルート（ノーコード型など）もあります。4つのルートを俯瞰したい方は、AIエージェントの作り方を4ルートで俯瞰した記事を先に読むと位置づけが掴みやすいはずです。
旧claude-code-sdkからの移行
移行の1点目はパッケージ名です。Python は claude-code-sdk → claude-agent-sdk、TypeScript は @anthropic-ai/claude-code → @anthropic-ai/claude-agent-sdk に入れ替えます（import 名も同様に変更）。
2点目が見落としやすい破壊的変更です。新 SDK はデフォルトでは Claude Code のシステムプロンプトや設定ファイル（CLAUDE.md など）を読み込まなくなったため、旧 SDK と同じ挙動にしたい場合は setting_sources を明示する必要があります。
# 旧SDKの挙動に寄せたいときは setting_sources を明示
from claude_agent_sdk import ClaudeAgentOptions
options = ClaudeAgentOptions(
setting_sources=["user", "project", "local"],
)何ができる｜組み込みツール・フック・サブエージェント・MCP
Agent SDK のいちばんの価値は、「エージェントを動かすのに必要な手足が最初から付いてくる」ことです。Read / Write / Edit / Bash / Glob / Grep といった組み込みツールが入っていて、ツール実行を自分で書かなくても AI がファイルを読み書きし、コマンドを動かせます。最近の版では長時間処理を見張る Monitor や、実行中に人へ質問を返す AskUserQuestion も組み込みツールに加わりました。
フックは動きの前後に自分の処理を割り込ませる仕組みで、監査ログや危険操作の停止に使えます。サブエージェントは大きな仕事を役割ごとに子エージェントへ分ける仕組み、MCP は外部システムへの差込口の規格で、さらに Claude Skills やプラグインも SDK から使えます。全体を安全に保つ許可制御は安全に動かす章で詳しく書きます。
Claude Code・素のAPI・Managed Agentsとの違い
サジェストで「claude agent sdk claude code 違い」が出てくる通り、ここが一番混同されるポイントです。先に結論を言うと、能力そのものは似ていて、違うのは「どこで・どう動かすか」です。
| 選択肢 | どこで動かす | 向く場面 |
|---|---|---|
| Claude Code（CLI） | ターミナルで対話 | 日々の開発・単発作業 |
| Agent SDK | 自分のアプリ・CI/CD | 本番の自動化・組み込み |
| 素の Anthropic API | 自分のコード（ループ自前） | 最小依存・細かい制御 |
| Managed Agents | Anthropic 側でホスト | 実行環境ごと任せたい |
公式の使い分けもこの整理で、対話しながらの開発は CLI（Claude Code）、CI/CD や本番アプリへの組み込みは SDK です。私の周りでも、日々の開発は手元の Claude Code で進め、本番に載せるところは Agent SDK で組む、という併用が自然でした。CLI 自体の使い方はClaude Code の使い方の記事や始め方の記事が入口になります。
Managed Agents は「Anthropic 側にエージェントの実行ごと任せる」ホスティング型の REST API です。SDK は「自分のプロセスで動かす」、Managed Agents は「Anthropic 側で動かす」と覚えておけば十分です。
素の Anthropic API との違い｜ループを書くか・入っているか
素の API は、messages.create を呼び、AI が「この道具を使いたい」（tool_use）と返してきたら、ツール実行を自分でループして返す書き方です。Agent SDK はそのループが最初から入っています。
# 素のAPI：道具を使うループを「自分で」回す（イメージ）
import anthropic
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "ファイルを調べて"}]
while True:
res = client.messages.create(
model="claude-...",
max_tokens=1024,
tools=my_tools,
messages=messages,
)
if res.stop_reason != "tool_use":
break
# tool_use が来たら自分でツールを実行して結果を返す
messages.append(
{"role": "assistant", "content": res.content})
messages.append(
{"role": "user", "content": run_tools(res)})# Agent SDK：ループ内蔵。async for で結果を受け取るだけ
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
options = ClaudeAgentOptions(
allowed_tools=["Glob", "Read"])
async for message in query(
prompt="このフォルダのファイルを調べて",
options=options,
):
print(message)
asyncio.run(main())細かく制御したい・依存を最小にしたいなら素の API、自律的な動きを速く組み上げたいなら Agent SDK。私はこの2つを目的で使い分けています。素の API の総論やキー取得はAnthropic API の総論記事へどうぞ。
pipで動かす最小手順（Python）／npm（TypeScript）
ここがいちばん知りたい人が多いところだと思います。前提は Python 3.10 以上で、執筆時点の最新版は claude-agent-sdk v0.2.110（2026-06-24 公開、PyPI、取得：2026-07-05）。Claude Code CLI が同梱されるので、別途 Claude Code をインストールする必要はありません。
# Claude Agent SDK（Python版）をインストール
pip install claude-agent-sdk実際に入れると、claude-agent-sdk が依存（mcp や httpx など）とともにそろいます。下は私が手元で pip install したときのターミナル出力です。
次に、API キーを環境変数に置きます。キーをコードに直接書くのは避け、環境変数に逃がすのが基本です（取得手順はAnthropic API の記事やAnthropic Console の使い方に譲ります）。
# API キーを環境変数に登録
export ANTHROPIC_API_KEY="sk-ant-..."そして最小サンプルです。「このフォルダにどんなファイルがある？」を、ファイル一覧と読み取りの道具だけを許可して1回動かします（query() は async / asyncio.run で回します）。
# 最小サンプル：許可した道具だけで1回動かす
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
# 使わせる道具を「これだけ」に絞る
options = ClaudeAgentOptions(
allowed_tools=["Glob", "Read"])
async for message in query(
prompt="このディレクトリのファイルを調べて要点を教えて",
options=options,
):
print(message)
asyncio.run(main())実際に検証用フォルダで動かすと、SDK が Glob / Read を自分で呼び、最初は存在しないパスで空振りしつつ、最終的に a.txt / b.txt を読んで「メモ1 / メモ2」と要約までしてくれました。下が、そのとき /tmp のフォルダで流れてきた実際の出力です（query() が ToolUseBlock → ToolResultBlock を自分で回しているのが見えます）。
私が最初につまずいたのは、(1) Python が 3.10 未満だとインストールで弾かれる（「No matching distribution」）、(2) API キーの環境変数を設定し忘れて認証で止まる、(3) async / asyncio.run の書き方に慣れず手が止まる、の3つです。どれも一度通れば怖くないので、まずは上の3ブロックをそのまま写経して1回動かすのをおすすめします。
TypeScript 版｜npm install して同じことを動かす
TypeScript でも同じことができます。執筆時点の最新版は @anthropic-ai/claude-agent-sdk v0.3.201（2026-07-03 公開、GitHub Releases、取得：2026-07-05）で、こちらも Claude Code 本体が同梱される作りです。
# Claude Agent SDK（TypeScript版）をインストール
npm install @anthropic-ai/claude-agent-sdk最小サンプルは、query() の結果を for await で1つずつ受け取る形です。
// 最小サンプル（TypeScript）
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "このディレクトリのファイルを調べて要点を教えて",
options: { allowedTools: ["Glob", "Read"] },
})) {
console.log(message);
}Python 版と TypeScript 版は、ほぼ同じ機能が「書き方の作法だけ違う」関係です。道具のリストは Python では allowed_tools（スネークケース）、TypeScript では allowedTools（キャメルケース）。片方を覚えれば、もう片方も読めるようになります。
MCP・自作ツールを足す｜SDK から外部システムに繋ぐ
Agent SDK は、最初から付いてくる道具だけでなく、外部システムにつなぐ口（MCP）や自作の道具も使えます。外部の MCP サーバー（たとえばブラウザ操作の Playwright など）につなぐときは、mcp_servers オプションで指定します。
# 外部 MCP サーバーに繋ぐ（設定を渡すだけ）
from claude_agent_sdk import ClaudeAgentOptions
options = ClaudeAgentOptions(
mcp_servers={
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"],
},
},
)私は業務で社内 API や自社データベースを MCP サーバー化して本番投入した経験がありますが、「MCP サーバーを作る側」の話は本記事のスコープから外します。作り方はMCP サーバーの作り方の記事、MCP を使う側の全体像はAIエージェント × MCP の記事へどうぞ。
安全な動かし方と料金｜サブスクのSDKクレジットは一時停止中
エージェントは自律的にファイルを書き換え、コマンドを実行し、外部に通信します。便利な反面、放っておくと「権限が広すぎて余計なファイルまで触る」「気づいたら呼び出し回数が膨らんでいる」が起こり得ます。絶対に安全だと言い切れる仕組みは存在しないからこそ、安全側に倒す設計を最初から入れておくのが筋です。
まず効くのは許可制御です。allowed_tools を読み取り系に絞れば実質的に読み取り専用にでき、書き換えや危険な操作は permission_mode で承認制（人が OK を出すまで止める）にできます。さらにフックで操作ログを残せば、「いつ・何を・どう変えたか」を後から追えます。
# 安全運用の例：道具を絞り、危険操作は承認制に寄せる
from claude_agent_sdk import ClaudeAgentOptions
options = ClaudeAgentOptions(
allowed_tools=["Glob", "Read"], # 読み取り中心から
permission_mode="default", # 承認の余地を残す
)
# PostToolUse フックで変更ログを残すと後から追えるその上で、私が業務で必ず守る運用ルールは次の3点です。実際、権限を絞っていたおかげで「想定外のファイルに触れずに止まった」場面があり、最初から絞っておいてよかったと実感しています。
- 金額が動く処理・本番DBへの書き込み・外部への送信は、必ず人間が最終確認する
- コストやトークン（処理量）の上限を設けておく
- 検証は本番と切り離した場所で自由に、本番は権限を最小に絞りログと承認のゲートを通す
料金｜API 従量課金が基本・SDK クレジットの開始は一時停止中
先に結論を言うと、Agent SDK は基本的に「Anthropic API のトークン従量課金」で動きます。つまり Claude.ai のサブスク（Pro / Max）とは別系統だと考えるのが出発点です。
公式は、サブスクプラン向けに対話利用とは別枠の「月次 SDK クレジット」を案内しています。ただしこのクレジットの開始（ロールアウト）は一時停止中（paused）で、クレジット枠を超えた分は標準の API レートで課金されるとされています（取得：2026-07-05）。
| プラン | 月次 SDK クレジット |
|---|---|
| Pro | $20 |
| Max 5x | $100 |
| Max 20x | $200 |
金額・条件・開始時期は変わり得るので、必ず公式の最新案内でご確認ください。「サブスクと API 従量、結局どっちが得か」はClaude Code の料金を比較した記事、サブスクの全体像はClaude の料金プランの記事、モデル別の単価はClaude のモデルの違いの記事へどうぞ。
もう1つ、SDK で作ったものを外部に提供する場合の規定があります。サードパーティ製品では claude.ai ログイン（サブスク認証）をエンドユーザーに提供できず API キーでの利用になること、製品名に「Claude Code」の名称を使えないブランディング規定があることは、企画段階で押さえておくと手戻りしません。
使う／使わないの判断軸と、進め方の順番
私が使うのは、アプリや CI・本番の自動化に、ファイル操作やツール実行込みの自律的な動きを組み込みたいときです。逆に、対話で十分なら Claude Code（CLI）、単純な1往復の生成だけなら素の API、実行環境ごと任せたいなら Managed Agents が向きます。
進め方は、私が業務でたどった順番そのままをおすすめします。まず Claude Code（CLI）を毎日触って「AI が勝手にファイルを読んで直す」感覚を掴み、次に最小サンプルを検証用フォルダで1回動かし、業務に載せる段では許可制御とログ設計を必ず先に入れる——この順番なら大きく転びません。
非エンジニアの方は「いきなり SDK」ではなく、まず Claude Code（CLI）で下書き作りや小さな自動化に慣れてから進むのが現実的です。どの入口でも共通して大事なのは、出力は必ず人が確認することだと感じています。
本記事の出典
料金やバージョンの細部は変わり得るので、最終的には必ず公式でご確認ください。本記事の出典は以下です。
Claude Agent SDK の概要・組み込みツール・許可制御・CLI / SDK の使い分け・改名の経緯 出典: Claude Agent SDK overview｜Claude Docs（取得：2026-07-05）
Python 版：v0.2.110（2026-06-24 公開）・Python 3.10 以上・Claude Code CLI 同梱 出典: claude-agent-sdk｜PyPI（取得：2026-07-05）
TypeScript 版：v0.3.201（2026-07-03 公開）・リリース履歴 出典: claude-agent-sdk-typescript Releases｜GitHub（取得：2026-07-05）
サブスクの月次 SDK クレジット（Pro $20／Max 5x $100／Max 20x $200・開始は一時停止中・超過は標準 API レート）・サードパーティ提供の規定 出典: Use the Claude Agent SDK with your Claude plan｜Claude Support（取得：2026-07-05）
2025年9月の claude-code-sdk → claude-agent-sdk 改名と移行時の破壊的変更（日本語の移行実例） 出典: Claude Agent SDK への移行｜LayerX エンジニアブログ（2025-10-10 公開、取得：2026-07-05）
よくある質問
Q1: Claude Agent SDK と Claude Code は何が違いますか？
A. 能力は近く、違うのは「どこで動かすか」です。ターミナルで人が対話しながら使うのが Claude Code（CLI）、同じ能力を自分のアプリ・スクリプト・CI に組み込むのが Agent SDK です。公式も、対話的な開発は CLI、CI/CD や本番組み込みは SDK という使い分けを示しています。
Q2: 旧「Claude Code SDK」と「Claude Agent SDK」は別物ですか？
A. 同じものです。2025年9月に Claude Code SDK から Claude Agent SDK へ改名されました。パッケージ名は claude-agent-sdk（Python）/ @anthropic-ai/claude-agent-sdk（TypeScript）です。移行時はデフォルトで Claude Code の設定を読まなくなる破壊的変更（setting_sources の明示）に注意してください。
Q3: Pro や Max のサブスクで Claude Agent SDK は使えますか？別料金ですか？
A. 基本は Anthropic API のトークン従量課金で、サブスクとは別系統です。公式は月次の SDK クレジット（Pro $20／Max 5x $100／Max 20x $200、超過は標準 API レート）を案内していますが、開始は一時停止中（paused）です（取得：2026-07-05）。最新状況は必ず公式でご確認ください。
Q4: Python と TypeScript、どちらでも使えますか？
A. 両方とも公式に提供されています。Python は pip install claude-agent-sdk（Python 3.10 以上・Claude Code CLI 同梱）、TypeScript は npm install @anthropic-ai/claude-agent-sdk です。どちらも別途 Claude Code をインストールする必要はありません。
Q5: 素の Anthropic API と Agent SDK、どちらを使えばいいですか？
A. 細かく制御したい・依存を最小にしたいなら素の API（道具を使うループは自前）。ファイル操作やツール実行込みの自律的な動きを速く組みたいなら Agent SDK（ループが入っています）。目的で使い分けるのが現実的です。
関連記事
- AI 動画生成 自動化——Claude Code 7 サブエージェントで作った動画自動生成パイプラインの実装体験
- AIエージェントの作り方を4ルートで俯瞰する
- 生成AIエンジニアになるには — SDK でエージェントを組めるスキルを仕事にする道筋
- Anthropic API の全体像（素の API・キー取得・モデル）
- MCP サーバーの作り方
- AIエージェント × MCP
- Claude Code の使い方
- Claude Code の始め方
- Claude Code の料金
- Claude 料金プラン
- Claude Opus と Sonnet の違い
- Claude Skills とは
- Claude Skills 自作
- LM Studio 使い方——ターミナル不要の GUI でローカル LLM を入れる→モデル管理→OpenAI 互換 API まで、Ollama との使い分けも整理
この記事は、営業出身の現役生成AIエンジニア aikun が、Claude Agent SDK を業務でエージェント実装に使う立場から整理しました（プロフィールは about ページ をご覧ください）。料金・仕様は変動するため、本文の数値・手順は必ず公式情報で最新をご確認ください。記事内容に誤り・古い情報を見つけられた場合は、send@bon-bon-tools.com までご連絡いただけると助かります。