Come implementare l'uso degli strumenti

Scegliere un modello

In generale, usa Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 (deprecato) o Claude Opus 3 (deprecato) 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, fai riferimento alla nostra guida qui per maggiori informazioni.

Specificare 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 semplice di strumento

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 ed è analizzato con espressioni regolari.
Ecco le funzioni disponibili in formato JSONSchema:
{{ DEFINIZIONI STRUMENTI IN JSON SCHEMA }}
{{ PROMPT DI SISTEMA UTENTE }}
{{ CONFIGURAZIONE 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 sullo 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. Anche se 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 grande borsa valori statunitense 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 povera di strumento

JSON

{
  "name": "get_stock_price",
  "description": "Ottiene il prezzo dell'azione 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 povera è 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 vorresti 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 completo funzionante.

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 (deprecato) 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 ore sono lì?”, Claude potrebbe rispondere con:

JSON

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "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."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

Questa catena di pensiero dà intuizioni sul processo di ragionamento di Claude e può aiutarti a debuggare comportamenti inaspettati. È importante notare che Claude può usare vari formati per denotare la sua catena di pensiero. Il tuo codice dovrebbe trattare la catena di pensiero come qualsiasi altro testo generato dall’assistente, e non fare affidamento su convenzioni di formattazione specifiche.

Uso parallelo degli strumenti

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

Impostando disable_parallel_tool_use=true quando il tipo tool_choice è auto, che assicura che Claude usi al massimo uno strumento
Impostando disable_parallel_tool_use=true quando il tipo tool_choice è any o tool, 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 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-1-20250805",
    max_tokens=1024,
    tools=tools,
    messages=[
        {
            "role": "user",
            "content": "Com'è il tempo a SF e NYC, e che ore sono 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 ore sono 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: 14:30 PST"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_04",
                "content": "Ora di New York: 17:30 EST"
            }
        ]
    }
]

# Ottenere risposta finale
final_response = client.messages.create(
    model="claude-opus-4-1-20250805",
    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 tempo 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 client
client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

# Definire 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 ore sono lì?"
    }
]

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

# Controllare 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 esecuzione strumenti e formattare 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 = "14:30 PST"
        else:
            result = "17:30 EST"
    
    tool_results.append({
        "type": "tool_result",
        "tool_use_id": tool_use.id,
        "content": result
    })

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

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

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

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

Questo script dimostra:

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

Esegui questo script per testare la tua implementazione e assicurarti che Claude stia facendo 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.1, 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 il 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 di 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 tempo per Parigi, Londra e Tokyo allo stesso tempo."

Uso parallelo degli strumenti con Claude Sonnet 3.7Claude 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 degli strumenti in termini di token, 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 aderire alla beta dell’uso efficiente degli strumenti in termini di token, 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 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 risultati da 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 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-1-20250805",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Devo usare get_weather, e l'utente vuole SF, che è probabilmente San Francisco, CA."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

Quando ricevi una risposta di uso 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 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 strumento per cui questo è un risultato.
- content: Il risultato dello strumento, come stringa (ad es. "content": "15 gradi"), una lista di blocchi di contenuto annidati (ad es. "content": [{"type": "text", "text": "15 gradi"}]), o una lista di blocchi documento (ad es. "content": ["type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 gradi"}]). Questi blocchi di contenuto possono usare i tipi text, image o document.
- is_error (opzionale): Imposta su true se l’esecuzione dello strumento ha risultato in un errore.

Requisiti di formattazione importanti:

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

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 strumenti siano formattati correttamente.

Esempio di risultato strumento riuscito

Esempio di risultato 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 strumento vuoto

Esempio di risultato strumento con documenti

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "Il tempo è"},
        {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "15 gradi"
          }
        }
      ]
    }
  ]
}

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

Gestire risultati da strumenti server

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

Differenze da altre APIA 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 stop `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 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-1-20250805",
            max_tokens=4096,  # Limite aumentato
            messages=messages,
            tools=tools
        )

Gestire il motivo di stop `pause_turn`

Quando usi strumenti server come la ricerca web, l’API può restituire un motivo di stop pause_turn, indicando che l’API ha messo in pausa un turno di lunga durata. Ecco come gestire il motivo di stop 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 calcolo quantistico nel 2025"
        }
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 10
    }]
)

# Controllare se la risposta ha motivo di stop 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 calcolo quantistico 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 degli strumenti: 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 strumento

Se lo strumento stesso genera un errore durante l’esecuzione (ad es. un errore di rete quando recupera 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’utente, ad es. “Mi dispiace, non sono riuscito a recuperare il meteo attuale perché l’API del servizio meteo non è disponibile. Per favore riprova più tardi.”

Nome 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 per Claude per usare lo strumento correttamente. La tua migliore opzione durante lo sviluppo è provare la richiesta di nuovo con valori description più dettagliati nelle tue definizioni di strumento.Tuttavia, puoi anche continuare la conversazione in avanti con un tool_result che indica l’errore, e Claude proverà a usare lo strumento di nuovo con le informazioni mancanti compilate:

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Errore: Parametro obbligatorio 'location' 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 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 strumentiIl problema più comune è formattare incorrettamente i risultati 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 strumento
✅ Corretto: Tutti i risultati strumenti devono essere in un singolo messaggio utente

// ❌ Questo riduce l'uso parallelo degli strumenti
[
  {"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 parallelo degli strumenti
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1, tool_result_2]}  // Singolo messaggio
]

Vedi i requisiti di formattazione generali sopra per altre regole di formattazione.2. Prompt deboleIl 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 parallelo degli strumentiPer verificare che le chiamate di strumenti paralleli funzionino:

# Calcolare strumenti medi per messaggio di chiamata strumento
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"Strumenti medi per messaggio: {avg_tools_per_message}")
# Dovrebbe essere > 1.0 se le chiamate parallele funzionano

4. Comportamento specifico del modello

Claude Opus 4.1, Opus 4 e Sonnet 4: Eccellono nell’uso parallelo degli strumenti con prompt minimali
Claude Sonnet 3.7: Potrebbe aver bisogno di prompt più forti o uso efficiente degli strumenti in termini di token
Claude Haiku: Meno propenso a usare strumenti paralleli senza prompt esplicito

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 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 blocchi di contenuto tool use e tool result

Gestire risultati da strumenti client

Gestire risultati da strumenti server

Gestire il motivo di stop `max_tokens`

Gestire il motivo di stop `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 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 blocchi di contenuto tool use e tool result

​Gestire risultati da strumenti client

​Gestire risultati da strumenti server

​Gestire il motivo di stop max_tokens

​Gestire il motivo di stop pause_turn

​Risoluzione degli errori

Scegliere un modello

Specificare 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 blocchi di contenuto tool use e tool result

Gestire risultati da strumenti client

Gestire risultati da strumenti server

Gestire il motivo di stop `max_tokens`

Gestire il motivo di stop `pause_turn`

Risoluzione degli errori