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 dell'agente include i seguenti strumenti. Tutti sono abilitati per impostazione predefinita quando includi il toolset nella configurazione dell'agente. Ogni voce nell'array configs è identificata dal suo name, usando i valori nella colonna Nome, e accetta un campo type opzionale con lo stesso valore. Le voci web_search e web_fetch accettano impostazioni aggiuntive; consulta Limitare i domini di web search e web fetch.

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 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 web search e web fetch.

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 toolset 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 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 i domini di web search e web fetch

Per controllare quali siti gli strumenti web dell'agente possono raggiungere, 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 toolset. Ogni strumento ha la propria lista, 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 non consentito dalle sue liste restituisce all'agente un risultato di errore (is_error: true sull'evento agent.tool_result, con un contenuto che indica il codice di errore url_not_allowed), e web_search omette i risultati non consentiti dalle sue liste.

Il seguente toolset limita web_search a due siti e ne localizza i 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 toolset 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 le liste di domini

• Imposta allowed_domains oppure blocked_domains su una voce, non entrambi. Una voce che imposta entrambi viene rifiutata.
• Ogni lista contiene da 1 a 64 domini, ciascuno da 1 a 255 caratteri. Una lista vuota viene rifiutata: per non applicare alcuna restrizione, ometti il campo o invia null.
• Ogni dominio è un nome di dominio registrabile, o un suo sottodominio, scritto come semplice hostname: 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 a parte il suffisso di percorso opzionale per web_search descritto più avanti in questa lista. Usa example.com, non https://example.com, example.com:443 o *.example.com. Gli hostname vengono confrontati senza distinzione tra maiuscole e minuscole, e una singola / finale viene ignorata.
• 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 né api.example.com. Un www. iniziale è un sottodominio come qualsiasi altro, quindi www.example.com non copre example.com; elenca il dominio nudo per coprire entrambi.
• Gli indirizzi IP non sono accettati in alcuna forma, che siano IPv4, IPv6, tra parentesi quadre o in forma numerica abbreviata come 127.1. Elenca invece il nome di dominio del sito.
• Un dominio di primo livello nudo 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ò avere 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 di URL anziché come regole rigorose sugli host.
• I domini duplicati all'interno di una lista 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 entrambe le liste include Only one of allowed_domains or blocked_domains may be set., e il messaggio per una lista vuota 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 la sua lista 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 di 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 controlla nuovamente la configurazione quando inizializza lo strumento per la prima volta; se un'impostazione accettata in precedenza non è più valida a quel punto, la sessione emette un evento session.error e torna a idle senza riprovare. Correggi l'impostazione aggiornando gli strumenti della sessione, aggiorna anche l'agente in modo che le nuove sessioni partano con la configurazione corretta, quindi invia un nuovo user.message per continuare.

Sessioni multiagente, outcome e aggiornamenti a sessione in corso

In una sessione multiagente, ogni lista di domini che si applica a un thread viene applicata 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 dalle liste correnti del coordinatore.

• Le allowlist si combinano nei domini coperti da tutte, 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 loro interno, e un agente del roster che imposta i propri allowed_domains può raggiungere solo gli host coperti sia dalla sua lista sia da quella del coordinatore.
• Se le allowlist combinate non hanno alcun dominio in comune, lo strumento resta 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 evitarlo.
• max_content_tokens e user_location non vengono combinati: un thread usa il valore della propria configurazione dello strumento se impostato, altrimenti quello dell'agente che lo ha chiamato, altrimenti quello della configurazione corrente del coordinatore.
• Una voce di roster {"type": "self"} non ha impostazioni web proprie e segue le impostazioni correnti del coordinatore.
• Il grader nelle sessioni guidate da outcome viene eseguito senza web_search e web_fetch, indipendentemente da queste impostazioni.
• Puoi modificare le liste su una sessione inattiva aggiornandone gli strumenti. Le nuove liste si applicano al resto della sessione; in una sessione multiagente, ogni thread le applica dal turno successivo, mentre le liste proprie di un agente del roster restano come le ha impostate la sua definizione di agente al momento della creazione della sessione.

Differenze rispetto agli strumenti della Messages API

Queste impostazioni usano 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 lista è limitata a 64 domini.
• I domini elencati per web_fetch non possono includere un percorso.
• I domini devono essere ASCII: usa la forma xn-- (Punycode) per i nomi di dominio internazionalizzati. La Messages API accetta voci Unicode, anche se le sconsiglia.
• max_uses, citations e cache_control non sono disponibili sul toolset.

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: tu 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 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 no). Spiega cosa significa ogni parametro e come influisce sul comportamento dello strumento. Segnala eventuali avvertenze o limitazioni importanti. Più contesto puoi dare 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. Anziché creare uno strumento separato per ogni azione (create_pr, review_pr, merge_pr), raggruppale in un unico strumento con un parametro action. Strumenti meno numerosi e più capaci riducono l'ambiguità nella selezione e rendono la tua superficie di strumenti più facile da esplorare 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 segnale. 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