Strumenti

Claude Managed Agents fornisce un insieme di strumenti integrati che Claude può usare autonomamente all'interno di una sessione. 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.

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.

Quando l'output di uno strumento supera i 100.000 caratteri (circa 25.000 token), viene automaticamente scritto in un file nella sandbox. 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 per disabilitare strumenti specifici o sovrascriverne le impostazioni. Ogni voce è identificata dal suo name, che assume un valore dalla colonna Nome in Strumenti disponibili. Una voce accetta anche un campo opzionale type con lo stesso valore.

Ogni voce di configurazione può anche impostare una permission_policy. La policy controlla se le chiamate dello strumento vengono eseguite senza conferma, richiedono conferma o vengono valutate singolarmente dal server. Consulta Policy di autorizzazione per i tipi di policy disponibili.

L'esempio seguente abilita il toolset e disabilita web_fetch:

ant apply agent.md

---
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:

{
  "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:

{
  "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.

Tipi delle voci di configurazione negli SDK

Gli SDK Python, TypeScript, Go, Java, C#, Ruby e PHP tipizzano ogni voce di configs per strumento. Il tipo è un'unione con un membro per ciascuno strumento integrato, discriminata da 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 è l'unione stessa, quindi costruisci ogni voce a partire dal tipo del membro corrispondente allo strumento.

Puoi omettere type quando costruisci una voce, perché il server lo deduce da 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 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:

ant apply agent.md

---
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 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), su un agente nell'elenco predefined_agents di subagents, oppure su un agente nell'elenco predefined_agents di 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.

Per le sessioni eseguite in una sandbox self-hosted, il worker dell'ambiente può servire strumenti personalizzati dalla sandbox. 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