Claude Agent SDKって結局なに？Claude CodeやAPIとの違い
Claude Code CLI・Client SDK・Managed Agentsとの使い分けはどうなっている？
室谷代表取締役まず押さえたいのが、Agent SDKは「Claude Codeを動かしているツール・エージェントループ・コンテキスト管理を、ライブラリとして外から使えるようにしたもの」だということなんですよ。中身は同じで、置き場所が違うという理解でいいんですよね。
テキトー教師DotAI 認定講師そこが最初の戸惑いどころで。現場でよく聞くのは「Claude Codeと何が違うんですか」なんですよ。
手で対話しながら使うのがCLI、自分のプログラムの中から呼ぶのがSDK、という分け方だと腹落ちしやすいみたいです。
手で対話しながら使うのがCLI、自分のプログラムの中から呼ぶのがSDK、という分け方だと腹落ちしやすいみたいです。
室谷代表取締役公式の比較表だと4つに分かれてて。ターミナルで対話するのがClaude Code CLI、ツールループを自分で書くならClient SDK（Claude APIを直接叩く方）、AnthropicにホストさせるならManaged Agents、自分のプロセスにClaude Codeのエージェントを組み込みたいならAgent SDK、という整理なんですよ。
PythonとTypeScript以外の言語なら、CLIを
PythonとTypeScript以外の言語なら、CLIを
claude -p --output-format json でサブプロセス実行する形になります。テキトー教師DotAI 認定講師なるほど、全部をSDKで書くという話ではなくて、ホストを誰が持つかで置き場所が変わる、と。そこが一本につながると、選定で迷わなくなりますね。
旧Claude Code SDKからの移行で何が変わった？
室谷代表取締役名前が変わった話も触れておきますか。旧Claude Code SDKからClaude Agent SDKになっていて、
既存コードをそのまま持ってくると、ここで落ちます。
ClaudeCodeOptionsがClaudeAgentOptionsにリネームされてるんですよね。既存コードをそのまま持ってくると、ここで落ちます。
テキトー教師DotAI 認定講師初めて触る人が最初に転ぶのがまさにそこで。しかも名前だけの話じゃなくて、システムプロンプト設定が統合されたり、設定が分離されたり、プログラムからサブエージェントを定義できるようになったり、セッションフォークが追加されたり。
中身もそれなりに変わってます。
中身もそれなりに変わってます。
室谷代表取締役あと地味に効くのがブランディングで。Anthropicは「Claude Agent」という名称の使用は認めている一方で、「Claude Code」を名乗るのは禁止しているんですよ。
自社プロダクトに組み込んで名前を付ける場面で、これを知らないと後から揉める案件になる。
自社プロダクトに組み込んで名前を付ける場面で、これを知らないと後から揉める案件になる。
テキトー教師DotAI 認定講師それは経営目線だと痛いやつですね。ライセンスはMITのOSSでSDK自体は無料、APIキーで使う分にトークン課金が乗る、という切り分けだけ押さえておけば、社内説明は通ると思います。
どんな用途で使われている？
室谷代表取締役で、実際どこで使われているのか。公式のサブエージェントのドキュメントとクイックスタートに出てくる形だと、このあたりの粒度です。
- コードレビュー：Read / Grep / Glob だけを持たせた code-reviewer サブエージェントに、セキュリティと品質の観点でレビューさせる
- テスト実行と失敗分析：Bash を持たせた test-runner サブエージェントにテストを走らせ、落ちた理由を分析させる
- バグ修正：既存コードのバグを見つけて修正するエージェント（クイックスタートの最小例）
テキトー教師DotAI 認定講師この3つに共通しているのが、ツールを絞っている点なんですよね。レビュー役には書き込み系を渡さない。
現場感覚で言うと、そこが安全に回すコツです。
現場感覚で言うと、そこが安全に回すコツです。
室谷代表取締役サブエージェントはコンテキストが親に累積しないので、大量のファイルを読ませても本体側が汚れない。並列でも走らせられる。
これが効いてくるのは、CIに組み込んで毎回の変更で回すような使い方なんですよね。作る手間より、回し続けるコストの方が経営判断としては重いんですよ。
これが効いてくるのは、CIに組み込んで毎回の変更で回すような使い方なんですよね。作る手間より、回し続けるコストの方が経営判断としては重いんですよ。
PythonとTypeScriptで最初の一歩、インストール前に何を揃える？
Python / TypeScript 導入から最小コード実行までの流れ
- 01前提を用意Node.js 18以上 または Python 3.10以上、Anthropicアカウントを揃える
- 02SDKをインストールPython: pip install claude-agent-sdk / uv add claude-agent-sdk。TypeScript: npm install @anthropic-ai/claude-agent-sdk
- 03APIキーを設定Claude Consoleで取得し export ANTHROPIC_API_KEY=your-api-key。.envは自動で読まれないためシェル側か実行プロセス側で渡す
- 04最小コードを実行Pythonは from claude_agent_sdk import query から開始。TypeScriptはtsx経由で実行し、CommonJSプロジェクトでは拡張子を .mts にする
- 05動かないときは前提を確認同梱CLIとNode.jsの前提を疑う。ARM64 Windowsのソース配布時や npm ci --omit=optional 時は同梱されないためClaude Code本体を別途入れる
Pythonはpipとuvのどちらで入れる？
- Python 3.10以上とAnthropicアカウントを用意する
- pipで入れるなら
pip install claude-agent-sdk - uvで入れるなら
uv add claude-agent-sdk
室谷代表取締役まず前提なんですけど、Node.js 18以上かPython 3.10以上、それとAnthropicアカウント。ここが欠けてると何も始まらないんですよね。
テキトー教師DotAI 認定講師初めて触る人は、Pythonの環境をpipで揃えるかuvで揃えるかで手が止まりがちです。プロジェクトで決まってるなら、それに従うのが早いんですよ。
室谷代表取締役そうですね。新規でPythonなら
どっちでも同じSDKが入るので、環境管理の流儀で選べばいい。
pip install claude-agent-sdk、uvなら uv add claude-agent-sdk。どっちでも同じSDKが入るので、環境管理の流儀で選べばいい。
テキトー教師DotAI 認定講師たしかに。ここで悩むより、まず入れて最小コードを動かした方が学びが早いですね。
TypeScriptはnpmで入れてtsxで動かすまで
- Node.js 18以上を用意する
npm install @anthropic-ai/claude-agent-sdkを実行する- 実行はtsx経由で行う
- CommonJSプロジェクトでは拡張子を
.mtsにする
室谷代表取締役TypeScript側はNode.js 18以上が前提で、
npm install @anthropic-ai/claude-agent-sdk。実行はtsx経由なんですよね。テキトー教師DotAI 認定講師ここで現場でよく聞くのが、CommonJSのプロジェクトでそのまま書いて動かないパターンです。拡張子を
.mts にする必要があるので。室谷代表取締役パッケージ管理の前提が揃ってないと、コード以前で止まる。SDKがCLIを同梱する設計なのも、配布の摩擦を減らす方向なんですよね。
テキトー教師DotAI 認定講師まずは小さく動かす、が効きますね。
APIキーの設定と最小コードはどんな形？
- Claude ConsoleでAPIキーを取得する
export ANTHROPIC_API_KEY=your-api-keyで環境変数に設定する.envは自動で読まれないため、シェル側か実行プロセス側で渡す- Pythonの最小コードは
from claude_agent_sdk import queryから始める
テキトー教師DotAI 認定講師APIキーはClaude Consoleで取って、
export ANTHROPIC_API_KEY=your-api-key。ここまではいいんですけど、.env を置いて動かないって相談が多いんですよ。室谷代表取締役SDKは実行プロセスの環境変数から読むだけで、
.env は自動では読まない。だからシェル側かプロセス側で渡す必要があるんですよね。テキトー教師DotAI 認定講師最小コードはPythonだと
from claude_agent_sdk import query で、async for message in query(prompt=...) の形。まずこれが動けば前進です。室谷代表取締役動かないときに疑う同梱CLIとNode.jsの前提
室谷代表取締役動かないときに疑うのは、同梱CLIとNode.jsの前提ですね。両SDKともClaude Code CLIバイナリを同梱するので、別途インストール不要な場合が多い。
テキトー教師DotAI 認定講師ただ、ARM64 Windowsでソース配布になった場合や、
npm ci --omit=optional でオプション依存を省いた場合は同梱されないんですよ。そこを見落とす人が多い。室谷代表取締役その場合はClaude Code本体を別途入れる。エラーの文言だけ追うと、コードの問題に見えてしまうのが厄介なんですよね。
テキトー教師DotAI 認定講師環境の前提を先に潰すと、デバッグの時間がかなり変わりますね。
APIキー以外の認証はある？サブスクやクラウド経由の選択肢
APIキーとクラウド経由、どう使い分ける？
室谷代表取締役認証まわり、ここで一度手が止まる人が多い印象なんですよね。基本はAPIキーなんですけど、法人で使うなら鍵の置き場所のほうが問題になりませんか。
テキトー教師DotAI 認定講師現場でよく聞くのは「鍵を配るのが怖い」なんですよ。クラウド経由にしておけば、鍵はそっち側に寄せられますから。
室谷代表取締役で、SDK側は環境変数ひとつで切り替わる。Bedrockなら
CLAUDE_CODE_USE_BEDROCK=1、Google CloudのAgent Platformなら CLAUDE_CODE_USE_VERTEX=1、Microsoft Foundryなら CLAUDE_CODE_USE_FOUNDRY=1 という具合に。テキトー教師DotAI 認定講師Claude Platform on AWS の場合は
CLAUDE_CODE_USE_ANTHROPIC_AWS=1 と、ワークスペースIDの指定が要るんでしたよね。ここは名前だけ似ていて別物なので、表にしておくと迷いにくいです。| 経路 | 設定する環境変数 |
|---|---|
| Anthropic API（APIキー） | ANTHROPIC_API_KEY |
| Amazon Bedrock | CLAUDE_CODE_USE_BEDROCK=1 |
| Claude Platform on AWS | CLAUDE_CODE_USE_ANTHROPIC_AWS=1 + ANTHROPIC_AWS_WORKSPACE_ID |
| Google Cloud（Agent Platform） | CLAUDE_CODE_USE_VERTEX=1 |
| Microsoft Foundry | CLAUDE_CODE_USE_FOUNDRY=1 |
APIキーの取得から実行までの流れはClaude Code API完全ガイドのほうで実装寄りに追っています。
Pro/Maxのサブスクで動かしたいとき
テキトー教師DotAI 認定講師手元のサブスクのまま動かせないか、という相談もよく来るんですよ。
claude setup-token で発行したトークンを CLAUDE_CODE_OAUTH_TOKEN に入れる、という共有がされているのはご存じですか。室谷代表取締役それは把握してます。ただ、出どころがAnthropicの外の開発者による報告で、公式ドキュメントの正式手順として一本化されているわけではない。
ここは線を引いておきたいところです。
ここは線を引いておきたいところです。
テキトー教師DotAI 認定講師そうなんですよね。しかもAnthropicは、事前承認がない限りサードパーティ製品でclaude.aiのログインやレート制限を提供することは認めていない、と明記しています。
自分の環境で試すのと、プロダクトに組み込むのは別の話です。
自分の環境で試すのと、プロダクトに組み込むのは別の話です。
室谷代表取締役プロダクト前提なら、最初からAPIキーかクラウド経由で設計しておく。順番を逆にすると後で作り直しになるので、そこは最初に決めたほうがいいんですよね。
互換エンドポイントに向けるときの設定
- コード内で
ClaudeAgentOptionsのenvにANTHROPIC_BASE_URLを指定する - 必要に応じて同じ
envにANTHROPIC_MODELを入れてモデル名を切り替える - 実行して応答が返るか確認する
- 挙動が想定と違う場合は公式リポジトリのissueを確認する（独立した解説ページは用意されていません）
テキトー教師DotAI 認定講師設定としてはこれだけで、要は接続先とモデル名を丸ごと差し替える形です。初めて触る人は、どこまでがSDK側の設定でどこからが接続先の都合か、切り分けに戸惑うみたいですね。
室谷代表取締役そこは分けて考えたほうがよくて、SDKはあくまで投げ先を変えているだけ。中身の互換性は接続先の責任範囲ですから、障害時の切り分けもそっちに寄る。
テキトー教師DotAI 認定講師なるほど。とりあえず動かすときは互換エンドポイント、業務で回すならクラウド経由かAPIキー、という住み分けになりそうですね。
query()とClaudeSDKClient、どっちから使い始めればいい？
単発タスクならquery()、対話ならClaudeSDKClientでいい？
テキトー教師DotAI 認定講師最初に迷うのが、query()から入るかClaudeSDKClientから入るか。現場でよく聞くのは「両方出てきて、どっちが正面玄関なのか分からない」という声です。
名前だけ見ると並列の選択肢に見えますけど、役割はけっこうはっきり分かれています。
名前だけ見ると並列の選択肢に見えますけど、役割はけっこうはっきり分かれています。
室谷代表取締役公式の整理だと、query()は単発タスク向けの非同期イテレータなんですよ。最小コードは
まずこれで1個動かすのが一番早い。最初の一歩は短い方がいいんですよね。
from claude_agent_sdk import query して、async for message in query(prompt="...") で回すだけ。まずこれで1個動かすのが一番早い。最初の一歩は短い方がいいんですよね。
テキトー教師DotAI 認定講師そこから先が分かれ目で。カスタムツールやフックを絡めたいなら、最初からClaudeSDKClientが要ります。
双方向の対話に対応しているのはこちらだけなので。query()で組んでから「やっぱり会話にしたい」となって書き直す人が多くて、そこが一番もったいないんですよ。
双方向の対話に対応しているのはこちらだけなので。query()で組んでから「やっぱり会話にしたい」となって書き直す人が多くて、そこが一番もったいないんですよ。
室谷代表取締役その手戻り、地味に高いんですよね。試作ならquery()で割り切るのはアリですけど、要件に「対話」や「自前ツール」が入っている時点で、最初からClaudeSDKClientを選んだ方がトータルで安い。
まとめるとこういう切り分けです。
まとめるとこういう切り分けです。
| query() | ClaudeSDKClient | |
|---|---|---|
| 向いている用途 | 単発タスク | 双方向の対話 |
| カスタムツール・フック | ここでは賄えない | こちらが必要 |
組み込みツールには何が入っていて、どう許可する？
テキトー教師DotAI 認定講師次に、何が最初から使えるのか。初めて触る人はここが一番ぼんやりします。
代表的な組み込みツールはRead、Write、Edit、Bash、Glob、Grep、WebSearchあたり。名前だけ見ると全部便利そうなので、とりあえず全部オンにしたくなるんですよね。
代表的な組み込みツールはRead、Write、Edit、Bash、Glob、Grep、WebSearchあたり。名前だけ見ると全部便利そうなので、とりあえず全部オンにしたくなるんですよね。
室谷代表取締役そこは事業判断なんですよ。Bashを渡すのとReadだけ渡すのでは、事故ったときの影響範囲がまるで違う。
で、制御は2つあって、
で、制御は2つあって、
allowed_toolsが自動承認、disallowed_toolsがツール自体を見せない、という役割分担になっています。この2つ、似ているようで効き方が違うんですよね。テキトー教師DotAI 認定講師そうなんですよ。ここ、ハマる人多いんですけど、disallowedは「実行したら拒否される」ではなくて「そもそも選択肢に出てこない」。
モデルから見ると存在しないのと同じなので、断られて別の手段を探す、みたいな回り道が起きないんです。拒否ルールと削除は別物として考える必要があります。
モデルから見ると存在しないのと同じなので、断られて別の手段を探す、みたいな回り道が起きないんです。拒否ルールと削除は別物として考える必要があります。
室谷代表取締役権限モードの細かい話は次の章に譲るとして、ここでは「見せる範囲」と「自動で通す範囲」を別々に決める、と覚えておけば十分。最初はRead系だけ渡して、必要になったら足していく。
この順番が一番事故らないと思います。
この順番が一番事故らないと思います。
権限設定はどう決める？acceptEditsやbypassPermissionsの落とし穴
6つの権限モードはそれぞれ何を許すのか
室谷代表取締役ここが一番事故りやすいところで。SDK側でツールを自動承認するのが allowed_tools、逆にツール自体を見せないのが disallowed_tools。
その上に権限モードが6種類あって、default / dontAsk / acceptEdits / bypassPermissions / plan / auto なんですよね。
その上に権限モードが6種類あって、default / dontAsk / acceptEdits / bypassPermissions / plan / auto なんですよね。
テキトー教師DotAI 認定講師名前だけ見ると「全部許可」が一番楽に見えるんですけど、実際は逆で。整理するとこうです。
| モード | 挙動 |
|---|---|
| default | 承認が要る呼び出しは canUseTool コールバックへ |
| dontAsk | プロンプトを出さず拒否 |
| acceptEdits | ファイル編集と mkdir/rm/mv などのファイルシステム操作を自動承認（作業ディレクトリ外や保護パスは対象外） |
| bypassPermissions | critical-path の削除などを除いて全承認。root/sudo では起動自体を拒否 |
| plan | 編集は常に canUseTool へ、読み取り専用ツールのみ自動実行 |
| auto | 分類モデルがシェルコマンドやネットワークリクエストを個別に許可/拒否 |
室谷代表取締役で、どれが優先されるかも決まってて。Hooks → 拒否ルール → ask ルール → 権限モード → 許可ルール → canUseTool コールバック、の順で評価されるんですよ。
つまり Hook で deny を返せば、後ろのモード設定に関係なくそこで止まる。
つまり Hook で deny を返せば、後ろのモード設定に関係なくそこで止まる。
テキトー教師DotAI 認定講師最初に戸惑うのがまさにそこなんですよ。「bypassPermissions にしてるのに止まる」ってなるのは、前段の Hook が効いてるからなんですね。
autoモードは何を自動で判断している？
テキトー教師DotAI 認定講師auto は比較的新しく追加されたモードで、分類モデルがシェルコマンドやネットワークリクエストを1件ずつ見て許可するか拒否するかを判断する仕組みです。人が全部承認しなくていい代わりに、判断そのものをモデルに渡す形になる。
室谷代表取締役これ、チームに配るときに効く話で。何を許すかのルールを人が持つのか、モデルに寄せるのかで運用がまるで変わるんですよね。
ルールを決める人がいないまま配ると、後から「なんでこれが通ってたの」ってなる。
ルールを決める人がいないまま配ると、後から「なんでこれが通ってたの」ってなる。
テキトー教師DotAI 認定講師現場感覚で言うと、auto は「便利になった」で終わらせず、何を判断させているかを一度読んでおく方がいいです。読まずに使うと、止まったときに理由が分からないままになりますから。
サブエージェントに権限が継承されるのはなぜ危ない？
6つの権限モードの挙動
| モード | 挙動 |
|---|---|
| default | 承認が要る呼び出しは canUseTool コールバックへ |
| dontAsk | プロンプトを出さず拒否 |
| acceptEdits | ファイル編集と mkdir/rm/mv などのファイルシステム操作を自動承認（作業ディレクトリ外や保護パスは対象外） |
| bypassPermissions | critical-path の削除などを除いて全承認。root/sudo では起動自体を拒否 |
| plan | 編集は常に canUseTool へ、読み取り専用ツールのみ自動実行 |
| auto | 分類モデルがシェルコマンドやネットワークリクエストを個別に許可/拒否 |
室谷代表取締役サブエージェントって、親の権限を引き継ぐんですよ。メインが plan モードなら、サブ側で acceptEdits を指定しても plan のまま動く。
逆にメインが bypassPermissions の場合は、サブエージェントも道連れで全承認になり得る。ここは公式ドキュメントにも注意として書かれてます。
逆にメインが bypassPermissions の場合は、サブエージェントも道連れで全承認になり得る。ここは公式ドキュメントにも注意として書かれてます。
テキトー教師DotAI 認定講師それが一番の落とし穴で。サブエージェントはコンテキストが分離されるから「別物」に見えるんですけど、権限は別物じゃないんですよね。
分かれるのは会話の文脈であって、許可の範囲ではない。
分かれるのは会話の文脈であって、許可の範囲ではない。
室谷代表取締役だから設計としては「メインを緩くしない」がそのままサブエージェントの安全策になる、と。サブエージェント側の作り込みはClaude Codeのエージェント機能完全解説の方が詳しいので、そっちと突き合わせながら決めるのが早いと思います。
テキトー教師DotAI 認定講師たしかに。権限だけ先に緩めて後から気づくパターンが一番怖いので、最初は default で組んで、必要なところだけ allowed_tools で足していく順番が安心ですね。
サブエージェント・MCP・フック・セッション、拡張の仕組みをまとめて
拡張の仕組み4種と選択肢
サブエージェントの作り方(3通り)
①プログラムで agents に AgentDefinition を渡す(description・prompt・tools・model を指定) ②.claude/agents/ に Markdown を置く ③定義不要で呼べる general-purpose。定義をコードに寄せると差分を追いやすく、コンテキストは親に累積しない
MCPで外部連携
stdio で別プロセスを立てる方式と、Python 関数に @tool を付けて in-process サーバーにする方式。in-process は別プロセス管理が不要で障害点が減る。まず関数を1つツール化して広げる
フック(PreToolUse)
ツール実行直前に Python 関数を走らせ、permissionDecision: deny で実行を止められる。許可・拒否の理由をコードに残せる。危ない操作だけに絞ると保守が軽い
セッション(resume/fork/continue)
resume は指定して再開、fork は分岐、continue は直前を自動再開。fork は同じ前提から別案を比較でき、価値がある時だけ使うとトークン増を抑えられる
サブエージェントの作り方は3通り、どれを選ぶ？
室谷代表取締役サブエージェントって、結局どう作るのが実務的なんですか。選択肢が多いと初手で迷うんですよね。
テキトー教師DotAI 認定講師三つあって、まずプログラムで
agents に AgentDefinition を渡す方法があります。description と prompt、tools、model を指定する形ですね。室谷代表取締役ファイルを置く方式も残ってるんですよね。チームで使うならどっちなんだろう。
テキトー教師DotAI 認定講師.claude/agents/ に Markdown を置くやり方と、何も定義しなくても呼べる general-purpose があります。定義をコードに寄せると差分が追いやすいので、最初はそこからが無難ですね。コンテキストが親に累積しないのも大きくて、本体側の使い方と並べて見たい人はClaude Codeのエージェント機能完全解説が参考になります。
MCPで外部ツールやデータソースにつなぐには
テキトー教師DotAI 認定講師外部連携は MCP ですね。stdio で別プロセスを立てる方式と、Python 関数に
@tool を付けて in-process のサーバーにする方式があります。室谷代表取締役別プロセス管理が要らないのは、運用コスト的にかなり違いますよ。障害点が減るので、小さいチームほど効きます。
テキトー教師DotAI 認定講師現場でよく聞くのは「サーバーをどこで動かすの」で止まる人ですね。in-process ならその悩みがかなり減ります。
室谷代表取締役なるほど。まず関数をひとつツール化して、そこから広げるのが現実的ですね。
最初から全部つなぐと、だいたい検証が回りません。
最初から全部つなぐと、だいたい検証が回りません。
フックでツール実行の直前に割り込むと何ができる？
室谷代表取締役フックって、監査ログみたいな使い方ができるんですか。
テキトー教師DotAI 認定講師できます。PreToolUse のタイミングで Python 関数を走らせて、
permissionDecision: deny を返せばその実行を止められます。室谷代表取締役権限モードだけだと「なぜ止まったか」が残らないので、そこは経営目線でも効きますね。事故の説明責任が変わります。
テキトー教師DotAI 認定講師許可・拒否の理由をコードに残せるのが大きいです。ただ、便利だからって全部フックに寄せると保守が重くなるので、危ない操作だけに絞るのがちょうどいいと思います。
resumeとforkで会話を続ける・分岐させる
テキトー教師DotAI 認定講師セッションは resume で再開、fork で分岐、continue で直前を自動再開、という整理です。
室谷代表取締役fork は分岐なので、同じ前提から別案を試せますね。意思決定の比較に使えるのが面白いところです。
テキトー教師DotAI 認定講師初めて触る人は resume と continue の違いで戸惑います。continue は直前をそのまま、resume は指定して戻すイメージです。
室谷代表取締役試行錯誤を並べるほどトークンも増えるので、fork は比較する価値がある時だけ、がいいですね。
料金はかかる？サブスクとAPIキー、2026年10月時点の課金事情
課金事情の変遷と現在地(2026年10月時点)
- 6月15日別枠課金が予定されるも当日に一時停止Agent SDKやclaude -pをサブスクの使用制限から切り離し専用クレジットに移す予定だった
- 2026年10月時点別枠課金は未実施今もPro/Max/Teamの使用制限から消費される
- 10月7日Max/TeamにAPI月額クレジット付与開始毎月の請求サイクルごとに付与。サブスク使用制限とは別枠の上乗せ。用途はAgent SDK、claude -p、Claude API、Claude Managed Agents。Proは対象外
6月に予定されていた別枠課金はどうなった？
室谷代表取締役まず大前提として、SDKそのものはMITライセンスのOSSで無料なんですよ。で、実際に財布に響くのは中のClaudeをどう呼ぶかのほうで・・・ここが混ざると判断を間違えるんですよね。
テキトー教師DotAI 認定講師たしかに。「SDKに料金表があるわけじゃない」って言うと、初めて触る人はけっこう驚きます。
何に払ってるのかが見えにくいんですよ。
何に払ってるのかが見えにくいんですよ。
室谷代表取締役6月15日に予定されてた「Agent SDKとかclaude -pをサブスクの使用制限から切り離して専用クレジットに移す」話があるじゃないですか。あれ、当日に一時停止されて、2026年10月時点でも実施されてないんですよ。
つまり今もPro/Max/Teamの使用制限から消費される。
つまり今もPro/Max/Teamの使用制限から消費される。
テキトー教師DotAI 認定講師なので「別枠課金が始まったらどうしよう」と身構えなくていい、と。ここを知らずに昔の情報のまま止まってる人が多くて、現場でもよく質問が出るポイントなんです。
Max/Teamに付く毎月のAPIクレジットは何に使える？
室谷代表取締役で、10月7日からMaxとTeamには毎月の請求サイクルごとにAPI月額クレジットが付くようになったんですよ。これはサブスクの使用制限とは別枠の上乗せ、という扱いですね。
テキトー教師DotAI 認定講師用途はAgent SDK、claude -p、Claude API、Claude Managed Agents。あとProは対象外なんですね。
ここは覚えておきたいところです。
ここは覚えておきたいところです。
室谷代表取締役そうなんですよ。経営目線で言うと「Maxに上げる理由が1つ増えた」という見方になるんですよね。
チームでエージェントを回すなら、クレジット込みの実質コストで見たほうが判断を誤らない。
チームでエージェントを回すなら、クレジット込みの実質コストで見たほうが判断を誤らない。
テキトー教師DotAI 認定講師順番としては、個人で試すうちはサブスクの範囲で回して、複数人で並走させ始めたらプランを見直す、くらいが自然ですね。
total_cost_usdは推定値、正式な請求はどこで見る？
室谷代表取締役実装してると結果メッセージにtotal_cost_usdが入ってくるので、これを見て「安いな」と思うんですけど・・・あれは推定値なんですよ。SDKがビルド時に埋め込んだ価格表から計算してるだけなので。
テキトー教師DotAI 認定講師価格改定があったり、SDKが認識しないモデルだったり、クライアント側で再現できない課金ルールがあったりするとズレる、と。最初に戸惑うのがまさにそこです。
室谷代表取締役データレジデンシーをusにするとトークン単価が1.1倍になる、みたいな例もありますからね。うちの現場でも、その数字をそのまま経費に突っ込むのは危ないなと。
時給換算の話をしてるのに土台の数字が推定値、では意味がないので。
時給換算の話をしてるのに土台の数字が推定値、では意味がないので。
テキトー教師DotAI 認定講師正式な金額はUsage and Cost APIかConsoleのUsageページで確認する、が正解なんですね。コスト構造の比較という文脈だと、Agent Teamsとの違いを整理した記事も合わせて読むと整理しやすいと思います。
よくある質問
Q1. 他のベンダーのエージェントSDKと迷ったとき、選び方の基準はどこに置くべき？
室谷代表取締役うちでも比較検討したんですけど、結局「モデルを差し替える前提かどうか」で見てます。特定のモデルに最適化されたSDKは最初の体験はいいんですけど、後から乗り換えるコストが重くのしかかるんですよね・・・
テキトー教師DotAI 認定講師現場感覚でも同じです。最初に触る人は「動くまでの速さ」で選びがちなんですが、三ヶ月後に触る自分のことを考えた方がいいですよ。
室谷代表取締役あと、権限まわりの設計思想がSDK側に組み込まれているかは見た方がいいですね。後付けで自前実装すると、そこが一番バグるので。
Q2. 社内の機密データをエージェントに触らせても大丈夫？
テキトー教師DotAI 認定講師ここ、最初に戸惑うのが「何を渡してよくて、何を渡しちゃいけないか」の線引きなんですよ。技術的な権限設定とは別の話として、社内ルールを先に決めておく必要があります。
室谷代表取締役そうですよね。権限を絞る話と、そもそも渡さない設計にする話は別物で。
そこを混ぜると、現場が「とりあえず全部読める状態」で走らせちゃう。
そこを混ぜると、現場が「とりあえず全部読める状態」で走らせちゃう。
テキトー教師DotAI 認定講師まずは触らせる範囲をディレクトリ単位で区切って、慣れてから広げる。この順番が安全ですね。
Q3. 本番サービスに組み込むと、どこで詰まりやすい？
室谷代表取締役デモは動くのに本番で死ぬ、というのはよく聞きます。原因はだいたいレート制限とタイムアウトで、エージェントは1リクエストで何回もモデルを呼ぶので、想定より呼び出し回数が膨らむんですよ。
テキトー教師DotAI 認定講師リトライ設計もそうですね。何度も同じ処理をやり直すと、結果が二重に反映されたりするので。
冪等性を意識しておくとだいぶ楽になります。
冪等性を意識しておくとだいぶ楽になります。
室谷代表取締役コスト側も同じで、上限をコードで切っておかないと、気づいたときには想定の何倍、ということが普通に起きます。
Q4. チームに広げるとき、最初に誰から始めるのがいい？
テキトー教師DotAI 認定講師現場でよく聞くのは「エンジニア全員に一斉に」で失敗するパターンです。まずは日常的に手を動かしている人ひとりが触って、つまずきを言語化してくれるのが一番早いですね。
室谷代表取締役経営目線だと、最初の1人が「時短の実例」を数字で出せると、他のメンバーの腰が軽くなるんですよ。ツールの説明より、その人の一時間がどう変わったかの方が説得力あるので。
Q5. 動かないときは、どこから疑えばいい？
テキトー教師DotAI 認定講師初めて触る人が一番ハマるのが、エージェントが何をしたのか見えないまま「動かない」と言ってしまうケースです。まずログを出して、どのツールを呼んだか追えるようにするのが先ですね。
室谷代表取締役あとは認証まわりを疑う順番も決めておくといいです。APIキーは合ってるのに権限で止まってる、みたいなのはエラーメッセージだけだと判別しづらいので。
テキトー教師DotAI 認定講師「モデルが悪い」と思う前に、渡している情報が足りているかを見る。これだけで解決する割合がぐっと変わりますよ。
まとめ
室谷代表取締役ここまで来ると、Claude Agent SDK って「すごいツール」というより「設計の自由度が高い道具」なんですよね。何を許可して、どこまで自動で走らせるかを決めるのはこっち側。
そこを曖昧にしたまま動かすと、だいたい後で痛い目を見ます。
そこを曖昧にしたまま動かすと、だいたい後で痛い目を見ます。
テキトー教師DotAI 認定講師たしかに。最初の一歩としては、小さなディレクトリで、権限を絞って、ログを見ながら一個だけ動かしてみる。
それで十分だと思います。
それで十分だと思います。
室谷代表取締役経営の感覚で言うと、PoC の段階で「どの業務の何分が減ったか」を測っておくのが大事なんですよ。数字が出れば社内の合意も早いですし、逆に出ないなら早めに引く判断もできます。
テキトー教師DotAI 認定講師あと、詰まったときは Claude Code 側の体験と見比べてみるといいですよ。同じ会社の技術なので、考え方が分かると一気に腹落ちします。
室谷代表取締役まずは公式のドキュメントを眺めて、自分の手元の小さな作業をひとつ任せてみる。そこからでいいと思います。
