Risoluzione dei problemi dell’uso degli strumenti
Risolvi gli errori più comuni dell’uso degli strumenti con tabelle diagnostiche dal sintomo alla soluzione.
Trova il sintomo o l’errore che riscontri, quindi applica la soluzione indicata per esso.
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 di nomi degli 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 effettua chiamate con tipi di parametro errati | 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à rigorosa | Aggiungi strict: true se il tuo schema rientra nel sottoinsieme supportato. |
| Valori dei parametri al di fuori del tuo enum | Modalità rigorosa 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 | Impostalo 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 ragionamento 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 ragionamento 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 | Dichiara lo strumento con defer_loading: true fin dalla prima richiesta e lascia che la ricerca degli strumenti lo carichi inline, invece di aggiungerlo all’array in un secondo momento. |
Errori al momento della richiesta
La colonna Errore mostra una parte di ciascun messaggio, e ... indica testo variabile.
| 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. Inserisci i blocchi tool_result prima di qualsiasi testo. Consulta Gestire le chiamate agli strumenti e Uso parallelo degli strumenti. |
was found without a corresponding ... block | La richiesta successiva impedisce l’esecuzione di uno strumento server in attesa | Consulta Una chiamata a uno strumento server non ha un blocco di risultato. |
Unsupported regex feature in pattern field: ... | Il pattern di uno strumento rigoroso usa una funzionalità regex che la modalità rigorosa non può compilare, come un backreference, un confine di parola o un intervallo {n,m} ampio | Semplifica il pattern. Consulta Limitazioni di JSON Schema. |
Invalid regex in pattern field: ... | Il pattern di uno strumento rigoroso contiene un lookahead, un lookbehind o un errore di sintassi | Rimuovi qualsiasi lookahead o lookbehind e correggi eventuali errori di sintassi. 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. |
Una chiamata a uno strumento server non ha un blocco di risultato
Uno strumento server è ancora in attesa di essere eseguito quando il suo blocco server_tool_use o mcp_tool_use non ha un blocco di risultato. L’errore was found without a corresponding ... block indica che la richiesta successiva impedisce l’esecuzione dello strumento in attesa. Il messaggio di errore e lo stop_reason precedente ne mostrano il motivo. Usa il primo caso corrispondente:
- Il messaggio termina con
but no `<name>` tool was providedois not available after the last message: In questo caso,<name>è il nome dello strumento, ad esempioweb_search. La richiesta non definisce più lo strumento. Invia lo stesso arraytoolsdi prima e, per uno strumento MCP, gli stessimcp_servers. - Lo
stop_reasonprecedente eratool_use: Il tuo messaggio utente conteneva contenuto dopo i blocchitool_result. Invia solo i blocchitool_result, uno per ogni bloccotool_usedel client. - Lo
stop_reasonprecedente erapause_turn: Hai aggiunto un messaggio utente. Rimuovilo in modo che la richiesta termini con la risposta in pausa come messaggioassistant.
Per i passaggi completi, consulta Quando uno strumento server è ancora in attesa e il motivo di arresto pause_turn.
Errore: i blocchi di ragionamento 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 di ragionamento dell’assistente prima di rinviarli. Rinvia l’intero messaggio dell’assistente invariato, quindi aggiungi il tuo tool_result.
Consulta I blocchi di ragionamento 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 tra versioni del modello
| 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.
Questa pagina ti è stata utile?