Claude Platform Docs
MessaggiStrumenti

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

SintomoCausa probabileSoluzione
Claude chiama lo strumento A quando volevi lo strumento BAmbiguità nella descrizioneAffina 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 strumentoCollisione di nomi degli strumenti o schema troppo genericoVerifica 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 erratiSchema ambiguoAggiungi strict: true (se il tuo schema rientra nel sottoinsieme supportato) oppure aggiungi input_examples.

Claude inventa parametri degli strumenti

SintomoCausa probabileSoluzione
Parametro che non esiste nel tuo schemaSovra-generazione del modello senza modalità rigorosaAggiungi strict: true se il tuo schema rientra nel sottoinsieme supportato.
Valori dei parametri al di fuori del tuo enumModalità rigorosa mancante o enum troppo grandeRiduci l’enum oppure aggiungi input_examples che mostrino le scelte valide.

Le chiamate parallele agli strumenti non funzionano

SintomoCausa probabileSoluzione
Claude chiama gli strumenti in sequenza quando sarebbe meglio in paralleloFormattazione della cronologia dei messaggiInvia più blocchi tool_result in UN SOLO messaggio utente, non uno per turno. Consulta Uso parallelo degli strumenti.
disable_parallel_tool_use sembra ignoratoImpostato troppo tardi nella conversazioneImpostalo sulla richiesta che restituisce tool_use. Impostarlo su una richiesta successiva non ha effetto sulle chiamate agli strumenti precedenti.

La cache continua a invalidarsi

SintomoCausa probabileSoluzione
Ogni richiesta è un cache misstool_choice, la configurazione del ragionamento o output_config.effort variano tra le richiesteMantieni 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 cacheStrumento inserito all’inizio dell’array toolsDichiara 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.

ErroreCausaSoluzione
tool_use ids were found without tool_result blocks immediately aftertool_result mancante per alcuni ID tool_use, oppure tool_result non è il primo blocco di contenuto nel messaggio utenteRestituisci 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 ... blockLa richiesta successiva impedisce l’esecuzione di uno strumento server in attesaConsulta 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} ampioSemplifica 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 sintassiRimuovi qualsiasi lookahead o lookbehind e correggi eventuali errori di sintassi. Consulta Limitazioni di JSON Schema.
All tools have defer_loading: trueNessuno strumento visibile al modelloAlmeno 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 provided o is not available after the last message: In questo caso, <name> è il nome dello strumento, ad esempio web_search. La richiesta non definisce più lo strumento. Invia lo stesso array tools di prima e, per uno strumento MCP, gli stessi mcp_servers.
  • Lo stop_reason precedente era tool_use: Il tuo messaggio utente conteneva contenuto dopo i blocchi tool_result. Invia solo i blocchi tool_result, uno per ogni blocco tool_use del client.
  • Lo stop_reason precedente era pause_turn: Hai aggiunto un messaggio utente. Rimuovilo in modo che la richiesta termini con la risposta in pausa come messaggio assistant.

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

SintomoCausa probabileSoluzione
Claude si rifiuta di agire su un risultato di uno strumento, oppure chiede all’utente di confermare istruzioni che provengono da essoLe tue stesse istruzioni vengono fornite all’interno del contenuto del tool_resultClaude è 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

SintomoCausaSoluzione
Il confronto tra stringhe sugli input degli strumenti fallisce con i modelli più recentiL’escaping di Unicode e delle barre oblique differisce tra le versioni dei modelliEsegui 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?