Claude Codeに毎日仕事を頼んでいると、ふと「これ、自分のPythonから呼べたら楽なのに」と思う瞬間があります。
その答えがClaude Agent SDKです。Claude Codeと同じ道具・同じ考え方のループを、PythonとTypeScriptのライブラリとして使えます。旧名はClaude Code SDKで、パッケージ名ごと変わりました。
入れるのは pip install claude-agent-sdk か npm install @anthropic-ai/claude-agent-sdk の1行。認証の基本はAPIキーです。
気になるサブスク(Pro・Max)については、自分で使う範囲ならログインのままでも動き、使った分はプランの枠から引かれます。ただし、他人に配るアプリにclaude.aiのログインを組み込むことは認められていません。
手元のMacにPython版とTypeScript版を入れ、APIを呼ばない範囲で型と中身を確かめながら順に書きます。
この記事でわかること
- Claude Agent SDKの正体と、Claude Code SDKからの改名で変わった点
- Python・TypeScriptのインストールと、最小の
query()のコード - ツールの許可・6つの権限モード・カスタムツール・サブエージェント・セッション
- APIキーとサブスクのログイン、どちらで動かせるか(公式の書き方どおりに)
- Claude Code・
claude -p・Messages APIとの使い分け
PARTS LIST /目次
Claude Agent SDKとは?Claude Codeをライブラリにしたもの
Claude Agent SDKとは、Claude Codeのエージェントの仕組みを、自分のPythonやTypeScriptのプログラムから動かすためのライブラリです。仕組みとは、組み込みツール・権限・セッション・フックのことです。
ポイントは「Claudeに質問を投げるライブラリ」とは違うところです。ファイルを読む、コマンドを打つ、結果を見て次の手を決める、というループをSDKの側が回します。プログラムの側は、届いたメッセージを順に受け取るだけで済みます。
中身もClaude Codeそのものです。PythonとTypeScriptのどちらのパッケージにも、Claude Codeの本体(ネイティブのバイナリ)が同梱されていて、SDKはそれを動かしています。
Claude Code SDKから改名した経緯
最初は「Claude Code SDK」という名前でした。コーディング以外のエージェントも作れる道具になったため、Claude Agent SDKに改名され、ドキュメントもAgent SDKの専用の章に移りました。
名前のほかに、v0.1.0で既定の動きが1つ変わっています。Claude Codeのシステムプロンプトが既定では使われなくなりました。最小限のプロンプトで動くので、Claude Codeと同じふるまいが欲しいときは system_prompt={"type": "preset", "preset": "claude_code"} を明示します。
一方、設定ファイル(~/.claude/settings.json・.claude/settings.json・CLAUDE.md・自作コマンド)は、何も指定しなければCLIと同じように読み込まれます。v0.1.0で一度「読まない」に変わり、すぐ元に戻されました。古い記事を見て「設定は読まれない」と覚えていると、手元の .claude/ が混ざって首をかしげることになります。
SDKでできること7つ
Claude Codeでおなじみの機能は、ほぼそのままSDKから使えます。
このほか、スキル・エージェント・フック・MCPサーバーをまとめたプラグインも、ローカルのパスを指定して読み込めます。
Claude Codeを使い込んでいる人ほど、覚え直すことは少なめです。.claude/agents/ のサブエージェントや CLAUDE.md の書き方は、Claude Codeの記事で書いたものがそのまま効きます。
Claude Code・claude -p・Messages APIとの違い
似た道具が4つあり、違いは「誰がエージェントを動かすか」と「最初から何が入っているか」です。
Messages APIを直接使う場合、ツールの定義も、ツールを実行して結果を返すループも、全部自分で書きます。Agent SDKはそこを肩代わりします。「Readを呼ぶか決めるのはClaude、実際にファイルを読むのもSDK」という分担です。
逆に言えば、テキストを1回生成するだけなら、Agent SDKは重すぎます。手元で入れると後で書くとおり数百MBの本体が付いてくるので、文章の要約や分類だけならClient SDKで十分です。
道具の選び方を図にすると、次のようになります。
flowchart TD
A["Claudeに仕事を頼みたい"] --> B{"自分のコードから<br>呼ぶ?"}
B -->|"いいえ"| C["Claude Code(CLI)"]
B -->|"はい"| D{"ファイル操作や<br>コマンドも任せる?"}
D -->|"いいえ"| E["Client SDK<br>(Messages API)"]
D -->|"はい"| F{"Python・TSで<br>書く?"}
F -->|"はい"| G["Claude Agent SDK"]
F -->|"いいえ"| H["claude -p を<br>子プロセスで呼ぶ"]
PythonとTypeScript以外の言語から同じループを使いたいときは、claude -p に --output-format json を付けて子プロセスとして呼ぶ方法が案内されています。
インストールと動作環境|Python・TypeScript
インストールはどちらも1行で、Claude Codeを別に入れておく必要はほぼありません。必要なのはPython 3.10以上かNode.js 18.14以上と、Anthropicのアカウントです。
ここではインストールの手順に、手元のMac(Apple Silicon)で実際に入れたときの数字を添えます。動作確認した版はPython版が claude-agent-sdk 0.2.187、TypeScript版が @anthropic-ai/claude-agent-sdk 0.3.330 です(2026年11月)。
Pythonはpip install claude-agent-sdk
仮想環境を作ってからpipで入れます。uvを使うなら uv add claude-agent-sdk です。
python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk
Windowsは py -m venv .venv のあと .venv\Scripts\Activate.ps1 で有効にします。PowerShellが実行ポリシーで止めたら、先に Set-ExecutionPolicy -Scope Process RemoteSigned を打ちます。
ARM64のWindowsのように、環境向けのwheelが無くソース配布物から入った場合は、Claude Codeの本体が同梱されません。そのときはClaude Codeを別に入れておけば、SDKが PATH から見つけてくれます。
TypeScriptはnpmで入れる
新しいプロジェクトなら、package.json を作って type を module にし、SDKと tsx を入れます。
npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx
type: module にするのは、トップレベルで await を書くためです。既存のCommonJSのプロジェクトなら、ファイル名を agent.mts にすれば、プロジェクト全体を変えずに済みます。
TypeScript版は、Claude Codeの本体をnpmの「任意の依存(optionalDependencies)」として入れます。npm ci --omit=optional のように任意の依存を飛ばすと、対応OSでも本体が入りません。CIで本体が見つからないと言われたら、まずここを疑います。
手元で入れて分かった3つのこと
手元のMacで両方を入れてみると、公式の手順には書かれていない「重さ」が見えました。
- Python版のダウンロードは148.7MiB。中の
_bundled/claude(Claude Codeの本体)だけで347MBあった - TypeScript版もMac用の本体パッケージ(
claude-agent-sdk-darwin-arm64)が347MBで、Client SDK(@anthropic-ai/sdk)も一緒に入った - 同梱の本体は Claude Code 2.1.330。手元で普段使っている
claudeは 2.1.310 で、SDKのほうが新しかった
3つ目は地味に効きます。SDKはPATHの claude ではなく同梱の本体を使うので、CLIで試して動いた設定がSDKでは違う版で動く、ということが起こります。Python版の0.2.187とTypeScript版の0.3.330は、どちらも本体2.1.330を積んでいて、末尾の番号がそろっていました。
APIキーを .env に書いても、SDKは自動では読みません。エージェントを動かすプロセスの環境変数から読みます。Not logged in や Invalid API key が出たら、まず実行したシェルに ANTHROPIC_API_KEY があるかを確かめます。
.env で管理したいなら、Pythonは python-dotenv、Nodeは dotenv で、SDKを呼ぶ前に自分で読み込みます。
旧Claude Code SDKから移す4ステップ
古い claude-code-sdk で書いたコードが手元にあるなら、移行は名前の付け替えが中心です。Pythonなら次の順に進めます。
step
1旧パッケージを外す
pip uninstall -y claude-code-sdk を打ちます。もともと入っていなければ「Skipping」と警告が出るだけなので、そのまま次へ進んでかまいません。
step
2新パッケージを入れる
pip install claude-agent-sdk を打ち、requirements.txt や pyproject.toml に旧名が残っていれば書き換えます。
step
3importと型の名前を変える
from claude_code_sdk import query, ClaudeCodeOptions を from claude_agent_sdk import query, ClaudeAgentOptions に変えます。オプションの中身(model や permission_mode)はそのまま使えます。
step
4システムプロンプトの既定を確かめる
旧版の「Claude Codeのシステムプロンプトで動く」ふるまいに頼っていたなら、system_prompt にプリセット claude_code を明示します。何も書かないと最小限のプロンプトで動くので、答えの調子が変わります。
TypeScriptは npm uninstall @anthropic-ai/claude-code のあと npm install @anthropic-ai/claude-agent-sdk を入れ、importの文字列を差し替えます。package.json に旧名が残っていたら、版の指定も ^0.3.0 のように新しい系列へ上げます。
最小のquery()でエージェントを動かす
いちばん小さな使い方は、query() にプロンプトとオプションを渡し、返ってくるメッセージを async for で受け取る形です。
クイックスタートの例は、バグ入りの utils.py を読ませて直させる例です。空のリストで割り算して落ちる関数と、None を渡すと落ちる関数を用意し、エージェントに「落ちる箇所を直して」と頼みます。
Pythonのコード
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage
async def main():
# エージェントのループ。Claudeが動くたびにメッセージが流れてくる
async for message in query(
prompt="utils.py を読んで、落ちる原因になるバグを直してください",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob"], # この3つは確認なしで通す
permission_mode="acceptEdits", # ファイルの編集を自動で承認
),
):
if isinstance(message, AssistantMessage):
for block in message.content:
if hasattr(block, "text"):
print(block.text) # Claudeの考え
elif hasattr(block, "name"):
print(f"Tool: {block.name}") # 呼んだツール
elif isinstance(message, ResultMessage):
print(f"Done: {message.subtype}") # 最後の結果
asyncio.run(main())
python agent.py(uvなら uv run agent.py)で動かすと、Claudeの考えと呼んだツールが順に出て、最後に Done: success で終わります。実行後の utils.py には、空のリストと None を受けたときの守りのコードが足されています。
Pythonでは、続けて質問したい対話型のアプリなら query() の代わりに ClaudeSDKClient を使います。同じクライアントで client.query() を呼ぶたびに、前の会話の続きになります。
TypeScriptのコード
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "utils.py を読んで、落ちる原因になるバグを直してください",
options: {
allowedTools: ["Read", "Edit", "Glob"], // この3つは確認なしで通す
permissionMode: "acceptEdits" // ファイルの編集を自動で承認
}
})) {
if (message.type === "assistant" && message.message?.content) {
for (const block of message.message.content) {
if ("text" in block) {
console.log(block.text);
} else if ("name" in block) {
console.log(`Tool: ${block.name}`);
}
}
} else if (message.type === "result") {
console.log(`Done: ${message.subtype}`);
}
}
npx tsx agent.ts で動かします。Pythonとの違いは、オプション名がキャメルケース(allowedTools)になることと、アシスタントのメッセージの中身が message.message.content に入っていることです。
TypeScriptには型が付いているので、打ち間違いはコンパイル時に分かります。手元で permissionMode を "acceptEdit"(sが抜けた)にして tsc --noEmit をかけると、次のように止まりました。
error TS2820: Type '"acceptEdit"' is not assignable to type 'PermissionMode | undefined'. Did you mean '"acceptEdits"'?
返ってくるメッセージの種類
query() から届くメッセージは、大きく4種類です。
結果の subtype は、成功なら success、ターン数の上限なら error_max_turns、予算の上限なら error_max_budget_usd です。無人で回すなら、max_turns と max_budget_usd を必ず付けておくと、暴走したときに財布が守られます。
もう1つ、1回きりの query() はエラーの結果を流したあとに例外を投げます。try で囲まないと、session_id を拾う前にスクリプトが落ちます。
query()とClaudeSDKClientの選び方
Python版には、入口が2つあります。1回で終わる仕事なら query()、やり取りを続けるなら ClaudeSDKClient です。
手元の0.2.187で ClaudeSDKClient の公開メソッドを数えると15個ありました。set_permission_mode() や set_model() で途中から権限やモデルを変えられ、rewind_files() でファイルの変更を戻す機能も付いています。
TypeScriptには、この「会話を持ち続けるクライアント」に当たるものがありません。2回目以降の query() に continue: true を付けて、直前のセッションを続けます。以前あった実験的なV2のセッションAPI(createSession())は、TypeScript版0.3.142で外されました。
ツールの許可と権限モードの決め方
Agent SDKで一番気をつけたいのが権限です。ファイルを書き換え、コマンドを打てるエージェントを自分のプログラムに入れるので、「何を勝手にやってよいか」をコードで決めておく必要があります。
権限は、ツールの「見える・見えない」と「呼んだときに通す・通さない」の2段で考えると整理しやすくなります。
allowed_tools・tools・disallowed_toolsの違い
名前が似ている3つのオプションは、効く段がそれぞれ違います。
いちばん誤解しやすいのは allowed_tools です。「このツールだけ使わせる」ではなく「このツールは確認なしで通す」という意味で、書いていないツールもClaudeには見えています。読むだけのエージェントにしたいなら、tools で道具そのものを絞ります。
固く閉じたエージェントを作るなら、allowed_tools と権限モード dontAsk を組み合わせます。書いたツールは通り、確認が要るはずの呼び出しは聞かずに拒否されます。
権限モード6種類の使い分け
権限モードは permission_mode(TypeScriptは permissionMode)で渡します。手元のPython版で型を見ると、受け付ける値は次の6つでした。
typing.Optional[typing.Literal['default', 'acceptEdits', 'plan', 'bypassPermissions', 'dontAsk', 'auto']]
Claude Code v2.1.302以降を積んだSDKは、何も指定しなければ default で始まります。そして default では、許可ルールにもコールバックにも引っかからない呼び出しは拒否されます。「SDKで動かしたら何もできずに終わった」というときは、たいていここです。
モードを途中で変えることもできます。Pythonなら ClaudeSDKClient の set_permission_mode() で、最初は default で方針を見て、良さそうなら acceptEdits に切り替える、という使い方ができます。
権限が決まる順番
ツールを呼ぶたびに、SDKは決まった順番でチェックします。
flowchart TD
A["Claudeがツールを呼ぶ"] --> B["1. フック"]
B --> C["2. 拒否ルール<br>disallowed_tools"]
C --> D["3. 確認ルール<br>settings.json の ask"]
D --> E["4. 権限モード"]
E --> F["5. 許可ルール<br>allowed_tools"]
F --> G["6. can_use_tool<br>コールバック"]
どの段でも「ここで決める」「次へ回す」が起こります。拒否ルールは bypassPermissions でもフックの許可でも覆せません。逆に、前の段で通った呼び出しはコールバックまで来ません。
allowed_tools=["Read"] と bypassPermissions を一緒に渡しても、Bash・Write・Edit は確認なしで通ります。allowed_tools は「通すリスト」であって「これ以外を止めるリスト」ではないからです。
bypassPermissions を使うなら、止めたいものは disallowed_tools に書きます。can_use_tool に書いたチェックも、前の段で自動承認された呼び出しには走りません。すべての呼び出しを見たいなら PreToolUse フックに書きます。
SDKで広げる4つの機能|ツール・エージェント・会話・フック
組み込みツールだけでも動きますが、SDKらしさが出るのはここからです。自分の関数をツールにする、仕事を専用のエージェントに分ける、会話を続ける、危ない操作を途中で止める。この4つがそろうと、Claude Codeを部品として組み込む意味が出てきます。
順に、手元で確かめたコードと一緒に見ていきます。
自作関数をMCPツールにする
Pythonでは @tool デコレーターで関数をツールにし、create_sdk_mcp_server でMCPサーバーに包みます。このサーバーは別プロセスではなく、自分のアプリの中で動きます。
from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions
@tool("add", "2つの数を足す", {"a": float, "b": float})
async def add(args: dict) -> dict:
# Claudeに返す結果は content の配列で書く
return {"content": [{"type": "text", "text": str(args["a"] + args["b"])}]}
calc = create_sdk_mcp_server(name="calc", version="1.0.0", tools=[add])
options = ClaudeAgentOptions(
mcp_servers={"calc": calc},
allowed_tools=["mcp__calc__add"], # mcp__サーバー名__ツール名
)
手元では query() を呼ばず、作ったサーバーとツールの中身だけを確かめました。ツールのハンドラーは普通の非同期関数なので、Claudeを通さずに直接呼べます。
server type: sdk / name: calc
tool name: add
handler result: {'content': [{'type': 'text', 'text': '5'}]}
allowed_tools: ['mcp__calc__add'] / agents: ['reviewer']
ツール名は mcp__{サーバー名}__{ツール名} の形になります。サーバー名は mcp_servers に渡した辞書のキーです。例外を投げてもエージェントのループは止まらず、その文面がClaudeに渡ります。Claudeに読ませる文面を自分で決めたいなら、"is_error": True を付けて返します。
TypeScriptでは tool() と createSdkMcpServer() を使い、引数の型はZodで書きます。外部のMCPサーバー(GitHubなど)につなぐ方法は、Claude Codeの設定と同じ考え方です。
サブエージェントをコードで定義する
サブエージェントは、agents に AgentDefinition を渡して作ります。.claude/agents/ にファイルを置く方法もありますが、SDKのアプリにはコードでの定義が勧められています。実行時の条件で中身(使うモデルや厳しさ)を変えられるからです。
from claude_agent_sdk import ClaudeAgentOptions, AgentDefinition
options = ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Glob", "Agent"], # Agent ツールで呼び出す
agents={
"reviewer": AgentDefinition(
description="読むだけのレビュー係。品質と安全性を見るときに使う",
prompt="コードを読んで問題点を挙げる。ファイルは書き換えない",
tools=["Read", "Grep", "Glob"], # 読むだけに絞る
model="sonnet",
),
},
)
description と prompt が必須で、tools を省くと、サブエージェントで使えるツールを全部受け継ぎます。同じ名前のファイル定義があっても、コードで渡したほうが勝ちます。
気をつけたいのは数と費用です。サブエージェントは自分でAPIを呼び、さらに子を呼べます。入れ子の深さは既定で3階層まで、同時に走るのは20個まで。費用は max_budget_usd を付けない限り上限がありません。深さは環境変数 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH、同時の数は CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS で絞れます。
セッションを続ける・再開する・分岐する
1回の query() の中では、Claudeは必要なだけターンを重ねます。セッションの扱いが要るのは、複数のプロンプトで文脈を共有したいときです。
セッションIDは、結果のメッセージの session_id から取れます。会話の記録は ~/.claude/projects/<作業フォルダを変換した名前>/*.jsonl に保存され、Claude Codeのセッションと同じ場所です。
分岐で分かれるのは会話だけで、ファイルは分かれません。分岐した先でファイルを書き換えると、同じフォルダの元の会話からもその変更が見えます。ファイルの変更を巻き戻したいときは、別の機能(ファイルのチェックポイント)を使います。
フックで危ない操作を止める
フックは、ツールを呼ぶ前後などの節目で自分の関数を走らせる仕組みです。Claude Codeの settings.json に書くシェルのフックと同じ考え方で、SDKではPythonやTypeScriptの関数をそのまま渡せます。
たとえば、.env への書き込みと編集だけを止めるなら、PreToolUse に Write|Edit の絞り込みを付けて登録します。
from claude_agent_sdk import ClaudeAgentOptions, HookMatcher
async def protect_env_files(input_data, tool_use_id, context):
file_path = input_data["tool_input"].get("file_path", "")
if file_path.split("/")[-1].lower() == ".env":
return {
"hookSpecificOutput": {
"hookEventName": input_data["hook_event_name"],
"permissionDecision": "deny",
"permissionDecisionReason": ".env は書き換えない",
}
}
return {} # 何も決めない(ふつうの権限の流れに任せる)
options = ClaudeAgentOptions(
hooks={"PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])]}
)
手元では、この関数に作り物の入力を渡して直接呼び、返り値を見ました。.env には拒否が返り、それ以外のファイルには空の辞書が返ります。
/work/app/.env -> {'hookSpecificOutput': {'hookEventName': 'PreToolUse', 'permissionDecision': 'deny', 'permissionDecisionReason': '.env は書き換えない'}}
/work/app/main.py -> {}
registered: ['PreToolUse'] Write|Edit
フックの穴とPython版の差
Write|Edit で絞ったフックは、Claudeが Bash の echo で .env に書いたときには走りません。Bash も止めたいなら、Bash 用のフックかサンドボックスの設定を足します。また SessionStart・SessionEnd などいくつかのイベントは TypeScript 版だけで、Python 版では関数のフックとして登録できません。
フックの考え方そのもの(イベントの種類・設定ファイルでの書き方)は、Claude Codeの記事と共通です。
認証とサブスク(Pro・Max)で使えるか
Agent SDKで一番聞かれるのがここです。先に答えると、自分で使う範囲ならサブスクのログインでも動き、他人に配るアプリはAPIキーで作る、というのが公式の線引きです。
SDKは中でClaude Codeの本体を動かすので、認証の決まり方も本体と同じです。順に分けて見ていきます。
基本はAPIキー(ANTHROPIC_API_KEY)
クイックスタートの手順は、Claude ConsoleでAPIキーを作り、環境変数に入れる形です。
export ANTHROPIC_API_KEY=your-api-key
APIキーで動かした分は、Claude APIの料金として請求されます。モデルごとの料金は次のとおりで、SDKの model には "sonnet" のような別名か、claude-sonnet-5-5 のような正式なIDを渡します。
会社のクラウドを使うなら、環境変数を1つ立てて回し先を変えられます。Amazon Bedrockは CLAUDE_CODE_USE_BEDROCK=1、Google CloudのAgent Platformは CLAUDE_CODE_USE_VERTEX=1、Microsoft Foundryは CLAUDE_CODE_USE_FOUNDRY=1 です。
自分で使うならサブスクのログインでも動く
Claude Codeの認証は、複数の資格情報があると次の順で1つを選びます。SDKもこの順番に従います。
- クラウドの資格情報(
CLAUDE_CODE_USE_BEDROCKなどが立っているとき) - 環境変数
ANTHROPIC_AUTH_TOKEN - 環境変数
ANTHROPIC_API_KEY apiKeyHelperのスクリプトの出力- 環境変数
CLAUDE_CODE_OAUTH_TOKEN(claude setup-tokenで作る1年有効のトークン) - Anthropicのプロファイル・フェデレーションの資格情報
/loginでログインしたサブスク(Pro・Max・Ultra・Team・Enterprise)
つまり、APIキーを置かずにClaude Codeへログインしたままなら、SDKはサブスクで動きます。プランでログインして使ったAgent SDKと claude -p の分は、サブスクの利用枠から引かれます。
2026年6月には、Agent SDKと claude -p の利用をプランの枠から切り離す変更が予告されていました。これは一時停止になり、プランの枠から引かれる扱いが続いています。
APIキーがあると、そちらが勝つ
サブスクのつもりでも、環境変数に ANTHROPIC_API_KEY が残っていると、-p やSDKの実行では確認なしでAPIキーが使われます。API側に請求が立って驚かないよう、使っている資格情報は Claude Code の /status で確かめます。
もう1つの線引きは「ふつうの個人の使い方」です。Pro・Max・Ultraの利用上限は、Claude CodeとAgent SDKを個人がふつうに使う前提で決められています。自分のマシンで自分の作業を回す範囲が、サブスクで動かす想定です。
無人のジョブやCIで動かすときの認証
ブラウザでログインできない場所(cron・launchd・CI)でサブスクを使うなら、claude setup-token で作るトークンを使います。打つとブラウザの承認画面が開き、承認するとターミナルにトークンが表示されます。どこにも保存されないので、その場で控えます。
- 有効期限は1年。Pro・Max・Ultra・Team・Enterpriseのプランが要る
- 使う側では、環境変数
CLAUDE_CODE_OAUTH_TOKENに入れる - このトークンでできるのはモデルへのリクエストだけ。Remote Controlやclaude.aiのコネクターには使えない(手元で設定したMCPサーバーは動く)
- 起動を速くする
--bareモードでは読まれない。その場合はAPIキーかapiKeyHelperにする
普段のログインには期限があり、使っていても延びません。Claude Code v2.1.318以降なら、claude auth status --text の Sign-in ends: の行で終わる日が分かります。無人のジョブがある人は、この日付を先に見ておくと、ある日ジョブがまとめて止まる事態を避けやすくなります。
GitHub Actionsのように、組織で複数のリポジトリに配るなら、トークンよりAPIキーが向いています。トークンは発行した人のサブスクに結びつき、その人の枠から引かれるからです。
他人に配るアプリにclaude.aiログインは不可
ここは曖昧さがありません。事前の承認がない限り、サードパーティの開発者は、自分の製品でclaude.aiのログインやその利用上限を提供できません。Agent SDKで作ったエージェントも、この「製品」に含まれます。
- 製品やサービスとして作るなら、Claude ConsoleのAPIキーか、対応するクラウドで認証する
- 利用者の代わりに、Free・Pro・Max・Ultraの資格情報でリクエストを流さない
- claude.aiの資格情報やセッショントークンを集めたり保存したりしない
- 自分のアプリやサービスの名前に「Claude Code」を使わない(「Claude Agent」「○○ Powered by Claude」はよい)
名前の付け方にも決まりがあります。製品は自分の名前で出し、Claude Codeや他のAnthropic製品に見えないようにします。Claudeの名前を出すかどうかは任意です。
Max・Ultra・Teamに付く月々のAPIクレジット
サブスクとAPIキーの間には、もう1つ道があります。Max・Ultra・Teamのプランには、毎月のAPIクレジットが付きます。claude.aiの請求の設定からClaude Consoleの組織をつなぐと、その組織に届きます。受け取り方はAPI credits for Max, Ultra, and Team plansにあります。
このクレジットは、Claude API・Managed Agents・Agent SDKに使えます。Claude Code本体の利用には使えません。そのため、つないだ組織のAPIキーでSDKを動かすと、プランの枠とは別にこのクレジットから引かれます。使い残しは請求の周期ごとに消え、繰り越しはありません。
私はプライベートでMaxプランを契約していて、週の利用上限の近くまで使っています。ログインのままSDKで自動の仕事を足すと、その分も同じ枠から引かれ、手元のClaude Codeの作業とぶつかります。
APIクレジットをつないだ組織のAPIキーで回せば、手元のClaude Codeの枠には触りません。上限に届く週がある人ほど、どちらの財布から払うかを先に決めておく意味があります。
Claude Code・claude -pとどう使い分けるか
ここまで来ると、「じゃあ claude -p で足りるのでは?」という疑問が出てきます。目安は、シェルから1回頼むだけなら claude -p、プログラムの中で会話やツールを細かく扱うならAgent SDKです。
どちらも中身は同じClaude Codeなので、できることの差より、書き方と管理のしやすさの差で選ぶことになります。
私の自動ジョブはclaude -pのまま
このブログを回しているリポジトリでは、Agent SDKをまだ使っていません。リポジトリ全体を検索しても、SDKのパッケージを読み込むコードは1つもありませんでした。
代わりにあるのが、claude -p を子プロセスとして呼ぶ共通部品です。ニュースの選別、YouTubeの台本づくり、記事の言い回しの手直しなど、9本のスクリプトがこの部品経由でClaude Codeを呼んでいます。
この共通部品は、claude setup-token で作った長期のトークンをファイルから読み、CLAUDE_CODE_OAUTH_TOKEN に入れてから claude -p を呼びます。コードのコメントには、普段のログインは更新に失敗するとログインし直すまで全ジョブが止まるから、と理由が書いてあります。
認証切れの失敗は何度やり直しても直らないので、リトライしないようにもしてありました。SDKに移しても中身は同じClaude Codeなので、この認証の悩みはそのまま付いてきます。
claude -p のオプションや出力形式、launchdで定期実行するときの設定は、別の記事にまとめています。
Agent SDKに移すと楽になる場面
claude -p で困るのは、ツールの呼び出しを途中でつかみたいときです。JSONの出力を後から読むことはできても、「このコマンドは打たせない」を実行中に判断するには、フックや権限の設定を外から渡すしかありません。
claude -p で十分
・cronやlaunchdから決まった指示を1回投げる
・結果のテキストかJSONを受け取れればよい
・PythonとTypeScript以外の言語から呼ぶ
Agent SDK が楽
・自分の関数をツールとして渡したい
・ツールを呼ぶたびにコードで許可を決めたい
・会話を続けたり、分岐させたりしたい
・メッセージを1つずつ画面に流したい
私のリポジトリの9本は、どれも「決まった指示を投げて、文章を受け取る」形で、左側にすっぽり収まります。
移すかどうかは、ジョブごとに決めれば足ります。全部を一度にSDKへ書き換える必要はなく、右側の要件が出てきたジョブだけを移すのが、手間の小さい順番です。どちらも同じClaude Codeの本体を動かすので、CLAUDE.mdやスキルはそのまま引き継げます。
動かないときに見る6つの場所
SDKで最初につまずく原因は、だいたい認証・権限・設定の読み込みのどれかです。症状から引けるように、表にまとめます。
4つ目の設定の混ざり込みは、CIや他人に配るアプリで効いてきます。自分のマシンでは便利な ~/.claude/ の設定も、配った先では存在しないので、手元でだけ動くエージェントになりがちです。
費用の上限は、付けておけば error_max_budget_usd で止まり、例外として受け取れます。無人で回すスクリプトなら、この例外を拾って通知に流すところまで書いておくと安心です。
よくある質問
Claude Agent SDKについて、読者が引っかかりやすい7つの疑問をまとめました。
名前・認証・費用・Claude Codeとの関係が中心です。くわしい根拠は、本文の各見出しにあります。
Q1. Claude Agent SDKとは何ですか?
A1. Claude Codeのエージェントの仕組みを、PythonとTypeScriptのプログラムから使うためのライブラリです。組み込みツール・権限・セッション・フック・サブエージェントが使えます。パッケージにClaude Codeの本体が同梱されていて、SDKが本体を動かします。
Q2. Claude Code SDKとClaude Agent SDKは同じものですか?
A2. 同じものの旧名と新名です。Pythonは claude-code-sdk から claude-agent-sdk へ、TypeScriptは @anthropic-ai/claude-code から @anthropic-ai/claude-agent-sdk へ変わりました。v0.1.0から、既定のシステムプロンプトがClaude Codeのものではなくなった点に注意します。
Q3. Claude ProやMaxのサブスクで使えますか?
A3. 自分で使う範囲なら、Claude Codeにログインしたままで動き、使った分はプランの利用枠から引かれます。ただし、他人に配る製品にclaude.aiのログインを組み込むことは、事前の承認なしには認められていません。製品にするならAPIキーで認証します。
Q4. Agent SDKの料金はいくらですか?
A4. SDK自体は無料のライブラリで、お金がかかるのはClaudeの利用分です。APIキーならモデルごとのAPI料金(Claude Sonnet 5.5は入力100万トークンあたり$2、出力$10)、サブスクのログインならプランの枠から引かれます。Max・Ultra・Teamには毎月のAPIクレジットが付き、Agent SDKにも使えます。
Q5. Claude Codeを別にインストールする必要はありますか?
A5. ほとんどの環境では不要です。Python版・TypeScript版ともにClaude Codeの本体を同梱しています。ARM64のWindowsでソース配布物から入った場合や、npmで任意の依存を飛ばした場合だけ、Claude Codeを別に入れます。
Q6. claude -p とAgent SDKはどちらを使えばいいですか?
A6. シェルやcronから決まった指示を1回投げるなら claude -p、自分の関数をツールにしたい・ツールの呼び出しをコードで許可したい・会話を続けたいならAgent SDKです。どちらも中身は同じClaude Codeです。
Q7. Messages APIで自分で作るのと何が違いますか?
A7. Messages APIでは、ツールの定義も、ツールを実行して結果を返すループも自分で書きます。Agent SDKはファイル操作・コマンド実行・Web検索などの組み込みツールと、そのループを最初から持っています。テキストを生成するだけなら、Client SDKのほうが軽く済みます。
まとめ|まずはAPIを呼ばずに入れてみる
Claude Agent SDKは、Claude Codeを自分のPython・TypeScriptのプログラムに組み込むためのライブラリです。旧名はClaude Code SDKで、中ではClaude Codeの本体が動いています。
押さえる3点
- 入れるのは
pip install claude-agent-sdkかnpm install @anthropic-ai/claude-agent-sdk。本体が同梱されるので数百MBになる allowed_toolsは「確認なしで通す」の意味。道具を絞るのはtools、止めるのはdisallowed_tools- 自分で使うならサブスクのログインでも動き、プランの枠から引かれる。他人に配るならAPIキー
いきなりエージェントを走らせるより、先にパッケージを入れて、型とオプションを眺めるところから始めるのが安全です。ClaudeAgentOptions には手元の版で50個の項目があり、どこで何が決まるかを見ておくと、権限で迷う時間が減ります。
ここまではAPIを呼ばないので、費用はかかりません。動いたら max_turns と max_budget_usd を付けた query() を1回だけ流して、ResultMessage の total_cost_usd を見てみてください。
続きを追う:X(@Tom_Java_Tech) / RSS
途中経過は、また書きます。

