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. Ogni voce nell'array configs è identificata dal suo name, utilizzando i valori nella colonna Nome, e accetta un campo opzionale type con lo stesso valore. Le voci web_search e web_fetch accettano impostazioni aggiuntive; consulta Limitare i domini di ricerca web e recupero web.

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 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 Criteri di autorizzazione per i tipi di criteri disponibili.

Le voci di configurazione per web_search e web_fetch accettano anche filtri di dominio e altre impostazioni web; consulta Limitare i domini di ricerca web e recupero web.

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-5
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 baseline 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 }
  ]
}



Limitare i domini di ricerca web e recupero web

Per controllare quali siti possono essere raggiunti dagli strumenti web dell'agente, imposta allowed_domains (lo strumento può raggiungere solo questi host) o blocked_domains (lo strumento non può mai raggiungere questi host) sulle voci web_search e web_fetch dell'array configs del set di strumenti. Ogni strumento ha il proprio elenco, quindi web_search e web_fetch possono avere restrizioni diverse. Un dominio elencato copre quell'host e tutti i suoi sottodomini. In fase di esecuzione, una chiamata web_fetch per un URL che i suoi elenchi non consentono restituisce un risultato di errore all'agente (is_error: true sull'evento agent.tool_result, con contenuto che indica il codice di errore url_not_allowed), e web_search omette i risultati che i suoi elenchi non consentono.

Il seguente set di strumenti limita web_search a due siti e localizza i suoi risultati, e blocca un host per web_fetch limitando al contempo la quantità di contenuto recuperato che entra nel contesto:

{
  "type": "agent_toolset_20260401",
  "configs": [
    {
      "type": "web_search",
      "name": "web_search",
      "allowed_domains": ["docs.example.com", "arxiv.org"],
      "user_location": {
        "type": "approximate",
        "country": "US",
        "timezone": "America/Los_Angeles"
      }
    },
    {
      "type": "web_fetch",
      "name": "web_fetch",
      "blocked_domains": ["ads.example.com"],
      "max_content_tokens": 50000
    }
  ]
}

La seguente richiesta crea un agente con questo set di strumenti e stampa l'array configs dalla risposta:

ant beta:agents create --transform tools.0.configs <<'YAML'
name: Research Agent
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
    configs:
      - type: web_search
        name: web_search
        allowed_domains: [docs.example.com, arxiv.org]
        user_location:
          type: approximate
          country: US
          timezone: America/Los_Angeles
      - type: web_fetch
        name: web_fetch
        blocked_domains: [ads.example.com]
        max_content_tokens: 50000
YAML

Nella Claude Console, imposta i domini consentiti o bloccati dalle righe web_search e web_fetch della scheda Built-in tools nel modulo dell'agente; imposta max_content_tokens e user_location nella vista Raw della configurazione dell'agente.

Oltre a enabled e permission_policy, le voci degli strumenti web accettano le seguenti impostazioni:



Regole per gli elenchi di domini

• Imposta allowed_domains oppure blocked_domains su una voce, non entrambi. Una voce che imposta entrambi viene rifiutata.
• Ogni elenco contiene da 1 a 64 domini, ciascuno da 1 a 255 caratteri. Un elenco vuoto viene rifiutato: per non applicare alcuna restrizione, ometti il campo o invia null.
• Ogni dominio è un nome di dominio registrabile, o un suo sottodominio, scritto come hostname semplice: lettere ASCII, cifre, trattini, underscore e punti, senza schema, porta, credenziali, wildcard o spazi, senza etichette che iniziano o terminano con un trattino, e senza percorso diverso dal suffisso di percorso opzionale per web_search descritto più avanti in questo elenco. Usa example.com, non https://example.com, example.com:443 o *.example.com. Gli hostname vengono confrontati senza distinzione tra maiuscole e minuscole, e un singolo / finale viene ignorato.
• Un dominio elencato corrisponde a quell'host e ai suoi sottodomini: example.com copre docs.example.com, ma docs.example.com non copre example.com o api.example.com. Un www. iniziale è un sottodominio come qualsiasi altro, quindi www.example.com non copre example.com; elenca il dominio semplice per coprire entrambi.
• Gli indirizzi IP non sono accettati in nessuna forma, che si tratti di IPv4, IPv6, tra parentesi quadre o in notazione numerica abbreviata come 127.1. Elenca invece il nome di dominio del sito.
• Un dominio di primo livello semplice o un suffisso di registro come com, co.uk o gov.uk viene rifiutato, così come un nome a etichetta singola come intranet. Elenca un dominio completo come example.co.uk.
• localhost e gli host che terminano in .localhost, .local, .internal, .localdomain o .invalid vengono rifiutati.
• Usa la forma xn-- (Punycode) per i nomi di dominio internazionalizzati; un dominio che contiene caratteri non ASCII viene rifiutato.
• Un dominio web_fetch non può includere un percorso: usa example.com, non example.com/*. Un dominio web_search può includere un suffisso di percorso come example.com/blog, in cui il percorso non può contenere spazi, ?, # o nessuno dei caratteri $ , | ^ !. Preferisci hostname semplici anche per web_search, perché il provider di ricerca confronta i suffissi di percorso come pattern URL anziché come regole di host rigorose.
• I domini duplicati all'interno di un elenco vengono rifiutati. www.example.com e example.com contano come domini diversi; consulta la regola di corrispondenza precedente per sapere cosa copre ciascuno.



Quando vengono validate le impostazioni

Le violazioni di formato e di limite vengono rifiutate con un errore 400 invalid_request_error quando crei un agente o aggiorni un agente, e quando crei o aggiorni una sessione che fornisce tools. Ad esempio, il messaggio per una voce che imposta entrambi gli elenchi include Only one of allowed_domains or blocked_domains may be set., e il messaggio per un elenco vuoto include allowed_domains: Empty list of domains is ambiguous. Provide at least one domain or null. Il messaggio per un dominio che viola una regola di formato indica il suo elenco e la posizione a base zero, ad esempio allowed_domains.0: IP addresses are not supported; provide a plain hostname like "example.com".

Le stesse richieste rifiutano anche tre impostazioni che dipendono dai provider di ricerca e recupero: un dominio in allowed_domains a cui il crawler di Anthropic non è autorizzato ad accedere, un user_location.country che il provider di ricerca non supporta (il messaggio termina con user_location.country: not a country the search provider supports), e un user_location.timezone che non è un nome IANA valido. La sessione verifica nuovamente la configurazione quando inizializza lo strumento per la prima volta; se un'impostazione che era stata accettata in precedenza non è più valida in quel momento, la sessione emette un evento session.error e torna allo stato idle senza riprovare. Correggi l'impostazione aggiornando gli strumenti della sessione, aggiorna anche l'agente in modo che le nuove sessioni inizino con la configurazione corretta, quindi invia un nuovo user.message per continuare.



Sessioni multiagente, outcome e aggiornamenti durante la sessione

In una sessione multiagente, ogni elenco di domini che si applica a un thread viene applicato contemporaneamente: un agente nel roster del coordinatore è vincolato dai propri allowed_domains e blocked_domains, da quelli di qualsiasi agente che lo ha chiamato e dagli elenchi correnti del coordinatore.

• Le allowlist si combinano nei domini che tutte coprono, e le blocklist si sommano, quindi un agente del roster può restringere ciò che uno strumento raggiunge ma mai ampliarlo. Ad esempio, un agente del roster che imposta blocked_domains mantiene gli allowed_domains del coordinatore e blocca quegli host al suo interno, e un agente del roster che imposta i propri allowed_domains può raggiungere solo gli host che sia il suo elenco sia quello del coordinatore coprono.
• Se le allowlist combinate non hanno alcun dominio in comune, lo strumento rimane disponibile per quell'agente ma ogni chiamata fallisce con un errore url_not_allowed che indica che nessun dominio è consentito, e la descrizione dello strumento lo comunica al modello. Mantieni l'allowlist di ogni agente del roster all'interno di quella del coordinatore per evitare questo.
• max_content_tokens e user_location non vengono combinati: un thread utilizza il valore dalla propria configurazione dello strumento se impostato, altrimenti dall'agente che lo ha chiamato, altrimenti dalla configurazione corrente del coordinatore.
• Una voce del roster {"type": "self"} non ha impostazioni web proprie e segue le impostazioni correnti del coordinatore.
• Il grader nelle sessioni basate su outcome viene eseguito senza web_search e web_fetch, indipendentemente da queste impostazioni.
• Puoi modificare gli elenchi su una sessione inattiva aggiornando i suoi strumenti. I nuovi elenchi si applicano al resto della sessione; in una sessione multiagente, ogni thread li applica dal suo turno successivo, mentre gli elenchi propri di un agente del roster rimangono come li ha impostati la sua definizione di agente quando la sessione è stata creata.



Differenze rispetto agli strumenti della Messages API

Queste impostazioni utilizzano lo stesso vocabolario allowed_domains e blocked_domains del filtraggio dei domini sugli strumenti server della Messages API, con le seguenti differenze su Managed Agents:

• Ogni elenco è limitato a 64 domini.
• I domini elencati per web_fetch non possono includere un percorso.
• max_uses, citations e cache_control non sono disponibili sul set di strumenti.



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 rientra nella conversazione. Consulta Flusso di eventi della sessione per sapere come ricevere le chiamate agli strumenti personalizzati e restituire i risultati durante una sessione.

Se le tue sessioni vengono eseguite in una sandbox self-hosted, il worker dell'ambiente può servire strumenti personalizzati dalla tua sandbox, inclusi strumenti che incapsulano un server MCP all'interno della tua rete.

ant beta:agents create < agent.yaml

name: Weather Agent
model: claude-opus-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

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



Best practice per le definizioni di 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, meglio sarà in grado 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 per restituire 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 gonfiate sprecano contesto e rendono più difficile per Claude estrarre ciò che conta.



Passaggi successivi