本文へスキップ

本ページはプロモーションが含まれています

AI

Claude Agent SDK入門|使い方とサブスクで使えるか

CATEGORY
DRAWN BY
TOM
DATE
REV.
READ
約31分
SHEETS
10枚
ClaudeAgent SDK(Python・TSで動かす入門)

トム

SESで約8年、環境を変えられないもどかしさの中にいました。32歳で自社開発企業に転職し、今はClaude Codeと自動化で、仕事も時間も組み直している途中です。
・Javaバックエンドエンジニア(Java歴12年以上)
・資格:基本情報技術者/応用情報技術者/Java Silver/Python3エンジニア認定基礎
詳細なプロフィール

𝕏

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の専用の章に移りました。

項目旧(Claude Code SDK)新(Claude Agent SDK)
Pythonのパッケージclaude-code-sdkclaude-agent-sdk
Pythonのimportclaude_code_sdkclaude_agent_sdk
オプションの型(Python)ClaudeCodeOptionsClaudeAgentOptions
TypeScriptのパッケージ@anthropic-ai/claude-code@anthropic-ai/claude-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から使えます。

機能SDKでの役割
組み込みツールファイルの読み書き・編集、コマンド実行、Web検索
フックエージェントの節目(ツールを呼ぶ前後など)で自分のコードを走らせる
サブエージェント小さな仕事を専用のエージェントに分けて任せる
MCP外部のツールやデータにつなぐ。自作の関数もMCPツールにできる
権限どのツールを自動で通し、どれを確認に回すかを決める
セッション会話を続ける・あとから再開する・分岐させる
スキル・コマンド・メモリ.claude/ と ~/.claude/ から、Claude Codeと同じように読み込む

このほか、スキル・エージェント・フック・MCPサーバーをまとめたプラグインも、ローカルのパスを指定して読み込めます。

Claude Codeを使い込んでいる人ほど、覚え直すことは少なめです。.claude/agents/ のサブエージェントや CLAUDE.md の書き方は、Claude Codeの記事で書いたものがそのまま効きます。

Claude Code本体の使い方はこちら

Claude Code・claude -p・Messages APIとの違い

似た道具が4つあり、違いは「誰がエージェントを動かすか」と「最初から何が入っているか」です。

道具向いている使い方ループを回すのは
Claude Code(CLI)ターミナルで対話しながら開発するClaude Code
claude -pシェルやcronから1回だけ頼むClaude Code(子プロセス)
◎ Claude Agent SDK自分のPython・TypeScriptのアプリに組み込むSDK(中でClaude Codeが動く)
Client SDK(Messages API)Claude APIを直接呼ぶ自分で書く(ベータのtool runnerもある)
Managed AgentsAnthropicのクラウドでエージェントを動かしてもらうAnthropic

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を積んでいて、末尾の番号がそろっていました。

ハマりポイント
SDKは .env を読まない

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
3
importと型の名前を変える

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種類です。

メッセージ中身よく使う場面
システム(init)起動時の情報。使えるツールの一覧などデバッグ
アシスタントClaudeの文章と、呼んだツール(tool_use)進み具合を表示する
ユーザーツールの実行結果(tool_result)ツールが何を返したか見る
結果(ResultMessage)成否(subtype)・最終回答(result)・費用(total_cost_usd)・session_id終わったかの判定、費用の記録

結果の 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 です。

比べる点query()ClaudeSDKClient
セッション呼ぶたびに新しく作る同じセッションを使い続ける
会話1往復同じ文脈で何往復も
接続自動connect()・disconnect() か async with で自分で管理
途中で止めるできないinterrupt() で止められる
フック・カスタムツール使える使える
向いている使い方決まった仕事を1回チャット画面、Claudeの返事で次の手が変わる処理

手元の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つのオプションは、効く段がそれぞれ違います。

オプション効く段動き
tools=["Read", "Grep"]見える・見えない書いた組み込みツールだけがClaudeに見える。MCPツールには影響しない
tools=[]見える・見えない組み込みツールを全部消す。自作のMCPツールだけで動かす
allowed_tools=["Read"]通す・通さない書いたツールを確認なしで通す。書いていないツールも消えはしない
disallowed_tools=["Bash"]両方ツール名だけなら、Claudeから見えなくなる
disallowed_tools=["Bash(rm *)"]通す・通さないBashは残し、rm * に当たる呼び出しだけを、どの権限モードでも拒否

いちばん誤解しやすいのは allowed_tools です。「このツールだけ使わせる」ではなく「このツールは確認なしで通す」という意味で、書いていないツールもClaudeには見えています。読むだけのエージェントにしたいなら、tools で道具そのものを絞ります。

固く閉じたエージェントを作るなら、allowed_tools と権限モード dontAsk を組み合わせます。書いたツールは通り、確認が要るはずの呼び出しは聞かずに拒否されます。

権限モード6種類の使い分け

権限モードは permission_mode(TypeScriptは permissionMode)で渡します。手元のPython版で型を見ると、受け付ける値は次の6つでした。

typing.Optional[typing.Literal['default', 'acceptEdits', 'plan', 'bypassPermissions', 'dontAsk', 'auto']]
モード動き向いている場面
defaultモードでは何も自動で通さない。許可ルールに無い呼び出しは can_use_tool のコールバックへ画面で人が承認するアプリ
dontAsk確認が要る呼び出しを、聞かずに拒否無人で回すジョブ
acceptEdits作業フォルダ内のファイル編集と mkdir・mv などを自動で通す隔離したフォルダでの試作
plan調べて計画を作る。編集はコールバックに回る大きな変更の前の下調べ
auto判定用のモデルがコマンドや通信を見て通すか決める対応モデルでの半自動の作業
bypassPermissionsほぼ全部を確認なしで通す使い捨ての隔離環境だけ

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 でもフックの許可でも覆せません。逆に、前の段で通った呼び出しはコールバックまで来ません。

ハマりポイント
bypassPermissions では allowed_tools が効かない

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の設定と同じ考え方です。

MCPの仕組みとサーバーの選び方

サブエージェントをコードで定義する

サブエージェントは、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は必要なだけターンを重ねます。セッションの扱いが要るのは、複数のプロンプトで文脈を共有したいときです。

やりたいことPythonTypeScript
1つのプロセスで会話を続けるClaudeSDKClientcontinue: true
再起動後に直前の会話へ戻るcontinue_conversation=Truecontinue: true
特定の会話を再開するresume=セッションIDresume: セッションID
元を残して別の道を試すresume + fork_session=Trueresume + forkSession: true

セッションIDは、結果のメッセージの session_id から取れます。会話の記録は ~/.claude/projects/<作業フォルダを変換した名前>/*.jsonl に保存され、Claude Codeのセッションと同じ場所です。

分岐で分かれるのは会話だけで、ファイルは分かれません。分岐した先でファイルを書き換えると、同じフォルダの元の会話からもその変更が見えます。ファイルの変更を巻き戻したいときは、別の機能(ファイルのチェックポイント)を使います。

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の記事と共通です。

Claude Code hooksの主要イベントと設定例

認証とサブスク(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を渡します。

モデルAPIのID入力(100万トークン)出力(100万トークン)
Claude Fable 5.2claude-fable-5-2$8$40
Claude Opus 5.5claude-opus-5-5$4$20
Claude Sonnet 5.5claude-sonnet-5-5$2$10
Claude Haiku 5.5claude-haiku-5-5$0.10から$0.50から

会社のクラウドを使うなら、環境変数を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もこの順番に従います。

  1. クラウドの資格情報(CLAUDE_CODE_USE_BEDROCK などが立っているとき)
  2. 環境変数 ANTHROPIC_AUTH_TOKEN
  3. 環境変数 ANTHROPIC_API_KEY
  4. apiKeyHelper のスクリプトの出力
  5. 環境変数 CLAUDE_CODE_OAUTH_TOKEN(claude setup-token で作る1年有効のトークン)
  6. Anthropicのプロファイル・フェデレーションの資格情報
  7. /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キーが向いています。トークンは発行した人のサブスクに結びつき、その人の枠から引かれるからです。

GitHub Actionsでの認証の選び方

他人に配るアプリに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にあります。

プラン毎月のAPIクレジット
Max$100
Ultra$200
TeamStandardの席1つ$20、Premiumの席1つ$100(合計の上限$500)
Free・Pro・Enterprise対象外

このクレジットは、Claude API・Managed Agents・Agent SDKに使えます。Claude Code本体の利用には使えません。そのため、つないだ組織のAPIキーでSDKを動かすと、プランの枠とは別にこのクレジットから引かれます。使い残しは請求の周期ごとに消え、繰り越しはありません。

LOG2026年10月〜週の上限の近くまで使っていると、枠の分け方が効いてくる

私はプライベートで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を呼んでいます。

LOGリポジトリの共通部品ログインが切れると、全部のジョブが一緒に止まる

この共通部品は、claude setup-token で作った長期のトークンをファイルから読み、CLAUDE_CODE_OAUTH_TOKEN に入れてから claude -p を呼びます。コードのコメントには、普段のログインは更新に失敗するとログインし直すまで全ジョブが止まるから、と理由が書いてあります。

認証切れの失敗は何度やり直しても直らないので、リトライしないようにもしてありました。SDKに移しても中身は同じClaude Codeなので、この認証の悩みはそのまま付いてきます。

claude -p のオプションや出力形式、launchdで定期実行するときの設定は、別の記事にまとめています。

claude -pの使い方と自動化の実例

Agent SDKに移すと楽になる場面

claude -p で困るのは、ツールの呼び出しを途中でつかみたいときです。JSONの出力を後から読むことはできても、「このコマンドは打たせない」を実行中に判断するには、フックや権限の設定を外から渡すしかありません。

claude -p で十分

・cronやlaunchdから決まった指示を1回投げる
・結果のテキストかJSONを受け取れればよい
・PythonとTypeScript以外の言語から呼ぶ

Agent SDK が楽

・自分の関数をツールとして渡したい
・ツールを呼ぶたびにコードで許可を決めたい
・会話を続けたり、分岐させたりしたい
・メッセージを1つずつ画面に流したい

私のリポジトリの9本は、どれも「決まった指示を投げて、文章を受け取る」形で、左側にすっぽり収まります。

移すかどうかは、ジョブごとに決めれば足ります。全部を一度にSDKへ書き換える必要はなく、右側の要件が出てきたジョブだけを移すのが、手間の小さい順番です。どちらも同じClaude Codeの本体を動かすので、CLAUDE.mdやスキルはそのまま引き継げます。

動かないときに見る6つの場所

SDKで最初につまずく原因は、だいたい認証・権限・設定の読み込みのどれかです。症状から引けるように、表にまとめます。

症状よくある原因確かめ方・直し方
Not logged in / Invalid API key実行したシェルにAPIキーが無い。.env に書いただけecho $ANTHROPIC_API_KEY で確かめ、SDKを呼ぶ前に自分で読み込む
読むだけで、編集やコマンドをせずに終わる権限モードが default のままで、確認が要る呼び出しが全部拒否されたallowed_tools に要るツールを書くか、permission_mode を決める
サブスクのつもりがAPIに請求が立った環境変数に ANTHROPIC_API_KEY が残っていて、そちらが優先されたClaude Codeの /status で使っている資格情報を見る
手元の .claude/ の設定が混ざる何も指定しないと、ユーザー・プロジェクト・ローカルの設定を読む隔離したいなら setting_sources=[](Python 0.1.59以前は空のリストが効かないので更新する)
本体が見つからないと言われるwheelが無くソース配布物から入った、npmで任意の依存を飛ばしたClaude Codeを別に入れる。TypeScriptは pathToClaudeCodeExecutable で場所を渡す
費用が思ったより膨らんだサブエージェントが子を呼び、上限を付けていなかったmax_turns と max_budget_usd を付け、結果の total_cost_usd を記録する

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個の項目があり、どこで何が決まるかを見ておくと、権限で迷う時間が減ります。

NEXT STEP
仮想環境に claude-agent-sdk を入れて、@tool で足し算のツールを1つ作り、ハンドラーを直接呼んでみる。

ここまではAPIを呼ばないので、費用はかかりません。動いたら max_turns と max_budget_usd を付けた query() を1回だけ流して、ResultMessage の total_cost_usd を見てみてください。

途中経過は、また書きます。

NEXT READ本棚から1本

AIで開発を組み直すなら、まずこの5冊から

入門・実践・設計まで、Claude Codeの本をレベル別に5冊選んで比べました。

→ おすすめ5冊を見る

トム

SESで約8年、環境を変えられないもどかしさの中にいました。32歳で自社開発企業に転職し、今はClaude Codeと自動化で、仕事も時間も組み直している途中です。
・Javaバックエンドエンジニア(Java歴12年以上)
・資格:基本情報技術者/応用情報技術者/Java Silver/Python3エンジニア認定基礎
詳細なプロフィール

𝕏

AI

TOC