Claude Agent SDK とは｜Claude Code の中身をアプリに組み込む

Q: Python と TypeScript、どちらでも使えますか？

両方とも公式に提供されています。Python は pip install claude-agent-sdk（Python 3.10 以上）、TypeScript は npm install @anthropic-ai/claude-agent-sdk（Claude Code 本体が同梱されます）です。

「Claude Code は毎日ターミナルで使っているけれど、あの“勝手にファイルを読んで直してくれる動き”を、自分のアプリの中に組み込めないんだろうか」——そう思い始めた頃の私も、何から手をつければいいか分からず止まっていました。「Claude Agent SDK」のラッコキーワード実測は直近月で 4,400 件・前年比 +1029% と急に伸びていて（ラッコキーワード、取得：2026-06-03）、同じ疑問を持つ人がいま一気に増えているのが分かります。

結論から言うと、Claude Agent SDK は「Claude Code の中身を、自分の Python / TypeScript のプログラムに組み込む部品セット」と捉えるのが筋です。私は業務でこの SDK を使ってエージェントを実装し、本番と検証で動かしています。本記事ではその経験をもとに、とは／何ができる／Claude Code・素の API との違い／最小サンプル／料金感／安全な動かし方までを、未経験の方にも届くように整理します。

とりあえず「まず一度だけ動かしてみたい」という方は、セクション 4（Python 最小サンプル）から読み始めても大丈夫です。

Claude Agent SDK とは（旧 Claude Code SDK）／迷ったらこの3つだけ

対話して使うClaude Code（CLI）、自分のアプリやCIに組み込むClaude Agent SDK（エージェントループ内蔵）、道具を使うループを全部自前で書く素のAnthropic APIの3つを、土台は同じClaudeとして使い分けるマップ図

📖 この章で使う用語

Claude Agent SDK：Claude Code の中身（自律的に動くエージェントの動き）を、自分の Python / TypeScript のプログラムに組み込むための部品セット。「調理ロボの中のエンジンと手足を、自分の厨房に取り付けるパーツ一式」のイメージ。

SDK（Software Development Kit）：あるサービスの機能を、自分のプログラムから使うための“道具箱”。

ライブラリ：プログラムに読み込んで使う、機能の部品集。

CLI（Command Line Interface）：ターミナル（黒い画面）に文字で命令して操作する方式。Claude Code はこれ。

エージェントループ：AI が「考える→道具を使う→結果を見てまた考える」を自分で繰り返す仕組み。人間が毎回指示しなくても回ります。

Claude Agent SDK を一言でいうと、「Claude Code がやっている自律的な動きを、ライブラリとして自分のアプリに取り付けられるようにしたもの」です。Claude Code が完成品の調理ロボットだとすれば、Agent SDK は、その中のエンジンと手足を、自分の厨房（アプリ）に組み付けるためのパーツ一式、という関係になります。

このSDKは、もともと「Claude Code SDK」という名前でした。2026 年に「Claude Agent SDK」へ改名され、いまはこちらが正式名です。「昔の Claude Code SDK と同じもの？」と迷う方が多いのですが、同じものだと考えて差し支えありません（出典はセクション 9に集約しています）。部品の名前（パッケージ名）は、Python が claude-agent-sdk、TypeScript が @anthropic-ai/claude-agent-sdk です。

迷ったときは、この3つの違いだけ押さえれば十分だと思います。対話しながら使うなら Claude Code（CLI）／自分のアプリに組み込むなら Agent SDK／道具を使うループを全部自前で書くなら素の Anthropic API。この一行マップを頭に置いておくと、以降の話が迷子になりません。

なお、AIエージェントには Agent SDK 以外のルート（ノーコード型など）もあります。4つのルートを俯瞰して「自分はどれを選ぶべきか」を考えたい方は、AIエージェントの作り方を4ルートで俯瞰した記事を先に読むと位置づけが掴みやすいはずです。本記事は、その中の「自分のプログラムに組み込むルート」である Agent SDK 単体を深掘りします。

Claude Agent SDK で何ができる（ツール・フック・サブエージェント・MCP・許可制御）

📖 この章で使う用語

組み込みツール（built-in tools）：ファイルを読む・書く・コマンドを動かす等、最初から付いてくる“手足”。Read / Write / Edit / Bash / Glob / Grep などがあります。

フック（hook）：エージェントが何かをする“前後”に、自分のコードを差し込む仕掛け。家の玄関に付ける「出入りを記録するセンサー」のイメージ。

