MessagesStrumenti
Risoluzione dei problemi dell'uso degli strumenti
Risolvi gli errori più comuni dell'uso degli strumenti con tabelle diagnostiche dal sintomo alla soluzione.
Tabelle dal sintomo alla soluzione per gli errori più comuni del "tool use" (uso degli strumenti). Ogni soluzione rimanda alla pagina dedicata alla funzionalità corrispondente.
Claude chiama lo strumento sbagliato
| Sintomo | Causa probabile | Soluzione |
|---|---|---|
| Claude chiama lo strumento A quando volevi lo strumento B | Ambiguità nella descrizione | Affina le descrizioni. Differenzia gli strumenti in base a QUANDO usarli, non solo a COSA fanno. Consulta Definire gli strumenti. |
| Claude non chiama mai il tuo strumento | Collisione tra nomi di strumenti o schema troppo generico | Verifica la presenza di nomi duplicati nell'elenco degli strumenti. Aggiungi input_examples per rendere concreto l'uso previsto. |
| Claude chiama con tipi di parametro errati | Il modello indovina di fronte a uno schema ambiguo | Aggiungi strict: true (se il tuo schema rientra nel sottoinsieme supportato) oppure aggiungi input_examples. |
Claude inventa parametri degli strumenti
| Sintomo | Causa probabile | Soluzione |
|---|---|---|
| Parametro che non esiste nel tuo schema | Sovra-generazione del modello senza modalità strict | Aggiungi strict: true se il tuo schema rientra nel sottoinsieme supportato. |
| Valori dei parametri al di fuori del tuo enum | Modalità strict mancante o enum troppo grande | Riduci l'enum oppure aggiungi input_examples che mostrino le scelte valide. |
Le chiamate parallele agli strumenti non funzionano
| Sintomo | Causa probabile | Soluzione |
|---|---|---|
| Claude chiama gli strumenti in sequenza quando sarebbe meglio in parallelo | Formattazione della cronologia dei messaggi | Invia più blocchi tool_result in UN SOLO messaggio utente, non uno per turno. Consulta Uso parallelo degli strumenti. |
disable_parallel_tool_use sembra ignorato | Impostato troppo tardi nella conversazione | Deve essere impostato sulla richiesta che restituisce tool_use. Impostarlo su una richiesta successiva non ha effetto sulle chiamate agli strumenti precedenti. |
La cache continua a invalidarsi
| Sintomo | Causa probabile | Soluzione |
|---|---|---|
| Ogni richiesta è un cache miss | tool_choice, la configurazione del thinking o output_config.effort variano tra le richieste | Mantieni tool_choice stabile oppure posiziona il breakpoint cache_control prima del punto di variazione; mantieni costanti la configurazione del thinking e il livello di effort per tutta la durata di una conversazione in cache. Consulta Uso degli strumenti con la cache dei prompt e Ragionamento e cache dei prompt. |
| Aggiungere uno strumento a metà conversazione rompe la cache | Strumento inserito all'inizio dell'array tools | Usa defer_loading: true con la ricerca degli strumenti per aggiungere lo strumento inline invece di modificare la testa dell'array. |
Errori al momento della richiesta
| Errore | Causa | Soluzione |
|---|---|---|
tool_use ids were found without tool_result blocks immediately after | tool_result mancante per alcuni id tool_use, oppure tool_result non è il primo blocco di contenuto nel messaggio utente | Restituisci un tool_result per ogni blocco tool_use nella risposta dell'assistente. Metti i blocchi tool_result prima di qualsiasi testo. Consulta Gestire le chiamate agli strumenti e Uso parallelo degli strumenti. |
was found without a corresponding <name>_tool_result block | Il turno precedente dell'assistente contiene un blocco server_tool_use senza blocco di risultato (il più delle volte, Claude lo ha chiamato insieme a uno strumento client), e il tuo messaggio utente successivo ha terminato quel turno (ad esempio, con del testo dopo i blocchi tool_result) oppure la richiesta di ripresa non definisce più quello strumento server (il messaggio termina allora con but no <name> tool was provided) | Invia un messaggio utente contenente solo i blocchi tool_result per gli id tool_use client e mantieni lo stesso array tools. Consulta Motivi di arresto e fallback. |
Unsupported regex feature in pattern field: ... | Un pattern nell'input_schema di uno strumento strict usa una funzionalità regex che la modalità strict non può compilare, come un backreference, un lookaround, un word boundary o un intervallo {n,m} ampio | Semplifica il pattern. Sono supportati i pattern ancorati con quantificatori di base, classi di caratteri e gruppi; consulta Limitazioni di JSON Schema. |
All tools have defer_loading: true | Nessuno strumento visibile al modello | Almeno uno strumento deve essere caricato immediatamente. Lo strumento di ricerca degli strumenti stesso non deve mai avere defer_loading: true. |
Errore: i blocchi thinking non possono essere modificati
Se una richiesta fallisce con un 400 invalid_request_error il cui messaggio contiene `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified quando prosegui una conversazione dopo una chiamata a uno strumento, la tua applicazione sta alterando i blocchi thinking dell'assistente prima di rinviarli. Rinvia l'intero messaggio dell'assistente invariato, quindi aggiungi il tuo tool_result.
Consulta I blocchi thinking non possono essere modificati per l'errore completo e i passaggi di risoluzione.
Claude segnala i risultati degli strumenti come prompt injection
| Sintomo | Causa probabile | Soluzione |
|---|---|---|
| Claude si rifiuta di agire su un risultato di uno strumento, oppure chiede all'utente di confermare istruzioni che provengono da esso | Le tue stesse istruzioni vengono fornite all'interno del contenuto del tool_result | Claude è addestrato a trattare le istruzioni all'interno dei risultati degli strumenti come contenuto di terze parti potenzialmente non attendibile. Sposta le tue istruzioni fuori dal risultato dello strumento: inviale in un turno user dopo il blocco tool_result oppure, sui modelli supportati, in un messaggio di sistema a metà conversazione. Limita il risultato dello strumento ai soli dati. Consulta Mitigare jailbreak e prompt injection. |
Differenze nell'escaping JSON (Opus 4.6+)
| Sintomo | Causa | Soluzione |
|---|---|---|
| Il confronto tra stringhe sugli input degli strumenti fallisce con i modelli più recenti | L'escaping di Unicode e delle barre oblique differisce tra le versioni dei modelli | Esegui il parsing con json.loads() o JSON.parse(). Non eseguire mai confronti tra stringhe grezze sull'input serializzato. |
Passaggi successivi
Scrivi schemi e descrizioni che indirizzino Claude verso lo strumento giusto.
Esegui gli strumenti e restituisci i risultati nel formato di messaggio richiesto.
Elenco completo degli strumenti forniti da Anthropic e delle relative stringhe di versione.
Was this page helpful?