--- title: Policy di autorizzazione url: https://platform.claude.com/docs/it/managed-agents/permission-policies description: Controlla quando vengono eseguiti gli strumenti dell'agente e gli strumenti MCP. featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- Le "permission policies" (criteri di autorizzazione) controllano se gli strumenti eseguiti dal server (il "toolset" (set di strumenti) predefinito dell'agente e il set di strumenti MCP) vengono eseguiti automaticamente, attendono la tua approvazione oppure vengono valutati dal server chiamata per chiamata. I "custom tools" (strumenti personalizzati) vengono eseguiti dalla tua applicazione e sono sotto il tuo controllo, quindi i criteri di autorizzazione non si applicano a essi. ## Tipi di policy di autorizzazione | Criterio | Comportamento | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `always_allow` | Lo strumento viene eseguito automaticamente senza conferma. | | `always_ask` | La sessione si mette in pausa e attende la tua approvazione prima dell'esecuzione. Consulta [Rispondere alle richieste di conferma](https://platform.claude.com/docs/it/managed-agents/permission-policies#respond-to-confirmation-requests) per il flusso degli eventi. | | `auto` | Il server valuta ogni chiamata e la esegue, la nega oppure si mette in pausa in attesa della tua approvazione. Consulta [Lasciare che il server valuti ogni chiamata con `auto`](https://platform.claude.com/docs/it/managed-agents/permission-policies#let-the-server-evaluate-each-call-with-auto). | Ogni tipo di toolset ha il proprio valore predefinito: il toolset dell'agente ha come valore predefinito `always_allow`, mentre i toolset MCP hanno come valore predefinito `always_ask`. Una policy di autorizzazione controlla quando viene eseguito uno strumento abilitato. Per rimuovere completamente uno strumento dall'agente, disabilitalo invece. Consulta [Disabilitare strumenti specifici](https://platform.claude.com/docs/it/managed-agents/tools#disabling-specific-tools). ## Impostare una policy per un toolset Imposti le policy di autorizzazione nella configurazione `tools` (csharp, go: `Tools`) dell'agente quando crei l'agente, e puoi modificarle in seguito [aggiornando l'agente](https://platform.claude.com/docs/it/managed-agents/agent-setup#update-an-agent). Le sessioni in esecuzione mantengono la configurazione del toolset con cui sono state create. Gli aggiornamenti si applicano alle sessioni create successivamente. ### Autorizzazioni del toolset dell'agente Quando crei un agente, puoi applicare una policy a ogni strumento in `agent_toolset_20260401` usando `default_config.permission_policy` (java, php: `defaultConfig.permissionPolicy`; csharp, go: `DefaultConfig.PermissionPolicy`): ```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`) è facoltativo. Se lo ometti, il toolset dell'agente viene abilitato con la policy di autorizzazione predefinita, `always_allow`. ### Autorizzazioni del toolset MCP I toolset MCP usano per impostazione predefinita `always_ask`. Questo garantisce che i nuovi strumenti aggiunti a un server MCP non vengano eseguiti nella tua applicazione senza approvazione. Per approvare automaticamente gli strumenti di un server MCP attendibile, imposta `default_config.permission_policy` (java, php: `defaultConfig.permissionPolicy`; csharp, go: `DefaultConfig.PermissionPolicy`) sulla voce `mcp_toolset`. Il valore `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) deve corrispondere al `name` (csharp, go: `Name`) di un server nell'array `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`). Questo esempio connette un server MCP GitHub e consente l'esecuzione dei suoi strumenti senza conferma: ```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"} } } ] ) ``` ## Sovrascrivere la policy di un singolo strumento Usa l'array `configs` (csharp, go: `Configs`) per sovrascrivere il valore predefinito per singoli strumenti. I valori `name` (csharp, go: `Name`) per il toolset dell'agente sono elencati in [Strumenti disponibili](https://platform.claude.com/docs/it/managed-agents/tools#available-tools). Questo esempio consente per impostazione predefinita l'intero toolset dell'agente, ma richiede una conferma prima dell'esecuzione di qualsiasi comando 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"} } ] } ] ``` Passa questa configurazione `tools` (csharp, go: `Tools`) nella richiesta di creazione dell'agente (la scheda CLI mostra il comando completo). I toolset MCP supportano le stesse sovrascritture per singolo strumento, con `name` (csharp, go: `Name`) impostato sul nome dello strumento riportato dal server MCP. Consulta [Configurare quali strumenti MCP sono disponibili](https://platform.claude.com/docs/it/managed-agents/mcp-connector#configure-which-mcp-tools-are-available). ## Lasciare che il server valuti ogni chiamata con `auto` Con il criterio di autorizzazione `auto`, il server valuta ogni chiamata prima che venga eseguita. Poiché la valutazione considera lo strumento, l'input della chiamata e il contenuto della sessione fino a quel momento, il server può trattare in modo diverso due chiamate allo stesso strumento. Ogni chiamata ha uno di tre esiti: * **La chiamata viene eseguita.** Quando il server determina che la chiamata è sicura, lo strumento viene eseguito come farebbe con `always_allow`. * **La chiamata viene negata.** Quando il server valuta la chiamata come ad alto rischio, lo strumento non viene eseguito. L'agente riceve un risultato dello strumento di errore con il contenuto `Permission to use {tool_name} has been denied.` e `is_error: true`. La sessione continua a essere eseguita e il tuo client non può sovrascrivere il diniego. * **La chiamata si mette in pausa in attesa della tua approvazione.** Quando il server non giunge a una determinazione, la sessione si mette in pausa come fa con `always_ask`. Consulta [Rispondere alle richieste di conferma](https://platform.claude.com/docs/it/managed-agents/permission-policies#respond-to-confirmation-requests). Per attivare `auto`, imposta `permission_policy` su `{"type": "auto"}`. Va negli stessi due punti degli altri criteri: il [`default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`)](https://platform.claude.com/docs/it/managed-agents/permission-policies#set-a-policy-for-a-toolset) di un set di strumenti per l'intero set, oppure una [voce `configs` (csharp, go: `Configs`)](https://platform.claude.com/docs/it/managed-agents/permission-policies#override-an-individual-tool-policy) per un singolo strumento. Sia il set di strumenti dell'agente sia i set di strumenti MCP lo accettano. Nessun set di strumenti usa `auto` per impostazione predefinita. L'esempio seguente imposta `auto` come valore predefinito per il set di strumenti dell'agente e per il set di strumenti MCP `github`, e sovrascrive `bash` con `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"} } } ] ) ``` Ciò che pubblichi negli eventi `user.message` conta come tua intenzione e può portare il server a consentire una chiamata che altrimenti negherebbe. Il server non ricava l'intenzione da un risultato dello strumento, da una pagina web recuperata, dalla risposta di un server MCP o da un messaggio tra [thread di sessione](https://platform.claude.com/docs/it/managed-agents/session-threads#tool-permissions-and-custom-tools). Valuta quel contenuto ma non ne accetta istruzioni. Il server valuta alcune chiamate come ad alto rischio indipendentemente da chi le richiede. Se inoltri input non attendibile dell'utente finale negli eventi `user.message`, il server legge anche quell'input come tua intenzione, e questo può far consentire una chiamata. Configura `always_ask` sugli strumenti che non lasceresti eseguire a quell'utente finale senza revisione. `auto` non è un punto di controllo umano. Se il server determina che una chiamata è sicura, la chiamata viene eseguita prima che qualcuno la veda, e i suoi effetti potrebbero non essere reversibili. Se una persona deve esaminare le chiamate di uno strumento prima che vengano eseguite, configura `always_ask` su quello strumento. ## Vedere come è stata valutata ogni chiamata Con qualsiasi criterio di autorizzazione, ogni evento `agent.tool_use` e `agent.mcp_tool_use` contiene `evaluated_permission`, l'esito del controllo di autorizzazione della chiamata: `"allow"`, `"ask"` o `"deny"`. La maggior parte degli eventi contiene anche un oggetto `evaluation` il cui `type` indica il criterio che ha prodotto quell'esito. Con `auto`, l'oggetto registra anche la determinazione del server, più un `reason_code` quando l'esito è `ask` o `deny`. Ad esempio, quando `bash` è sotto `auto` e il server valuta una chiamata come ad alto rischio, la chiamata negata appare nel flusso di eventi come segue: ```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" } ``` L'oggetto `evaluation` assume una delle forme riportate nella tabella seguente. | `evaluation` | `evaluated_permission` di primo livello | Significato | | ------------------------------------------------------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `{"type": "always_allow"}` | `"allow"` | Il criterio risolto è `always_allow`, quindi la chiamata è stata eseguita. | | `{"type": "always_ask"}` | `"ask"` | Il criterio risolto è `always_ask`, quindi la chiamata si è messa in pausa in attesa della tua approvazione. | | `{"type": "auto", "evaluated_permission": {"type": "allow"}}` | `"allow"` | Con `auto`, il server ha determinato che la chiamata era sicura ed è stata eseguita. | | `{"type": "auto", "evaluated_permission": {"type": "ask", "reason_code": "indeterminate"}}` | `"ask"` | Con `auto`, il server non è giunto a una determinazione, quindi la chiamata si è messa in pausa in attesa della tua approvazione. | | `{"type": "auto", "evaluated_permission": {"type": "deny", "reason_code": "high_risk"}}` | `"deny"` | Con `auto`, il server ha valutato la chiamata come ad alto rischio e l'ha negata. | Quando `evaluation.type` è `"auto"`, il suo `evaluated_permission.type` annidato ripete l'`evaluated_permission` di primo livello dell'evento, quindi puoi leggere l'esito da entrambi i campi. Un `reason_code` è un valore su cui il tuo client può basare le proprie diramazioni logiche e da conservare nei registri di audit, non un testo da mostrare agli utenti finali. `evaluation` è assente in due casi. Quando l'agente indica uno strumento non abilitato nella sessione, il server nega la chiamata senza valutare alcun criterio: l'evento contiene `evaluated_permission: "deny"` e nessun `evaluation`. Anche gli eventi registrati prima dell'introduzione di `evaluation` lo omettono: interpretali come `always_allow` quando `evaluated_permission` è `"allow"` e come `always_ask` quando è `"ask"`. Scrivi il tuo client in modo che tolleri un `evaluation.type` o un `reason_code` che non riconosce. Gli eventi `agent.custom_tool_use` non contengono nessuno dei due campi, perché i criteri di autorizzazione non si applicano agli [strumenti personalizzati](https://platform.claude.com/docs/it/managed-agents/permission-policies#custom-tools). ## Rispondere alle richieste di conferma Una chiamata a uno strumento viene valutata come `ask` con un criterio `always_ask`, oppure con `auto` quando il server non giunge a una determinazione. Quando ciò accade: 1. La sessione emette un evento `agent.tool_use` o `agent.mcp_tool_use`. 2. La sessione si mette in pausa con un evento `session.status_idle` il cui `stop_reason.type` è `requires_action`. Gli ID degli eventi bloccanti si trovano nell'array `stop_reason.event_ids`. La sessione attende una risposta a tempo indeterminato. Una chiamata proveniente da un thread di un'[esecuzione di workflow](https://platform.claude.com/docs/it/managed-agents/workflow-runs#while-a-run-is-open) raggiunge il tuo client sullo stream principale. Mentre qualcos'altro nella sessione è in lavorazione, la sessione può rimanere `running` e non inviare alcun `session.status_idle`, quindi rispondi direttamente all'evento di uso dello strumento. La chiamata attende solo finché l'esecuzione non ha terminato con quel thread o l'esecuzione non termina. Un'interruzione potrebbe lasciarla in attesa, quindi consentila o negala tu stesso. 3. Invia un evento `user.tool_confirmation` per ogni evento bloccante, passando l'ID dell'evento nel parametro `tool_use_id` (java: `toolUseId`; php: `toolUseID`; csharp, go: `ToolUseID`). Imposta `result` (csharp, go: `Result`) su `"allow"` o `"deny"`. Usa `deny_message` (java, php: `denyMessage`; csharp, go: `DenyMessage`) per spiegare un diniego. Puoi inviare più conferme in una singola richiesta `events`. 4. Una volta risolti tutti gli eventi bloccanti, la sessione torna allo stato `running`. Gli strumenti consentiti vengono eseguiti. Gli strumenti negati non vengono eseguiti e l'agente riceve un risultato dello strumento che indica che la chiamata è stata rifiutata, incluso il tuo `deny_message` (java, php: `denyMessage`; csharp, go: `DenyMessage`). Ad esempio, una chiamata `bash` messa in pausa con un criterio `always_ask` appare nel flusso come segue: ```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" } ``` Se invii un `user.tool_confirmation` per un evento il cui `evaluated_permission` (java, php: `evaluatedPermission`; csharp, go: `EvaluatedPermission`) non è `ask`, l'API lo rifiuta con un errore 400. Ciò include le chiamate che il server ha negato con `auto`: il tuo client non può sovrascriverle. Per rispondere invece in modo interattivo, usa `ant beta:sessions connect`, che mostra la chiamata in attesa e invia questo evento quando la consenti o la neghi. Consulta [Connettersi a una sessione Managed Agents dal terminale](https://platform.claude.com/docs/it/cli-sdks-libraries/cli/sessions-connect#follow-and-steer-the-session). Negli esempi seguenti, gli ID degli eventi di uso degli strumenti provengono dall'array `stop_reason.event_ids` dell'evento `session.status_idle`. Scopri di più sulla ricezione degli eventi nella guida [Stream di eventi della sessione](https://platform.claude.com/docs/it/managed-agents/events-and-streaming#stream-events), oppure [iscriviti ai webhook](https://platform.claude.com/docs/it/managed-agents/webhooks) per ricevere una notifica quando una sessione si mette in pausa in attesa di input. ```bash cURL # Consenti l'esecuzione dello strumento 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" } ] }' # Oppure negala con una spiegazione 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 # Consenti l'esecuzione dello strumento ant beta:sessions:events send \ --session-id "$SESSION_ID" \ --event "{type: user.tool_confirmation, tool_use_id: $AGENT_TOOL_USE_EVENT_ID, result: allow}" # Oppure negala con una spiegazione 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 # Consenti l'esecuzione dello strumento client.beta.sessions.events.send( session.id, events=[ { "type": "user.tool_confirmation", "tool_use_id": agent_tool_use_event.id, "result": "allow", }, ], ) # Oppure negala con una spiegazione 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 // Consenti l'esecuzione dello strumento await client.beta.sessions.events.send(session.id, { events: [ { type: "user.tool_confirmation", tool_use_id: agent_tool_use_event.id, result: "allow" } ] }); // Oppure negala con una spiegazione 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# // Consenti l'esecuzione dello strumento await client.Beta.Sessions.Events.Send(session.ID, new() { Events = [ new BetaManagedAgentsUserToolConfirmationEventParams { Type = BetaManagedAgentsUserToolConfirmationEventParamsType.UserToolConfirmation, ToolUseID = agentToolUseEvent.ID, Result = "allow", }, ], }); // Oppure negala con una spiegazione 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 // Consenti l'esecuzione dello strumento _, 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) } // Oppure negala con una spiegazione _, 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 // Consenti l'esecuzione dello strumento 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() ); // Oppure negala con una spiegazione 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; // Consenti l'esecuzione dello strumento $client->beta->sessions->events->send( $session->id, events: [ ManagedAgentsUserToolConfirmationEventParams::with( type: 'user.tool_confirmation', toolUseID: $agentToolUseEvent->id, result: 'allow', ), ], ); // Oppure negala con una spiegazione $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 # Consenti l'esecuzione dello strumento client.beta.sessions.events.send_( session.id, events: [ { type: "user.tool_confirmation", tool_use_id: agent_tool_use_event.id, result: "allow" } ] ) # Oppure negala con una spiegazione 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." } ] ) ``` ## Strumenti personalizzati Le policy di autorizzazione non si applicano agli strumenti personalizzati. Quando l'agente invoca uno strumento personalizzato, la tua applicazione riceve un evento `agent.custom_tool_use` ed è responsabile di decidere se eseguirlo prima di inviare un `user.custom_tool_result`. Consulta [Stream di eventi della sessione](https://platform.claude.com/docs/it/managed-agents/events-and-streaming#answer-tool-calls-that-pause-the-session) per il flusso completo. ## Prossimi passi Collega competenze riutilizzabili basate sul filesystem al tuo agente per flussi di lavoro specifici del dominio. Invia eventi, esegui lo streaming delle risposte e interrompi o reindirizza la tua sessione durante l'esecuzione.