サブエージェント：本体のエージェントが、専門の子エージェントに仕事を割り振る仕組み。

検索拡張ではなく接続の規格＝MCP（Model Context Protocol）：AI と外部システム（データベース・ブラウザ・API）をつなぐ共通の“差込口”の規格。

許可制御（permissions）：エージェントに「これは触っていい／ダメ」を決める設定。読み取り専用・承認制などにできます。

セッション：会話の文脈（読んだファイル・やり取り）を保持し、後で再開・分岐できる単位。

Agent SDK のいちばんの価値は、「エージェントを動かすのに必要な手足が、最初から付いてくる」ことです。素の AI に「ファイルを読んで」と頼んでも、AI 自身はファイルを読めません。Agent SDK には Read / Write / Edit / Bash / Glob / Grep といった組み込みツールが入っていて、ツール実行を自分で書かなくても、AI が自分でファイルを読み書きし、コマンドを動かせます。

フックは、その動きの“前後”に自分の処理を割り込ませる仕組みです。たとえば「ファイルを書き換える直前に内容を記録する」「危ない操作はその場で止める」といった監査や制御に使えます。私が業務でエージェントを本番に載せるとき、このフックで操作ログを残す設計は欠かせませんでした。

サブエージェントは、仕事を専門の子エージェントに分担させる仕組みです。深掘りは別記事に譲る予定ですが、「1つの大きな仕事を、役割ごとに分けて任せられる」と捉えておけば十分です。

外部のデータベースやブラウザにつなぎたいときは MCP を使います。これは外部システムへの“差込口”の規格で、SDK 側からその差込口に接続できます（接続のやり方はセクション 6で扱います）。そして全体を安全に保つのが許可制御です。「読み取りだけ許す」「危険な操作は承認制にする」といった線引きができ、これは安全運用の核なのでセクション 7で改めて詳しく書きます。

Claude Code（CLI）・素の Anthropic API との違い

📖 この章で使う用語

素の Anthropic API（Client SDK）：messages.create を呼んで、道具を使うループを“自分で”書く、一番素の使い方。

tool_use：AI が「この道具を使いたい」と返してくる合図。素の API では、これを見て自分でツールを実行します。

Managed Agents：Anthropic 側でエージェントとサンドボックスを動かす、ホスティング型の REST API。

サジェストで「claude code 違い」がよく出てくる通り、ここが一番混同されるポイントです。先に結論を言うと、能力そのものは似ていて、違うのは「どこで・どう動かすか」です。

Claude Code（CLI）と Agent SDK の違い

Claude Code（CLI）は、ターミナルで人が対話しながら使うものです。一方の Agent SDK は、同じ能力を「自分のアプリ・スクリプト・CI（自動実行の仕組み）」に組み込んで動かすためのものです。公式の使い分けをかみ砕くと、対話しながらの開発や単発の作業は CLI、本番の自動化やカスタムアプリへの組み込みは SDK、という整理になります。

私の周りでも、両方を併用するチームが多い印象です。日々の開発は手元の Claude Code で進め、出来上がったものを本番に載せるところは Agent SDK で組む、という分け方が自然でした。CLI 自体の使い方をもっと知りたい方は、Claude Code の使い方をまとめた記事やClaude Code の始め方の記事が入口になります。

素の Anthropic API と Agent SDK の違い

素の Anthropic API は、messages.create を呼び、AI が「この道具を使いたい」（tool_use）と返してきたら、ツール実行を“自分でループして”返す、という書き方です。Agent SDK は、そのループを Claude が自律的に回してくれます。手で書くか、最初から入っているか、の違いです。

# 素の Anthropic 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_yourself(res)})

# Claude 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 の総論記事に、モデル別の単価や選び方はClaude のモデルの違いをまとめた記事にまとめているので、そちらへどうぞ。

ちなみに「Anthropic 側にエージェントの実行ごと任せたい」という選択肢として Managed Agents（ホスティング型の REST API）もあります。ここは私自身が本番フル運用しているわけではないので、公式情報からの整理として軽く触れるにとどめます。SDK は「自分のプロセスで動かす」、Managed Agents は「Anthropic 側で動かす」と覚えておけば十分です。

最小サンプル①：Python（pip install → エージェントを1回動かす）

📖 この章で使う用語

pip：Python の部品（パッケージ）を入れるコマンド。

環境変数：プログラムに渡す“設定値の置き場”。API キーをコードに直接書かず、ここに置きます。

