AIコーディングエージェント 2026.06.10

Claude Agent SDKを業務アプリに組み込む前に：permissions・MCP・hooks・subagentsの設計ポイント

3行まとめ

VisualClaude Agent SDK導入前に見る3つの境界SDKを社内アプリへ入れる前に、機能ではなく実行権限の境界から整理します。

実行基盤として見る

Claude Codeで使われるagent loop、ファイル操作、コマンド実行、権限管理をアプリ側へ持ち込むSDKとして扱う。

権限境界を先に決める

permissions、MCP tools、hooks、subagents、認証、コスト、監査ログを最初の設計対象にする。

利用枠と課金を分ける

ClaudeプランのAgent SDK creditとAPIキー課金を混同せず、導入前に費用の見え方を分ける。

モデル選定より先に、agentが何を読めて、何を実行できて、何を記録するかを決めます。

Claude Agent SDKは、Claude Codeで使われているagent loop、ファイル操作、コマンド実行、権限管理の考え方を、PythonまたはTypeScriptのアプリへ持ち込むためのSDKです。
業務アプリに組み込むなら、最初に決めるべきなのはモデル選びではなく、permissions、MCP tools、hooks、subagents、認証、コスト、監査ログの境界です。
2026年6月10日に公式DocsとHelp Centerを確認した範囲では、2026年6月15日からClaudeプランのAgent SDK利用枠が別creditとして扱われる予定なので、導入前に利用枠とAPIキー課金を分けて見てください。

X上ではClaude CodeやCodexを並行して使う話、Agent SDKのsubagents、MCP、hooksを業務に近づける話題が目立っていました。ただし、SNS投稿は読者需要を見るためだけに使います。仕様、料金、認証、権限の説明はAnthropicとClaudeの公式ドキュメント、公式GitHubリポジトリ、Claude Help Centerで確認した内容に限定します。

この記事でわかること

Visual導入設計で分けて見る6領域Claude Agent SDKを業務アプリに入れる時の論点を、権限、接続、監査、責任、費用、観測に分けます。

permissions

`permissionMode`、`allowedTools`、`disallowed_tools`、`canUseTool`、hooksの役割を分ける。

MCP tools

社内API、GitHub、DB、ストレージへ触る権限をMCP server単位で棚卸しする。

hooks

`PreToolUse`、`PostToolUse`、失敗時hookを、承認フローと監査ログにつなげる。

subagents

並列化だけでなく、役割、権限、コスト、レビュー責任の単位として設計する。

認証とコスト

APIキー、OAuth token、ClaudeプランのAgent SDK credit、コスト推定を切り分ける。

telemetry

OpenTelemetryを使い、tool実行、拒否、承認待ち、cost、errorを追える形にする。

SDKの技術検証を、本番運用の境界設計へつなげるための読み方です。

Claude Agent SDKを、Claude Codeの便利機能ではなく「権限を持つ実行基盤」として見る理由
permissionMode、allowedTools、disallowed_tools、canUseTool、hooksをどう分けて設計するか
MCP serverを社内APIやGitHub、DB、ストレージに触る権限台帳として扱う方法
PreToolUse、PostToolUse、失敗時hookを、承認フローと監査ログにつなげる考え方
subagentsを並列化の道具ではなく、役割、権限、コスト、レビュー責任の単位として設計する方法
APIキー、OAuth token、ClaudeプランのAgent SDK credit、コスト推定、OpenTelemetryを導入前に切り分けるポイント

すでにAIコーディングエージェント全体の選び方を整理したい場合は、先にAIコーディングエージェントを比べる前にを読んでおくと、この記事の位置づけがつかみやすくなります。この記事は、その中でもClaude Agent SDKを社内アプリや自動化に埋め込む直前の設計判断に絞ります。

前提知識

VisualチャットAPIではなくagent loopとして見るClaude Agent SDKは、回答生成だけでなく、ツール実行を含むagentの行動をアプリから扱うための入口です。

1アプリから呼び出す
PythonまたはTypeScriptのアプリから、Claude Codeを支える仕組みに接続する。
2contextを持つ
会話だけでなく、作業対象、ツール、実行履歴を含めてagentが判断する。
3toolを実行する
ファイル読み取り、編集、コマンド実行、MCP server接続などの行動が起きる。
4権限を評価する
tool requestごとに、許可、拒否、確認、実行後ログの設計が必要になる。
5運用責任を持つ
動くサンプルから本番アプリへ進むほど、監査、認証、コスト、レビュー責任が重くなる。

入り口のコードは軽くても、agentに与える行動権限は軽く扱わない方が安全です。

Claude Agent SDKは、Claude Codeの実行基盤をアプリ側から使うもの

Anthropicの公式説明では、Claude Agent SDKはClaude Codeを支えるツール、agent loop、context managementをPythonとTypeScriptから使えるようにするものとして位置づけられています。つまり、通常のチャットAPIに関数を数個つないだだけのものではありません。

