權限政策

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



權限政策類型

每種工具集類型都有各自的預設值：代理工具集預設為 always_allow，MCP 工具集預設為 always_ask。

權限政策控制已啟用的工具何時執行。若要將某個工具從代理中完全移除，請改為停用它。請參閱停用特定工具。



為工具集設定政策

您在建立代理時，於代理的 tools 設定中設定權限政策，之後可以透過更新代理來變更。執行中的工作階段會保留其建立時的工具集設定。更新會套用至之後建立的工作階段。



代理工具集權限

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

ant beta:agents create < agent.yaml

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 工具集預設為 always_ask。這可確保新增至 MCP 伺服器的新工具不會在未經核准的情況下於您的應用程式中執行。若要自動核准來自受信任 MCP 伺服器的工具，請在 mcp_toolset 項目上設定 default_config.permission_policy。

mcp_server_name 必須與 mcp_servers 陣列中某個伺服器的 name 相符。

此範例連接一個 GitHub MCP 伺服器，並允許其工具在無需確認的情況下執行：

ant beta:agents create < agent.yaml

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



覆寫個別工具的政策

使用 configs 陣列來覆寫個別工具的預設值。代理工具集的 name 值列於可用工具中。此範例預設允許完整的代理工具集，但在執行任何 bash 指令前需要確認：

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_allow
    configs:
      - name: bash
        permission_policy:
          type: always_ask
YAML

請在代理建立請求中傳入此 tools 設定（CLI 分頁顯示完整指令）。MCP 工具集支援相同的個別工具覆寫，其中 name 設為 MCP 伺服器回報的工具名稱。請參閱設定可用的 MCP 工具。



回應確認請求

當代理呼叫具有 always_ask 政策的工具時：

1. 工作階段會發出 agent.tool_use 或 agent.mcp_tool_use 事件。
2. 工作階段會以 session.status_idle 事件暫停，其 stop_reason.type 為 requires_action。造成阻擋的事件 ID 位於 stop_reason.event_ids 陣列中。工作階段會無限期等待回應。
3. 針對每個造成阻擋的事件傳送一個 user.tool_confirmation 事件，並在 tool_use_id 參數中傳入該事件 ID。將 result 設為 "allow" 或 "deny"。使用 deny_message 說明拒絕原因。您可以在單一 events 請求中傳送多個確認。
4. 一旦所有造成阻擋的事件都已解決，工作階段會轉換回 running。獲允許的工具會執行。遭拒絕的工具不會執行，且代理會收到一個工具結果，說明該呼叫已被拒絕，其中包含您的 deny_message。

在以下範例中，工具使用事件 ID 來自 session.status_idle 事件的 stop_reason.event_ids 陣列。請在工作階段事件串流指南中進一步了解如何接收事件，或訂閱 webhook，以便在工作階段暫停等待輸入時收到通知。

# 允許工具執行
ant beta:sessions:events send \
  --session-id "$SESSION_ID" \
  --event "{type: user.tool_confirmation, tool_use_id: $AGENT_TOOL_USE_EVENT_ID, result: allow}"

# 或拒絕並附上說明
ant beta:sessions:events send \
  --session-id "$SESSION_ID" \
  --event "{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.}"



自訂工具

權限政策不適用於自訂工具。當代理呼叫自訂工具時，您的應用程式會收到 agent.custom_tool_use 事件，並負責在回傳 user.custom_tool_result 之前決定是否執行它。完整流程請參閱工作階段事件串流。



後續步驟