Managed Agentsの権限ポリシー設計 — ツールセット単位の制御

Managed Agentsの権限ポリシーは、サーバー実行型のツール(エージェントツールセットとMCPツールセット)が確認なしで動くか、承認待ちで止まるかを制御します。デフォルトはエージェントツールセットがalways_allow、MCPツールセットがalways_askと対極に設定されており、この非対称を理解したうえでconfigs配列による個別オーバーライドを組み合わせるのが設計の基本です。

always_allowとalways_askの2種類しかない

権限ポリシーはalways_allow(確認なしで即実行)とalways_ask(承認が下りるまでセッションが一時停止)の2種類だけです。中間の選択肢はありません。ツールセットの種類ごとに既定値が違い、エージェントツールセット(agent_toolset_20260401)はalways_allow、MCPツールセットはalways_askが既定です。

この非対称には理由があります。エージェントツールセットの中身(bash・read・write・edit・glob・grep・web_fetch・web_search)は事前に定義された固定の顔ぶれで、エージェント作成の時点で何が実行され得るかをあらかじめすべて把握できます。一方MCPサーバーが公開するツールは運用中に増減し得るため、信頼していないサーバーの新しいツールがいきなり無確認で動く事故を防ぐ目的で、既定が承認待ちに寄せてあります。

権限ポリシーはあくまで「実行のタイミングをどう扱うか」を制御するものであり、ツールをエージェントから完全に取り除きたい場合は無効化(enabled: false)を使う点にも注意が必要です。ポリシーをalways_askにしても、ツール自体は有効なままモデルに見え続けます。

ツールセット単位でデフォルトを設定する

権限ポリシーはエージェント作成時のtools設定で指定し、あとからエージェントを更新して変更することもできます。稼働中のセッションは作成時点のツールセット構成を保持し続け、更新は以降に作られる新しいセッションにだけ適用されます。

エージェントツールセット全体に一括でポリシーをかける場合はdefault_config.permission_policyを使います。

curl -fsSL https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "Coding Assistant",
    "model": "claude-opus-5",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "default_config": {
          "permission_policy": {"type": "always_ask"}
        }
      }
    ]
  }'

default_configは省略可能で、省略した場合はエージェントツールセットの既定であるalways_allowがそのまま使われます。MCPツールセット側で信頼済みのサーバーを自動承認にしたい場合は、mcp_toolsetエントリのdefault_config.permission_policyをalways_allowに設定します。このときmcp_server_nameはmcp_servers配列に登録したサーバーのnameと一致させる必要があります。GitHubのMCPサーバーを自動承認にする例は次の通りです。

{
  "name": "Dev Assistant",
  "model": "claude-opus-5",
  "mcp_servers": [
    {"type": "url", "name": "github", "url": "https://mcp.example.com/github"}
  ],
  "tools": [
    {"type": "agent_toolset_20260401"},
    {
      "type": "mcp_toolset",
      "mcp_server_name": "github",
      "default_config": {
        "permission_policy": {"type": "always_allow"}
      }
    }
  ]
}

ポリシー変更は稼働中のセッションに効かない

エージェントの権限ポリシーを更新しても、その時点ですでに走っているセッションには反映されません。稼働中のセッションは、作成された瞬間のツールセット構成をそのまま保持し続けます。ポリシー変更が効くのは、更新より後に新しく作られるセッションだけです。

この挙動は設計として理にかなっています。もしポリシー変更が稼働中のセッションにも即座に反映されると、エージェントが一連の操作の途中で急にツールの挙動が変わり、モデルが前提としていた実行モデルと食い違う事態が起こり得ます。セッションの構成を作成時点に固定することで、少なくとも1セッションの中では権限まわりの前提が変わらないという一貫性が保証されます。

裏を返すと、緊急でツールの挙動を止めたい場合には注意が必要です。「危険な使われ方をしているツールを見つけたのでポリシーをalways_askに変更した」というだけでは、その時点ですでに走っているセッションを止める効果はありません。新しいポリシーが実際に効いてくるのは、変更より後に作られるセッションからです。日常的な運用では、まず新規セッションに厳しめのポリシーを適用しつつ、既存セッションが自然に終わるのを待つという段階的な移行になりやすい点を織り込んでおく必要があります。

個別ツールだけポリシーを上書きする

ツールセット全体のデフォルトとは別に、configs配列で特定のツールだけポリシーを上書きできます。エージェントツールセットで指定できるnameの一覧は利用可能なツールにまとまっています。次の例は、エージェントツールセット全体をにしつつ、bashコマンドの実行だけは確認を必須にする設定です。

tools='[
  {
    "type": "agent_toolset_20260401",
    "default_config": {
      "permission_policy": {"type": "always_allow"}
    },
    "configs": [
      {
        "name": "bash",
        "permission_policy": {"type": "always_ask"}
      }
    ]
  }
]'

MCPツールセットも同じconfigsの仕組みで個別ツールを上書きできますが、nameにはMCPサーバー側が報告するツール名を指定します。「全体は自動承認、破壊的な操作だけ確認を挟む」という設計は、bash実行・ファイル書き込み・外部APIへの書き込み系ツールなど、取り消しにくい操作を持つツールセットで特に有効です。逆に読み取り専用のグレップやWeb検索まで一律always_askにすると、承認待ちが頻発してエージェントの自律性が損なわれます。

