Utilizzo degli strumenti (chiamata di funzione)

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 compiti.

Ecco un esempio di come fornire strumenti a Claude usando 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 dello strumento di Claude (passaggio 2) potrebbe essere tutto ciò di cui hai bisogno, senza inviare i risultati di nuovo a Claude.

​

Come implementare l’utilizzo degli strumenti

​

Scegliere un modello

In generale, usa Claude 3 Opus per strumenti complessi e query ambigue; gestisce meglio più strumenti e cerca chiarimenti quando necessario.

Usa Haiku per strumenti semplici, ma nota che potrebbe inferire 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 data 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"]
  }
}

​

Migliori pratiche per le definizioni degli strumenti

Per ottenere le migliori prestazioni da Claude quando si usano 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, inclusi:
  • Cosa fa lo strumento
  • Quando dovrebbe essere usato (e quando no)
  • Cosa significa ogni parametro e come influisce sul 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à in grado di decidere quando e come usarli. Mira ad almeno 3-4 frasi per descrizione dello strumento, di più se lo strumento è complesso.
• Dai priorità alle descrizioni rispetto agli esempi. Sebbene tu possa 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.

{
  "name": "get_stock_price",
  "description": "Recupera il prezzo azionario attuale per un dato simbolo ticker. Il simbolo ticker deve essere un simbolo valido per una società quotata in borsa su una grande borsa statunitense come NYSE o NASDAQ. Lo strumento restituirà il prezzo dell'ultima transazione in USD. Dovrebbe essere usato 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, ad 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 Claude con molte domande aperte sul comportamento e l’utilizzo dello strumento.

​

Controllare l’output di Claude

​

Forzare l’uso dello strumento

In alcuni casi, potresti voler far usare a Claude 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 in questo modo:

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

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

• 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. Ciò 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.

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 al modello di utilizzare uno strumento specifico, puoi utilizzare {"type": "auto"} per tool_choice (il valore predefinito) e aggiungere istruzioni esplicite in un messaggio user. Ad esempio: Com'è il tempo 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 un output JSON che segue uno schema fornito. Ad 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 si usano 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 dello strumento), e Sonnet e Haiku possono essere indotti a farlo.

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

{
  "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 dà un’idea del processo di ragionamento di Claude e può aiutarti a debuggare comportamenti imprevisti.

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

È importante notare che, sebbene i tag <thinking> siano una convenzione comune che Claude usa per denotare la sua catena di pensiero, il formato esatto (come il nome di questo tag XML) può 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>.

​

Gestire i blocchi di contenuto tool use e tool result

Quando Claude decide di usare 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 dell’API che includono:

• id: Un identificatore univoco per questo particolare blocco di utilizzo dello strumento. Questo verrà usato per abbinare i risultati dello strumento in seguito.
• name: Il nome dello strumento utilizzato.
• input: Un oggetto contenente l’input passato allo strumento, conforme allo input_schema dello strumento.

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20240620",
  "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 utilizzo dello strumento, dovresti:

1. Estrarre name, id e input dal blocco tool_use.
2. Eseguire lo strumento effettivo nel tuo codice corrispondente a quel nome di 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 dello strumento per cui questo è un risultato.
   • content: Il risultato dello strumento, come stringa (ad es. "content": "15 gradi") o elenco 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): Impostato su true se l’esecuzione dello strumento ha provocato 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à quelle informazioni per continuare a generare una risposta al prompt originale dell’utente.

​

Risoluzione dei problemi

Ci sono alcuni 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: l'API del servizio meteo non è disponibile (HTTP 500)",
      "is_error": true
    }
  ]
}

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

​

Esempi di utilizzo degli strumenti

Ecco alcuni esempi di codice che dimostrano vari modelli 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-20240620",
  "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-20240620",
  "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 degli strumenti sono tariffate come qualsiasi altra richiesta API di Claude, in base al numero totale di token di input inviati al modello (incluso nel parametro tools) e al 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 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 panoramica dei modelli per i prezzi attuali per modello.

Quando invii un prompt di utilizzo degli strumenti, 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 degli strumenti pronti per l’implementazione nei nostri ricettari: