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.

L’utilizzo di strumenti è ora generalmente disponibile in tutta la famiglia di modelli Claude 3 per gli sviluppatori che utilizzano l’API Anthropic Messages, Amazon Bedrock e Google Vertex AI! Continua a condividere le tue idee e suggerimenti utilizzando questo modulo.

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

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [
      {
        "name": "get_weather",
        "description": "Ottieni il meteo attuale in una determinata posizione",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "La città e lo stato, ad es. San Francisco, CA"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Com'è il tempo a San Francisco?"
      }
    ]
  }'

​
Come funziona l’utilizzo di strumenti

L’utilizzo di strumenti con Claude prevede i seguenti passaggi:

  1. Fornisci a Claude strumenti e un prompt utente: (richiesta API)
    • Definisci l’insieme di strumenti a cui vuoi che Claude abbia accesso, inclusi i loro nomi, descrizioni e schemi di input.
    • Fornisci un prompt utente che potrebbe richiedere l’uso di uno o più di questi strumenti per rispondere, come “Com’è il tempo a San Francisco?“.
  2. Claude utilizza uno strumento: (risposta API)
    • Claude valuta il prompt utente e decide se uno qualsiasi degli strumenti disponibili potrebbe aiutare con la query o il compito dell’utente. In tal caso, decide anche quali strumenti utilizzare e con quali input.
    • Claude costruisce una richiesta di utilizzo dello strumento correttamente formattata.
    • La risposta API avrà un stop_reason di tool_use, indicando che Claude vuole utilizzare uno strumento esterno.
  3. Estrai l’input dello strumento, esegui il codice e restituisci i risultati: (richiesta API)
    • Sul lato client, dovresti estrarre il nome dello strumento e l’input dalla richiesta di utilizzo dello strumento di Claude.
    • Esegui il codice effettivo dello strumento sul lato client.
    • Restituisci i risultati a Claude continuando la conversazione con un nuovo messaggio user contenente un blocco di contenuto tool_result.
  4. Claude utilizza il risultato dello strumento per formulare una risposta: (risposta API)
    • Dopo aver ricevuto i risultati dello strumento, Claude utilizzerà quelle informazioni per formulare la sua risposta finale al prompt utente originale.

I passaggi (3) e (4) sono opzionali: per alcuni flussi di lavoro, l’utilizzo dello strumento da parte di Claude è tutte le informazioni di cui hai bisogno e potresti non aver bisogno di restituire i risultati dello strumento a Claude.

Tutti gli strumenti sono forniti dall’utente

È importante notare che Claude non ha accesso a nessuno strumento integrato lato server. Tutti gli strumenti devono essere esplicitamente forniti da te, l’utente, in ogni richiesta API. Questo ti dà il pieno controllo e flessibilità sugli strumenti che Claude può utilizzare.

​
Specificare gli strumenti

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

  • name: Il nome dello strumento. Deve corrispondere all’espressione regolare ^[a-zA-Z0-9_-]{1,64}$.
  • description: Una descrizione dettagliata in testo semplice di ciò che fa lo strumento, quando dovrebbe essere usato e come si comporta.
  • input_schema: Un oggetto JSON Schema che definisce i parametri previsti per lo strumento.

Ecco un esempio di semplice definizione di strumento:

JSON
{
  "name": "get_weather",
  "description": "Ottieni il meteo attuale in una determinata posizione",
  "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”.

​
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 nelle prestazioni degli strumenti. Le tue descrizioni dovrebbero spiegare ogni dettaglio sullo 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 utilizzare 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.

Ecco un esempio di una buona descrizione di uno strumento:

JSON
{
  "name": "get_stock_price",
  "description": "Recupera il prezzo azionario corrente 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à il prezzo dell'ultima transazione in USD. Dovrebbe essere utilizzato quando l'utente chiede il prezzo corrente 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"]
  }
}

Al contrario, ecco un esempio di una cattiva descrizione di uno 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 cattiva descrizione è troppo breve e lascia Claude con molte domande aperte sul comportamento e l’utilizzo dello strumento.

​
Blocchi di contenuto per l’utilizzo e il risultato degli strumenti

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 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 allo input_schema dello strumento.

Ecco un esempio di risposta API con un blocco di contenuto tool_use:

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-opus-20240229",
  "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 codebase 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 una stringa (ad es. "content": "15 gradi") o una lista di blocchi di contenuto annidati (ad 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 provocato un errore.

Ecco un esempio di restituzione di un risultato di strumento riuscito:

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

Anche le immagini sono supportate in content:

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

Ed ecco un esempio di restituzione di un risultato di errore:

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

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

Puoi anche restituire un risultato di strumento non errato con content vuoto, indicando che lo strumento è stato eseguito con successo senza alcun output:

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

Differenze da altre API

