权限策略

"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 数组。请在会话事件流指南中了解有关接收事件的更多信息，或订阅 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 之前决定是否执行该工具。有关完整流程，请参阅会话事件流。



后续步骤