权限策略 - 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.",
        },
    ],
)