async / asyncio.run：「待ち時間のある処理を並行で進める」書き方。Agent SDK の query() はこれで回します。

ここがいちばん知りたい人が多いところだと思います。実際に手を動かして、1回だけ動かしてみます。前提は Python 3.10 以上です。

まず部品を入れます。

# Claude Agent SDK（Python版）をインストール
pip install claude-agent-sdk

実際に入れると、次のように claude-agent-sdk が依存（mcp や httpx など）とともにそろいます。下は私が手元で pip install したときのターミナル出力です。

pip install claude-agent-sdk を実行したターミナル画面。claude-agent-sdk が mcp や httpx、jsonschema、pydantic-settings、uvicorn などの依存とともに導入されている実際の出力

次に、API キーを環境変数に置きます。キーをコードに直接書くのは避け、環境変数に逃がすのが基本です（キーの取得手順そのものはAnthropic API の記事やAnthropic Console の使い方に譲ります。ここでは登録だけ）。

# API キーを環境変数に登録（毎回打つか、シェルの設定ファイルに書く）
export ANTHROPIC_API_KEY="sk-ant-..."

そして最小サンプルです。「このフォルダにどんなファイルがある？」を、ファイル一覧と読み取りの道具だけを許可して1回動かします。

# 最小サンプル：許可した道具だけでエージェントを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 を自分で回しているのが見えます）。

Claude Agent SDK の最小サンプルを検証フォルダで実行したターミナル出力。query() が Glob と Read を自動で呼び、最初は存在しないパスで空振りしつつ最終的に a.txt と b.txt を読んでメモ1・メモ2と要約している実際のメッセージ列

私自身が最初につまずいたところを正直に書いておきます。1つ目は Python が 3.10 未満だと、インストール時に「条件に合う配布がない（No matching distribution）」というエラーが出ること。2つ目は API キーの環境変数を設定し忘れて、認証で止まること。3つ目は、async や asyncio.run という非同期の書き方に慣れていないと、最初の数行で手が止まること。どれも一度通れば怖くないので、まずは上の3ブロックをそのまま写経して、1回動かすのをおすすめします。

最小サンプル②：TypeScript（npm install → エージェントを1回動かす）

📖 この章で使う用語

npm：JavaScript / TypeScript の部品を入れるコマンド。

optional dependency：必要な人にだけ入る“おまけの依存部品”。TS 版はここで Claude Code 本体を同梱します。

for await：非同期で流れてくる結果を、1つずつ受け取るループの書き方。

TypeScript でも同じことができます。こちらは部品を入れると Claude Code 本体が“おまけの依存部品”として一緒に入る作りなので、別途 Claude Code をインストールする必要はありません。

# Claude Agent SDK（TypeScript版）をインストール
npm install @anthropic-ai/claude-agent-sdk

最小サンプルは、query() の結果を for await で1つずつ受け取る形です。

// 最小サンプル（TypeScript）：許可した道具だけで1回動かす
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（キャメルケース）になります。片方を覚えれば、もう片方も読めるようになります。

SDK から MCP を使う・自分の道具を足す

📖 この章で使う用語

mcp_servers（オプション）：SDK に「この外部 MCP サーバーに繋いで」と渡す設定。

カスタムツール：自分で作って AI に持たせる道具。SDK では Python / TypeScript の関数として足せます。

Agent SDK は、最初から付いてくる道具だけでなく、外部システムにつなぐ口（MCP）や、自分で作った道具も使えます。本記事の範囲は「SDK からそれらをどう呼ぶか」という関係だけに絞ります。

外部の MCP サーバー（たとえばブラウザ操作の Playwright など）につなぐときは、mcp_servers オプションで指定します。

# SDK から外部 MCP サーバーに繋ぐ（イメージ：設定を渡すだけ）
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    mcp_servers={
        "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]},
    },
)

自分で作った道具（カスタムツール）も足せます。Python / TypeScript の関数を、SDK が扱える道具として登録するイメージです。「社内の特定の処理だけは自前で持たせたい」というときに使います。

ここで1つだけ正直に線を引いておきます。私は業務で、社内 API や自社データベースを MCP サーバー化して本番運用に投入した経験があります。ただ、その「MCP サーバーを“作る”側」の話は本記事のスコープから外し、専用記事に譲ります。作り方はMCP サーバーの作り方の記事、MCP を“使う”側の全体像はAIエージェント × MCP の記事が詳しいので、深掘りはそちらへどうぞ。