SDKを使うagentは、ファイルを読む、ファイルを編集する、コマンドを実行する、MCP serverへ接続する、権限確認を挟む、といった行動をアプリの中で実行できます。これは便利ですが、業務アプリに入れた瞬間に「ユーザーの代わりに操作できる実行主体」が増えるという意味でもあります。

TypeScriptとPythonの入り口は軽いが、運用の責任は軽くない

公式Docsでは、TypeScriptは@anthropic-ai/claude-agent-sdk、Pythonはclaude-agent-sdkとして導入できます。Python版はPython 3.10以上が必要です。TypeScript版はプラットフォーム向けのClaude Code native binaryをoptional dependencyとして同梱する説明があり、別途Claude Codeを入れなくても使える構成になっています。

最小コードは短く済みます。それでも業務アプリでは、すぐに次の問いが出ます。

誰の権限で実行するのか
どのファイル、リポジトリ、社内API、DBまで触らせるのか
どの操作を自動承認し、どの操作を人間に戻すのか
失敗時に誰が止め、どのログで追跡するのか
サブスクリプション枠、APIキー課金、クラウドプロバイダ課金をどう分けるのか

ここを決めないままSDKだけ入れると、実装は速くても運用レビューで止まります。

結果：最初はread-first、deny-first、log-firstで始める

Visual初期pilotの3原則最初から広い自律実行を許すのではなく、読み取り、拒否、記録を標準にします。

read-first

GitHub issue、仕様書、テストログ、PR差分、社内ドキュメントの読み取りと要約に閉じる。

deny-first

削除、外部送信、本番更新、広いBash実行などは先に拒否ルールへ入れる。

log-first

agentが何を読み、何を試し、どこで止まったかを先に追える状態にする。

書き込みや外部API更新は、観察できる読み取りpilotの後で段階的に広げます。

業務導入の結論はシンプルです。Claude Agent SDKを最初から「自律実行できる社内アプリ」として広く開けるのではなく、読み取り中心、禁止ルール優先、ログ優先で始めます。

read-first

評価基準

最初のpilotでは、GitHub issue、仕様書、テストログ、PR差分、社内ドキュメントの読み取りと要約に閉じるのが扱いやすいです。ファイル編集や外部API更新をさせる前に、agentがどの情報を読み、どのように判断し、どこで誤るかを観察します。

deny-first

注意点

自動承認したい操作から考えるより、絶対にさせない操作と、人間に聞く操作から決めます。削除、外部送信、課金、公開、秘密情報の読み取り、production DB更新は、初期導入で自動承認しない方が安全です。

log-first

確認項目

ログは後付けにしないでください。誰のセッションで、どのagentが、どのtoolを、どの対象に実行し、どの承認を経て、何が変わったのか。これが残らないと、事故が起きた時に「AIがやった」で止まってしまいます。

permissionsはmode名ではなく評価順で設計する

Visualtool requestの権限評価フロー`permissionMode`の名前だけで安全性を判断せず、どの順番で止まり、確認され、許可されるかを見ます。

1tool request
agentがファイル操作、コマンド、MCP toolなどの実行を要求する。
2hooks
`PreToolUse`などで、実行前の検査、承認画面への戻し、監査情報の付与を行う。
3deny rules
危険操作、対象外パス、本番更新、秘密情報へのアクセスなどを先に拒否する。
4ask rules
人間の確認が必要な操作を、実行前の承認対象として分ける。
5allow rules
定型の読み取りや限定されたtoolだけを、自動承認の対象にする。
6runtime approval
残った操作は実行時の承認やpermission modeの扱いに委ねられる。

hookで許可してもdenyやaskの評価が残るため、mode名より評価順を設計します。

Claude Agent SDKのpermissionsは、permissionModeをひとつ選べば終わりではありません。公式Docsでは、tool requestに対してhooks、deny rules、ask rules、allow rules、permission mode、runtime approvalが関わる流れが説明されています。特に重要なのは、hookで許可してもdenyやaskの評価が残る点です。

`allowedTools`は制限ではなく自動承認と見る

根拠

allowedToolsまたはallowed_toolsという名前を見ると、「ここに書いたtoolだけ使える」と誤解しがちです。しかし公式Docsでは、allowed_tools=["Read", "Grep"]のように指定した場合、指定したtoolは自動承認されますが、指定していないtoolもpermission modeやcanUseToolの判定へ進むと説明されています。

locked-downにする条件

locked-downなagentにしたいなら、allowedToolsだけでは足りません。たとえばTypeScriptでは、許可したtool以外をその場で拒否する方針としてpermissionMode: "dontAsk"と組み合わせる設計が紹介されています。

const options = {
  allowedTools: ["Read", "Glob", "Grep"],
  permissionMode: "dontAsk",
};

この設定は、読み取り中心の初期pilotに向きます。ファイル編集やMCP toolを後から足す場合も、まず「許可しないものが本当に拒否されるか」を小さなサンプルで確認してください。

