--- title: Strumenti url: https://platform.claude.com/docs/it/managed-agents/tools description: Configura gli strumenti disponibili per il tuo agente. featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- Claude Managed Agents fornisce un insieme di strumenti integrati che Claude può usare autonomamente all'interno di una [sessione](https://platform.claude.com/docs/it/managed-agents/sessions). Controlli quali strumenti sono disponibili specificandoli nella configurazione dell'agente. Claude Managed Agents supporta anche strumenti personalizzati definiti dall'utente. La tua applicazione esegue questi strumenti separatamente e restituisce i risultati a Claude, che li usa per proseguire l'attività. Per fornire all'agente strumenti da un server MCP, usa invece il [connettore MCP](https://platform.claude.com/docs/it/managed-agents/mcp-connector). ## Strumenti disponibili Il "toolset" (insieme di strumenti) dell'agente include i seguenti strumenti. Sono tutti abilitati per impostazione predefinita quando includi il toolset nella configurazione dell'agente. | Strumento | Nome | Descrizione | | ---------- | ------------ | ------------------------------------------------------------ | | Bash | `bash` | Esegue comandi bash in una sessione shell | | Read | `read` | Legge un file dal filesystem della sandbox | | Write | `write` | Scrive un file nel filesystem della sandbox | | Edit | `edit` | Esegue la sostituzione di stringhe in un file | | Glob | `glob` | Corrispondenza rapida di pattern di file usando pattern glob | | Grep | `grep` | Ricerca di testo usando pattern regex | | Web fetch | `web_fetch` | Recupera contenuti da un URL | | Web search | `web_search` | Cerca informazioni sul web | Quando l'output di uno strumento supera i 100.000 caratteri (circa 25.000 token), viene automaticamente scritto in un file nella [sandbox](https://platform.claude.com/docs/it/managed-agents/environments). Il modello riceve un'anteprima troncata con il percorso del file e può leggere il contenuto completo da lì. ## Configurazione del toolset Abilita il toolset completo con `agent_toolset_20260401` quando crei un agente. Usa l'array `configs` (csharp, go: `Configs`) per disabilitare strumenti specifici o sovrascriverne le impostazioni. Ogni voce è identificata dal suo `name` (csharp, go: `Name`), che assume un valore dalla colonna Nome in [Strumenti disponibili](https://platform.claude.com/docs/it/managed-agents/tools#available-tools). Una voce accetta anche un campo opzionale `type` (csharp, go: `Type`) con lo stesso valore. Ogni voce di configurazione può anche impostare una `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`). La policy controlla se le chiamate dello strumento vengono eseguite senza conferma, richiedono conferma o vengono valutate singolarmente dal server. Consulta [Policy di autorizzazione](https://platform.claude.com/docs/it/managed-agents/permission-policies) per i tipi di policy disponibili. L'esempio seguente abilita il toolset e disabilita `web_fetch`: ```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", "configs": [ {"name": "web_fetch", "enabled": false} ] } ] }' ) ``` ```bash CLI ant apply agent.md ``` ```markdown --- name: Coding Assistant model: claude-opus-5-5 tools: - type: agent_toolset_20260401 configs: - name: web_fetch enabled: false --- ``` ```python Python agent = client.beta.agents.create( name="Coding Assistant", model="claude-opus-5-5", tools=[ { "type": "agent_toolset_20260401", "configs": [ {"name": "web_fetch", "enabled": False}, ], }, ], ) ``` ```typescript TypeScript const agent = await client.beta.agents.create({ name: "Coding Assistant", model: "claude-opus-5-5", tools: [ { type: "agent_toolset_20260401", configs: [{ name: "web_fetch", enabled: false }] } ] }); ``` ```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 = "agent_toolset_20260401", Configs = [ new BetaManagedAgentsWebFetchToolConfigParams { Enabled = false }, ], }, ], }); ``` ```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, Configs: []anthropic.BetaManagedAgentsAgentToolConfigParamsUnion{{ OfWebFetch: &anthropic.BetaManagedAgentsWebFetchToolConfigParams{ Enabled: anthropic.Bool(false), }, }}, }, }}, }) 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) .addConfig(BetaManagedAgentsWebFetchToolConfigParams.builder() .enabled(false) .build()) .build()) .build()); ``` ```php PHP use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params; use Anthropic\Beta\Agents\BetaManagedAgentsWebFetchToolConfigParams; $agent = $client->beta->agents->create( name: 'Coding Assistant', model: 'claude-opus-5-5', tools: [ BetaManagedAgentsAgentToolset20260401Params::with( type: 'agent_toolset_20260401', configs: [ BetaManagedAgentsWebFetchToolConfigParams::with(enabled: false), ], ), ], ); ``` ```ruby Ruby agent = client.beta.agents.create( name: "Coding Assistant", model: "claude-opus-5-5", tools: [ { type: :agent_toolset_20260401, configs: [ {name: :web_fetch, enabled: false} ] } ] ) ``` ### Disabilitare strumenti specifici Per disabilitare uno strumento, imposta `enabled: false` nella sua voce `configs`: ```json { "type": "agent_toolset_20260401", "configs": [ { "name": "web_fetch", "enabled": false }, { "name": "web_search", "enabled": false } ] } ``` ### Abilitare solo strumenti specifici L'oggetto `default_config` imposta la base per ogni strumento dell'insieme, e le voci `configs` per singolo strumento la sovrascrivono. Per partire con tutto disattivato e abilitare solo ciò che ti serve, imposta `default_config.enabled` su `false`: ```json { "type": "agent_toolset_20260401", "default_config": { "enabled": false }, "configs": [ { "name": "bash", "enabled": true }, { "name": "read", "enabled": true }, { "name": "write", "enabled": true } ] } ``` ### Limitare web search e web fetch Le voci `web_search` e `web_fetch` accettano anche elenchi di domini, un limite sui contenuti recuperati e una località di ricerca. Consulta [Limitare i domini di web search e web fetch](https://platform.claude.com/docs/it/managed-agents/tools-web-restrictions). ### Tipi delle voci di configurazione negli SDK Gli SDK Python, TypeScript, Go, Java, C#, Ruby e PHP tipizzano ogni voce di `configs` (csharp, go: `Configs`) per strumento. Il tipo è un'unione con un membro per ciascuno strumento integrato, discriminata da `type` (csharp, go: `Type`). In Go, Java, C# e PHP, costruisci le voci a partire da valori tipizzati anziché da semplici dizionari o hash. In questi SDK, il tipo degli elementi di `configs` (csharp, go: `Configs`) è l'unione stessa, quindi costruisci ogni voce a partire dal tipo del membro corrispondente allo strumento. Puoi omettere `type` (csharp, go: `Type`) quando costruisci una voce, perché il server lo deduce da `name` (csharp, go: `Name`). Le risposte lo includono sempre. Questa tipizzazione non modifica il JSON in cui una voce viene serializzata. Una richiesta le cui voci impostano solo `name`, `enabled` e `permission_policy` è valida con o senza `type`. ## Strumenti personalizzati Gli strumenti personalizzati sono analoghi agli [strumenti client definiti dall'utente](https://platform.claude.com/docs/it/agents-and-tools/tool-use/how-tool-use-works#user-defined-tools-client-executed) nella Messages API. Specifichi quali operazioni sono disponibili e cosa restituiscono, e Claude determina quando e come chiamarle. Claude non esegue direttamente uno strumento personalizzato. Emette una richiesta strutturata, il tuo codice esegue l'operazione e tu restituisci il risultato alla sessione. L'esempio seguente crea un agente con il toolset integrato e uno strumento personalizzato, `get_weather`: ```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": "Weather Agent", "model": "claude-opus-5-5", "tools": [ { "type": "agent_toolset_20260401" }, { "type": "custom", "name": "get_weather", "description": "Get current weather for a location", "input_schema": { "type": "object", "properties": { "location": {"type": "string", "description": "City name"} }, "required": ["location"] } } ] }' ) ``` ```bash CLI ant apply agent.md ``` ```markdown --- name: Weather Agent model: claude-opus-5-5 tools: - type: agent_toolset_20260401 - type: custom name: get_weather description: Get current weather for a location input_schema: type: object properties: location: type: string description: City name required: - location --- ``` ```python Python agent = client.beta.agents.create( name="Weather Agent", model="claude-opus-5-5", tools=[ { "type": "agent_toolset_20260401", }, { "type": "custom", "name": "get_weather", "description": "Get current weather for a location", "input_schema": { "type": "object", "properties": { "location": {"type": "string", "description": "City name"}, }, "required": ["location"], }, }, ], ) ``` ```typescript TypeScript const agent = await client.beta.agents.create({ name: "Weather Agent", model: "claude-opus-5-5", tools: [ { type: "agent_toolset_20260401" }, { type: "custom", name: "get_weather", description: "Get current weather for a location", input_schema: { type: "object", properties: { location: { type: "string", description: "City name" } }, required: ["location"] } } ] }); ``` ```csharp C# using System.Text.Json; using Anthropic.Models.Beta.Agents; var agent = await client.Beta.Agents.Create(new() { Name = "Weather Agent", Model = BetaManagedAgentsModel.ClaudeOpus5_5, Tools = [ new BetaManagedAgentsAgentToolset20260401Params { Type = "agent_toolset_20260401", }, new BetaManagedAgentsCustomToolParams { Type = "custom", Name = "get_weather", Description = "Get current weather for a location", InputSchema = new() { Properties = new Dictionary { ["location"] = JsonSerializer.SerializeToElement( new { type = "string", description = "City name" } ), }, Required = ["location"], }, }, ], }); ``` ```go Go agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ Name: "Weather Agent", Model: anthropic.BetaManagedAgentsModelConfigParams{ ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5, }, Tools: []anthropic.BetaAgentNewParamsToolUnion{{ OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{ Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401, }, }, { OfCustom: &anthropic.BetaManagedAgentsCustomToolParams{ Type: anthropic.BetaManagedAgentsCustomToolParamsTypeCustom, Name: "get_weather", Description: "Get current weather for a location", InputSchema: anthropic.BetaManagedAgentsCustomToolInputSchemaParam{ Properties: map[string]any{ "location": map[string]any{ "type": "string", "description": "City name", }, }, Required: []string{"location"}, }, }, }}, }) if err != nil { panic(err) } _ = agent ``` ```java Java import com.anthropic.models.beta.agents.*; import java.util.Map; var agent = client.beta().agents().create(AgentCreateParams.builder() .name("Weather Agent") .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5) .addTool(BetaManagedAgentsAgentToolset20260401Params.builder() .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) .build()) .addTool(BetaManagedAgentsCustomToolParams.builder() .type(BetaManagedAgentsCustomToolParams.Type.CUSTOM) .name("get_weather") .description("Get current weather for a location") .inputSchema(BetaManagedAgentsCustomToolInputSchema.builder() .properties(BetaManagedAgentsCustomToolInputSchema.Properties.builder() .putAdditionalProperty("location", JsonValue.from(Map.of( "type", "string", "description", "City name"))) .build()) .addRequired("location") .build()) .build()) .build()); ``` ```php PHP use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params; use Anthropic\Beta\Agents\BetaManagedAgentsCustomToolInputSchema; use Anthropic\Beta\Agents\BetaManagedAgentsCustomToolParams; $agent = $client->beta->agents->create( name: 'Weather Agent', model: 'claude-opus-5-5', tools: [ BetaManagedAgentsAgentToolset20260401Params::with( type: 'agent_toolset_20260401', ), BetaManagedAgentsCustomToolParams::with( type: 'custom', name: 'get_weather', description: 'Get current weather for a location', inputSchema: BetaManagedAgentsCustomToolInputSchema::with( properties: ['location' => ['type' => 'string', 'description' => 'City name']], required: ['location'], ), ), ], ); ``` ```ruby Ruby agent = client.beta.agents.create( name: "Weather Agent", model: "claude-opus-5-5", tools: [ {type: :agent_toolset_20260401}, { type: :custom, name: "get_weather", description: "Get current weather for a location", input_schema: { type: :object, properties: {location: {type: "string", description: "City name"}}, required: ["location"] } } ] ) ``` Il nome di uno strumento personalizzato non può iniziare con `mcp__` o `ant__`, né corrispondere al nome di uno strumento integrato dell'agente. Una richiesta che viola questa regola restituisce un errore 400. Un agente che ha già uno strumento personalizzato il cui nome inizia con `ant__` accetta un aggiornamento solo se l'aggiornamento invia `tools` (csharp, go: `Tools`) senza quel nome, quindi rinomina o rimuovi lo strumento nel tuo prossimo aggiornamento. Una nuova sessione viene rifiutata con un errore 400 se tale strumento si trova sul suo agente (dopo eventuali [sovrascritture](https://platform.claude.com/docs/it/managed-agents/sessions#override-agent-configuration-for-a-session)), su un agente nell'elenco `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) di `subagents` (csharp, go: `Subagents`), oppure su un agente nell'elenco `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) di `workflows` (csharp, go: `Workflows`). Le sessioni già esistenti non sono interessate. L'agente chiama i suoi strumenti personalizzati durante una sessione. Per ricevere le chiamate e restituire i risultati, consulta [Flusso di eventi della sessione](https://platform.claude.com/docs/it/managed-agents/events-and-streaming#handling-custom-tool-calls). Per le sessioni eseguite in una sandbox self-hosted, il worker dell'ambiente può [servire strumenti personalizzati dalla sandbox](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-custom-tools). Questi possono includere strumenti che incapsulano un server MCP all'interno della tua rete. ### Best practice per le definizioni degli strumenti personalizzati * **Fornisci descrizioni estremamente dettagliate.** Questo è di gran lunga il fattore più importante per le prestazioni degli strumenti. Più contesto riesci a dare a Claude sui tuoi strumenti, meglio riuscirà a determinare quando e come usarli. Punta a tre o quattro frasi per ogni descrizione di strumento, di più se lo strumento è complesso. Le tue descrizioni dovrebbero coprire: * Cosa fa lo strumento * Quando usarlo e quando non usarlo * Cosa significa ciascun parametro e come influisce sul comportamento dello strumento * Eventuali avvertenze o limitazioni importanti * **Consolida le operazioni correlate in un numero minore di strumenti.** Raggruppa azioni come `create_pr`, `review_pr` e `merge_pr` in un unico strumento con un parametro `action`. Strumenti meno numerosi ma più capaci riducono l'ambiguità nella selezione e rendono l'insieme dei tuoi strumenti più facile da navigare per Claude. * **Usa namespace significativi nei nomi degli strumenti.** Quando i tuoi strumenti coprono più servizi o risorse, anteponi ai nomi la risorsa (ad esempio, `db_query` o `storage_read`). Questo rende la selezione degli strumenti non ambigua man mano che la tua libreria cresce. * **Progetta le risposte degli strumenti in modo che restituiscano solo informazioni ad alto valore.** Restituisci identificatori semantici e stabili (ad esempio, slug o UUID) anziché riferimenti interni opachi. Includi solo i campi di cui Claude ha bisogno per determinare il passo successivo. Risposte sovraccariche sprecano contesto e rendono più difficile per Claude estrarre ciò che conta. ## Passaggi successivi Controlla quali siti possono raggiungere gli strumenti web, limita i contenuti recuperati e localizza i risultati di ricerca. Collega server MCP ai tuoi agenti per accedere a strumenti e fonti di dati esterni. Controlla quando vengono eseguiti gli strumenti dell'agente e MCP. Invia eventi, ricevi le risposte in streaming e interrompi o reindirizza la sessione durante l'esecuzione.