Claude Platform Docs
Managed Agents定义您的智能体

权限策略

控制智能体工具和 MCP 工具何时执行。

"Permission policies"（权限策略）控制由服务器执行的工具（预构建的智能体工具集和 MCP 工具集）是自动运行还是等待您的批准。自定义工具由您的应用程序执行并由您控制，因此不受权限策略管辖。

权限策略类型

策略行为
always_allow工具自动执行，无需确认。
always_ask会话暂停并在执行前等待您的批准。有关事件流程，请参阅响应确认请求。

每种工具集类型都有自己的默认值：智能体工具集默认为 always_allow，MCP 工具集默认为 always_ask。

权限策略控制已启用的工具何时运行。若要将某个工具从智能体中完全移除，请改为禁用它。请参阅禁用特定工具。

为工具集设置策略

您在创建智能体时于智能体的 tools 配置中设置权限策略，之后可以通过更新智能体来更改它们。正在运行的会话会保留其创建时的工具集配置。更新仅适用于之后创建的会话。

智能体工具集权限

创建智能体时，您可以使用 default_config.permission_policy 将策略应用于 agent_toolset_20260401 中的每个工具：

ant beta:agents create < agent.yaml
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
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 之前决定是否执行它。有关完整流程，请参阅会话事件流。

后续步骤

技能

为您的智能体附加可复用的、基于文件系统的专业知识，以支持特定领域的工作流程。

会话事件流

发送事件、流式传输响应，并在执行过程中中断或重定向您的会话。

Was this page helpful?