denyとaskを先に決める

確認項目

disallowed_tools=["Bash"]のようにbare nameでdenyすると、そのtool自体がClaudeに見えなくなります。一方、disallowed_tools=["Bash(rm *)"]のようなscoped ruleでは、特定のBash呼び出しをdenyできます。公式Docsでは、このdenyはbypassPermissionsでもブロックされると説明されています。

初期設計では、次のように分けるとレビューしやすくなります。

種類	例	初期方針
deny	削除、秘密情報読み取り、production DB更新	自動実行させない
ask	ファイル編集、PRコメント投稿、チケット更新	人間承認へ戻す
allow	Read、Grep、Glob、限定MCP read tool	pilot中だけ自動承認
runtime approval	差分や対象を見て判断する操作	UIやSlack承認に接続

許可リストから始めるより、denyとaskから始める方が事故を減らしやすくなります。

`bypassPermissions`を初期標準にしない

bypassPermissionsは検証中には楽に見えます。しかし業務アプリの標準設定にすると、権限境界の説明が難しくなります。特にsubagentsを使う場合、親agentのpermission modeをsubagentが引き継ぐ挙動が公式Docsに記載されています。親が広いmodeで動いていれば、役割の異なるsubagentにも広い権限が渡りえます。

導入初期は、少なくとも次の条件がそろうまで広い自動承認を避けてください。

deny ruleが明文化されている
ask ruleが人間承認フローにつながっている
toolごとの実行ログが残る
MCP serverごとにownerとscopeがある
subagentごとの役割と出力形式が決まっている

MCPは社内権限台帳として扱う

VisualMCP server台帳で見る項目MCP serverを便利な接続先ではなく、Claudeに渡す社内権限の台帳として管理します。

項目	内容	見方
server名		どの業務システムやデータ領域へ接続するserverかを明確にする。
transport		stdio、HTTP、remote接続など、運用リスクが変わる接続方式を記録する。
tools		tool名だけでなく、読み取り、作成、更新、削除、送信などの業務動詞で棚卸しする。
scope		リポジトリ、チャンネル、DB、ストレージ、顧客データなどアクセス範囲を限定する。
secret		APIキーやtokenの保管場所、ローテーション、ログ非表示の扱いを決める。
owner		server設定、権限変更、障害対応、レビュー責任を持つ人またはチームを置く。
approval		自動実行、確認必須、常時拒否の境界をtool単位で定義する。
logging		誰のagentが、どのtoolを、どの入力で、どの結果として使ったかを追えるようにする。

MCP serverを増やすほど、agentが触れる業務面も広がります。

MCPは便利な連携規格ですが、業務アプリでは「Claudeにどの社内権限を渡すか」の台帳として扱うべきです。GitHub、Slack、DB、ストレージ、CRM、請求系APIのMCP serverをつなぐと、agentは外部システムに触れる経路を持ちます。

MCP accessは`allowedTools`で絞る

実装条件

Claude Agent SDKのMCP docsでは、MCP accessにはpermission modesよりallowedToolsを使う考え方が示されています。たとえばpermissionMode: "acceptEdits"はファイル編集やfilesystem Bash向けであり、MCP toolsを自動承認する目的の設定ではありません。

MCP toolを許可する場合は、server名を含むtool名で絞ります。

const options = {
  mcpServers: {
    github: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-github"],
      env: {
        GITHUB_TOKEN: process.env.GITHUB_TOKEN,
      },
    },
  },
  allowedTools: ["mcp__github__list_issues"],
};

server全体をwildcardで許可する設計もありますが、その場合はowner、利用目的、secret管理、監査ログ、承認要否を台帳化してください。mcp__github__*は便利ですが、権限台帳なしで許可すると「GitHubの何をしてよいのか」が曖昧になります。

transportごとに運用リスクを分ける

比較基準

公式Docsでは、MCP serverはstdio、HTTP、SSE、SDK application内で動くin-process serverなどの形で接続できます。どれが優れているというより、運用リスクが違います。

transport	向く用途	注意点
stdio	ローカルプロセスとして動かす既存MCP server	subprocess、環境変数、ログ分離を管理する
HTTPまたはSSE	remote MCP server、社内API gateway	認証header、ネットワーク境界、可用性を見る
in-process SDK MCP server	アプリ内の小さな独自tool	デプロイは単純だが、アプリプロセス内の責任が重い

in-processはデプロイしやすく、型やデバッグも扱いやすい一方で、アプリ本体とtool実行の障害境界が近くなります。DB更新や外部送信のような重い操作は、MCP tool側にも冪等性、dry-run、rate limit、監査IDを入れてください。

tool名ではなく業務動詞で棚卸しする

MCP台帳はtool名だけで作ると漏れます。業務上の動詞で整理してください。