エージェントを“安全に”動かす：許可制御・上限・人間の確認

📖 この章で使う用語

allowed_tools：エージェントに使わせて良い道具のリスト。これだけ＝読み取り専用、という絞り方もできます。

permission_mode：操作の承認のされ方（自動承認・承認待ちなど）の設定。

Secrets：API キーやパスワード等の秘密情報。コードや Git に置かず、環境変数で扱います。

ここは、便利さの裏にある一番大事な話です。エージェントは、自律的にファイルを書き換え、コマンドを実行し、外部に通信します。便利な反面、放っておくと「権限が広すぎて余計なファイルまで触る」「気づいたら呼び出し回数が膨らんでいる」といったことが起こり得ます。絶対に安全だと言い切れる仕組みは存在しません。だからこそ、安全側に倒す設計を最初から入れておくのが筋だと考えています。

実装としてまず効くのは、許可制御です。allowed_tools を読み取り系の道具だけに絞れば、実質的に読み取り専用にできます。書き換えや危険な操作は、permission_mode で承認制（人がOKを出すまで止める）にできます。さらにフックで操作ログを残せば、「いつ・何を・どう変えたか」を後から追えます。

# 安全運用の例：道具を絞り、危険操作は承認制に寄せる
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    allowed_tools=["Glob", "Read"],   # まずは読み取り中心から始める
    permission_mode="default",        # 自動で何でも実行はさせず、承認の余地を残す
)
# さらに PostToolUse フックで「何を変更したか」をログに残すと、後から追える

その上で、運用面の決めごととして、私は次の3点を必ず守るようにしています。1つ目、金額が動く処理・本番データベースへの書き込み・外部への送信は、必ず人間が最終確認すること。ここを自動実行に丸投げしないだけで、事故の多くは防げます。2つ目、コストやトークン（処理量）の上限を設けておくこと。3つ目、検証は本番と切り離した場所で、本番は権限を最小に絞り、ログと承認のゲートを通すこと。私の場合も、検証は思い切り自由に試し、本番は権限を絞ってログを残す、というふうに環境ごとに態度を変えています。

料金感：API 従量課金が基本／サブスクで使えるのか・別課金なのか

📖 この章で使う用語

API 従量課金：使った分（処理量）だけ払う料金体系。

トークン：AI が文章を処理する“文字のかたまり”の単位。量で料金が決まります。タクシーのメーターのイメージ。

Agent SDK クレジット：サブスク利用での SDK 利用に充てられる、別枠の月次クレジット（後述／公式確認が必須です）。

サブスク（Pro / Max）：Claude を月額で使うプラン。Agent SDK の API 従量とは別系統です。

ここはサジェストでも「料金」「サブスクリプション」「クレジット」「max plan」が並ぶ、最大の不安どころです。先に結論を言うと、Agent SDK は基本的に「Anthropic API のトークン従量課金」で動きます。つまり、Claude.ai のサブスク（Pro / Max）とは別系統だと考えるのが出発点です。

ただし、ここに最近の動きがあります。公式の案内によると、2026-06-15 以降、サブスクプランでの Agent SDK 利用は、対話利用の上限とは別枠の「月次の Agent SDK クレジット」から引かれる予定とされています（出典はセクション 9、取得：2026-06-03）。金額・条件・対象は変わり得るので、必ず公式の Pricing やサポート記事で、最新の内容を確認してください。

認証の経路も触れておきます。基本は直 API キー（ANTHROPIC_API_KEY）です。AWS Bedrock / Google Vertex AI / Azure 経由も、環境変数の切り替えで使えます（たとえば CLAUDE_CODE_USE_BEDROCK のような変数で切り替えます）。私自身が業務の本番運用でメインにしているのは直 API なので、経由ルートの細部は公式情報からの整理として書きます。

最後にお金まわりの線引きです。**金額のベタ貼りはしません。「絶対に安い」「必ず◯円」とも言いません。**料金は、使うモデル・呼び出す回数・道具の使い方で大きく変わるからです。「サブスク同梱と API 従量、結局どっちが得か」という損益分岐はClaude Code の料金を比較した記事に、サブスクそのものの全体像はClaude の料金プランの記事に、モデル別の単価はClaude のモデルの違いの記事にまとめています。深掘りはそちらへどうぞ。

どんな時に Agent SDK を使う／使わないの判断軸

📖 この章で使う用語

（新しい用語はありません。これまでの言葉だけで読み進められます）