Potresti avere familiarità con altre API che restituiscono l’utilizzo dello strumento separatamente dall’output principale del modello, o che utilizzano un role di messaggio speciale tool o function.

Al contrario, i modelli e l’API di Anthropic sono costruiti attorno a messaggi user e assistant alternati, dove ogni messaggio è un array di ricchi blocchi di contenuto: text, image, tool_use e tool_result.

In questo formato, i messaggi user rappresentano contenuti gestiti dal lato client e dall’utente/umano, mentre i messaggi assistant rappresentano contenuti gestiti dal lato server e dall’AI. Di conseguenza, non esiste un role di messaggio speciale tool o function e dovresti includere i blocchi tool_result nel content dei tuoi messaggi user.

​
Forzare l’utilizzo di uno strumento

In alcuni casi, potresti voler far utilizzare a Claude 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"}

Dicendo esplicitamente a Claude di utilizzare lo strumento get_weather, puoi incoraggiarlo a utilizzare lo strumento che desideri. Questa tecnica può essere utile per testare e fare il debug delle tue integrazioni di strumenti, o quando sai che lo strumento dovrebbe essere sempre utilizzato, indipendentemente dall’input.

Puoi anche dire a Claude di utilizzare uno qualsiasi degli strumenti forniti tramite {"type": "any"}. Il tool_choice predefinito è {"type": "auto"}, che consente a Claude di decidere se utilizzare o meno uno strumento.

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 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 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 di strumenti per un esempio completo funzionante.

​
Gestione degli errori

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

​
Errore di esecuzione dello strumento

Se lo strumento stesso genera un errore durante l’esecuzione (ad es. un errore di rete durante il recupero dei dati meteo), puoi restituire il messaggio di errore in content insieme a "is_error": true:

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

Claude incorporerà quindi questo errore nella sua risposta all’utente, ad es. “Mi dispiace, non sono stato in grado di recuperare il meteo attuale perché il servizio API meteo non è disponibile. Per favore riprova più tardi.”

​
Superamento del limite di token

Se la risposta di Claude viene troncata a causa del raggiungimento del limite max_tokens e la risposta troncata contiene un blocco di utilizzo dello strumento incompleto, dovrai riprovare la richiesta con un valore max_tokens più alto per ottenere l’utilizzo completo dello strumento.

​
Utilizzo non valido dello strumento

Se il tentativo di utilizzo di uno strumento da parte di Claude non è valido (ad es. parametri richiesti mancanti), di solito significa che non c’erano abbastanza informazioni per consentire a Claude di utilizzare correttamente lo strumento. La tua migliore scommessa durante lo sviluppo è riprovare la richiesta con valori description più dettagliati nelle definizioni dei tuoi strumenti.

Tuttavia, puoi anche continuare la conversazione con un tool_result che indica l’errore e Claude proverà a utilizzare nuovamente lo strumento con le informazioni mancanti compilate:

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

​
Utilizzo di strumenti con catena di pensiero

Quando utilizza gli strumenti, Claude mostrerà spesso la sua “catena di pensiero”, cioè il ragionamento passo dopo passo che utilizza per scomporre il problema e decidere quali strumenti utilizzare. Il modello Claude 3 Opus lo farà se tool_choice è impostato su auto (questo è il valore predefinito, vedi Forzare l’utilizzo di uno strumento), mentre 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:

JSON
{
  "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 fornisce informazioni sul processo di ragionamento di Claude e può aiutarti a fare il debug di comportamenti imprevisti.

Con il modello Claude 3 Sonnet, la catena di pensiero è meno comune per impostazione predefinita, ma puoi chiedere a Claude di 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. Per un esempio più approfondito, vedi esempio di utilizzo di strumenti con catena di pensiero.

È importante notare che, sebbene i tag <thinking> siano una convenzione comune che Claude utilizza per indicare 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>.

​
Migliori pratiche e limitazioni per l’utilizzo di strumenti

Quando utilizzi gli strumenti con Claude, tieni presente le seguenti limitazioni e migliori pratiche:

  • Utilizza Claude 3 Opus per navigare nell’utilizzo di strumenti complessi, Haiku se hai a che fare con strumenti semplici: Opus è in grado di gestire il maggior numero di strumenti simultanei ed è migliore nel rilevare argomenti mancanti rispetto ad altri modelli. È più probabile che chieda chiarimenti in casi ambigui in cui un argomento non è esplicitamente fornito o quando uno strumento potrebbe non essere necessario per completare la richiesta dell’utente. Haiku tende a provare a utilizzare gli strumenti più frequentemente (anche se non sono rilevanti per la query) e dedurrà i parametri mancanti se non sono esplicitamente forniti.
  • Numero di strumenti: Tutti i modelli Claude 3 possono mantenere un’accuratezza >90% anche quando lavorano con centinaia di strumenti semplici e un numero inferiore di strumenti complessi. Uno strumento “complesso” sarebbe uno con un gran numero di parametri o parametri con schemi complessi (ad es. oggetti annidati).
  • Strumenti complessi e profondamente annidati: Proprio come un essere umano, Claude può lavorare meglio con interfacce più semplici e strumenti più semplici. Se Claude ha difficoltà a utilizzare correttamente il tuo strumento, prova ad appiattire lo schema di input allontanandolo da oggetti json profondamente annidati e riduci il numero di input.
  • Utilizzo sequenziale degli strumenti: Claude generalmente preferisce utilizzare uno strumento alla volta, quindi utilizzare l’output di quello strumento per informare la sua azione successiva. Sebbene tu possa chiedere a Claude di utilizzare più strumenti in parallelo progettando attentamente il tuo prompt e gli strumenti, questo potrebbe portare Claude a compilare valori fittizi per i parametri che dipendono dai risultati di un utilizzo precedente dello strumento. Per ottenere i migliori risultati, progetta il tuo flusso di lavoro e gli strumenti per ottenere e lavorare con una serie di utilizzi sequenziali degli strumenti da parte di Claude.
  • Tentativi: Se la richiesta di utilizzo dello strumento di Claude non è valida o manca di parametri richiesti, puoi restituire una risposta di errore e Claude di solito riproverà la richiesta con le informazioni mancanti compilate. Tuttavia, dopo 2-3 tentativi falliti, Claude potrebbe rinunciare e restituire delle scuse all’utente invece di riprovare ulteriormente.
  • Debug: Quando fai il debug di un comportamento imprevisto nell’utilizzo degli strumenti, presta attenzione all’output della catena di pensiero di Claude (se presente) per capire perché sta facendo le scelte che sta facendo. Puoi anche provare a chiedere a Claude di utilizzare uno strumento specifico per vedere se questo porta al comportamento previsto. Se Claude sta utilizzando in modo errato uno strumento, ricontrolla che le descrizioni e gli schemi dei tuoi strumenti siano chiari e non ambigui.
  • Tag <search_quality_reflection>: A volte, quando si utilizzano strumenti di ricerca, il modello può restituire tag XML <search_quality_reflection> e un punteggio di qualità della ricerca nella sua risposta. Per impedire al modello di farlo, aggiungi la frase “Non riflettere sulla qualità dei risultati di ricerca restituiti nella tua risposta.” alla fine del tuo prompt.

Tenendo presenti queste limitazioni e linee guida, puoi progettare strumenti efficaci e orchestrazioni agentive che estendono significativamente le capacità di Claude per affrontare un’ampia varietà di compiti.

​
Cronologia delle versioni beta

  • 30 maggio 2024: L’utilizzo di strumenti viene lanciato in GA e non è più in beta
  • tools-2024-05-16
    • Modifica del prompt di sistema per Opus per gestire meglio gli scenari in cui potrebbero essere necessari più utilizzi di strumenti in un singolo turno
  • tools-2024-04-04: Rilascio beta iniziale per l’utilizzo di strumenti

​
Prossimi passi

L’utilizzo di strumenti è una tecnica potente per estendere le capacità di Claude collegandolo a fonti di dati e funzionalità esterne. Con un insieme ben progettato di strumenti, puoi consentire a Claude di affrontare un’enorme varietà di compiti che sarebbero impossibili con la sua sola conoscenza di base.

Alcuni potenziali passi successivi da esplorare:

  • Sfoglia i nostri ricettari sull’utilizzo di strumenti: esplora il nostro repository di esempi di codice pronti per l’implementazione sull’utilizzo di strumenti, come:
  • Migliora la qualità e l’affidabilità dell’utilizzo degli strumenti: Itera e migliora le descrizioni e i prompt dei tuoi strumenti per ottenere un utilizzo più affidabile e accurato degli strumenti da parte di Claude
  • Espandi le capacità di Claude:
    • Sperimenta diversi strumenti e schemi per vedere come Claude gestisce diversi tipi di formati di input e output.
    • Concatena più strumenti insieme per scomporre compiti complessi in una serie di passaggi più semplici.
    • Costruisci orchestrazioni agentive in cui Claude può completare una varietà di compiti dall’inizio alla fine come se fosse un assistente.
    • Esplora architetture complesse di utilizzo di strumenti come dare a Claude strumenti per eseguire ricerche RAG, o per chiamare sottoagenti di modelli più piccoli, come Haiku, per eseguire compiti per suo conto

Mentre costruisci con l’utilizzo di strumenti, ci piacerebbe sentire il tuo feedback e vedere cosa crei! Unisciti al nostro Discord per sviluppatori per condividere i tuoi progetti e discutere suggerimenti e tecniche con altri sviluppatori.

Siamo entusiasti di vedere come utilizzerai l’uso di strumenti per spingere i confini di ciò che è possibile con Claude. Buon lavoro!

Google Sheets add-onEsempi di utilizzo degli strumenti