業務動詞	例	初期方針
読む	issue取得、ログ取得、ドキュメント検索	まず許可候補
作る	下書き作成、draft PR作成	人間承認つき
更新する	チケット状態変更、DB更新	対象を限定
削除する	ファイル削除、レコード削除	原則deny
送る	Slack投稿、メール送信	previewと承認必須
公開する	本番反映、外部公開	初期pilotでは対象外

prompt injection対策もここで考えます。外部issue、PRコメント、ドキュメント、Slackログなどに悪意ある指示が混ざると、agentがMCP toolを想定外に使う可能性があります。MCP連携の前にAIコーディングエージェントのprompt injectionとMCP guardrailsも確認しておくと、外部入力を読むagentの危険度を説明しやすくなります。

hooksはガードレール、監査、承認フローをつなぐ場所にする

Visualhookイベントの使い分けhooksは危険操作を止めるだけでなく、承認と監査の流れをつくる接点です。

UserPromptSubmit
入力時点で、秘密情報、対象外依頼、危険な指示を検出する。
PreToolUse
tool実行前に、禁止操作、承認必須操作、対象外パスへのアクセスを止める。
PostToolUse
実行後に、tool名、対象、結果、承認者、差分を人間が読める粒度で記録する。
PostToolUseFailure
失敗時に、権限不足、外部APIエラー、リトライ可否、通知先を分けて扱う。
Stop / SubagentStop
agentやsubagentの終了時に、判断、未完了、次の確認事項を残す。

hooksに権限設計を丸投げせず、permissionsと役割を分けて使います。

hooksは「イベントが起きたら何かする」だけの拡張点ではありません。業務アプリでは、危険操作を止める、承認画面へ戻す、監査ログを整える、失敗時に通知するための接点になります。

PreToolUseで止める操作を先に決める

確認項目

PreToolUseはtool実行前に動くため、危険操作を止める場所として使いやすいです。初期導入では、少なくとも次の操作をPreToolUseの対象にします。

shell command
file write
DB write
外部APIへの送信
secretやcredentialに触れる可能性がある読み取り
production相当の環境へ影響する操作

ただし、hookにすべてのポリシーを詰め込むと読みにくくなります。hookはpolicy判定を呼び出し、結果をログに残し、必要なら承認へ回す場所と考えるのがよいです。

PostToolUseで監査ログを人間が読める粒度にする

ログ項目

PostToolUseでは、実行後の結果を監査ログへ落とします。ログに残す項目は、tool名だけでは足りません。

項目	残す理由
userまたはteam	誰の権限で動いたかを見る
session ID	一連の流れを追う
agentまたはsubagent名	どの役割のagentが実行したかを見る
toolとMCP server	どの接続経路を使ったかを見る
対象リソース	issue、file、record、URLなどを追う
承認ID	人間承認との対応を追う
差分または結果要約	変更内容をレビューする
エラーとretry	障害調査に使う

prompt全文、secret、個人情報をそのままログに入れるのは避けます。監査に必要な情報と、残すと危険な情報を分けてください。

hooksとpermissionsを混ぜない

公式Docsでは、hookがallowを返しても、その後のdenyやaskの評価が残ることが説明されています。これは重要です。hookは「許可したから全部通る」場所ではなく、permissions評価の一部です。

チーム内の説明では、次のように責務を分けると伝わりやすくなります。

hooksは、実行前後のpolicy、監査、通知、入力整形を担当する
permissions rulesは、toolごとのdeny、ask、allowを担当する
MCP tool側は、対象APIのscope、冪等性、dry-run、rate limitを担当する
アプリ側workflowは、承認画面、差分表示、承認履歴、取り消しを担当する

Codex側のhooks運用を先にイメージしたい場合は、Codex HooksをPreToolUse・PostToolUse・Stopで分ける記事も近い考え方で読めます。

subagentsは並列化より先に責任境界を設計する

Visualmain agentとsubagentsの責任分担subagentsは速くするためだけでなく、誰が何を判断したかを分けるために使います。

1main agent
依頼全体を受け、必要なsubtaskを分け、最終判断と実行可否をまとめる。
2research subagent
仕様、ドキュメント、既存コード、関連issueを読み、根拠を集める。
3review subagent
変更案のリスク、権限、テスト不足、監査観点を確認する。
4test subagent
テスト実行、失敗ログ、再現条件、修正後の確認範囲を整理する。
5security subagent
secret、外部送信、MCP権限、prompt injection、deny ruleの抜けを確認する。
6handoff artifact
subagentの結論をそのまま実行せず、根拠、制約、未確認点を残して人間が見直す。

並列化は速さだけでなく、コストとレビュー負荷も増やします。

subagentsは、タスクを並列に進めたり、専門の指示を持つagentへ分けたりする時に便利です。しかし、業務導入では「速くなる」より先に「誰が何を判断したことにするか」を決めます。

subagentごとに役割、tools、model、上限を定義する

定義項目

