Utilizzo degli strumenti (chiamate di funzione)

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

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

​

Come funziona l’utilizzo 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 strumento di Claude (passaggio 2) potrebbe essere tutto ciò di cui hai bisogno, senza inviare risultati a Claude.

​

Come implementare l’utilizzo degli strumenti

​

Scegliere un modello

In generale, usa 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": "Ottieni il meteo attuale in una determinata località",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "La città e lo stato, es. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "L'unità di temperatura, 'celsius' o 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

​

Prompt di sistema per l’utilizzo 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 una serie 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": "Recupera il prezzo attuale delle azioni per un dato simbolo ticker. Il simbolo ticker deve essere un simbolo valido per una società quotata in borsa su una delle principali borse statunitensi come NYSE o NASDAQ. Lo strumento restituirà l'ultimo prezzo di scambio in USD. Dovrebbe essere utilizzato quando l'utente chiede il 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, es. AAPL per Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

{
  "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 scadente è troppo breve e lascia a Claude molte domande aperte sul comportamento e l’utilizzo dello strumento.

​

Controllare l’output di Claude

​

Forzare l’utilizzo 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 così:

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, precompileremo 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: Che tempo fa a Londra? Usa lo strumento get_weather nella tua risposta.

​

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’utilizzo degli strumenti), e Sonnet e Haiku possono essere sollecitati a farlo.

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

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Per rispondere a questa domanda, dovrò: 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 informazioni sul processo di ragionamento di Claude e può aiutare a debuggare comportamenti inaspettati.

Con il modello Claude 3 Sonnet, la catena di pensiero è meno comune per impostazione predefinita, ma puoi sollecitare Claude a mostrare il suo ragionamento aggiungendo qualcosa come "Prima di rispondere, spiega il tuo ragionamento passo dopo passo nei 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 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 uno 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 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-5-sonnet-20241022",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Ho bisogno di 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 utilizzo 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. [opzionale] 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 strumento per cui questo è un risultato.
   • content: Il risultato dello strumento, come stringa (es. "content": "15 gradi") o lista di blocchi di contenuto annidati (es. "content": [{"type": "text", "text": "15 gradi"}]). 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 gradi"
    }
  ]
}

{
  "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...",
          }
        }
      ]
    }
  ]
}

{
  "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 usano gli strumenti con Claude:

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

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Errore: Parametro 'location' obbligatorio mancante",
      "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-5-sonnet-20241022",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Devo chiamare la funzione 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"}
    }
  ]
}

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "stop_sequence",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Il meteo attuale a San Francisco è di 15 gradi Celsius (59 gradi Fahrenheit). È una giornata fresca nella città sulla baia!"
    }
  ]
}

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

​

Prezzi

Le richieste di utilizzo 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’utilizzo 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’utilizzo degli strumenti. Il numero di token di utilizzo 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 strumento, proprio come qualsiasi altra richiesta API, la risposta emetterà 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 di utilizzo strumenti pronti per l’implementazione nei nostri cookbooks: