定义您的智能体

权限策略

控制代理和 MCP 工具的执行时机。

权限策略控制服务器执行的工具（预构建的代理工具集和 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 中的每个工具应用策略：

agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "Coding Assistant",
    "model": "claude-sonnet-4-6",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "default_config": {
          "permission_policy": {"type": "always_ask"}
        }
      }
    ]
  }')

default_config 是一个可选设置。如果省略，代理工具集将以默认权限策略 always_allow 启用。

MCP 工具集权限

MCP 工具集默认为 always_ask。这确保了添加到 MCP 服务器的新工具不会在未经批准的情况下在您的应用程序中执行。要自动批准来自受信任 MCP 服务器的工具，请在 mcp_toolset 条目上设置 permission_policy。

mcp_server_name 必须与 mcp_servers 数组中引用的 name 匹配。

此示例连接 GitHub MCP 服务器并允许其工具无需确认即可运行：

agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "Dev Assistant",
    "model": "claude-sonnet-4-6",
    "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 数组覆盖单个工具的默认策略。此示例默认允许完整的代理工具集，但在运行任何 bash 命令之前需要确认：

tools='[
  {
    "type": "agent_toolset_20260401",
    "default_config": {
      "permission_policy": {"type": "always_allow"}
    },
    "configs": [
      {
        "name": "bash",
        "permission_policy": {"type": "always_ask"}
      }
    ]
  }
]'

响应确认请求

当代理调用具有 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 状态。

在会话事件流指南中了解有关事件处理的更多信息。

# 允许工具执行
curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.tool_confirmation",
        "tool_use_id": "'$AGENT_TOOL_USE_EVENT_ID'",
        "result": "allow"
      }
    ]
  }'

# 或拒绝并附上说明
curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "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."
      }
    ]
  }'

自定义工具

权限策略不适用于自定义工具。当代理调用自定义工具时，您的应用程序会收到 agent.custom_tool_use 事件，并负责在发送回 user.custom_tool_result 之前决定是否执行它。完整流程请参见会话事件流。

Was this page helpful?

定义您的智能体

权限策略

控制代理和 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 中的每个工具应用策略：

agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "Coding Assistant",
    "model": "claude-sonnet-4-6",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "default_config": {
          "permission_policy": {"type": "always_ask"}
        }
      }
    ]
  }')

default_config 是一个可选设置。如果省略，代理工具集将以默认权限策略 always_allow 启用。

MCP 工具集权限

mcp_server_name 必须与 mcp_servers 数组中引用的 name 匹配。

此示例连接 GitHub MCP 服务器并允许其工具无需确认即可运行：

agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "Dev Assistant",
    "model": "claude-sonnet-4-6",
    "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 数组覆盖单个工具的默认策略。此示例默认允许完整的代理工具集，但在运行任何 bash 命令之前需要确认：

tools='[
  {
    "type": "agent_toolset_20260401",
    "default_config": {
      "permission_policy": {"type": "always_allow"}
    },
    "configs": [
      {
        "name": "bash",
        "permission_policy": {"type": "always_ask"}
      }
    ]
  }
]'

响应确认请求

当代理调用具有 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 状态。

在会话事件流指南中了解有关事件处理的更多信息。

# 允许工具执行
curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.tool_confirmation",
        "tool_use_id": "'$AGENT_TOOL_USE_EVENT_ID'",
        "result": "allow"
      }
    ]
  }'

# 或拒绝并附上说明
curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "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."
      }
    ]
  }'

自定义工具

Was this page helpful?