Claude Agent SDKのsubagents docsでは、subagentsはmain agentがfocused subtasksを処理するために起動する別のagent instanceとして説明されています。contextを分け、専門指示を持たせ、複数の分析を並列に走らせる用途に向きます。

定義時に最低限決める項目は次の通りです。

項目	決めること
name	ログや監査で追える名前
description	いつ使うagentなのか
system prompt	役割、禁止事項、出力形式
tools	読み取りのみか、編集も可能か
MCP servers	どの外部システムへ触れるか
model	速度、品質、コストのバランス
timeout	長時間化した時の停止条件
output	根拠、未確認、推奨アクションを分ける

subagentの結論をそのまま実行させないことも大切です。subagentは調査、レビュー、テスト観点、セキュリティ観点を返し、main agentまたは人間が統合判断する流れにしてください。

並列化はコストとレビュー負荷も増やす

subagentsを増やすと、調査漏れが減る一方で、同じコードやログを複数agentが読むことがあります。token消費、tool call、ログ量、レビュー対象が増えるため、単純に「速いから増やす」とは言えません。

初期pilotでは、次の3種類に絞ると扱いやすいです。

research agent: 読み取り専用で根拠を集める
review agent: PR差分を見て懸念点だけ返す
test agent: 失敗ログと再現手順を整理する

実装や外部API更新を任せるsubagentは、権限設計と承認フローが固まってからで十分です。Codexでsubagentsの並列レビューを設計する時の考え方は、Codex subagentsをチームで使う前にも参考になります。

認証、利用枠、コストを導入前に分けておく

Visual認証と費用の切り分け表誰の認証で動き、どの利用枠を消費し、どの請求に反映されるかを分けて確認します。

項目	内容	見方
APIキー		サーバー側の自動化やCIでは、所有者、保管場所、ローテーション、請求先を決める。
OAuth token		ユーザー操作に紐づく接続では、同意範囲、失効、再認証の扱いを明確にする。
Claudeプランのcredit		Agent SDK creditがClaudeプラン側で扱われる場合、APIキー課金と分けて追う。
MCP serverのsecret		GitHub、DB、ストレージ、CRMなどのtokenを記事、ログ、promptへ出さない。
コスト推定		実行前の見積もりは判断材料として扱い、請求データとは別の数字として見る。
請求データ		実績のcost、token、tool calls、subagent数を後から照合できる形にする。

動いたサンプルをそのまま社内アプリ化すると、誰の権限と費用で動くのかが曖昧になります。

Claude Agent SDKの技術検証で見落としやすいのが、認証と費用です。動いたサンプルをそのまま社内アプリ化すると、誰の利用枠を使っているのか、APIキー課金なのか、Claudeプランのcreditなのかが曖昧になります。

認証方式は実行場所ごとに変える

実行場所ごとの条件

公式のauthentication docsでは、Claude Codeが複数の認証方式を扱うことが説明されています。クラウドプロバイダ認証、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEY、apiKeyHelper、CLAUDE_CODE_OAUTH_TOKEN、subscription OAuthなどです。

実務では、実行場所ごとに分けるのが安全です。

実行場所	推奨する考え方
ローカル開発	個人の検証用に限定し、社内データを広く読ませない
CI	long-lived tokenやAPI keyをvaultで管理し、対象repoと操作を絞る
社内Webアプリ	ユーザー単位の承認履歴とtenant境界を持つ
バッチ処理	実行頻度、予算上限、停止条件を先に置く
LLM gateway経由	gateway側の認証、rate limit、監査ログと接続する

第三者向けサービスとしてClaude Agent SDKを使う場合は、公式Docsの認証方針も確認してください。未承認の第三者開発者がclaude.aiログインやrate limitを自社製品に提供することは認められない旨の注意が示されています。社内向けと外部顧客向けでは、認証設計の重さが変わります。

2026年6月15日のAgent SDK credit変更を確認する

再確認ポイント

Claude Help Centerでは、2026年6月15日から、Claude Agent SDKとclaude -pの利用が通常のClaudeプラン利用枠とは別の月次Agent SDK creditで扱われる予定だと説明されています。2026年6月10日時点の記載では、Pro、Max、Team、Enterpriseの対象ユーザーがclaimできる別creditとして案内されています。

Help Centerの表では、たとえばProは月20ドル、Max 5xは月100ドル、Max 20xは月200ドル、Team Standard seatsは月20ドル、Team Premium seatsは月100ドルのcreditが示されています。一方で、Claude PlatformのAPI key利用はこのcredit対象ではなく、pay-as-you-go billingは従来どおりと説明されています。

この記事の公開時点では開始前の情報なので、導入判断では必ず最新のHelp Centerと自社アカウントの請求画面を確認してください。個人のClaudeプランで動いている検証と、会社のAPIキーで動く本番アプリは、同じ費用構造ではありません。

コスト推定と請求データを分ける

Agent SDKのcost tracking docsでは、query()ごとのtotal_cost_usdやmodel usageのcostを取得する例が示されています。ただし、SDKの値は開発時の目安として扱い、請求や顧客課金の唯一の根拠にしないでください。

実務では、次の3層に分けるとよいです。

層	使う値	用途
実行中の制御	`total_cost_usd`、token usage	予算超過の早期停止、ログ
管理画面	session、user、team別集計	社内利用量の把握
請求	Claude Console、Bedrock、Vertex AIなど公式billing	精算、顧客請求、会計

SDKが返すコスト値だけで顧客請求や部署間精算を決めるのは避けます。

telemetryは最初から設計する

Visual最初に追うtelemetry項目後からログを足すのではなく、pilotの時点で判断と実行の足跡を残します。

session

どの依頼から始まり、どのagentやsubagentが関わったかを追う。

user

誰の依頼、誰の承認、誰の認証でtoolが実行されたかを分ける。

tool

tool名、対象、入力の種類、結果、拒否理由、承認待ち時間を記録する。

cost

token、cost、subagent数、外部API呼び出しを継続的に見られるようにする。

error

権限不足、API失敗、実行失敗、timeout、rollback要否を分けて残す。

approval

自動承認、人間承認、拒否、保留を監査で追える粒度にする。

alertはコスト超過だけでなく、権限逸脱や想定外tool利用にも置きます。

Agent SDKを社内アプリに入れる場合、後からログを足すのはつらいです。最小構成でも、session、user、agent、tool、cost、error、approvalを追える形にしておきます。

OpenTelemetryで見る軸を決める

監視項目

Claude Codeのmonitoring docsでは、OpenTelemetryを通じてmetrics、events、tracesを出力できることが説明されています。token usage、cost usage、tool activity、agent name、skill name、plugin nameなどの属性を使えば、チームやagent種別ごとの傾向を見やすくなります。

ただし、Agent SDKアプリ側で必要なメタデータは自社側でも付与する前提で設計してください。

user IDまたはteam ID
tenant ID
session ID
agent名またはsubagent名
MCP server名
approval result
policy decision
error category
redaction済みの対象リソース

prompt全文や秘密情報をログに入れないことも、最初の設計に含めます。

alertはコスト超過だけでなく権限逸脱にも置く

監視は「月末の請求が高い」だけを見るものではありません。権限逸脱の兆候もalert対象にします。

alert	見たいこと
cost spike	急な高額利用や無限ループ
token spike	大きすぎる入力、不要な再読み込み
denied call増加	agentが禁止操作を試している
approval拒否増加	指示やtool設計が危険側に寄っている
same tool連続失敗	外部API障害、認証切れ、仕様変更
subagent count増加	並列化が過剰になっている

Datadog、Grafana、Cloud Loggingなど監視先は何でも構いません。重要なのは、agentが何をしたかだけでなく、何をしようとして止められたかを見ることです。

失敗点：導入時に起きやすい事故

Visual初期導入で避けたい5つの思い込み便利に動くことと、安全に運用できることを分けて確認します。

mode名だけで安全だと思う

`acceptEdits`などの名前だけで判断せず、MCP tools、Bash、外部API、denyとaskの評価を見る。

MCP serverを増やしすぎる

serverを増やすほどagentが触れる業務面が増えるため、読み取り、更新、削除、送信を分ける。

hooksへ詰め込みすぎる

hooksはガードレールと監査の接点にし、複雑な業務判断は別の設計に分ける。

subagentの結論をそのまま実行する

subagentの出力は根拠と未確認点を含むhandoff artifactとして扱う。

コスト推定を請求根拠にする

推定値は実行前判断に使い、請求や配賦は実績データで確認する。

事故は単一の設定ミスだけでなく、権限、接続、承認、ログの境界が曖昧な時に起きます。

permission modeの名前だけで安全だと思う

acceptEditsという名前だけを見て「編集だけ許可しているから安全」と考えるのは危険です。MCP toolsの扱い、Bash、外部API、subagentsの継承、denyとaskの評価を別に見てください。

MCP serverを便利ツールとして増やしすぎる

MCP serverを増やすほど、agentが触れる業務面が増えます。GitHub、DB、Slack、CRM、請求系APIを同じagentに渡すなら、それは社内権限を束ねた強い実行主体です。serverごとのownerとscopeがない状態で増やすのは避けます。

hooksに業務ロジックを詰め込みすぎる

hookは便利ですが、全てのpolicy、承認、ログ整形、通知を1つの巨大なhookに入れると、テストしにくくなります。policy判定、監査イベント生成、通知、承認画面を分けて、hookはそれらをつなぐ薄い層にします。

subagentの結論をそのまま実行する

subagentは専門家のように見えますが、出力はあくまで判断材料です。根拠、未確認、推奨アクションを分けて返させ、main agentまたは人間が統合します。

コスト推定を請求根拠にする

