權限政策

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



權限政策類型

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

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



為工具集設定政策

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



代理程式工具集權限

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

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-4-8
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 項目上設定 default_config.permission_policy。

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

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

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



覆寫個別工具政策

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

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-4-8
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 陣列。請在工作階段事件串流指南中進一步了解如何接收事件，或訂閱 webhooks 以在工作階段暫停等待輸入時收到通知。

# 允許工具執行
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 之前決定是否執行該工具。請參閱工作階段事件串流以了解完整流程。



後續步驟