Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Tabelle dal sintomo alla soluzione per gli errori più comuni nel "tool use" (uso degli strumenti). Ogni soluzione rimanda alla pagina di riferimento della funzionalità.
| 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. Vedi Definire gli strumenti. |
| Claude non chiama mai il tuo strumento | Collisione di nomi degli strumenti o schema troppo generico | Controlla 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. |
| 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. |
| 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. Vedi Uso parallelo degli strumenti. |
disable_parallel_tool_use sembra ignorato | Impostato troppo tardi nella conversazione | Deve essere impostato nella richiesta che restituisce tool_use. Impostarlo in una richiesta successiva non ha effetto sulle chiamate agli strumenti precedenti. |
| 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. Vedi Uso degli strumenti con la cache dei prompt e Thinking e cache dei prompt. |
| Aggiungere uno strumento a metà conversazione rompe la cache | Strumento anteposto all'array degli strumenti | Usa defer_loading: true con la ricerca degli strumenti per aggiungere lo strumento inline invece di modificare la testa dell'array. |
| 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. Vedi 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 (nella maggior parte dei casi, 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. Vedi 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; vedi 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. |
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.
Vedi I blocchi thinking non possono essere modificati per l'errore completo e i passaggi di risoluzione.
| Sintomo | Causa probabile | Soluzione |
|---|---|---|
| Claude si rifiuta di agire su un risultato di uno strumento, oppure chiede all'utente di confermare istruzioni provenienti 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. Vedi Mitigare jailbreak e prompt injection. |
| 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 di stringhe grezze sull'input serializzato. |
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 con schema Anthropic e delle relative stringhe di versione.
Was this page helpful?