「とりあえず Agent SDK を使えばいい」とは、私は申し上げません。普段の開発スタイルと、「どこまで AI に自律させたいか」で選ぶのが現実的だと感じています。

私が使うのは、アプリや CI・本番の自動化に、ファイル操作やツール実行込みの自律的な動きを組み込みたいときです。ループを自分で書く手間が省け、速く形にできます。

逆に 使わない（別の選択肢を選ぶ）のは、次のようなときです。対話で十分なら、手元の Claude Code（CLI）で足ります。単純な1往復の生成だけなら、道具を使うループが要らないので、素の API のほうがシンプルです。実行環境ごと Anthropic に任せたいなら、Managed Agents という手もあります（こちらは公式情報からの整理として挙げています）。

ここでも「絶対にこれが正解」とは言えません。自分の開発スタイルと、自律させたい度合いの2軸で選ぶのが、結局いちばん遠回りしない選び方だと思います。

このセクションの出典は以下です。料金やバージョンの細部は変わり得るので、最終的には必ず公式でご確認ください。

Claude Agent SDK の概要・ツール・許可制御・CLI / 素の API との比較・最小サンプル・サブスク向けクレジットの案内出典: Claude Agent SDK overview｜Claude Docs（取得：2026-06-03）

Python 版：pip install claude-agent-sdk（Python 3.10 以上）、query() / カスタムツール / フック出典: claude-agent-sdk-python｜GitHub（取得：2026-06-03）

TypeScript 版：npm install @anthropic-ai/claude-agent-sdk、Claude Code バイナリ同梱、Claude Code SDK → Agent SDK 改名の注記出典: claude-agent-sdk-typescript｜GitHub（取得：2026-06-03）

検索ボリューム・難易度・成長率の実測（直近月 4,400／年平均 1,900／SEO 40／CPC $20.75／+1029%）出典: ラッコキーワード｜Claude Agent SDK 実測（取得：2026-06-03）

実装に踏み出す人へ：私が業務でたどった順番と、つまずきどころ

📖 この章で使う用語

スクリプト：「決まった作業を自動でやってくれる、短いプログラム」。台所のタイマー予約のような“仕込み”のイメージ。

正直に最初に書いておきます。Agent SDK は「コードを書いて使う」道具です。いま自分のパソコンで動かすには、Python か TypeScript の最小限の知識が要ります。ここが最初の壁なので、非エンジニアの方は「いきなり SDK」ではなく「まず Claude Code（CLI）で AI の自律的な動きに慣れて、必要になったら SDK に進む」のが現実的です。この章では、私が業務で実際にたどった順番と、その途中で止まった具体を、これから実装する方に向けて共有します（読みやすい一般論ではなく、自分が踏んだ手順そのものです）。

私がたどった順番：CLI → 最小サンプル → 許可制御 → 本番

最初にやったのは、Agent SDK ではなく Claude Code（CLI）を毎日触ることでした。「AI が勝手にファイルを読んで直す」感覚を手で掴んでおくと、SDK で同じ動きをコードに落とすときに迷いません。

次に、セクション 4の最小サンプル（allowed_tools=["Glob", "Read"] でフォルダを調べるだけ）を、検証用のフォルダで1回動かしました。ここで async / asyncio.run の書き方に最初は手が止まりましたが、一度通れば怖くありませんでした。

そこから業務に載せる段では、セクション 7の許可制御を必ず先に入れました。読み取り系の道具だけに絞り、書き換えや危険な操作は承認制に寄せ、フックで「いつ・何を・どう変えたか」をログに残す。私の場合、このログ設計を抜きに本番へ出すことはありませんでした。本番に載せたあと、権限を絞っていたおかげで「想定外のファイルに触れずに止まった」場面が実際にあり、最初から絞っておいてよかったと実感しています。

さらに踏み込んだのが、社内 API や自社データベースを MCP サーバー化して、Agent SDK から呼ぶ構成です。ここは作る側の話になるので深掘りはMCP サーバーの作り方の記事に譲りますが、「SDK は接続する側、MCP サーバーは接続される側」という関係だけ掴んでおくと、設計の見通しが立ちます。

つまずきどころ：私が実際に止まった3つ＋本番で気をつけた1つ

最初の3つはセクション 4でも触れた通りで、(1) Python が 3.10 未満だとインストールで弾かれる（「No matching distribution」）、(2) API キーの環境変数を設定し忘れて認証で止まる、(3) 非同期の書き方に慣れず最初の数行で止まる、でした。どれも一度通れば再発しません。

