定義您的代理

權限政策

控制代理和 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?