Claude Agent SDKは、Claude Codeのツール実行・エージェントのループ・コンテキスト管理を、PythonやTypeScriptから自社のプログラムに組み込めるAnthropicの開発ライブラリです。社内AIエージェントを構築する場合も、利用者の権限、実行環境の分離、監査、業務ごとの評価は別途設計する必要があります。
本記事は、社内基盤を検討する開発責任者や情報システム・DX推進担当者に向けて、SDKの使い方と費用、2026年10月に株式会社みずほフィナンシャルグループが発表した「みずほCowork」の二層構成、全社展開の前に決める項目を整理します。企業事例で公表された事実と、自社で導入する際の設計上の提案を区別して解説します。
この記事でわかること
- Claude Agent SDKがClaude Code・Claude API・Managed Agentsとどう違うか
- SDKの最小の使い方と、Skills(業務手順をフォルダにまとめる仕組み)の置き方
- 料金の考え方と、APIキー・Amazon Bedrock・Google Cloud・Microsoft Foundry経由の利用条件
- みずほCoworkで公表された内容と、公表されていない内容の区別
- 権限・監査ログ・評価・Skills管理・コストを、全社展開の前にどう決めるか
Claude Agent SDKはClaude Codeのエージェントを部品として使えるライブラリ
Claude Agent SDKは、Claude Codeが使っているツール実行・エージェントのループ・コンテキスト管理を、自社のプログラムに組み込めるようにしたライブラリです。Claude APIではモデルへのリクエストを送りますが、SDKはモデルの応答に応じてツールを実行し、その結果をモデルへ返すループも提供します。ファイルを読む、コマンドを実行する、結果を見て次の手を決める、という繰り返しを自分で書く必要がありません。
公式ドキュメントは、これを「Claude Codeをライブラリとして使い、本番用のAIエージェントを作る」ものと位置づけています。もとは「Claude Code SDK」という名前でしたが、コーディング以外のエージェント構築にも使われるようになったため、Claude Agent SDKに改称されました。旧名のパッケージ(@anthropic-ai/claude-code、claude-code-sdk)で書かれた情報を見かけたら、移行ガイドの対応表で読み替えます。
Claude Code・Claude API・Managed Agentsとの違い
四つの選択肢は、「ループを誰が書くか」と「どこで動かすか」の二軸で分かれます。
| 選択肢 | ループとツール実行 | 動く場所 | 向いている用途 |
|---|---|---|---|
| Claude API | 自分で実装する | 呼び出し元は自社、モデル推論は提供元 | 単発の生成、独自のエージェントを一から組む場合 |
| Claude Code | 完成品として提供される | 開発者の端末など | 個人・チームの開発作業 |
| Claude Agent SDK | ライブラリとして借りる | 自社が運用するプロセス | 自社の仕組みにエージェントを組み込む場合 |
| Managed Agents | Anthropicが提供する | Anthropic管理のクラウド(自社インフラでのセルフホストも可) | 運用基盤ごと任せたい場合 |
公式の使い分けでは、自社が運用するプロセスにClaude Codeのエージェントを組み込むならAgent SDK、AnthropicにホストさせるならManaged Agentsです。2026年11月16日に確認した公式説明では、Managed Agentsはベータ版です。Anthropicがホストする方式では、セッションの会話記録は削除するまで保持され、ゼロデータ保持(ZDR)の対象外です。ただし、ZDRにはself-hosted Managed Agentsの例外があり、ホスト方式ごとの条件確認が必要です。HIPAA BAAの対象外という条件もあるため、データ保持と実行環境の要件をそろえて比較します。
仕組みも押さえておくと、設計の見通しが立ちます。SDKは内部でclaudeのコマンドを子プロセスとして起動し、標準入出力で通信します。1セッションにつき1プロセスです。このコマンド本体はSDKのパッケージに同梱されており、SDKを更新すればコマンドも更新されます。つまり、利用者ごとに環境を分けたい場合は、プロセスやコンテナを増やす設計になります。
組み込みツール・Hooks・MCPなど、できること
公式の機能一覧にあるものを整理します。
- 組み込みツール:ファイルの読み書き・編集、コマンド実行、Web検索
- Hooks:ツール実行の前後に自前の処理を差し込む仕組み。禁止や記録に使う
- Subagents:役割を分けた別のエージェントを呼び出す
- MCP:外部システムやデータベースとつなぐ標準規格
- Permissions:ツールごとの許可・拒否・確認の制御
- Sessions:会話の再開とフォーク
- Skills・スラッシュコマンド・メモリ:設定に応じて、
.claude/配下のファイルやCLAUDE.mdなどを読み込む
これらは、社内エージェントの周辺の仕組み、つまりハーネスの部品そのものです。SDKが出荷時に持っている部品と、自社で足すものの境目を知ることが、基盤設計の最初の仕事になります。
料金はSDK本体・モデル利用料・運用費を分けて考える
SDK自体は無償のライブラリですが、自社基盤ではモデル利用料に加え、実行環境、ストレージ、ログ保存・監視などの費用がかかります。公式の標準手順はAPIキー認証(環境変数ANTHROPIC_API_KEY)で、Anthropicの商用利用規約の下で提供されます。自社が顧客向けの製品やサービスの動力にする場合も同じ扱いです。
法人の社内基盤であれば、クラウド経由の利用も選べます。切り替えは環境変数で行いますが、各クラウドの認証情報とアクセス権の設定も必要です。
| 経由先 | 有効にする環境変数 |
|---|---|
| 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、旧Vertex AI) | CLAUDE_CODE_USE_VERTEX=1 |
| Microsoft Foundry | CLAUDE_CODE_USE_FOUNDRY=1 |
注意点が二つあります。第一に、事前承認がない限り、第三者の開発者が自作の製品(Agent SDK製を含む)でclaude.aiのログインやそのレート制限を提供することはできません。社内基盤でも、個人のサブスクリプションを全社員に使い回す構成は想定されていないので、APIキーかクラウド経由で組みます。
第二に、ブランド表記の規則です。「Claude Agent」や「{自社名} Powered by Claude」は使えますが、「Claude Code」「Claude Code Agent」は使えません。社内ポータルの名前を決めるときに引っかかります。
サブスクリプションの扱いは動いています。Claudeヘルプセンターの2026年11月時点の記載では、Agent SDKやclaude -pをClaudeプランのサインインで使う場合は従来どおりサブスクリプションの上限から消費されます。Agent SDKの利用の扱いを変える先行発表の案は、2026年6月15日の更新で一時停止とされ、現在も続いています。なお、Max・Ultra・Teamプランには2026年10月7日から月次のAPIクレジットが付き、リンクしたClaude Consoleの組織のAPIキーでSDKを使う場合に充当されます。法人の基盤はAPIキーかクラウド経由が前提なので、この論点は補足にとどまります。
公式のホスティング解説は、最小構成のコンテナ費用の概算として1時間あたり約0.05米ドル、リソースの出発点として1エージェントあたり1 GiBのメモリ・5 GiBのディスク・1 CPUを示しています。料金表の確定価格ではなく、税の扱いやログ保存・監視などの費用は別途確認が必要です。モデル、入出力トークン数、実行時間、同時利用数、キャッシュの再利用率で費用は変わります。PoCでは、1件あたりのモデル利用料と基盤・保管・監視費を分けて測定します。
みずほCoworkは「汎用エージェント層+社内独自層」の二層構成で作られたPoC
みずほCoworkは、Claude Agent SDKを活用した自律型AIエージェント基盤のPoC(概念実証)です。2026年10月5日に発表されました。ここで先に区別しておきます。Anthropicの製品である「Claude Cowork」とは別物で、Claude Coworkを導入したという話ではありません。名称が似ているだけで、みずほが自社で基盤を作り、その中核にAgent SDKを使っています。
公式発表で確認できる範囲と、利用実績の区別
みずほFGのリリース(PR TIMES)に書かれているのは、次の内容です。
- 目的:生成AIとの対話から、AIに業務を任せる働き方への転換
- 開発体制:AWSプロフェッショナルサービスの支援を受けて開発
- 仕組み:AWS上に社員一人ひとりの専用作業環境を割り当て、与えられた権限の範囲内で作業手順を組み立てる。資料の横断調査・分析・整理、画面操作、レポートやプレゼン資料の作成を行う
- PoCの対象業務:案件資料の分析・整理と資料作成、調査データの分析、業務監査に関するチェック、専門レポートの海外向け要約・翻訳
日経クロステックの報道は補足の参照先とし、ここでは2026年10月5日の公式発表で確認できる範囲を整理します。公式発表には、導入人数や全社展開時期、PoCの対象人数・部署の規模、費用、使用モデル、評価方法の記載はありません。「約3万人」「2027年度」といった数字を、公式に公表された利用実績として扱うことはできません。効果の測定結果も、この発表では示されていません。
つまり、みずほの事例から読み取れるのは「設計の考え方」であって、「効果の実績」ではありません。
二層のハーネス構成とSDKの機能の対応
リリースが示す構成は、役割の異なる二つの層です。
汎用エージェントレイヤーは、Claude Agent SDKのツール実行とコンテキスト管理を使い、ファイル操作・情報収集・分析・成果物作成といった基本動作を受け持ちます。みずほ独自レイヤーは、社内ルールに準拠したガードレールを組み込み、各部門の業務手順・判断基準・専門知識をSkillsとして追加する層です。基盤技術と業務ノウハウを切り分けて蓄積するので、最新のモデルや技術を取り込みやすくなる、というのが狙いとされています。
この二層をSDKの部品に当てはめると、次の整理になります。リリースはどのSDK機能を使っているかまでは書いていないため、あくまで自社で同じ形を作るときの対応づけです。
| 層の役割 | SDKで対応する部品 | 自前で用意するもの |
|---|---|---|
| 基本動作(読む・調べる・書く) | エージェントのループ、組み込みツール、コンテキスト管理 | 対象業務・利用ツールの選定、入出力の接続 |
| 業務手順・判断基準 | Skills(SKILL.mdを含むフォルダ) | 内容の作成、承認、更新 |
| 社内ルールに沿った制御 | Permissions、Hooks | ルールの設計、入出力の統制 |
| 利用者ごとの実行環境 | 1セッション1プロセスの構造 | コンテナ分離、ネットワーク制限 |
リリースの実行環境の記載を見ると、最後の行が「自前で用意するもの」の中心であることがわかります。作業環境はみずほが管理するAWS上で完結し、利用者の業務端末やローカルデータには直接アクセスしません。Amazon ECS on AWS FargateとAmazon S3 Filesで利用者ごとに実行環境と作業領域を分離し、利用状況に応じて起動・破棄します。入出力の統制にはAmazon Bedrock Guardrailsを使い、ログ記録と運用監視も組み込まれています。
端末から切り離されているので、利用者が端末を操作していない間も長時間の処理が続きます。エージェントに仕事を任せる体験は、この「手元のPCに依存しない」設計から生まれています。
今後の予定が示す、Skills中心の育て方
リリースの今後の予定は三つです。各部門の知識・社内ルールをSkillsとして検証・整備し、対応業務を広げていくこと。API整備が難しい古いシステム向けに、ブラウザ画面を操作する仕組みを必要に応じて作ること(大規模改修や新規API開発は前提にしない)。AIが必要なタイミングで適切な人に確認・承認を求めながら進める体験を更新し続けること。
どれも、基盤を作って終わりではなく、現場に合わせて足していく前提の計画です。Skillsの承認フローや権限モデルの詳細は公表されていませんが、育てる対象が「モデル」ではなく「周辺の仕組み」に置かれている点は読み取れます。
SDKの使い方:最小のコードとSkillsの置き方
SDKの基本は、query()にプロンプトとオプションを渡し、返ってくるメッセージを順に受け取る形です。要件はNode.js 18.14以上、またはPython 3.10以上で、パッケージ名はclaude-agent-sdk(Python)と@anthropic-ai/claude-agent-sdk(TypeScript)です。更新が速いため、導入・更新前にPython版のリリース履歴とTypeScript版のCHANGELOGを確認し、検証したバージョンを依存関係に固定します。
最小のエージェントを動かすコード
クイックスタートの形に沿った最小例です。Python環境にpip install claude-agent-sdkで導入し、検証用のauth.pyを置いたディレクトリから実行します。allowed_toolsは事前承認するツールの一覧であり、利用可能なツールをその一覧だけに制限する設定ではありません。この例はファイル編集とコマンド実行を許可するため、機密情報を含まない検証用環境で試します。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="auth.py のバグを見つけて直してください",
options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
):
print(message)
asyncio.run(main())
APIキーは環境変数ANTHROPIC_API_KEYから読まれます。.envファイルは自動では読み込まれないので、起動前に環境変数へ流し込みます。他の言語から使う場合は、claudeコマンドを-pと--output-format jsonで呼びます。
Skillsはファイルとして置く、登録APIはない
Skillsは、業務手順・判断基準・スクリプトをSKILL.mdと一緒にフォルダへまとめたものです。依頼の内容に応じて、必要な情報が段階的に読み込まれます。仕組みの詳細はAgent Skillsの解説記事にまとめています。
SDKのSkills仕様では、押さえる点が四つあります。
.claude/skills/<名前>/SKILL.mdとしてファイルで置きます。プログラムからSkillを登録するAPIはありません- 設定の読み込み元(
settingSources、Pythonではsetting_sources)にuserやprojectを含めると、Skillが見つかります(既定のオプションでは両方が読み込まれます) skillsオプションで"all"、名前のリスト、空リスト[]を指定すると、呼び出せるSkillを絞れます- 起動時には各Skillのメタデータだけを読み、呼び出されたときに全文を読みます
たとえば「稟議書の書式チェック」の手順をSKILL.mdに書き、経理部門のエージェントにだけskillsで渡す、という使い方ができます。部門ごとの知識を部門ごとのフォルダで管理するのは、みずほの「各部門の業務手順を追加する」形と同じ発想です。
Skillsの仕様は、2026年10月22日にAgentic AI Foundation(AAIF)へ寄贈されました。AAIFはLinux Foundation傘下の団体で、MCPもすでに寄贈されています。Skills資産を特定のベンダーに閉じない形で積み上げられるのは、長く育てる社内基盤にとって安心材料です。
OpenAI Agents SDK・Google ADKとの比較軸
他のフレームワークと比べるときは、モデル、ツール実行、運用の役割分担を同じ軸で確認します。
| 比較軸 | Claude Agent SDK | OpenAI Agents SDK | Google ADK |
|---|---|---|---|
| ループとツール実行 | Claude Codeのループと組み込みツール | エージェントのループ、ツール、ハンドオフなど | エージェント実行とツール、順次・並列・ループなどのワークフロー |
| モデル | Claudeモデル(クラウド経由も可) | OpenAI以外のモデルにも対応 | Gemini・Claudeなど複数モデルに対応 |
| 実行環境の隔離 | 自社のプロセス・コンテナ等で設計 | Sandbox Agentsで実行基盤を選択。ローカル実行だけではOS隔離なし | コンテナやGoogle Cloudなど、選んだ実行基盤で設計 |
| 観測 | OpenTelemetryで自社コレクターへ送信 | 組み込みトレーシング、外部送信先への拡張 | ログ・メトリクス・トレース |
| Skillsの読み込み | ファイル配置とskillsオプション | Sandbox AgentsのSkills機能 | SkillToolset |
比較の根拠は、OpenAI Agents SDKの概要、サンドボックスの実行基盤、Skillsの読み込み、Google ADKのモデル対応・デプロイ・Skillsです。対応機能は言語・バージョンでも異なるため、採用する版で確認してください。SKILL.mdを共有できても、接続ツールや権限設定までそのまま移せるとは限りません。
複数のモデルを混ぜて使うことが必須なら、別の軸での検討が必要です。Agent SDKはClaudeのモデルを前提にした作りです。Claudeを中心に据える方針が決まっていて、ファイル操作や調査・資料作成のような「手を動かす」業務を任せたい場合に、Agent SDKの強みが出ます。
全社展開の前に決める五つの論点:権限・監査・評価・Skills・コスト
全社展開に向けて確認したいのは、権限・監査・評価・Skillsの管理・コストです。以下では公式仕様と、それを踏まえた自社運用の設計案を整理します。
権限は「許可リスト」だけでは足りない
権限の評価は、Hooks、deny(拒否)、ask(確認)、権限モード、allow(許可)、canUseToolの順に行われます。拒否ルールはbypassPermissions(確認を飛ばして実行するモード)でも効きます。
落とし穴はallowed_toolsです。これは「事前に承認するツール」の一覧であって、bypassPermissionsのもとでは未列挙のツールも通ります。使わせたくないツールはdisallowed_toolsで明示的に塞ぎます。無人運用では、allowedToolsとpermissionMode: "dontAsk"を組み合わせて確認待ちの操作を拒否できます。ただし、承認不要の読み取りなどは未列挙でも実行されるため、厳密な許可リストにはなりません。ツールの提供範囲を絞るtools、明示的な拒否、実行環境側の制限を組み合わせます。
環境の側でも守ります。安全なデプロイの指針は、最小権限・多層防御に加え、資格情報を境界の外のプロキシで注入してエージェント自身に鍵を見せないこと、通信先をプロキシ経由のドメイン許可リストに絞ること、コンテナを読み取り専用にして不要な権限を落とすことを挙げています。マルチテナントや信頼できない入力を扱うなら、gVisorやVMも選択肢です。プロンプトインジェクションを脅威モデルに入れる前提も明記されています。権限管理の全体像はAIエージェントの権限管理で扱っています。
利用者ごとに設定を分ける場合は、settingSourcesを空にしないと、実行ユーザーの設定やプロジェクトのCLAUDE.mdが読み込まれます。デプロイ済みアプリやマルチテナントでは[]にして分離し、CLAUDE_CODE_DISABLE_AUTO_MEMORY=1、テナント別のCLAUDE_CONFIG_DIRと作業ディレクトリ、テナント別の外向き通信ルールを組み合わせます。
監査ログはHooksとOpenTelemetryで残す
HooksのPreToolUseはツール実行前にブロックでき、PostToolUseは実行後の監査証跡を残せます。公式が用途として「コンプライアンスのためにツール呼び出しを記録・監査する」と明記しています。セッション保存を担うSessionStoreはベストエフォートで、失敗するとmirror_errorが返るため、保存の成否を監視する設計にします。
自社ホストのSDKでは、環境変数(CLAUDE_CODE_ENABLE_TELEMETRY=1、OTEL_*_EXPORTER=otlp、トレースはCLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1)を設定して、自前のコレクターへトレース・メトリクス・ログを送れます。OpenTelemetryの公式説明では、プロンプト本文とツールの入力は既定で出力されません。監査用途では、収集対象だけでなく、送信失敗や保存の欠落を検知する仕組みも設計します。
Claude Platform側にもOpenTelemetry形式のトレース送信がパブリックベータで用意され、Datadog、Grafana Cloud、Langfuseなどへ連携できます。人の承認が要る操作は、canUseToolのコールバックやaskルールで実装します。「どの操作を人に確認させるか」は技術ではなく、業務上のリスクで決める論点です。
Skillsの承認運用と評価は自社で設計する
SDKのSkills読み込み機能だけでは、自社の承認者や業務ごとの合格基準は決まりません。みずほのリリースも、各部門の知識・社内ルールをSkillsとして検証・整備する方針を示していますが、承認体制の詳細は記載していません。
以下は、社内基盤を運用する際の設計案です。
- 作成者と承認者を分け、
SKILL.mdの変更をレビューの対象にする - 本番に配布するSkillのバージョンを固定し、いつの版が動いたかを追跡できるようにする
- 業務ごとに「正解の見本」を用意し、Skillの変更前後で出力を比べる
- トレースを評価用のツールに流し、失敗した依頼を集めて次の改善に回す
もう一つ、Skillsの安全性には注意が要ります。Skillは任意のファイルやスクリプトを含められ、ReadやBash経由で到達できます。skillsで呼び出しを絞っても、ファイル自体はディスク上に残ります。「見せたくないSkill」は、そもそもそのエージェントの環境に置かない運用が確実です。Skillsを足し続けて品質を保つ作業は、AIエージェントの運用・保守の中心になります。
コストは予算の停止条件と実際の請求額を分けて管理する
maxTurnsでターン数を、maxBudgetUsdで呼び出し単位の予算の停止条件を設定できます。ただし、予算はモデルの応答後に推定費用で判定されるため、最後の応答や停止までのサブエージェント分で設定額を超える可能性があります。請求の厳密な上限として扱わず、余裕を持たせて設定します。
セッションは自動ではタイムアウトしないため、運用側でも実行時間と停止条件を決めます。サブエージェントの深さ・並列数・支出上限も設定できますが、並列数が増えるとレート制限に当たることがあります。
結果メッセージのtotal_cost_usdとmodelUsageは、クライアント側の推定値で、請求の正本ではありません。請求額はUsage and Cost APIかConsoleのUsageページで確認します。コスト追跡の解説によれば、プロンプトキャッシュは自動で効き、APIやクラウド経由の既定の保持時間は5分です。ENABLE_PROMPT_CACHING_1Hで1時間に延ばせますが、5分より書き込み単価が高くなるため、呼び出し間隔と再利用率で判断します。
運用体制の検討と当協会の支援
導入後は、Skillsの追加、ガードレールの調整、ツール接続の見直しを担当する人と、業務上の判断を担う人を決めます。内製と外部支援を比較する際も、継続的な評価・更新を誰が担うかを確認します。
AI駆動開発協会(AIDDA)は、法人のAI導入を研修、伴走支援、環境の構築、FDE(Forward Deployed Engineer)による継続的な最適化・保守の4段階で支援しています。FDE支援では、モデルそのものではなく、ルールファイル・プロンプト・ツール接続といったハーネスを継続的に調整します。AIエージェントの調整・最適化、障害時の保守対応、運用の伴走や質問対応が主な業務で、主な形態は客先常駐です。社内エージェント基盤の構築や導入後の最適化について相談したい場合は、お問い合わせフォームから連絡できます。支援の考え方はFDEサービスの解説も参考になります。
内製で育てる場合は、Skillsを書き、レビューし、評価できる人が社内に必要です。そうした人材の育成にはAI駆動開発研修があります。
よくある質問
Claude Agent SDKは無料で使えますか?
SDK自体は無償ですが、自社基盤の運用費は別です。APIキーやクラウド経由ではモデル利用料が発生し、実行基盤・保存・監視の費用も必要です。本人がClaudeプランでサインインして使う場合の扱いは、本文の料金節にある公式ヘルプを確認してください。
Claude Agent SDKとClaude Codeは何が違いますか?
Claude Codeは開発者が端末で使う完成品で、SDKはそのエージェントの仕組みを自社のプログラムに組み込むライブラリです。社内の業務エージェントのように、自社の環境で動かして独自の制御を足す場合はSDKを使います。
みずほCoworkはAnthropicのClaude Coworkを導入したものですか?
違います。みずほCoworkは、みずほFGがClaude Agent SDKを活用してAWS上に開発した独自の基盤です。名称が似ていますが、Anthropicの製品であるClaude Coworkの導入ではありません。
みずほCoworkは約3万人が使っているのですか?
約3万人が利用中という実績は、確認した公式発表では裏付けられません。2026年10月5日の発表はPoCの開始を示しており、利用人数や全社展開の完了は記載されていません。計画と実際の利用状況は分けて確認する必要があります。
Skillsはどこで管理すればよいですか?
SDKでは.claude/skills/配下のフォルダとして置くので、Gitで版を管理し、変更はレビューを通す運用が現実的です。承認者、配布する版、更新後の評価基準は、自社の業務に合わせて決めます。
まとめ
社内エージェント基盤では、SDKによる実装と、継続運用の設計を一緒に進めます。最初の一歩は、ひとつの業務を選び、必要なツールとアクセス可能なデータを限定して、読み取り中心の作業を任せてみることです。そこで見えた失敗を、Skillsの追記とHooksによる記録に反映します。
次に決めるのは、権限の境界、監査ログの保存先、Skillsの承認者、予算の上限の四つです。PoCでは、業務上の合格基準とともにこれらを検証し、全社展開の可否を判断します。みずほの事例が示すのは、その土台を「汎用の層」と「社内独自の層」に分けておけば、モデルが変わっても業務ノウハウは残せる、という設計の方向です。


