Come implementare l'uso degli strumenti

​

Scegliere un modello

In generale, utilizza 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.

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

​

Specificare gli strumenti client

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

​

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 utilizzare lo/gli strumento/i specificato/i e fornire il contesto necessario affinché lo strumento funzioni correttamente:

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

​

Best practice per le definizioni degli strumenti

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

• Fornisci descrizioni estremamente dettagliate. Questo è di gran lunga il fattore più importante per le prestazioni degli strumenti. Le tue descrizioni dovrebbero spiegare ogni dettaglio sullo strumento, inclusi:
  • Cosa fa lo strumento
  • Quando dovrebbe essere utilizzato (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 utilizzarli. Punta ad almeno 3-4 frasi per descrizione dello strumento, di più se lo strumento è complesso.
• Dai priorità alle descrizioni rispetto agli esempi. Mentre puoi includere esempi di come utilizzare uno strumento nella sua descrizione o nel prompt di accompagnamento, questo è meno importante che avere una spiegazione chiara e completa dello scopo e dei parametri dello strumento. Aggiungi esempi solo dopo aver sviluppato completamente la descrizione.

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

​

Controllare l’output di Claude

​

Forzare l’uso degli strumenti

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

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

Quando si lavora con il parametro tool_choice, abbiamo quattro possibili opzioni:

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

Questo diagramma illustra come funziona ciascuna opzione:

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

I nostri test hanno dimostrato che questo non dovrebbe ridurre le prestazioni. Se desideri mantenere la catena di pensiero (in particolare con Opus) pur richiedendo che il modello utilizzi uno strumento specifico, puoi usare {"type": "auto"} per tool_choice (il valore predefinito) e aggiungere istruzioni esplicite in un messaggio user. Ad esempio: What's the weather like in London? Use the get_weather tool in your response.

​

Output JSON

Gli strumenti non devono necessariamente essere funzioni client — puoi utilizzare gli strumenti ogni volta che desideri che il modello restituisca un output JSON che segue uno schema fornito. Ad esempio, potresti utilizzare uno strumento record_summary con uno schema particolare. Vedi esempi di utilizzo degli strumenti per un esempio completo funzionante.

​

Catena di pensiero

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

Ad esempio, dato il prompt “What’s the weather like in San Francisco right now, and what time is it there?”, Claude potrebbe rispondere con:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>To answer this question, I will: 1. Use the get_weather tool to get the current weather in San Francisco. 2. Use the get_time tool to get the current time in the America/Los_Angeles timezone, which covers San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

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

Con il modello Claude Sonnet 3, la catena di pensiero è meno comune per impostazione predefinita, ma puoi indurre Claude a mostrare il suo ragionamento aggiungendo qualcosa come "Before answering, explain your reasoning step-by-step in tags." al messaggio dell’utente o al prompt di sistema.

È importante notare che mentre i tag <thinking> sono una convenzione comune che Claude utilizza per indicare 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 sulla formattazione specifica dei tag <thinking>.

​

Uso parallelo degli strumenti

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

• Impostando disable_parallel_tool_use=true quando il tipo di tool_choice è auto, il che garantisce che Claude utilizzi al massimo uno strumento
• Impostando disable_parallel_tool_use=true quando il tipo di tool_choice è any o tool, il che garantisce che Claude utilizzi esattamente uno strumento

​

Gestione dei blocchi di contenuto tool_use e tool_result

La risposta di Claude differisce a seconda che utilizzi uno strumento client o server.

​

Gestione dei 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 univoco per questo particolare blocco di utilizzo dello strumento. Questo verrà utilizzato per abbinare i risultati dello strumento in seguito.
• name: Il nome dello strumento utilizzato.
• input: Un oggetto contenente l’input passato allo strumento, conforme all’input_schema dello strumento.

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

1. Estrarre il name, l’id e l’input dal blocco tool_use.
2. Eseguire lo strumento effettivo nel tuo codebase corrispondente a quel nome di strumento, passando l’input dello strumento.
3. 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 utilizzo dello strumento per cui questo è un risultato.
   • content: Il risultato dello strumento, come stringa (ad es. "content": "15 degrees") o elenco di blocchi di contenuto annidati (ad es. "content": [{"type": "text", "text": "15 degrees"}]). Questi blocchi di contenuto possono utilizzare i tipi text o image.
   • is_error (opzionale): Impostato su true se l’esecuzione dello strumento ha generato un errore.

Dopo aver ricevuto il risultato dello strumento, Claude utilizzerà queste informazioni per continuare a generare una risposta al prompt originale dell’utente.

​

Gestione dei risultati dagli strumenti server

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

​

Gestione del motivo di arresto pause_turn

Quando si utilizzano 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()

# Initial request with web search
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025"
        }
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 10
    }]
)

# Check if the response has pause_turn stop reason
if response.stop_reason == "pause_turn":
    # Continue the conversation with the paused content
    messages = [
        {"role": "user", "content": "Search for comprehensive information about quantum computing breakthroughs in 2025"},
        {"role": "assistant", "content": response.content}
    ]
    
    # Send the continuation request
    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 si gestisce 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 dei problemi

Ci sono diversi tipi di errori che possono verificarsi quando si utilizzano gli strumenti con Claude: