Strumenti

Claude Managed Agents fornisce un insieme di strumenti integrati che Claude può utilizzare autonomamente all'interno di una sessione. Puoi controllare 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 utilizza per continuare l'attività. Per fornire all'agente strumenti da un server MCP, usa invece il connettore MCP.



Strumenti disponibili

Il set di strumenti dell'agente include i seguenti strumenti. Tutti sono abilitati per impostazione predefinita quando includi il set di strumenti nella configurazione dell'agente. Usa i valori nella colonna Nome per fare riferimento agli strumenti nell'array configs.

Quando l'output di uno strumento supera i 100.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 set di strumenti

Abilita il set di strumenti completo con agent_toolset_20260401 quando crei un agente. Usa l'array configs per disabilitare strumenti specifici o sovrascrivere le loro impostazioni. Ogni voce di configurazione può anche impostare una permission_policy che controlla se le chiamate dello strumento vengono approvate automaticamente o richiedono conferma. Consulta Policy di autorizzazione per i tipi di policy disponibili.

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-4-8
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_fetch
        enabled: false
YAML



Disabilitare strumenti specifici

Per disabilitare uno strumento, imposta enabled: false nella sua voce di configurazione nell'oggetto del set di strumenti dell'array tools del tuo agente:

{
  "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 configurazione di base per ogni strumento nel set, e le voci configs per singolo strumento la sovrascrivono. Per iniziare con tutto disattivato e abilitare solo ciò di cui hai bisogno, 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 }
  ]
}



Strumenti personalizzati

Oltre agli strumenti integrati, puoi definire strumenti personalizzati. Gli strumenti personalizzati sono analoghi agli strumenti client definiti dall'utente nella Messages API.

Ogni strumento personalizzato definisce un contratto: specifichi quali operazioni sono disponibili e cosa restituiscono, e Claude determina quando e come chiamarle. Il modello non esegue mai nulla da solo. Emette una richiesta strutturata, il tuo codice esegue l'operazione e il risultato rifluisce nella conversazione. Consulta Flusso di eventi della sessione per sapere come ricevere le chiamate agli strumenti personalizzati e restituire i risultati durante una sessione.

ant beta:agents create <<'YAML'
name: Weather Agent
model: claude-opus-4-8
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
YAML

Una volta definiti gli strumenti personalizzati sull'agente, l'agente li invoca durante una sessione.



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. Le tue descrizioni dovrebbero spiegare cosa fa lo strumento e quando usarlo (e quando non usarlo). Spiega cosa significa ogni parametro e come influisce sul comportamento dello strumento. Segnala eventuali avvertenze o limitazioni importanti. Più contesto puoi fornire a Claude sui tuoi strumenti, migliore sarà la sua capacità di determinare quando e come usarli. Punta a tre o quattro frasi per ogni descrizione di strumento, di più se lo strumento è complesso.
• Consolida le operazioni correlate in meno strumenti. Invece di creare uno strumento separato per ogni azione (create_pr, review_pr, merge_pr), raggruppale in un unico strumento con un parametro action. Meno strumenti, ma più capaci, riducono l'ambiguità nella selezione e rendono la superficie degli strumenti più facile da navigare per Claude.
• Usa un namespacing significativo nei nomi degli strumenti. Quando i tuoi strumenti coprono più servizi o risorse, aggiungi un prefisso ai nomi con 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, e 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