Utilizzo degli strumenti con Claude

Claude è in grado di interagire con strumenti e funzioni esterni lato client, permettendoti di equipaggiare Claude con i tuoi strumenti personalizzati per eseguire una più ampia varietà di attività.

Ecco un esempio di come fornire strumenti a Claude utilizzando l’API Messages:

​

Come funziona l’uso degli strumenti

Integra strumenti esterni con Claude in questi passaggi:

Nota: I passaggi 3 e 4 sono opzionali. Per alcuni flussi di lavoro, la richiesta di utilizzo dello strumento di Claude (passaggio 2) potrebbe essere tutto ciò di cui hai bisogno, senza inviare risultati a Claude.

​

Come implementare l’uso degli strumenti

​

Scelta di un modello

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

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

​

Specificare gli strumenti

Gli strumenti sono specificati nel parametro di primo livello tools della richiesta API. Ogni definizione di strumento include:

{
  "name": "get_weather",
  "description": "Get the current weather in a given location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and state, e.g. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

​

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 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 utilizzare per rispondere alla domanda dell'utente.
{{ ISTRUZIONI DI FORMATTAZIONE }}
I parametri stringa e scalari devono essere specificati così come sono, mentre liste e oggetti devono utilizzare il formato JSON. Nota che gli spazi per i valori stringa non vengono rimossi. L'output non deve essere 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 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, incluso:
  • Cosa fa lo strumento
  • Quando dovrebbe essere usato (e quando non dovrebbe)
  • Cosa significa ogni parametro e come influenza il comportamento dello strumento
  • Eventuali importanti avvertenze o limitazioni, 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 completamente sviluppato la descrizione.

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

{
  "name": "get_stock_price",
  "description": "Gets the stock price for a 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 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 tre possibili opzioni:

• auto permette a Claude di decidere se chiamare o meno gli strumenti forniti. Questo è il valore predefinito.
• 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.

Questo diagramma illustra come funziona ogni opzione:

Nota che quando hai tool_choice come any o tool, precompiliamo il messaggio dell’assistente per forzare l’uso di uno strumento. Questo significa che i modelli non emetteranno un blocco di contenuto text chain-of-thought 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 il chain-of-thought (in particolare con Opus) mentre richiedi comunque che il modello utilizzi uno strumento specifico, puoi usare {"type": "auto"} per tool_choice (il default) e aggiungere istruzioni esplicite in un messaggio user. Per 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 lato 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 esempi di utilizzo degli strumenti per un esempio completo funzionante.

​

Catena di pensiero

Quando usa gli strumenti, Claude spesso mostrerà 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 3 Opus lo farà 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 “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 debuggare comportamenti inaspettati.

Con il modello Claude 3 Sonnet, la catena di pensiero è meno comune per impostazione predefinita, ma puoi spingere Claude a mostrare il suo ragionamento aggiungendo qualcosa come "Before answering, explain your reasoning step-by-step in tags." 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 sulla formattazione specifica dei tag <thinking>.

​

Disabilitare l’uso parallelo degli strumenti

Per impostazione predefinita, Claude può utilizzare più strumenti per rispondere a una query utente. Puoi disabilitare questo comportamento impostando disable_parallel_tool_use=true nel campo tool_choice.

• Quando il tipo di tool_choice è auto, questo assicura che Claude usi al massimo uno strumento
• Quando il tipo di tool_choice è any o tool, questo assicura che Claude usi esattamente uno strumento

​

Gestire i blocchi di contenuto tool_use e tool_result

Quando Claude decide di utilizzare uno degli strumenti che hai fornito, restituirà una risposta con un stop_reason di tool_use e uno o più blocchi di contenuto tool_use nella risposta API che includono:

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

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-7-sonnet-20250219",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>I need to use the get_weather, and the user wants SF, which is likely 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 utilizzo dello strumento, dovresti:

1. Estrarre il name, id e input dal blocco tool_use.
2. Eseguire lo strumento effettivo nel tuo codebase corrispondente a quel nome 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 (es. "content": "15 degrees") o lista di blocchi di contenuto annidati (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 prodotto un errore.

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}

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

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
    }
  ]
}

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

​

Risoluzione dei problemi

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

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: the weather service API is not available (HTTP 500)",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Missing required 'location' parameter",
      "is_error": true
    }
  ]
}

​

Esempi di utilizzo degli strumenti

Ecco alcuni esempi di codice che dimostrano vari pattern e tecniche di utilizzo degli strumenti. Per brevità, gli strumenti sono strumenti semplici, e le descrizioni degli strumenti sono più brevi di quanto sarebbe ideale per garantire le migliori prestazioni.

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-7-sonnet-20250219",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>I need to call the get_weather function, and the user wants SF, which is likely San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-7-sonnet-20250219",
  "stop_reason": "stop_sequence",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "The current weather in San Francisco is 15 degrees Celsius (59 degrees Fahrenheit). It's a cool day in the city by the bay!"
    }
  ]
}

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "get_weather",
  "input": {"location": "New York, NY", "unit": "fahrenheit"}
}

​

Prezzi

Le richieste di utilizzo degli strumenti hanno lo stesso prezzo di qualsiasi altra richiesta API Claude, basato sul numero totale di token di input inviati al modello (inclusi nel parametro tools) e il numero di token di output generati.”

I token aggiuntivi dall’uso degli strumenti provengono da:

• Il parametro tools nelle richieste API (nomi degli strumenti, descrizioni e schemi)
• Blocchi di contenuto tool_use nelle richieste e risposte API
• Blocchi di contenuto tool_result nelle richieste API

Quando usi tools, includiamo anche automaticamente un prompt di sistema speciale per il modello che abilita l’uso degli strumenti. Il numero di token di utilizzo degli strumenti richiesti per ogni modello sono elencati di seguito (esclusi i token aggiuntivi elencati sopra):

Questi conteggi di token vengono aggiunti ai tuoi normali token di input e output per calcolare il costo totale di una richiesta. Fai riferimento alla nostra tabella di panoramica dei modelli per i prezzi attuali per modello.

Quando invii un prompt di utilizzo dello strumento, proprio come qualsiasi altra richiesta API, la risposta restituirà sia i conteggi dei token di input che di output come parte delle metriche di usage riportate.

​

Prossimi passi

Esplora il nostro repository di esempi di codice per l’uso degli strumenti pronti per l’implementazione nei nostri cookbooks: