Come implementare l'uso degli strumenti

Scegliere un modello

In generale, usa Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 o Claude Opus 3 per strumenti complessi e query ambigue; gestiscono meglio più strumenti e cercano chiarimenti quando necessario.

Usa Claude Haiku 3.5 o Claude Haiku 3 per strumenti semplici, ma nota che potrebbero inferire parametri mancanti.

Se usi Claude Sonnet 3.7 con l’uso di strumenti e il pensiero esteso, consulta la nostra guida qui per maggiori informazioni.

Specificare gli strumenti client

Gli strumenti client (sia definiti da Anthropic che dall’utente) sono specificati nel parametro di livello superiore tools della richiesta API. Ogni definizione di strumento include:

Parametro	Descrizione
`name`	Il nome dello strumento. Deve corrispondere alla regex `^[a-zA-Z0-9_-]{1,64}$`.
`description`	Una descrizione dettagliata in testo semplice di cosa fa lo strumento, quando dovrebbe essere usato e come si comporta.
`input_schema`	Un oggetto JSON Schema che definisce i parametri attesi per lo strumento.

Esempio di definizione di strumento semplice

JSON
{
  "name": "get_weather",
  "description": "Ottieni il meteo attuale in una determinata località",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "La città e lo stato, ad es. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "L'unità di temperatura, 'celsius' o 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

Questo strumento, chiamato get_weather, si aspetta un oggetto di input con una stringa location obbligatoria e una stringa unit opzionale che deve essere “celsius” o “fahrenheit”.

Prompt di sistema per l’uso degli strumenti

Quando chiami l’API Anthropic con il parametro tools, costruiamo un prompt di sistema speciale dalle definizioni degli strumenti, dalla configurazione degli strumenti e da qualsiasi prompt di sistema specificato dall’utente. Il prompt costruito è progettato per istruire il modello a usare gli strumenti specificati e fornire il contesto necessario per il corretto funzionamento dello strumento:

In questo ambiente hai accesso a un set di strumenti che puoi usare per rispondere alla domanda dell'utente.
{{ ISTRUZIONI DI FORMATTAZIONE }}
I parametri stringa e scalari dovrebbero essere specificati così come sono, mentre liste e oggetti dovrebbero usare il formato JSON. Nota che gli spazi per i valori stringa non vengono rimossi. L'output non è previsto che sia XML valido e viene analizzato con espressioni regolari.
Ecco le funzioni disponibili in formato JSONSchema:
{{ DEFINIZIONI DEGLI STRUMENTI IN JSON SCHEMA }}
{{ PROMPT DI SISTEMA UTENTE }}
{{ CONFIGURAZIONE DEGLI STRUMENTI }}

Migliori pratiche per le definizioni degli strumenti

Per ottenere le migliori prestazioni da Claude quando usi gli strumenti, segui queste linee guida:

Fornisci descrizioni estremamente dettagliate. Questo è di gran lunga il fattore più importante nelle prestazioni degli strumenti. Le tue descrizioni dovrebbero spiegare ogni dettaglio dello strumento, incluso:
- Cosa fa lo strumento
- Quando dovrebbe essere usato (e quando non dovrebbe)
- Cosa significa ogni parametro e come influisce sul comportamento dello strumento
- Eventuali avvertenze o limitazioni importanti, come quali informazioni lo strumento non restituisce se il nome dello strumento non è chiaro. Più contesto puoi dare a Claude sui tuoi strumenti, meglio sarà nel decidere quando e come usarli. Punta ad almeno 3-4 frasi per descrizione di strumento, di più se lo strumento è complesso.
Dai priorità alle descrizioni rispetto agli esempi. Mentre puoi includere esempi di come usare uno strumento nella sua descrizione o nel prompt di accompagnamento, questo è meno importante di avere una spiegazione chiara e completa dello scopo e dei parametri dello strumento. Aggiungi esempi solo dopo aver completamente sviluppato la descrizione.

Esempio di una buona descrizione di strumento

JSON
{
  "name": "get_stock_price",
  "description": "Recupera il prezzo attuale delle azioni per un determinato simbolo ticker. Il simbolo ticker deve essere un simbolo valido per una società quotata in borsa su una borsa valori statunitense principale come NYSE o NASDAQ. Lo strumento restituirà l'ultimo prezzo di scambio in USD. Dovrebbe essere usato quando l'utente chiede del prezzo attuale o più recente di un'azione specifica. Non fornirà altre informazioni sull'azione o sulla società.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "Il simbolo ticker dell'azione, ad es. AAPL per Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

Esempio di descrizione di strumento scadente

JSON
{
  "name": "get_stock_price",
  "description": "Ottiene il prezzo delle azioni per un ticker.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

La buona descrizione spiega chiaramente cosa fa lo strumento, quando usarlo, quali dati restituisce e cosa significa il parametro ticker. La descrizione scadente è troppo breve e lascia Claude con molte domande aperte sul comportamento e l’uso dello strumento.

Controllare l’output di Claude

Forzare l’uso degli strumenti

In alcuni casi, potresti voler che Claude usi uno strumento specifico per rispondere alla domanda dell’utente, anche se Claude pensa di poter fornire una risposta senza usare uno strumento. Puoi farlo specificando lo strumento nel campo tool_choice così:

tool_choice = {"type": "tool", "name": "get_weather"}

Quando lavori con il parametro tool_choice, abbiamo quattro opzioni possibili:

auto permette a Claude di decidere se chiamare qualsiasi strumento fornito o no. Questo è il valore predefinito quando vengono forniti tools.
any dice a Claude che deve usare uno degli strumenti forniti, ma non forza uno strumento particolare.
tool ci permette di forzare Claude a usare sempre uno strumento particolare.
none impedisce a Claude di usare qualsiasi strumento. Questo è il valore predefinito quando non vengono forniti tools.

Quando usi la cache dei prompt, le modifiche al parametro tool_choice invalideranno i blocchi di messaggi memorizzati nella cache. Le definizioni degli strumenti e i prompt di sistema rimangono nella cache, ma il contenuto dei messaggi deve essere rielaborato.

Questo diagramma illustra come funziona ogni opzione:

Nota che quando hai tool_choice come any o tool, precompileremo il messaggio dell’assistente per forzare l’uso di uno strumento. Questo significa che i modelli non emetteranno un blocco di contenuto text di catena di pensiero prima dei blocchi di contenuto tool_use, anche se esplicitamente richiesto di farlo.

Quando usi il pensiero esteso con l’uso degli strumenti, tool_choice: {"type": "any"} e tool_choice: {"type": "tool", "name": "..."} non sono supportati e risulteranno in un errore. Solo tool_choice: {"type": "auto"} (il predefinito) e tool_choice: {"type": "none"} sono compatibili con il pensiero esteso.

I nostri test hanno mostrato che questo non dovrebbe ridurre le prestazioni. Se vuoi mantenere la catena di pensiero (particolarmente con Opus) mentre richiedi ancora che il modello usi uno strumento specifico, puoi usare {"type": "auto"} per tool_choice (il predefinito) e aggiungere istruzioni esplicite in un messaggio user. Per esempio: Com'è il tempo a Londra? Usa lo strumento get_weather nella tua risposta.

Output JSON

Gli strumenti non devono necessariamente essere funzioni client — puoi usare gli strumenti ogni volta che vuoi che il modello restituisca output JSON che segue uno schema fornito. Per esempio, potresti usare uno strumento record_summary con uno schema particolare. Vedi Uso degli strumenti con Claude per un esempio funzionante completo.

Catena di pensiero

Quando usa gli strumenti, Claude mostrerà spesso la sua “catena di pensiero”, cioè il ragionamento passo dopo passo che usa per scomporre il problema e decidere quali strumenti usare. Il modello Claude Opus 3 farà questo se tool_choice è impostato su auto (questo è il valore predefinito, vedi Forzare l’uso degli strumenti), e Sonnet e Haiku possono essere spinti a farlo.

Per esempio, dato il prompt “Com’è il tempo a San Francisco adesso, e che ora è lì?”, Claude potrebbe rispondere con:

JSON
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Per rispondere a questa domanda, farò: 1. Usare lo strumento get_weather per ottenere il meteo attuale a San Francisco. 2. Usare lo strumento get_time per ottenere l'ora attuale nel fuso orario America/Los_Angeles, che copre San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

Questa catena di pensiero fornisce intuizioni sul processo di ragionamento di Claude e può aiutarti a debuggare comportamenti inaspettati.

Con il modello Claude Sonnet 3, la catena di pensiero è meno comune per impostazione predefinita, ma puoi spingere Claude a mostrare il suo ragionamento aggiungendo qualcosa come "Prima di rispondere, spiega il tuo ragionamento passo dopo passo in tag." al messaggio utente o al prompt di sistema.

È importante notare che mentre i tag <thinking> sono una convenzione comune che Claude usa per denotare la sua catena di pensiero, il formato esatto (come il nome di questo tag XML) potrebbe cambiare nel tempo. Il tuo codice dovrebbe trattare la catena di pensiero come qualsiasi altro testo generato dall’assistente, e non fare affidamento sulla presenza o formattazione specifica dei tag <thinking>.

Uso parallelo degli strumenti

Per impostazione predefinita, Claude può usare più strumenti per rispondere a una query utente. Puoi disabilitare questo comportamento:

Impostando disable_parallel_tool_use=true quando il tipo tool_choice è auto, il che assicura che Claude usi al massimo uno strumento
Impostando disable_parallel_tool_use=true quando il tipo tool_choice è any o tool, il che assicura che Claude usi esattamente uno strumento

Esempio completo di uso parallelo degli strumenti

Ecco un esempio completo che mostra come formattare correttamente le chiamate di strumenti paralleli nella cronologia dei messaggi:

import anthropic

client = anthropic.Anthropic()

# Definire gli strumenti
tools = [
    {
        "name": "get_weather",
        "description": "Ottieni il meteo attuale in una determinata località",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "La città e lo stato, ad es. San Francisco, CA"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Ottieni l'ora attuale in un determinato fuso orario",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "Il fuso orario, ad es. America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# Richiesta iniziale
response = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    tools=tools,
    messages=[
        {
            "role": "user",
            "content": "Com'è il tempo a SF e NYC, e che ora è lì?"
        }
    ]
)

# Risposta di Claude con chiamate di strumenti paralleli
print("Claude vuole usare strumenti:", response.stop_reason == "tool_use")
print("Numero di chiamate di strumenti:", len([c for c in response.content if c.type == "tool_use"]))

# Costruire la conversazione con i risultati degli strumenti
messages = [
    {
        "role": "user",
        "content": "Com'è il tempo a SF e NYC, e che ora è lì?"
    },
    {
        "role": "assistant",
        "content": response.content  # Contiene più blocchi tool_use
    },
    {
        "role": "user",
        "content": [
            {
                "type": "tool_result",
                "tool_use_id": "toolu_01",  # Deve corrispondere all'ID da tool_use
                "content": "San Francisco: 68°F, parzialmente nuvoloso"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_02",
                "content": "New York: 45°F, cielo sereno"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_03",
                "content": "Ora di San Francisco: 2:30 PM PST"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_04",
                "content": "Ora di New York: 5:30 PM EST"
            }
        ]
    }
]

# Ottenere la risposta finale
final_response = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    tools=tools,
    messages=messages
)

print(final_response.content[0].text)

Il messaggio dell’assistente con chiamate di strumenti paralleli apparirebbe così:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Controllerò il meteo e l'ora sia per San Francisco che per New York City."
    },
    {
      "type": "tool_use",
      "id": "toolu_01",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    },
    {
      "type": "tool_use",
      "id": "toolu_02",
      "name": "get_weather",
      "input": {"location": "New York, NY"}
    },
    {
      "type": "tool_use",
      "id": "toolu_03",
      "name": "get_time",
      "input": {"timezone": "America/Los_Angeles"}
    },
    {
      "type": "tool_use",
      "id": "toolu_04",
      "name": "get_time",
      "input": {"timezone": "America/New_York"}
    }
  ]
}

Script di test completo per strumenti paralleli

Ecco uno script completo ed eseguibile per testare e verificare che le chiamate di strumenti paralleli funzionino correttamente:

#!/usr/bin/env python3
"""Script di test per verificare le chiamate di strumenti paralleli con l'API Anthropic"""

import os
from anthropic import Anthropic

# Inizializzare il client
client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

# Definire gli strumenti
tools = [
    {
        "name": "get_weather",
        "description": "Ottieni il meteo attuale in una determinata località",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "La città e lo stato, ad es. San Francisco, CA"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Ottieni l'ora attuale in un determinato fuso orario",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "Il fuso orario, ad es. America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# Conversazione di test con chiamate di strumenti paralleli
messages = [
    {
        "role": "user",
        "content": "Com'è il tempo a SF e NYC, e che ora è lì?"
    }
]

# Fare la richiesta iniziale
print("Richiedendo chiamate di strumenti paralleli...")
response = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

# Controllare le chiamate di strumenti paralleli
tool_uses = [block for block in response.content if block.type == "tool_use"]
print(f"\n✓ Claude ha fatto {len(tool_uses)} chiamate di strumenti")

if len(tool_uses) > 1:
    print("✓ Chiamate di strumenti paralleli rilevate!")
    for tool in tool_uses:
        print(f"  - {tool.name}: {tool.input}")
else:
    print("✗ Nessuna chiamata di strumenti paralleli rilevata")

# Simulare l'esecuzione degli strumenti e formattare i risultati correttamente
tool_results = []
for tool_use in tool_uses:
    if tool_use.name == "get_weather":
        if "San Francisco" in str(tool_use.input):
            result = "San Francisco: 68°F, parzialmente nuvoloso"
        else:
            result = "New York: 45°F, cielo sereno"
    else:  # get_time
        if "Los_Angeles" in str(tool_use.input):
            result = "2:30 PM PST"
        else:
            result = "5:30 PM EST"
    
    tool_results.append({
        "type": "tool_result",
        "tool_use_id": tool_use.id,
        "content": result
    })

# Continuare la conversazione con i risultati degli strumenti
messages.extend([
    {"role": "assistant", "content": response.content},
    {"role": "user", "content": tool_results}  # Tutti i risultati in un messaggio!
])

# Ottenere la risposta finale
print("\nOttenendo la risposta finale...")
final_response = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

print(f"\nRisposta di Claude:\n{final_response.content[0].text}")

# Verificare la formattazione
print("\n--- Verifica ---")
print(f"✓ Risultati degli strumenti inviati in un singolo messaggio utente: {len(tool_results)} risultati")
print("✓ Nessun testo prima dei risultati degli strumenti nell'array content")
print("✓ Conversazione formattata correttamente per futuro uso di strumenti paralleli")

Questo script dimostra:

Come formattare correttamente le chiamate e i risultati di strumenti paralleli
Come verificare che le chiamate parallele vengano effettuate
La struttura corretta dei messaggi che incoraggia il futuro uso di strumenti paralleli
Errori comuni da evitare (come testo prima dei risultati degli strumenti)

Esegui questo script per testare la tua implementazione e assicurarti che Claude stia effettuando chiamate di strumenti paralleli efficacemente.

Massimizzare l’uso parallelo degli strumenti

Mentre i modelli Claude 4 hanno eccellenti capacità di uso parallelo degli strumenti per impostazione predefinita, puoi aumentare la probabilità di esecuzione parallela degli strumenti su tutti i modelli con prompt mirati:

Prompt di sistema per l'uso parallelo degli strumenti

Per i modelli Claude 4 (Opus 4 e Sonnet 4), aggiungi questo al tuo prompt di sistema:

Per la massima efficienza, ogni volta che devi eseguire più operazioni indipendenti, invoca tutti gli strumenti rilevanti simultaneamente piuttosto che sequenzialmente.

Per un uso ancora più forte degli strumenti paralleli (raccomandato se quello predefinito non è sufficiente), usa:

<use_parallel_tool_calls>
Per la massima efficienza, ogni volta che esegui più operazioni indipendenti, invoca tutti gli strumenti rilevanti simultaneamente piuttosto che sequenzialmente. Dai priorità alle chiamate di strumenti in parallelo quando possibile. Per esempio, quando leggi 3 file, esegui 3 chiamate di strumenti in parallelo per leggere tutti e 3 i file nel contesto allo stesso tempo. Quando esegui più comandi di sola lettura come `ls` o `list_dir`, esegui sempre tutti i comandi in parallelo. Sbaglia verso la massimizzazione delle chiamate di strumenti paralleli piuttosto che eseguire troppi strumenti sequenzialmente.
</use_parallel_tool_calls>

Prompt nei messaggi utente

Puoi anche incoraggiare l’uso parallelo degli strumenti all’interno di messaggi utente specifici:

# Invece di:
"Com'è il tempo a Parigi? Controlla anche Londra."

# Usa:
"Controlla il tempo a Parigi e Londra simultaneamente."

# O sii esplicito:
"Per favore usa chiamate di strumenti paralleli per ottenere il meteo per Parigi, Londra e Tokyo allo stesso tempo."

Uso parallelo degli strumenti con Claude Sonnet 3.7

Claude Sonnet 3.7 potrebbe essere meno propenso a fare chiamate di strumenti paralleli in una risposta, anche quando non hai impostato disable_parallel_tool_use. Per aggirare questo, raccomandiamo di abilitare l’uso efficiente dei token degli strumenti, che aiuta a incoraggiare Claude a usare strumenti paralleli. Questa funzionalità beta riduce anche la latenza e risparmia in media il 14% nei token di output.

Se preferisci non optare per la beta dell’uso efficiente dei token degli strumenti, puoi anche introdurre uno “strumento batch” che può agire come meta-strumento per avvolgere invocazioni ad altri strumenti simultaneamente. Troviamo che se questo strumento è presente, il modello lo userà per chiamare simultaneamente più strumenti in parallelo per te.

Vedi questo esempio nel nostro cookbook per come usare questa soluzione alternativa.

Gestire i blocchi di contenuto tool use e tool result

La risposta di Claude differisce in base al fatto che usi uno strumento client o server.

Gestire i risultati dagli strumenti client

La risposta avrà un stop_reason di tool_use e uno o più blocchi di contenuto tool_use che includono:

id: Un identificatore unico per questo particolare blocco di uso dello strumento. Questo sarà usato per abbinare i risultati dello strumento più tardi.
name: Il nome dello strumento che viene usato.
input: Un oggetto contenente l’input che viene passato allo strumento, conforme all’input_schema dello strumento.

Esempio di risposta API con un blocco di contenuto `tool_use`

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-20250514",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Devo usare get_weather, e l'utente vuole SF, che è probabilmente San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

Quando ricevi una risposta di uso dello strumento per uno strumento client, dovresti:

Estrarre name, id e input dal blocco tool_use.
Eseguire lo strumento effettivo nel tuo codebase corrispondente a quel nome dello strumento, passando l’input dello strumento.
Continuare la conversazione inviando un nuovo messaggio con il role di user, e un blocco content contenente il tipo tool_result e le seguenti informazioni:
- tool_use_id: L’id della richiesta di uso dello strumento per cui questo è un risultato.
- content: Il risultato dello strumento, come stringa (ad es. "content": "15 gradi") o lista di blocchi di contenuto annidati (ad es. "content": [{"type": "text", "text": "15 gradi"}]). Questi blocchi di contenuto possono usare i tipi text o image.
- is_error (opzionale): Imposta su true se l’esecuzione dello strumento ha risultato in un errore.

Requisiti di formattazione importanti:

I blocchi di risultato dello strumento devono seguire immediatamente i loro corrispondenti blocchi di uso dello strumento nella cronologia dei messaggi. Non puoi includere messaggi tra il messaggio di uso dello strumento dell’assistente e il messaggio di risultato dello strumento dell’utente.
Nel messaggio utente contenente i risultati dello strumento, i blocchi tool_result devono venire PRIMA nell’array content. Qualsiasi testo deve venire DOPO tutti i risultati dello strumento.

Per esempio, questo causerà un errore 400:

{"role": "user", "content": [
  {"type": "text", "text": "Ecco i risultati:"},  // ❌ Testo prima di tool_result
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}

Questo è corretto:

{"role": "user", "content": [
  {"type": "tool_result", "tool_use_id": "toolu_01", ...},
  {"type": "text", "text": "Cosa dovrei fare dopo?"}  // ✅ Testo dopo tool_result
]}

Se ricevi un errore come “tool_use ids were found without tool_result blocks immediately after”, controlla che i tuoi risultati dello strumento siano formattati correttamente.

Esempio di risultato dello strumento riuscito

Esempio di risultato dello strumento con immagini

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "15 gradi"},
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRg...",
          }
        }
      ]
    }
  ]
}

Esempio di risultato dello strumento vuoto

Dopo aver ricevuto il risultato dello strumento, Claude userà quell’informazione per continuare a generare una risposta al prompt utente originale.

Gestire i risultati dagli strumenti server

Claude esegue lo strumento internamente e incorpora i risultati direttamente nella sua risposta senza richiedere ulteriore interazione dell’utente.

Differenze da altre API

A differenza delle API che separano l’uso degli strumenti o usano ruoli speciali come tool o function, l’API di Anthropic integra gli strumenti direttamente nella struttura dei messaggi user e assistant.

I messaggi contengono array di blocchi text, image, tool_use e tool_result. I messaggi user includono contenuto client e tool_result, mentre i messaggi assistant contengono contenuto generato dall’AI e tool_use.

Gestire il motivo di arresto `max_tokens`

Se la risposta di Claude viene troncata a causa del raggiungimento del limite max_tokens, e la risposta troncata contiene un blocco di uso dello strumento incompleto, dovrai riprovare la richiesta con un valore max_tokens più alto per ottenere l’uso completo dello strumento.

# Controllare se la risposta è stata troncata durante l'uso dello strumento
if response.stop_reason == "max_tokens":
    # Controllare se l'ultimo blocco di contenuto è un tool_use incompleto
    last_block = response.content[-1]
    if last_block.type == "tool_use":
        # Inviare la richiesta con max_tokens più alto
        response = client.messages.create(
            model="claude-opus-4-20250514",
            max_tokens=4096,  # Limite aumentato
            messages=messages,
            tools=tools
        )

Gestire il motivo di arresto `pause_turn`

Quando usi strumenti server come la ricerca web, l’API potrebbe restituire un motivo di arresto pause_turn, indicando che l’API ha messo in pausa un turno di lunga durata.

Ecco come gestire il motivo di arresto pause_turn:

import anthropic

client = anthropic.Anthropic()

# Richiesta iniziale con ricerca web
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Cerca informazioni complete sui progressi del quantum computing nel 2025"
        }
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 10
    }]
)

# Controllare se la risposta ha il motivo di arresto pause_turn
if response.stop_reason == "pause_turn":
    # Continuare la conversazione con il contenuto in pausa
    messages = [
        {"role": "user", "content": "Cerca informazioni complete sui progressi del quantum computing nel 2025"},
        {"role": "assistant", "content": response.content}
    ]
    
    # Inviare la richiesta di continuazione
    continuation = client.messages.create(
        model="claude-3-7-sonnet-latest",
        max_tokens=1024,
        messages=messages,
        tools=[{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 10
        }]
    )
    
    print(continuation)
else:
    print(response)

Quando gestisci pause_turn:

Continua la conversazione: Passa la risposta in pausa così com’è in una richiesta successiva per permettere a Claude di continuare il suo turno
Modifica se necessario: Puoi opzionalmente modificare il contenuto prima di continuare se vuoi interrompere o reindirizzare la conversazione
Preserva lo stato dello strumento: Includi gli stessi strumenti nella richiesta di continuazione per mantenere la funzionalità

Risoluzione degli errori

Ci sono alcuni tipi diversi di errori che possono verificarsi quando usi gli strumenti con Claude:

Errore di esecuzione dello strumento

Se lo strumento stesso genera un errore durante l’esecuzione (ad es. un errore di rete quando si recuperano dati meteo), puoi restituire il messaggio di errore nel content insieme a "is_error": true:

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: l'API del servizio meteo non è disponibile (HTTP 500)",
      "is_error": true
    }
  ]
}

Claude incorporerà quindi questo errore nella sua risposta all’ut ente, ad es. “Mi dispiace, non sono riuscito a recuperare il meteo attuale perché l’API del servizio meteo non è disponibile. Riprova più tardi.”

Nome dello strumento non valido

Se il tentativo di uso di uno strumento da parte di Claude non è valido (ad es. parametri obbligatori mancanti), di solito significa che non c’erano abbastanza informazioni perché Claude usasse lo strumento correttamente. La tua migliore opzione durante lo sviluppo è provare di nuovo la richiesta con valori description più dettagliati nelle tue definizioni degli strumenti.

Tuttavia, puoi anche continuare la conversazione con un tool_result che indica l’errore, e Claude proverà a usare di nuovo lo strumento con le informazioni mancanti compilate:

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Errore: Parametro 'location' obbligatorio mancante",
      "is_error": true
    }
  ]
}

Se una richiesta di strumento non è valida o manca di parametri, Claude riproverà 2-3 volte con correzioni prima di scusarsi con l’utente.

Tag <search_quality_reflection>

Errori degli strumenti server

Chiamate di strumenti paralleli non funzionanti

Se Claude non sta facendo chiamate di strumenti paralleli quando previsto, controlla questi problemi comuni:

1. Formattazione incorretta dei risultati degli strumenti

Il problema più comune è formattare incorrettamente i risultati degli strumenti nella cronologia della conversazione. Questo “insegna” a Claude di evitare chiamate parallele.

Specificamente per l’uso parallelo degli strumenti:

❌ Sbagliato: Inviare messaggi utente separati per ogni risultato dello strumento
✅ Corretto: Tutti i risultati degli strumenti devono essere in un singolo messaggio utente

// ❌ Questo riduce l'uso di strumenti paralleli
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1]},
  {"role": "user", "content": [tool_result_2]}  // Messaggio separato
]

// ✅ Questo mantiene l'uso di strumenti paralleli
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1, tool_result_2]}  // Messaggio singolo
]

Vedi i requisiti di formattazione generali sopra per altre regole di formattazione.

2. Prompt debole

Il prompt predefinito potrebbe non essere sufficiente. Usa un linguaggio più forte:

<use_parallel_tool_calls>
Per la massima efficienza, ogni volta che esegui più operazioni indipendenti, 
invoca tutti gli strumenti rilevanti simultaneamente piuttosto che sequenzialmente. 
Dai priorità alle chiamate di strumenti in parallelo quando possibile.
</use_parallel_tool_calls>

3. Misurare l’uso di strumenti paralleli

Per verificare che le chiamate di strumenti paralleli funzionino:

# Calcolare la media degli strumenti per messaggio che chiama strumenti
tool_call_messages = [msg for msg in messages if any(
    block.type == "tool_use" for block in msg.content
)]
total_tool_calls = sum(
    len([b for b in msg.content if b.type == "tool_use"]) 
    for msg in tool_call_messages
)
avg_tools_per_message = total_tool_calls / len(tool_call_messages)
print(f"Media strumenti per messaggio: {avg_tools_per_message}")
# Dovrebbe essere > 1.0 se le chiamate parallele funzionano

4. Comportamento specifico del modello

Claude Opus 4 e Sonnet 4: Eccellono nell’uso di strumenti paralleli con prompt minimi
Claude Sonnet 3.7: Potrebbe aver bisogno di prompt più forti o uso efficiente dei token degli strumenti
Claude Haiku: Meno propenso a usare strumenti paralleli senza prompt espliciti

Panoramica Uso degli strumenti a efficienza di token (beta)

On this page

Scegliere un modello
Specificare gli strumenti client
Prompt di sistema per l’uso degli strumenti
Migliori pratiche per le definizioni degli strumenti
Controllare l’output di Claude
Forzare l’uso degli strumenti
Output JSON
Catena di pensiero
Uso parallelo degli strumenti
Massimizzare l’uso parallelo degli strumenti
Gestire i blocchi di contenuto tool use e tool result
Gestire i risultati dagli strumenti client
Gestire i risultati dagli strumenti server
Gestire il motivo di arresto max_tokens
Gestire il motivo di arresto pause_turn
Risoluzione degli errori

Primi passi

Modelli e prezzi

Scopri Claude

Funzionalità

Strumenti

Model Context Protocol (MCP)

Casi d'uso

Ingegneria dei prompt

Testa e valuta

Rafforza le protezioni

Centro legale

Come implementare l'uso degli strumenti

Scegliere un modello

Specificare gli strumenti client

Prompt di sistema per l’uso degli strumenti

Migliori pratiche per le definizioni degli strumenti

Controllare l’output di Claude

Forzare l’uso degli strumenti

Output JSON

Catena di pensiero

Uso parallelo degli strumenti

Massimizzare l’uso parallelo degli strumenti

Gestire i blocchi di contenuto tool use e tool result

Gestire i risultati dagli strumenti client

Gestire i risultati dagli strumenti server

Gestire il motivo di arresto `max_tokens`

Gestire il motivo di arresto `pause_turn`

Risoluzione degli errori

Primi passi

Modelli e prezzi

Scopri Claude

Funzionalità

Strumenti

Model Context Protocol (MCP)

Casi d'uso

Ingegneria dei prompt

Testa e valuta

Rafforza le protezioni

Centro legale

​Scegliere un modello

​Specificare gli strumenti client

​Prompt di sistema per l’uso degli strumenti

​Migliori pratiche per le definizioni degli strumenti

​Controllare l’output di Claude

​Forzare l’uso degli strumenti

​Output JSON

​Catena di pensiero

​Uso parallelo degli strumenti

​Massimizzare l’uso parallelo degli strumenti

​Gestire i blocchi di contenuto tool use e tool result

​Gestire i risultati dagli strumenti client

​Gestire i risultati dagli strumenti server

​Gestire il motivo di arresto max_tokens

​Gestire il motivo di arresto pause_turn

​Risoluzione degli errori

Scegliere un modello

Specificare gli strumenti client

Prompt di sistema per l’uso degli strumenti

Migliori pratiche per le definizioni degli strumenti

Controllare l’output di Claude

Forzare l’uso degli strumenti

Output JSON

Catena di pensiero

Uso parallelo degli strumenti

Massimizzare l’uso parallelo degli strumenti

Gestire i blocchi di contenuto tool use e tool result

Gestire i risultati dagli strumenti client

Gestire i risultati dagli strumenti server

Gestire il motivo di arresto `max_tokens`

Gestire il motivo di arresto `pause_turn`

Risoluzione degli errori