SDKやtelemetryから取れるコストは便利ですが、公式billingとずれる可能性があります。顧客請求や社内精算には公式billingを使い、SDK側の値は停止条件や傾向把握に使います。

実務で使うなら：4段階で広げる

VisualClaude Agent SDK導入ロードマップ読み取り中心のpilotから始め、巻き戻しやすい書き込み、運用ルール、subagentsへ段階的に広げます。

Phase 1 読み取りと提案
issue、PR差分、仕様書、ログ、社内ドキュメントの読み取りと要約に限定する。
Phase 2 巻き戻しやすい書き込み
下書き、ブランチ、PR、テスト用データなど、取り消しやすい対象から書き込みを始める。
Phase 3 hooksとMCP台帳
承認、拒否、監査ログ、MCP serverの権限台帳をチーム運用のルールにする。
Phase 4 subagents拡張
research、review、test、securityなどのsubagentsを、責任境界とコスト上限つきで広げる。

段階を飛ばすほど、誤実行、レビュー漏れ、コスト増加の原因が見えにくくなります。

Phase 1は読み取りと提案に限定する

最初は、issue、PR差分、仕様書、ログ、社内ドキュメントの読み取りと要約に閉じます。許可するtoolはRead、Grep、Glob、限定されたread-only MCP tool程度にします。

この段階で見るべきなのは、agentが正しく提案できるかだけではありません。誤提案時に業務状態が壊れないか、ログで追えるか、承認画面に必要な情報が何かも見ます。

Phase 2は巻き戻しやすい書き込みに進む

次に、draft作成、PRコメント、検証レポート、チケット更新など、巻き戻しやすい書き込みへ進みます。ここでは必ずpreviewと人間承認を挟みます。

production DB更新、外部メール送信、請求操作、公開操作はまだ自動承認しません。

Phase 3でhooksとMCP台帳を運用ルールにする

PreToolUseで危険操作を止め、PostToolUseで監査ログを整え、MCP server台帳にowner、scope、secret、logging、approvalを入れます。ここまで来ると、社内レビューで「何を許したのか」を説明しやすくなります。

AGENTS.mdやリポジトリ内ルールも合わせて整えるなら、チーム向けAGENTS.mdテンプレートのような共通ルールを先に作っておくと、agentごとの差が減ります。

Phase 4でsubagentsを広げる

最後に、research、review、test、securityなどのsubagentsを増やします。並列実行は、承認と監査がそろってからです。増やすたびに、token消費、ログ量、レビュー負荷も測ります。

CodexとClaude Codeを並行して使うチームでは、CodexとClaude Codeのdual-agent workflowのように、どちらに何を任せるかを別記事の観点で整理しておくと、SDK導入後の責任境界も曖昧になりにくくなります。

セキュリティ・コスト注意

Visual導入前に固定する注意点権限を持つagentとして扱うために、秘密情報、tool制限、コスト、ログの前提を先に置きます。

secretを出さない

APIキー、OAuth token、GitHub token、MCP serverのsecretは記事、ログ、promptへ出さない。

`allowedTools`だけに頼らない

tool利用全体の制限は、permission mode、deny rule、ask rule、hooksと合わせて見る。

locked-downを明示する

厳しく閉じたいagentでは、許可tool、拒否条件、確認条件、実行場所を具体的に決める。

課金を混同しない

Claudeプランのcredit、APIキー課金、外部APIの費用を別々に追う。

監査ログを残す

誰が依頼し、何を承認し、どのtoolが何をしたかを後から確認できる形にする。

セキュリティとコストは単純な勝敗ではなく、実行場所、権限範囲、承認者によって設計が変わります。

APIキー、OAuth token、GitHub token、MCP serverのsecretは記事やログに出さない。サンプルでは必ずダミー値を使う。
allowedToolsだけでtool利用全体を制限できると思わない。locked-downにするならpermission modeやdeny ruleも合わせて設計する。
bypassPermissionsを初期標準にしない。特にsubagentsを使う場合は、親の広いmodeが子にも影響しうる。
MCP wildcardを使うなら、server owner、scope、secret管理、承認要否、監査ログを台帳化する。
external issue、PRコメント、社内ドキュメントなど外部入力を読むagentでは、prompt injectionを前提にguardrailsを置く。
SDKのtotal_cost_usdやOpenTelemetryのcost metricsは目安として使い、正式な請求や顧客課金は公式billingで確認する。
2026年6月15日開始予定のAgent SDK creditは、公開後に変更される可能性がある。導入時はHelp Centerと自社アカウントの表示を確認する。

社内アプリにClaude Agent SDKを入れる前の権限台帳、MCP server棚卸し、hooks設計、telemetry設計を一緒にレビューしたい場合は、AI Dev Lab Japanのお問い合わせから相談できます。まずは読み取り限定のpilotを作り、何を許すかよりも、何を止めるかを先に決めるのが現実的です。

更新通知やAIコーディング導入チェックリストを追いたい方は、ニュースレターも使ってください。仕様変更が速い領域なので、記事末尾の更新履歴も合わせて確認する前提で運用するのが安全です。