ツールごとの使い分け早見表

configs配列でどのツールを上書きするかの判断材料として、リスクの性質に応じた組み合わせの目安を挙げます。

読み取り系のツールまで一律always_askにすると、簡単な調査を1つ進めるたびに承認待ちが挟まり、エージェントの自律性が大きく損なわれます。書き込み・実行系だけをalways_askに寄せるほうが、承認のコストと安全性のバランスが取れます。

read/glob/grepをalways_allowに寄せても、write/editのalways_askが最後の防波堤として残ります。誤った変更や意図しない削除は、承認待ちの一段階が挟まることで実行前に人の目を通せます。読み取り系を自動化するほど、この最終防波堤としてのwrite/editの承認待ちが相対的に重要になります。

web_fetchとweb_searchはドメイン制限と組み合わせる

web_searchとweb_fetchには、権限ポリシーとは別の制御軸としてallowed_domains(到達を許可するホストのみに限定)とblocked_domains(到達を禁止するホストを指定)を設定できます。どちらもconfigs配列の該当エントリに指定し、web_searchとweb_fetchで別々のリストを持てます。1つのドメインを指定すると、そのホストとすべてのサブドメインが対象になります。

{
  "type": "agent_toolset_20260401",
  "configs": [
    {
      "type": "web_search",
      "name": "web_search",
      "allowed_domains": ["docs.example.com", "arxiv.org"]
    },
    {
      "type": "web_fetch",
      "name": "web_fetch",
      "blocked_domains": ["ads.example.com"],
      "max_content_tokens": 50000
    }
  ]
}

許可リストに無いURLへweb_fetchが到達しようとすると、agent.tool_resultイベントでis_error: trueとurl_not_allowedエラーコードを含む結果が返ります。web_searchの場合はエラーにはならず、リストが許可しない結果が検索結果から単に除外されます。この2つのツールについては、「実行するかどうかを毎回尋ねる」よりも「そもそも到達できる範囲を絞る」ほうが、承認待ちを増やさずにリスクを抑えられる設計になります。権限ポリシーとドメイン制限は独立した設定項目なので、両方を組み合わせて使えます。

このis_error: trueはagent.tool_resultイベントとしてそのままモデルに渡り、アプリケーション側でセッションを中断させる必要はありません。モデルは結果を見て別のURLを試すか、承認が必要な別の手段に切り替えるかを自分で判断します。

カスタムツールは権限ポリシーの対象外

設計で見落としやすいのが、カスタムツールには権限ポリシーが一切適用されない点です。カスタムツールはアプリケーション側が実行するツールで、Managed Agentsのサーバー実行環境の外にあります。エージェントがカスタムツールを呼び出すとagent.custom_tool_useイベントが届き、実行するかどうかを判断してuser.custom_tool_resultを返すのはアプリケーション自身の責任です。

つまり「このツールは危ないからalways_askにしておこう」という発想が通用するのは、あらかじめ用意されたエージェントツールセットとMCPツールセットだけです。カスタムツールの実行可否は、権限ポリシーの設定ではなくアプリケーションコード側のロジックとして実装する必要があります。カスタムツールの作り方自体はAgent SDKカスタムツールの作り方で扱っています。

よくある質問

default_configを省略するとどうなりますか

省略した場合、そのツールセット固有の既定ポリシーがそのまま適用されます。エージェントツールセットならalways_allow、MCPツールセットならalways_askです。「明示的に何も指定していないから確認なしで動くはず」とは限らず、ツールセットの種類によって既定値が真逆である点に注意が必要です。

MCPツールセットの個別ツール上書きでnameには何を指定しますか

MCPサーバー自身が報告するツール名をそのまま使います。エージェントツールセットのように固定の名前一覧が公式ドキュメントに列挙されているわけではなく、接続先のMCPサーバーがどんなツールを公開しているかに依存します。事前にどんなツールが存在するかを把握しておかないと、configsで狙ったツールを正しく指定できません。

1つのエージェントに複数のMCPサーバーを繋いだ場合、ポリシーはサーバーごとに分けられますか

分けられます。mcp_toolsetのエントリはmcp_server_nameで対象サーバーを指定するため、信頼度の異なる複数のMCPサーバーを同じエージェントに接続しつつ、サーバーごとに別々の権限ポリシーを設定できます。社内で運用している信頼済みのMCPサーバーはalways_allowにしつつ、外部ベンダーが提供するMCPサーバーは既定のalways_askのまま残す、という組み合わせが典型的な使い方です。1つのtools配列に複数のmcp_toolsetエントリを並べ、それぞれ別のmcp_server_nameとdefault_configを持たせるだけで実現できます。

まとめ

権限ポリシーの設計は、エージェントツールセット(既定always_allow)とMCPツールセット(既定always_ask)という非対称な既定値を出発点にします。そのうえでdefault_configでツールセット単位のデフォルトを決め、configs配列で破壊的な個別ツールだけalways_askに寄せる、2段階の組み立てになります。カスタムツールはこの仕組みの外にあり、実行可否の制御はアプリケーション側の責任です。認証情報側の設計はAgent SDKのManaged Agentsの設計思想、SDKからMCPサーバーへ接続する手順はAgent SDK MCP接続ガイドを参照してください。