本番で一番気をつけたのは、4つ目——自律的に動くがゆえに、放っておくと権限が広すぎたり、呼び出し回数が膨らんだりすることです。だから「金額が動く処理・本番データベースへの書き込み・外部への送信は、必ず人間が最終確認する」を運用ルールにしました。ここを自動実行に丸投げしないだけで、事故の多くは防げます。

非エンジニアの入口は「小さな自動化」から

エンジニアでない方でも、Agent SDK が役に立つ場面はあります。たとえば事務職なら、フォルダ内のファイルを読んで一覧表や要約を毎朝作る“仕込み”を1つ用意しておく、といった小さな自動化です。営業なら、商談メモから日報や定型メールの下書きを作るところから。ただしどちらも、最初のスクリプトを用意するまではコードの基礎が要るので、まずは Claude Code（CLI）で下書き作りに使い、慣れてから自動化に進むのが、無理のない順番だと思います。

どの入口でも共通して大事なのは、出力は必ず人が確認することです。「これで誰でも稼げる」といった話ではなく、地道に手間を減らす道具として捉えるのが、結局いちばん長く使える付き合い方だと感じています。

まとめ：一行マップと、最初の一歩

最後に、迷ったときの一行マップをもう一度置いておきます。対話で使うなら Claude Code（CLI）／自分のアプリに組み込むなら Agent SDK／道具のループを全部自前で書くなら素の Anthropic API。この3択さえ覚えておけば、選択で迷いにくくなります。

進め方としては、まず Claude Code（CLI）で AI の自律的な動きに慣れる。次にセクション 4（Python）かセクション 5（TypeScript）の最小サンプルを、1回でいいので動かしてみる。動いたら、セクション 7の許可制御で安全に寄せる。そして料金は、使い方で変わるので必ず公式で確認する——この順番が、無理なく一歩ずつ進める道だと思います。

未経験から生成AIエンジニアを目指す方にとって、Agent SDK は「AIに仕事を任せる」を自分のアプリで実現する、面白い入口になります。私自身が業務で躓きながら使ってきた範囲を、こうして言葉にしました。営業出身でコードに苦手意識があった頃の自分に届けるつもりで書いたので、まずは「1回動かす」を達成してもらえたら嬉しいです。

よくある質問

Q1: Claude Agent SDK と Claude Code は何が違いますか？

A. 能力は近く、違うのは「どこで動かすか」です。ターミナルで人が対話しながら使うのが Claude Code（CLI）、同じ能力を自分のアプリ・スクリプト・CI に組み込むのが Agent SDK です。両方を併用するチームが多い印象です。

Q2: 旧「Claude Code SDK」と「Claude Agent SDK」は別物ですか？

A. 同じものです。2026 年に Claude Code SDK から Claude Agent SDK へ改名されました。パッケージ名は claude-agent-sdk（Python）/ @anthropic-ai/claude-agent-sdk（TypeScript）です。移行の案内も公式にあります。

Q3: Pro や Max のサブスクで Claude Agent SDK は使えますか？別料金ですか？

A. 基本は Anthropic API のトークン従量課金で動き、サブスクとは別系統です。ただし 2026-06-15 以降は、サブスク利用に別枠の月次「Agent SDK クレジット」が入る予定とされています。金額・条件は変わり得るので、必ず公式でご確認ください（取得：2026-06-03）。

Q4: Python と TypeScript、どちらでも使えますか？

A. 両方とも公式に提供されています。Python は pip install claude-agent-sdk（Python 3.10 以上）、TypeScript は npm install @anthropic-ai/claude-agent-sdk（Claude Code 本体が同梱されます）です。

Q5: 素の Anthropic API と Agent SDK、どちらを使えばいいですか？

A. 細かく制御したい・依存を最小にしたいなら素の API（道具を使うループは自前）。ファイル操作やツール実行込みの自律的な動きを速く組みたいなら Agent SDK（ループが入っています）。目的で使い分けるのが現実的です。

この記事は、営業出身の現役生成AIエンジニア aikun が、Claude Agent SDK を業務でエージェント実装に使う立場から整理しました（プロフィールは about ページをご覧ください）。料金・仕様は変動するため、本文の数値・手順は必ず公式情報で最新をご確認ください。記事内容に誤り・古い情報を見つけられた場合は、send@bon-bon-tools.com までご連絡いただけると助かります。