パーミッションポリシー

パーミッションポリシーは、サーバー実行ツール（事前構築済みのエージェントツールセットおよびMCPツールセット）が自動的に実行されるか、承認を待つかを制御します。カスタムツールはアプリケーションによって実行され、ユーザーが制御するため、パーミッションポリシーの対象外です。

すべてのManaged Agents APIリクエストには、managed-agents-2026-04-01ベータヘッダーが必要です。SDKはベータヘッダーを自動的に設定します。

パーミッションポリシーの種類

ポリシー	動作
`always_allow`	確認なしでツールが自動的に実行されます。
`always_ask`	セッションが`session.status_idle`イベントを発行し、実行前に`user.tool_confirmation`イベントを待ちます。

ツールセットのポリシーを設定する

エージェントツールセットのパーミッション

エージェントを作成する際、default_config.permission_policyを使用してagent_toolset_20260401内のすべてのツールにポリシーをオプションで適用できます。

agent=$(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-sonnet-4-6",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "default_config": {
          "permission_policy": {"type": "always_ask"}
        }
      }
    ]
  }')

default_configはオプションの設定です。省略した場合、エージェントツールセットはデフォルトのパーミッションポリシーalways_allowで有効になります。

MCPツールセットのパーミッション

MCPツールセットはデフォルトでalways_askになっています。これにより、MCPサーバーに追加された新しいツールが承認なしにアプリケーションで実行されないようにします。信頼できるMCPサーバーのツールを自動承認するには、mcp_toolsetエントリにpermission_policyを設定します。

mcp_server_nameはmcp_servers配列で参照されるnameと一致する必要があります。

この例では、GitHub MCPサーバーを接続し、そのツールを確認なしで実行できるようにします。

個別ツールのポリシーをオーバーライドする

configs配列を使用して、個別ツールのデフォルトをオーバーライドします。この例では、エージェントツールセット全体をデフォルトで許可しますが、bashコマンドを実行する前に確認を要求します。

確認リクエストへの応答

エージェントがalways_askポリシーのツールを呼び出した場合：

セッションがagent.tool_useまたはagent.mcp_tool_useイベントを発行します。
セッションがstop_reason: requires_actionを含むsession.status_idleイベントで一時停止します。ブロッキングイベントIDはstop_reason.requires_action.event_ids配列に含まれます。
それぞれに対してuser.tool_confirmationイベントを送信し、tool_use_idパラメータにイベントIDを渡します。resultを"allow"または"deny"に設定します。拒否の説明にはdeny_messageを使用します。
すべてのブロッキングイベントが解決されると、セッションはrunning状態に戻ります。

イベント処理の詳細については、セッションイベントストリームガイドを参照してください。

カスタムツール

パーミッションポリシーはカスタムツールには適用されません。エージェントがカスタムツールを呼び出すと、アプリケーションはagent.custom_tool_useイベントを受信し、user.custom_tool_resultを返す前に実行するかどうかを決定する責任があります。完全なフローについては、セッションイベントストリームを参照してください。

agent=$(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": "Dev Assistant",
    "model": "claude-sonnet-4-6",
    "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"}
        }
      }
    ]
  }')

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

# ツールの実行を許可する
curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -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 '{
    "events": [
      {
        "type": "user.tool_confirmation",
        "tool_use_id": "'$AGENT_TOOL_USE_EVENT_ID'",
        "result": "allow"
      }
    ]
  }'

# または説明付きで拒否する
curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -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 '{
    "events": [
      {
        "type": "user.tool_confirmation",
        "tool_use_id": "'$MCP_TOOL_USE_EVENT_ID'",
        "result": "deny",
        "deny_message": "Don'\''t create issues in the production project. Use the staging project."
      }
    ]
  }'