--- title: 權限政策 url: https://platform.claude.com/docs/zh-TW/managed-agents/permission-policies description: 控制代理工具與 MCP 工具何時執行。 featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- 「Permission policies」（權限政策）控制由伺服器執行的工具（預先建置的代理程式工具集與 MCP 工具集）是自動執行、等待您的核准，還是由伺服器逐一評估每次呼叫。「Custom tools」（自訂工具）由您的應用程式執行並由您控制，因此不受權限政策管轄。 ## 權限政策類型 | 政策 | 行為 | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `always_allow` | 工具會自動執行，無需確認。 | | `always_ask` | 工作階段會暫停，並在執行前等待您的核准。事件流程請參閱[回應確認請求](https://platform.claude.com/docs/zh-TW/managed-agents/permission-policies#respond-to-confirmation-requests)。 | | `auto` | 伺服器會評估每次呼叫，並決定執行、拒絕，或暫停以等待您的核准。請參閱[使用 `auto` 讓伺服器評估每次呼叫](https://platform.claude.com/docs/zh-TW/managed-agents/permission-policies#let-the-server-evaluate-each-call-with-auto)。 | 每種工具集類型都有各自的預設值：代理工具集預設為 `always_allow`，MCP 工具集預設為 `always_ask`。 權限政策控制已啟用的工具何時執行。若要將某個工具從代理中完全移除，請改為停用該工具。請參閱[停用特定工具](https://platform.claude.com/docs/zh-TW/managed-agents/tools#disabling-specific-tools)。 ## 為工具集設定政策 您可以在建立代理時，於代理的 `tools` (csharp, go: `Tools`) 設定中設定權限政策，之後也可以透過[更新代理](https://platform.claude.com/docs/zh-TW/managed-agents/agent-setup#update-an-agent)來變更。執行中的工作階段會保留其建立時的工具集設定。更新會套用至之後建立的工作階段。 ### 代理工具集權限 建立代理時，您可以使用 `default_config.permission_policy` (java, php: `defaultConfig.permissionPolicy`; csharp, go: `DefaultConfig.PermissionPolicy`) 將政策套用至 `agent_toolset_20260401` 中的每個工具： ```bash cURL 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-opus-5-5", "tools": [ { "type": "agent_toolset_20260401", "default_config": { "permission_policy": {"type": "always_ask"} } } ] }') ``` ```bash CLI ant apply agent.md ``` ```markdown --- name: Coding Assistant model: claude-opus-5-5 tools: - type: agent_toolset_20260401 default_config: permission_policy: type: always_ask --- ``` ```python Python agent = client.beta.agents.create( name="Coding Assistant", model="claude-opus-5-5", tools=[ { "type": "agent_toolset_20260401", "default_config": { "permission_policy": {"type": "always_ask"}, }, }, ], ) ``` ```typescript TypeScript const agent = await client.beta.agents.create({ name: "Coding Assistant", model: "claude-opus-5-5", tools: [ { type: "agent_toolset_20260401", default_config: { permission_policy: { type: "always_ask" } } } ] }); ``` ```csharp C# using Anthropic.Models.Beta.Agents; var agent = await client.Beta.Agents.Create(new() { Name = "Coding Assistant", Model = BetaManagedAgentsModel.ClaudeOpus5_5, Tools = [ new BetaManagedAgentsAgentToolset20260401Params { Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401, DefaultConfig = new() { PermissionPolicy = new BetaManagedAgentsAlwaysAskPolicy { Type = "always_ask" }, }, }, ], }); ``` ```go Go agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ Name: "Coding Assistant", Model: anthropic.BetaManagedAgentsModelConfigParams{ ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5, }, Tools: []anthropic.BetaAgentNewParamsToolUnion{{ OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{ Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401, DefaultConfig: anthropic.BetaManagedAgentsAgentToolsetDefaultConfigParams{ PermissionPolicy: anthropic.BetaManagedAgentsAgentToolsetDefaultConfigParamsPermissionPolicyUnion{ OfAlwaysAsk: &anthropic.BetaManagedAgentsAlwaysAskPolicyParam{ Type: anthropic.BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk, }, }, }, }, }}, }) if err != nil { panic(err) } _ = agent ``` ```java Java import com.anthropic.models.beta.agents.*; var agent = client.beta().agents().create( AgentCreateParams.builder() .name("Coding Assistant") .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5) .addTool( BetaManagedAgentsAgentToolset20260401Params.builder() .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) .defaultConfig( BetaManagedAgentsAgentToolsetDefaultConfigParams.builder() .permissionPolicy( BetaManagedAgentsAlwaysAskPolicy.builder() .type(BetaManagedAgentsAlwaysAskPolicy.Type.ALWAYS_ASK) .build() ) .build() ) .build() ) .build() ); ``` ```php PHP use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params; use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolsetDefaultConfigParams; use Anthropic\Beta\Agents\BetaManagedAgentsAlwaysAskPolicy; $agent = $client->beta->agents->create( name: 'Coding Assistant', model: 'claude-opus-5-5', tools: [ BetaManagedAgentsAgentToolset20260401Params::with( type: 'agent_toolset_20260401', defaultConfig: BetaManagedAgentsAgentToolsetDefaultConfigParams::with( permissionPolicy: BetaManagedAgentsAlwaysAskPolicy::with(type: 'always_ask'), ), ), ], ); ``` ```ruby Ruby agent = client.beta.agents.create( name: "Coding Assistant", model: "claude-opus-5-5", tools: [ { type: "agent_toolset_20260401", default_config: { permission_policy: {type: "always_ask"} } } ] ) ``` `default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`) 為選用項目。若省略，代理工具集會以預設權限政策 `always_allow` 啟用。 ### MCP 工具集權限 MCP 工具集預設為 `always_ask`。這可確保新增至 MCP 伺服器的新工具不會在未經核准的情況下於您的應用程式中執行。若要自動核准來自受信任 MCP 伺服器的工具，請在 `mcp_toolset` 項目上設定 `default_config.permission_policy` (java, php: `defaultConfig.permissionPolicy`; csharp, go: `DefaultConfig.PermissionPolicy`)。 `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) 必須與 `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) 陣列中某個伺服器的 `name` (csharp, go: `Name`) 相符。 此範例連接一個 GitHub MCP 伺服器，並允許其工具在無需確認的情況下執行： ```bash cURL 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-opus-5-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"} } } ] }') ``` ```bash CLI ant apply agent.md ``` ```markdown --- name: Dev Assistant model: claude-opus-5-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 --- ``` ```python Python agent = client.beta.agents.create( name="Dev Assistant", model="claude-opus-5-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"}, }, }, ], ) ``` ```typescript TypeScript const agent = await client.beta.agents.create({ name: "Dev Assistant", model: "claude-opus-5-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" } } } ] }); ``` ```csharp C# using Anthropic.Models.Beta.Agents; var agent = await client.Beta.Agents.Create(new() { Name = "Dev Assistant", Model = BetaManagedAgentsModel.ClaudeOpus5_5, McpServers = [ new() { Type = BetaManagedAgentsUrlMcpServerParamsType.Url, Name = "github", Url = "https://mcp.example.com/github", }, ], Tools = [ new BetaManagedAgentsAgentToolset20260401Params { Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401, }, new BetaManagedAgentsMcpToolsetParams { Type = BetaManagedAgentsMcpToolsetParamsType.McpToolset, McpServerName = "github", DefaultConfig = new() { PermissionPolicy = new BetaManagedAgentsAlwaysAllowPolicy { Type = "always_allow" }, }, }, ], }); ``` ```go Go agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ Name: "Dev Assistant", Model: anthropic.BetaManagedAgentsModelConfigParams{ ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5, }, MCPServers: []anthropic.BetaManagedAgentsURLMCPServerParams{{ Type: anthropic.BetaManagedAgentsURLMCPServerParamsTypeURL, Name: "github", URL: "https://mcp.example.com/github", }}, Tools: []anthropic.BetaAgentNewParamsToolUnion{ { OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{ Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401, }, }, { OfMCPToolset: &anthropic.BetaManagedAgentsMCPToolsetParams{ Type: anthropic.BetaManagedAgentsMCPToolsetParamsTypeMCPToolset, MCPServerName: "github", DefaultConfig: anthropic.BetaManagedAgentsMCPToolsetDefaultConfigParams{ PermissionPolicy: anthropic.BetaManagedAgentsMCPToolsetDefaultConfigParamsPermissionPolicyUnion{ OfAlwaysAllow: &anthropic.BetaManagedAgentsAlwaysAllowPolicyParam{ Type: anthropic.BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow, }, }, }, }, }, }, }) if err != nil { panic(err) } _ = agent ``` ```java Java import com.anthropic.models.beta.agents.*; var agent = client.beta().agents().create( AgentCreateParams.builder() .name("Dev Assistant") .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5) .addMcpServer( BetaManagedAgentsUrlMcpServerParams.builder() .type(BetaManagedAgentsUrlMcpServerParams.Type.URL) .name("github") .url("https://mcp.example.com/github") .build() ) .addTool( BetaManagedAgentsAgentToolset20260401Params.builder() .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) .build() ) .addTool( BetaManagedAgentsMcpToolsetParams.builder() .type(BetaManagedAgentsMcpToolsetParams.Type.MCP_TOOLSET) .mcpServerName("github") .defaultConfig( BetaManagedAgentsMcpToolsetDefaultConfigParams.builder() .permissionPolicy( BetaManagedAgentsAlwaysAllowPolicy.builder() .type(BetaManagedAgentsAlwaysAllowPolicy.Type.ALWAYS_ALLOW) .build() ) .build() ) .build() ) .build() ); ``` ```php PHP use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params; use Anthropic\Beta\Agents\BetaManagedAgentsAlwaysAllowPolicy; use Anthropic\Beta\Agents\BetaManagedAgentsMCPToolsetDefaultConfigParams; use Anthropic\Beta\Agents\BetaManagedAgentsMCPToolsetParams; use Anthropic\Beta\Agents\BetaManagedAgentsURLMCPServerParams; $agent = $client->beta->agents->create( name: 'Dev Assistant', model: 'claude-opus-5-5', mcpServers: [ BetaManagedAgentsURLMCPServerParams::with( type: 'url', name: 'github', url: 'https://mcp.example.com/github', ), ], tools: [ BetaManagedAgentsAgentToolset20260401Params::with( type: 'agent_toolset_20260401', ), BetaManagedAgentsMCPToolsetParams::with( type: 'mcp_toolset', mcpServerName: 'github', defaultConfig: BetaManagedAgentsMCPToolsetDefaultConfigParams::with( permissionPolicy: BetaManagedAgentsAlwaysAllowPolicy::with(type: 'always_allow'), ), ), ], ); ``` ```ruby Ruby agent = client.beta.agents.create( name: "Dev Assistant", model: "claude-opus-5-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` (csharp, go: `Configs`) 陣列來覆寫個別工具的預設值。代理工具集的 `name` (csharp, go: `Name`) 值列於[可用工具](https://platform.claude.com/docs/zh-TW/managed-agents/tools#available-tools)中。此範例預設允許完整的代理工具集，但在執行任何 bash 指令前需要確認： ```bash cURL tools='[ { "type": "agent_toolset_20260401", "default_config": { "permission_policy": {"type": "always_allow"} }, "configs": [ { "name": "bash", "permission_policy": {"type": "always_ask"} } ] } ]' ``` ```bash CLI ant apply agent.md ``` ```markdown --- name: Coding Assistant model: claude-opus-5-5 tools: - type: agent_toolset_20260401 default_config: permission_policy: type: always_allow configs: - name: bash permission_policy: type: always_ask --- ``` ```python Python tools = [ { "type": "agent_toolset_20260401", "default_config": { "permission_policy": {"type": "always_allow"}, }, "configs": [ { "name": "bash", "permission_policy": {"type": "always_ask"}, }, ], }, ] ``` ```typescript TypeScript const tools = [ { type: "agent_toolset_20260401", default_config: { permission_policy: { type: "always_allow" } }, configs: [ { name: "bash", permission_policy: { type: "always_ask" } } ] } ] satisfies Anthropic.Beta.AgentCreateParams["tools"]; ``` ```csharp C# using Anthropic.Models.Beta.Agents; using Tool = Anthropic.Models.Beta.Agents.Tool; Tool[] tools = [ new BetaManagedAgentsAgentToolset20260401Params { Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401, DefaultConfig = new() { PermissionPolicy = new BetaManagedAgentsAlwaysAllowPolicy { Type = "always_allow" }, }, Configs = [ new BetaManagedAgentsBashToolConfigParams { PermissionPolicy = new BetaManagedAgentsAlwaysAskPolicy { Type = "always_ask" }, }, ], }, ]; ``` ```go Go tools := []anthropic.BetaAgentNewParamsToolUnion{{ OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{ Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401, DefaultConfig: anthropic.BetaManagedAgentsAgentToolsetDefaultConfigParams{ PermissionPolicy: anthropic.BetaManagedAgentsAgentToolsetDefaultConfigParamsPermissionPolicyUnion{ OfAlwaysAllow: &anthropic.BetaManagedAgentsAlwaysAllowPolicyParam{ Type: anthropic.BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow, }, }, }, Configs: []anthropic.BetaManagedAgentsAgentToolConfigParamsUnion{{ OfBash: &anthropic.BetaManagedAgentsBashToolConfigParams{ PermissionPolicy: anthropic.BetaManagedAgentsBashToolConfigParamsPermissionPolicyUnion{ OfAlwaysAsk: &anthropic.BetaManagedAgentsAlwaysAskPolicyParam{ Type: anthropic.BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk, }, }, }, }}, }, }} _ = tools ``` ```java Java import com.anthropic.models.beta.agents.*; import java.util.List; var tools = List.of( AgentCreateParams.Tool.ofAgentToolset20260401( BetaManagedAgentsAgentToolset20260401Params.builder() .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) .defaultConfig( BetaManagedAgentsAgentToolsetDefaultConfigParams.builder() .permissionPolicy( BetaManagedAgentsAlwaysAllowPolicy.builder() .type(BetaManagedAgentsAlwaysAllowPolicy.Type.ALWAYS_ALLOW) .build() ) .build() ) .addConfig( BetaManagedAgentsBashToolConfigParams.builder() .permissionPolicy( BetaManagedAgentsAlwaysAskPolicy.builder() .type(BetaManagedAgentsAlwaysAskPolicy.Type.ALWAYS_ASK) .build() ) .build() ) .build() ) ); ``` ```php PHP use Anthropic\Beta\Agents\BetaManagedAgentsBashToolConfigParams; use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params; use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolsetDefaultConfigParams; use Anthropic\Beta\Agents\BetaManagedAgentsAlwaysAllowPolicy; use Anthropic\Beta\Agents\BetaManagedAgentsAlwaysAskPolicy; $tools = [ BetaManagedAgentsAgentToolset20260401Params::with( type: 'agent_toolset_20260401', defaultConfig: BetaManagedAgentsAgentToolsetDefaultConfigParams::with( permissionPolicy: BetaManagedAgentsAlwaysAllowPolicy::with(type: 'always_allow'), ), configs: [ BetaManagedAgentsBashToolConfigParams::with( permissionPolicy: BetaManagedAgentsAlwaysAskPolicy::with(type: 'always_ask'), ), ], ), ]; ``` ```ruby Ruby tools = [ { type: "agent_toolset_20260401", default_config: { permission_policy: {type: "always_allow"} }, configs: [ { name: "bash", permission_policy: {type: "always_ask"} } ] } ] ``` 請在建立代理的請求中傳入此 `tools` (csharp, go: `Tools`) 設定（CLI 分頁顯示完整指令）。MCP 工具集支援相同的個別工具覆寫，並將 `name` (csharp, go: `Name`) 設為 MCP 伺服器回報的工具名稱。請參閱[設定可用的 MCP 工具](https://platform.claude.com/docs/zh-TW/managed-agents/mcp-connector#configure-which-mcp-tools-are-available)。 ## 使用 `auto` 讓伺服器評估每次呼叫 使用 `auto` 權限政策時，伺服器會在每次呼叫執行前進行評估。由於評估會考量工具、呼叫的輸入，以及工作階段截至該時間點的內容，伺服器可能會以不同方式處理對同一工具的兩次呼叫。每次呼叫會有以下三種結果之一： * **呼叫執行。** 當伺服器判定呼叫是安全的，工具會如同在 `always_allow` 下一樣執行。 * **呼叫被拒絕。** 當伺服器將呼叫評估為高風險時，工具不會執行。代理會收到一個錯誤工具結果，內容為 `Permission to use {tool_name} has been denied.` 且 `is_error: true`。工作階段會繼續執行，且您的用戶端無法覆寫此拒絕。 * **呼叫暫停以等待您的核准。** 當伺服器無法做出判定時，工作階段會如同在 `always_ask` 下一樣暫停。請參閱[回應確認請求](https://platform.claude.com/docs/zh-TW/managed-agents/permission-policies#respond-to-confirmation-requests)。 若要啟用 `auto`，請將 `permission_policy` 設為 `{"type": "auto"}`。它與其他政策放在相同的兩個位置：工具集的 [`default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`)](https://platform.claude.com/docs/zh-TW/managed-agents/permission-policies#set-a-policy-for-a-toolset) 用於整個工具集，或 [`configs` (csharp, go: `Configs`) 項目](https://platform.claude.com/docs/zh-TW/managed-agents/permission-policies#override-an-individual-tool-policy) 用於單一工具。代理工具集與 MCP 工具集都接受此設定。沒有任何工具集預設使用 `auto`。 以下範例將 `auto` 設為代理工具集與 `github` MCP 工具集的預設值，並將 `bash` 覆寫為 `always_ask`： ```bash cURL 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": "Ops Agent", "model": "claude-opus-5-5", "mcp_servers": [ {"type": "url", "name": "github", "url": "https://mcp.example.com/github"} ], "tools": [ { "type": "agent_toolset_20260401", "default_config": { "permission_policy": {"type": "auto"} }, "configs": [ {"name": "bash", "permission_policy": {"type": "always_ask"}} ] }, { "type": "mcp_toolset", "mcp_server_name": "github", "default_config": { "permission_policy": {"type": "auto"} } } ] }') ``` ```bash CLI ant apply agent.md ``` ```markdown --- name: Ops Agent model: claude-opus-5-5 mcp_servers: - type: url name: github url: https://mcp.example.com/github tools: - type: agent_toolset_20260401 default_config: permission_policy: type: auto configs: - name: bash permission_policy: type: always_ask - type: mcp_toolset mcp_server_name: github default_config: permission_policy: type: auto --- ``` ```python Python agent = client.beta.agents.create( name="Ops Agent", model="claude-opus-5-5", mcp_servers=[ {"type": "url", "name": "github", "url": "https://mcp.example.com/github"}, ], tools=[ { "type": "agent_toolset_20260401", "default_config": { "permission_policy": {"type": "auto"}, }, "configs": [ {"name": "bash", "permission_policy": {"type": "always_ask"}}, ], }, { "type": "mcp_toolset", "mcp_server_name": "github", "default_config": { "permission_policy": {"type": "auto"}, }, }, ], ) ``` ```typescript TypeScript const agent = await client.beta.agents.create({ name: "Ops Agent", model: "claude-opus-5-5", mcp_servers: [{ type: "url", name: "github", url: "https://mcp.example.com/github" }], tools: [ { type: "agent_toolset_20260401", default_config: { permission_policy: { type: "auto" } }, configs: [{ name: "bash", permission_policy: { type: "always_ask" } }] }, { type: "mcp_toolset", mcp_server_name: "github", default_config: { permission_policy: { type: "auto" } } } ] }); ``` ```csharp C# using Anthropic.Models.Beta.Agents; var agent = await client.Beta.Agents.Create(new() { Name = "Ops Agent", Model = BetaManagedAgentsModel.ClaudeOpus5_5, McpServers = [ new() { Type = BetaManagedAgentsUrlMcpServerParamsType.Url, Name = "github", Url = "https://mcp.example.com/github", }, ], Tools = [ new BetaManagedAgentsAgentToolset20260401Params { Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401, DefaultConfig = new() { PermissionPolicy = new BetaManagedAgentsAutoPolicy(), }, Configs = [ new BetaManagedAgentsBashToolConfigParams { PermissionPolicy = new BetaManagedAgentsAlwaysAskPolicy { Type = "always_ask" }, }, ], }, new BetaManagedAgentsMcpToolsetParams { Type = BetaManagedAgentsMcpToolsetParamsType.McpToolset, McpServerName = "github", DefaultConfig = new() { PermissionPolicy = new BetaManagedAgentsAutoPolicy(), }, }, ], }); ``` ```go Go agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ Name: "Ops Agent", Model: anthropic.BetaManagedAgentsModelConfigParams{ ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5, }, MCPServers: []anthropic.BetaManagedAgentsURLMCPServerParams{{ Type: anthropic.BetaManagedAgentsURLMCPServerParamsTypeURL, Name: "github", URL: "https://mcp.example.com/github", }}, Tools: []anthropic.BetaAgentNewParamsToolUnion{ { OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{ Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401, DefaultConfig: anthropic.BetaManagedAgentsAgentToolsetDefaultConfigParams{ PermissionPolicy: anthropic.BetaManagedAgentsAgentToolsetDefaultConfigParamsPermissionPolicyUnion{ OfAuto: &anthropic.BetaManagedAgentsAutoPolicyParam{}, }, }, Configs: []anthropic.BetaManagedAgentsAgentToolConfigParamsUnion{{ OfBash: &anthropic.BetaManagedAgentsBashToolConfigParams{ PermissionPolicy: anthropic.BetaManagedAgentsBashToolConfigParamsPermissionPolicyUnion{ OfAlwaysAsk: &anthropic.BetaManagedAgentsAlwaysAskPolicyParam{ Type: anthropic.BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk, }, }, }, }}, }, }, { OfMCPToolset: &anthropic.BetaManagedAgentsMCPToolsetParams{ Type: anthropic.BetaManagedAgentsMCPToolsetParamsTypeMCPToolset, MCPServerName: "github", DefaultConfig: anthropic.BetaManagedAgentsMCPToolsetDefaultConfigParams{ PermissionPolicy: anthropic.BetaManagedAgentsMCPToolsetDefaultConfigParamsPermissionPolicyUnion{ OfAuto: &anthropic.BetaManagedAgentsAutoPolicyParam{}, }, }, }, }, }, }) if err != nil { panic(err) } _ = agent ``` ```java Java import com.anthropic.models.beta.agents.*; var agent = client.beta().agents().create( AgentCreateParams.builder() .name("Ops Agent") .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5) .addMcpServer( BetaManagedAgentsUrlMcpServerParams.builder() .type(BetaManagedAgentsUrlMcpServerParams.Type.URL) .name("github") .url("https://mcp.example.com/github") .build() ) .addTool( BetaManagedAgentsAgentToolset20260401Params.builder() .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) .defaultConfig( BetaManagedAgentsAgentToolsetDefaultConfigParams.builder() .permissionPolicy(BetaManagedAgentsAutoPolicy.builder().build()) .build() ) .addConfig( BetaManagedAgentsBashToolConfigParams.builder() .permissionPolicy( BetaManagedAgentsAlwaysAskPolicy.builder() .type(BetaManagedAgentsAlwaysAskPolicy.Type.ALWAYS_ASK) .build() ) .build() ) .build() ) .addTool( BetaManagedAgentsMcpToolsetParams.builder() .type(BetaManagedAgentsMcpToolsetParams.Type.MCP_TOOLSET) .mcpServerName("github") .defaultConfig( BetaManagedAgentsMcpToolsetDefaultConfigParams.builder() .permissionPolicy(BetaManagedAgentsAutoPolicy.builder().build()) .build() ) .build() ) .build() ); ``` ```php PHP use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params; use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolsetDefaultConfigParams; use Anthropic\Beta\Agents\BetaManagedAgentsAlwaysAskPolicy; use Anthropic\Beta\Agents\BetaManagedAgentsAutoPolicy; use Anthropic\Beta\Agents\BetaManagedAgentsBashToolConfigParams; use Anthropic\Beta\Agents\BetaManagedAgentsMCPToolsetDefaultConfigParams; use Anthropic\Beta\Agents\BetaManagedAgentsMCPToolsetParams; use Anthropic\Beta\Agents\BetaManagedAgentsURLMCPServerParams; $agent = $client->beta->agents->create( name: 'Ops Agent', model: 'claude-opus-5-5', mcpServers: [ BetaManagedAgentsURLMCPServerParams::with( type: 'url', name: 'github', url: 'https://mcp.example.com/github', ), ], tools: [ BetaManagedAgentsAgentToolset20260401Params::with( type: 'agent_toolset_20260401', defaultConfig: BetaManagedAgentsAgentToolsetDefaultConfigParams::with( permissionPolicy: BetaManagedAgentsAutoPolicy::with(), ), configs: [ BetaManagedAgentsBashToolConfigParams::with( permissionPolicy: BetaManagedAgentsAlwaysAskPolicy::with(type: 'always_ask'), ), ], ), BetaManagedAgentsMCPToolsetParams::with( type: 'mcp_toolset', mcpServerName: 'github', defaultConfig: BetaManagedAgentsMCPToolsetDefaultConfigParams::with( permissionPolicy: BetaManagedAgentsAutoPolicy::with(), ), ), ], ); ``` ```ruby Ruby agent = client.beta.agents.create( name: "Ops Agent", model: "claude-opus-5-5", mcp_servers: [ {type: "url", name: "github", url: "https://mcp.example.com/github"} ], tools: [ { type: "agent_toolset_20260401", default_config: { permission_policy: {type: "auto"} }, configs: [ {name: "bash", permission_policy: {type: "always_ask"}} ] }, { type: "mcp_toolset", mcp_server_name: "github", default_config: { permission_policy: {type: "auto"} } } ] ) ``` 您在 `user.message` 事件中發布的內容會被視為您的意圖，並可能使伺服器允許原本會拒絕的呼叫。伺服器不會從工具結果、擷取的網頁、MCP 伺服器的回應，或[工作階段執行緒](https://platform.claude.com/docs/zh-TW/managed-agents/session-threads#tool-permissions-and-custom-tools)之間的訊息中讀取意圖。它會評估這些內容，但不會從中接受指示。無論由誰提出要求，伺服器都會將某些呼叫評估為高風險。如果您在 `user.message` 事件中轉送不受信任的終端使用者輸入，伺服器也會將該輸入視為您的意圖，並可能因此允許某個呼叫。對於您不會讓該終端使用者在未經審查的情況下執行的工具，請設定 `always_ask`。 `auto` 並非人工檢查點。如果伺服器判定呼叫是安全的，該呼叫會在任何人看到之前執行，且其影響可能無法復原。如果某個工具的呼叫必須在執行前經過人員審查，請在該工具上設定 `always_ask`。 ## 查看每次呼叫的評估方式 在任何權限政策下，每個 `agent.tool_use` 與 `agent.mcp_tool_use` 事件都帶有 `evaluated_permission`，即該呼叫權限檢查的結果：`"allow"`、`"ask"` 或 `"deny"`。大多數事件也帶有一個 `evaluation` 物件，其 `type` 指出產生該結果的政策。在 `auto` 下，該物件還會記錄伺服器的判定，並在結果為 `ask` 或 `deny` 時附上 `reason_code`。 例如，當 `bash` 處於 `auto` 下，且伺服器將某次呼叫評估為高風險時，被拒絕的呼叫會以如下形式出現在事件串流中： ```json { "type": "agent.tool_use", "id": "sevt_01pqr...", "name": "bash", "input": { "command": "rm -rf /workspace/reports" }, "evaluated_permission": "deny", "evaluation": { "type": "auto", "evaluated_permission": { "type": "deny", "reason_code": "high_risk" } }, "processed_at": "2026-03-25T14:05:12Z" } ``` `evaluation` 物件會採用下表中的其中一種形式。 | `evaluation` | 頂層 `evaluated_permission` | 意義 | | ------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------ | | `{"type": "always_allow"}` | `"allow"` | 解析後的政策為 `always_allow`，因此呼叫已執行。 | | `{"type": "always_ask"}` | `"ask"` | 解析後的政策為 `always_ask`，因此呼叫已暫停以等待您的核准。 | | `{"type": "auto", "evaluated_permission": {"type": "allow"}}` | `"allow"` | 在 `auto` 下，伺服器判定呼叫是安全的，因此已執行。 | | `{"type": "auto", "evaluated_permission": {"type": "ask", "reason_code": "indeterminate"}}` | `"ask"` | 在 `auto` 下，伺服器無法做出判定，因此呼叫已暫停以等待您的核准。 | | `{"type": "auto", "evaluated_permission": {"type": "deny", "reason_code": "high_risk"}}` | `"deny"` | 在 `auto` 下，伺服器將呼叫評估為高風險並予以拒絕。 | 當 `evaluation.type` 為 `"auto"` 時，其巢狀的 `evaluated_permission.type` 會重複事件頂層的 `evaluated_permission`，因此您可以從任一欄位讀取結果。`reason_code` 是供您的用戶端進行分支判斷並保存於稽核紀錄中的值，而非用於向終端使用者顯示的文字。 在兩種情況下不會有 `evaluation`。當代理程式指定了一個未在工作階段中啟用的工具時，伺服器會在不評估政策的情況下拒絕該呼叫：事件會帶有 `evaluated_permission: "deny"` 且沒有 `evaluation`。在引入 `evaluation` 之前記錄的事件也會省略它：當 `evaluated_permission` 為 `"allow"` 時，請將其視為 `always_allow`；當其為 `"ask"` 時，請將其視為 `always_ask`。 請讓您的用戶端能夠容忍無法辨識的 `evaluation.type` 或 `reason_code`。`agent.custom_tool_use` 事件不帶有這兩個欄位，因為權限政策不管轄[自訂工具](https://platform.claude.com/docs/zh-TW/managed-agents/permission-policies#custom-tools)。 ## 回應確認請求 在 `always_ask` 政策下，或在 `auto` 下伺服器無法做出判定時，工具呼叫會評估為 `ask`。發生這種情況時： 1. 工作階段會發出 `agent.tool_use` 或 `agent.mcp_tool_use` 事件。 2. 工作階段會以 `session.status_idle` 事件暫停，其 `stop_reason.type` 為 `requires_action`。造成阻擋的事件 ID 位於 `stop_reason.event_ids` 陣列中。工作階段會無限期等待回應。來自[工作流程執行](https://platform.claude.com/docs/zh-TW/managed-agents/workflow-runs#while-a-run-is-open)之執行緒的呼叫會透過主要串流傳送到您的用戶端。當工作階段中有其他任何項目正在運作時，工作階段可能會維持 `running` 且不傳送 `session.status_idle`，因此請直接回應該工具使用事件本身。該呼叫只會等到該執行不再需要該執行緒，或該執行結束為止。中斷可能會使其持續等待，因此請自行允許或拒絕它。 3. 針對每個造成阻擋的事件傳送 `user.tool_confirmation` 事件，並在 `tool_use_id` (java: `toolUseId`; php: `toolUseID`; csharp, go: `ToolUseID`) 參數中傳入事件 ID。將 `result` (csharp, go: `Result`) 設為 `"allow"` 或 `"deny"`。使用 `deny_message` (java, php: `denyMessage`; csharp, go: `DenyMessage`) 說明拒絕的原因。您可以在單一 `events` 請求中傳送多個確認。 4. 所有造成阻擋的事件都解決後，工作階段會轉換回 `running`。已允許的工具會執行。已拒絕的工具不會執行，代理會收到一個工具結果，說明該呼叫已被拒絕，其中包含您的 `deny_message` (java, php: `denyMessage`; csharp, go: `DenyMessage`)。 例如，在 `always_ask` 政策下暫停的 `bash` 呼叫會在串流中顯示如下： ```json { "type": "agent.tool_use", "id": "sevt_01def...", "name": "bash", "input": { "command": "pip install -r requirements.txt" }, "evaluated_permission": "ask", "evaluation": { "type": "always_ask" }, "processed_at": "2026-03-25T14:01:45Z" } ``` 如果您針對 `evaluated_permission` (java, php: `evaluatedPermission`; csharp, go: `EvaluatedPermission`) 不是 `ask` 的事件傳送 `user.tool_confirmation`，API 會以 400 錯誤拒絕。這包括伺服器在 `auto` 下拒絕的呼叫：您的用戶端無法覆寫它們。 若要改以互動方式回應，請使用 `ant beta:sessions connect`，它會顯示等待中的呼叫，並在您允許或拒絕時傳送此事件。請參閱[從終端機連接至 Managed Agents 工作階段](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/cli/sessions-connect#follow-and-steer-the-session)。 在以下範例中，工具使用事件 ID 來自 `session.status_idle` 事件的 `stop_reason.event_ids` 陣列。在[工作階段事件串流](https://platform.claude.com/docs/zh-TW/managed-agents/events-and-streaming#stream-events)指南中進一步了解如何接收事件，或[訂閱 webhook](https://platform.claude.com/docs/zh-TW/managed-agents/webhooks)，以便在工作階段暫停等待輸入時收到通知。 ```bash cURL # 允許該工具執行 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." } ] }' ``` ```bash CLI # 允許工具執行 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.}" ``` ```python Python # 允許工具執行 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.", }, ], ) ``` ```typescript TypeScript // 允許工具執行 await client.beta.sessions.events.send(session.id, { events: [ { type: "user.tool_confirmation", tool_use_id: agent_tool_use_event.id, result: "allow" } ] }); // 或拒絕並附上說明 await 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." } ] }); ``` ```csharp C# // 允許工具執行 await client.Beta.Sessions.Events.Send(session.ID, new() { Events = [ new BetaManagedAgentsUserToolConfirmationEventParams { Type = BetaManagedAgentsUserToolConfirmationEventParamsType.UserToolConfirmation, ToolUseID = agentToolUseEvent.ID, Result = "allow", }, ], }); // 或拒絕並附上說明 await client.Beta.Sessions.Events.Send(session.ID, new() { Events = [ new BetaManagedAgentsUserToolConfirmationEventParams { Type = BetaManagedAgentsUserToolConfirmationEventParamsType.UserToolConfirmation, ToolUseID = mcpToolUseEvent.ID, Result = "deny", DenyMessage = "Don't create issues in the production project. Use the staging project.", }, ], }); ``` ```go Go // 允許工具執行 _, err = client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{ Events: []anthropic.BetaManagedAgentsEventParamsUnion{{ OfUserToolConfirmation: &anthropic.BetaManagedAgentsUserToolConfirmationEventParams{ Type: anthropic.BetaManagedAgentsUserToolConfirmationEventParamsTypeUserToolConfirmation, ToolUseID: agentToolUseEvent.ID, Result: anthropic.BetaManagedAgentsUserToolConfirmationEventParamsResultAllow, }, }}, }) if err != nil { panic(err) } // 或拒絕並附上說明 _, err = client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{ Events: []anthropic.BetaManagedAgentsEventParamsUnion{{ OfUserToolConfirmation: &anthropic.BetaManagedAgentsUserToolConfirmationEventParams{ Type: anthropic.BetaManagedAgentsUserToolConfirmationEventParamsTypeUserToolConfirmation, ToolUseID: mcpToolUseEvent.ID, Result: anthropic.BetaManagedAgentsUserToolConfirmationEventParamsResultDeny, DenyMessage: anthropic.String("Don't create issues in the production project. Use the staging project."), }, }}, }) if err != nil { panic(err) } ``` ```java Java // 允許工具執行 client.beta().sessions().events().send( session.id(), EventSendParams.builder() .addEvent( BetaManagedAgentsUserToolConfirmationEventParams.builder() .type(BetaManagedAgentsUserToolConfirmationEventParams.Type.USER_TOOL_CONFIRMATION) .toolUseId(agentToolUseEvent.id()) .result(BetaManagedAgentsUserToolConfirmationEventParams.Result.ALLOW) .build() ) .build() ); // 或拒絕並附上說明 client.beta().sessions().events().send( session.id(), EventSendParams.builder() .addEvent( BetaManagedAgentsUserToolConfirmationEventParams.builder() .type(BetaManagedAgentsUserToolConfirmationEventParams.Type.USER_TOOL_CONFIRMATION) .toolUseId(mcpToolUseEvent.id()) .result(BetaManagedAgentsUserToolConfirmationEventParams.Result.DENY) .denyMessage("Don't create issues in the production project. Use the staging project.") .build() ) .build() ); ``` ```php PHP use Anthropic\Beta\Sessions\Events\ManagedAgentsUserToolConfirmationEventParams; // 允許工具執行 $client->beta->sessions->events->send( $session->id, events: [ ManagedAgentsUserToolConfirmationEventParams::with( type: 'user.tool_confirmation', toolUseID: $agentToolUseEvent->id, result: 'allow', ), ], ); // 或拒絕並附上說明 $client->beta->sessions->events->send( $session->id, events: [ ManagedAgentsUserToolConfirmationEventParams::with( type: 'user.tool_confirmation', toolUseID: $mcpToolUseEvent->id, result: 'deny', denyMessage: "Don't create issues in the production project. Use the staging project.", ), ], ); ``` ```ruby Ruby # 允許工具執行 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." } ] ) ``` ## 自訂工具 權限政策不適用於自訂工具。當代理呼叫自訂工具時，您的應用程式會收到 `agent.custom_tool_use` 事件，並負責決定是否執行該工具，然後再傳回 `user.custom_tool_result`。完整流程請參閱[工作階段事件串流](https://platform.claude.com/docs/zh-TW/managed-agents/events-and-streaming#answer-tool-calls-that-pause-the-session)。 ## 後續步驟 為您的代理附加可重複使用、以檔案系統為基礎的專業知識，以支援特定領域的工作流程。 傳送事件、串流回應，並在執行過程中中斷或重新導向您的工作階段。