次に読むなら

Codex HooksをPreToolUse・PostToolUse・Stopで分ける

hooksを危険操作のブロック、実行後ログ、停止時処理に分ける考え方を、Codex側の運用例として確認できます。

CodexのSkills・Plugins・subagents・MCPをチーム運用に落とす

MCPやsubagentsを個人の便利機能で終わらせず、チームの権限、設定、レビュー運用に落とす視点を補えます。

Codex config.tomlでpermissions・rules・MCPを管理する

権限ルール、AGENTS.md、MCP設定を設定ファイルとして管理する発想を、Claude Agent SDK側の設計にも応用できます。

AIコーディングエージェントのprompt injectionとMCP guardrails

外部入力を読むagentがMCP toolを呼ぶ時のリスクを、導入前にチームへ説明しやすくなります。

参照した主な情報源

https://code.claude.com/docs/en/agent-sdk/overview
https://code.claude.com/docs/en/agent-sdk/permissions
https://code.claude.com/docs/en/agent-sdk/mcp
https://code.claude.com/docs/en/agent-sdk/hooks
https://code.claude.com/docs/en/agent-sdk/subagents
https://code.claude.com/docs/en/agent-sdk/cost-tracking
https://code.claude.com/docs/en/authentication
https://code.claude.com/docs/en/monitoring-usage
https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan
https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk
https://www.anthropic.com/news/enabling-claude-code-to-work-more-autonomously
https://github.com/anthropics/claude-agent-sdk-typescript
https://github.com/anthropics/claude-agent-sdk-python

更新履歴

Visual確認した情報と再確認ポイント公開時点で参照した公式情報と、日付が関係する注意点を分けて残します。

2026年6月10日
Claude Agent SDK overview、permissions、MCP、hooks、subagents、cost tracking、authentication、monitoring usageを確認。
公式情報源
Claude Help Center、Anthropic公式ブログ、Claude Agent SDKのTypeScript版とPython版の公式GitHubリポジトリを確認。
2026年6月15日予定
Agent SDK creditの扱いは、公開時点で再確認が必要な情報として扱う。

日付に関わる料金や利用枠の情報は、公開直前に公式情報で再確認します。

2026年6月10日: 初版作成。Claude Agent SDK overview、permissions、MCP、hooks、subagents、cost tracking、authentication、monitoring usage、Claude Help CenterのAgent SDK credit記事、Anthropic公式ブログ、公式GitHubリポジトリを確認。2026年6月15日開始予定のAgent SDK creditは、公開時点で再確認が必要な情報として扱った。

3行まとめ

この記事でわかること

前提知識

Claude Agent SDKは、Claude Codeの実行基盤をアプリ側から使うもの

TypeScriptとPythonの入り口は軽いが、運用の責任は軽くない

結果：最初はread-first、deny-first、log-firstで始める

read-first

評価基準

deny-first

注意点

log-first

確認項目

permissionsはmode名ではなく評価順で設計する

allowedToolsは制限ではなく自動承認と見る

根拠

locked-downにする条件

denyとaskを先に決める

確認項目

bypassPermissionsを初期標準にしない

MCPは社内権限台帳として扱う

MCP accessはallowedToolsで絞る

実装条件

transportごとに運用リスクを分ける

比較基準

tool名ではなく業務動詞で棚卸しする

hooksはガードレール、監査、承認フローをつなぐ場所にする

PreToolUseで止める操作を先に決める

確認項目

PostToolUseで監査ログを人間が読める粒度にする

ログ項目

hooksとpermissionsを混ぜない

subagentsは並列化より先に責任境界を設計する

subagentごとに役割、tools、model、上限を定義する

定義項目

並列化はコストとレビュー負荷も増やす

認証、利用枠、コストを導入前に分けておく

認証方式は実行場所ごとに変える

実行場所ごとの条件

2026年6月15日のAgent SDK credit変更を確認する

再確認ポイント

コスト推定と請求データを分ける

telemetryは最初から設計する

OpenTelemetryで見る軸を決める

監視項目

alertはコスト超過だけでなく権限逸脱にも置く

失敗点：導入時に起きやすい事故

permission modeの名前だけで安全だと思う

MCP serverを便利ツールとして増やしすぎる

hooksに業務ロジックを詰め込みすぎる

subagentの結論をそのまま実行する

コスト推定を請求根拠にする

実務で使うなら：4段階で広げる

Phase 1は読み取りと提案に限定する

Phase 2は巻き戻しやすい書き込みに進む

Phase 3でhooksとMCP台帳を運用ルールにする

Phase 4でsubagentsを広げる

セキュリティ・コスト注意

次に読むなら

参照した主な情報源

更新履歴

`allowedTools`は制限ではなく自動承認と見る

`bypassPermissions`を初期標準にしない

MCP accessは`allowedTools`で絞る