Strumenti

Claude Managed Agents fornisce un set di strumenti integrati che Claude può utilizzare autonomamente all'interno di una sessione. Controlli quali strumenti sono disponibili specificandoli nella configurazione dell'agente.

Sono supportati anche strumenti personalizzati definiti dall'utente. La tua applicazione esegue questi strumenti separatamente e invia i risultati dello strumento di nuovo a Claude; Claude può utilizzare i risultati per continuare l'attività in corso.

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.

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.

Disabilitazione di strumenti specifici

Per disabilitare uno strumento, imposta enabled: false nella sua voce di configurazione:

{
  "type": "agent_toolset_20260401",
  "configs": [
    { "name": "web_fetch", "enabled": false },
    { "name": "web_search", "enabled": false }
  ]
}

Abilitazione solo di strumenti specifici

Per iniziare con tutto disabilitato 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 ai strumenti client definiti dall'utente nell'API Messages.

Gli strumenti personalizzati ti permettono di estendere le capacità di Claude per eseguire una varietà più ampia di attività. Ogni strumento definisce un contratto: specifichi quali operazioni sono disponibili e cosa restituiscono; Claude decide quando e come chiamarli. Il modello non esegue mai nulla da solo. Emette una richiesta strutturata, il tuo codice esegue l'operazione e il risultato ritorna nella conversazione.

Una volta definito lo strumento a livello di agente, l'agente invocherà gli strumenti nel corso di una sessione. Vedi Flusso di eventi della sessione per il flusso completo.

Best practice per le definizioni di strumenti personalizzati

• Fornisci descrizioni estremamente dettagliate. Questo è di gran lunga il fattore più importante per le prestazioni dello strumento. Le tue descrizioni dovrebbero spiegare cosa fa lo strumento, quando dovrebbe essere utilizzato (e quando non dovrebbe), cosa significa ogni parametro e come influisce sul comportamento dello strumento, e eventuali avvertenze o limitazioni importanti. Più contesto puoi dare a Claude sui tuoi strumenti, meglio sarà nel decidere quando e come utilizzarli. Mira a almeno 3-4 frasi per descrizione dello strumento, di più se lo strumento è complesso.
• Consolida operazioni correlate in meno strumenti. Piuttosto che creare uno strumento separato per ogni azione (create_pr, review_pr, merge_pr), raggruppali in un singolo strumento con un parametro action. Meno strumenti, più capaci, riducono l'ambiguità di selezione e rendono la tua superficie di strumenti più facile da navigare per Claude.
• Usa spazi dei nomi significativi nei nomi degli strumenti. Quando i tuoi strumenti si estendono su più servizi o risorse, prefissa i nomi con la risorsa (ad es., db_query, storage_read). Questo rende la selezione dello strumento inequivocabile man mano che la tua libreria cresce.
• Progetta le risposte degli strumenti per restituire solo informazioni ad alto segnale. Restituisci identificatori semantici e stabili (ad es., slug o UUID) piuttosto che riferimenti interni opachi, e includi solo i campi di cui Claude ha bisogno per ragionare sul suo prossimo passo. Le risposte gonfie sprecano contesto e rendono più difficile per Claude estrarre ciò che conta.