權限政策 - Claude API Docs

權限政策

權限政策控制由伺服器執行的工具（預建代理工具集和 MCP 工具集）是自動執行還是等待您的批准。自訂工具由您的應用程式執行並由您控制，因此不受權限政策管制。

所有 Managed Agents API 請求都需要 managed-agents-2026-04-01 beta 標頭。SDK 會自動設定 beta 標頭。

權限政策類型

政策	行為
`always_allow`	工具自動執行，無需確認。
`always_ask`	工作階段發出 `session.status_idle` 事件，並在執行前等待 `user.tool_confirmation` 事件。

為工具集設定政策

代理工具集權限

建立代理時，您可以選擇使用 default_config.permission_policy 將政策套用到 agent_toolset_20260401 中的每個工具：

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-4-7
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_ask
YAML

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 前決定是否執行它。請參閱工作階段事件流了解完整流程。

ant beta:agents create <<'YAML'
name: Dev Assistant
model: claude-opus-4-7
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
YAML

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

# 允許工具執行
client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.tool_confirmation",
            "tool_use_id": agent_tool_use_event.id,
            "result": "allow",
        },
    ],
)

# 或以說明拒絕
client.beta.sessions.events.send(
    session.id,
    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.",
        },
    ],
)