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

​
Strumento singolo

Questo esempio mostra una situazione di base con un singolo strumento, utilizzando uno strumento get_weather.

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "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 esempio San Francisco, CA"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "L'unità di temperatura, \"celsius\" o \"fahrenheit\""
                }
            },
            "required": ["location"]
        }
    }],
    "messages": [{"role": "user", "content": "Com'è il tempo a San Francisco?"}]
}'

Claude restituirà una risposta simile a:

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-opus-20240229",
  "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"}
    }
  ]
}

Dovresti quindi eseguire la funzione get_weather con l’input fornito e restituire il risultato in un nuovo messaggio user:

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "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 esempio San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "L'unità di temperatura, \"celsius\" o \"fahrenheit\""
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Com'è il tempo a San Francisco?"
        },
        {
            "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"
                    }
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
                    "content": "15 gradi"
                }
            ]
        }
    ]
}'

Questo stamperà la risposta finale di Claude, incorporando i dati meteo:

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-opus-20240229",
  "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!"
    }
  ]
}

​
Informazioni mancanti

Se il prompt dell’utente non include abbastanza informazioni per compilare tutti i parametri richiesti per uno strumento, Claude 3 Opus è molto più propenso a riconoscere che manca un parametro e a chiederlo. Claude 3 Sonnet potrebbe chiedere, specialmente quando viene richiesto di pensare prima di generare una richiesta di strumento. Ma potrebbe anche fare del suo meglio per dedurre un valore ragionevole.

Ad esempio, utilizzando lo strumento get_weather di cui sopra, se chiedi a Claude “Com’è il tempo?” senza specificare una posizione, Claude, in particolare Claude 3 Sonnet, potrebbe fare una supposizione sugli input degli strumenti:

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

Questo comportamento non è garantito, specialmente per prompt più ambigui e per modelli meno intelligenti di Claude 3 Opus. Se Claude 3 Opus non ha abbastanza contesto per compilare i parametri richiesti, è molto più probabile che risponda con una domanda di chiarimento invece di effettuare una chiamata allo strumento.

​
Strumenti multipli

Puoi fornire a Claude più strumenti tra cui scegliere in una singola richiesta. Ecco un esempio con sia uno strumento get_weather che uno strumento get_time, insieme a una query dell’utente che richiede entrambi.

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "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 esempio San Francisco, CA"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "L'unità di temperatura, 'celsius' o 'fahrenheit'"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Ottieni l'ora attuale in un determinato fuso orario",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "Il nome del fuso orario IANA, ad esempio America/Los_Angeles"
                }
            },
            "required": ["timezone"]
        }
    }],
    "messages": [{
        "role": "user",
        "content": "Com'è il tempo in questo momento a New York? E che ora è lì?"
    }]
}'

In questo caso, Claude molto probabilmente cercherà di utilizzare due strumenti separati, uno alla volta - get_weather e poi get_time - per rispondere completamente alla domanda dell’utente. Tuttavia, occasionalmente potrebbe anche generare due blocchi tool_use contemporaneamente, in particolare se non sono dipendenti l’uno dall’altro. Dovresti eseguire ogni strumento e restituire i loro risultati in blocchi tool_result separati all’interno di un singolo messaggio user.

​
Strumenti sequenziali

Alcuni compiti potrebbero richiedere di chiamare più strumenti in sequenza, utilizzando l’output di uno strumento come input per un altro. In tal caso, Claude chiamerà uno strumento alla volta. Se viene richiesto di chiamare tutti gli strumenti contemporaneamente, Claude probabilmente supporrà i parametri per gli strumenti più a valle se dipendono dai risultati degli strumenti più a monte.

Ecco un esempio di utilizzo di uno strumento get_location per ottenere la posizione dell’utente, quindi passare tale posizione allo strumento get_weather:

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_location",
            "description": "Ottieni la posizione attuale dell'utente in base al suo indirizzo IP. Questo strumento non ha parametri o argomenti.",
            "input_schema": {
                "type": "object",
                "properties": {}
            }
        },
        {
            "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 esempio San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "L'unità di temperatura, 'celsius' o 'fahrenheit'"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [{
        "role": "user",
        "content": "Com'è il tempo dove mi trovo?"
    }]
}'

In questo caso, Claude chiamerebbe prima lo strumento get_location per ottenere la posizione dell’utente. Dopo aver restituito la posizione in un tool_result, Claude chiamerebbe quindi get_weather con quella posizione per ottenere la risposta finale.

La conversazione completa potrebbe essere simile a:

RuoloContenuto
UtenteCom’è il tempo dove mi trovo?
Assistente<thinking>Per rispondere, devo prima determinare la posizione dell’utente utilizzando lo strumento get_location. Quindi posso passare quella posizione allo strumento get_weather per trovare il meteo attuale lì.</thinking>[Utilizzo dello strumento per get_location]
Utente[Risultato dello strumento per get_location con id corrispondente e risultato di San Francisco, CA]
Assistente[Utilizzo dello strumento per get_weather con il seguente input]{ “location”: “San Francisco, CA”, “unit”: “fahrenheit” }
Utente[Risultato dello strumento per get_weather con id corrispondente e risultato di “59°F (15°C), per lo più nuvoloso”]
AssistenteIn base alla tua posizione attuale a San Francisco, CA, il meteo in questo momento è di 59°F (15°C) e per lo più nuvoloso. È una giornata piuttosto fresca e nuvolosa in città. Potresti voler portare una giacca leggera se esci.

Questo esempio dimostra come Claude possa concatenare più chiamate di strumenti per rispondere a una domanda che richiede la raccolta di dati da diverse fonti. I passaggi chiave sono:

  1. Claude si rende conto per primo che ha bisogno della posizione dell’utente per rispondere alla domanda sul meteo, quindi chiama lo strumento get_location.
  2. L’utente (cioè il codice client) esegue la funzione get_location effettiva e restituisce il risultato “San Francisco, CA” in un blocco tool_result.
  3. Ora che la posizione è nota, Claude procede a chiamare lo strumento get_weather, passando “San Francisco, CA” come parametro location (così come un parametro unit ipotizzato, poiché unit non è un parametro obbligatorio).
  4. L’utente esegue nuovamente la funzione get_weather effettiva con gli argomenti forniti e restituisce i dati meteo in un altro blocco tool_result.
  5. Infine, Claude incorpora i dati meteo in una risposta in linguaggio naturale alla domanda originale.

​
Utilizzo di strumenti con catena di pensiero

Per impostazione predefinita, Claude 3 Opus è istruito a pensare prima di rispondere a una query di utilizzo di strumenti per determinare al meglio se uno strumento è necessario, quale strumento utilizzare e i parametri appropriati. Claude 3 Sonnet e Claude 3 Haiku sono istruiti a cercare di utilizzare gli strumenti il più possibile e sono più propensi a chiamare uno strumento non necessario o a dedurre parametri mancanti. Per spingere Sonnet o Haiku a valutare meglio la query dell’utente prima di effettuare chiamate di strumenti, può essere utilizzato il seguente prompt:

Prompt di catena di pensiero

Rispondi alla richiesta dell'utente utilizzando strumenti pertinenti (se disponibili). Prima di chiamare uno strumento, fai un'analisi all'interno dei tag \<thinking>\</thinking>. Per prima cosa, pensa a quale degli strumenti forniti è lo strumento pertinente per rispondere alla richiesta dell'utente. In secondo luogo, esamina ciascuno dei parametri richiesti dallo strumento pertinente e determina se l'utente ha fornito direttamente o dato abbastanza informazioni per dedurre un valore. Quando decidi se il parametro può essere dedotto, considera attentamente tutto il contesto per vedere se supporta un valore specifico. Se tutti i parametri richiesti sono presenti o possono essere ragionevolmente dedotti, chiudi il tag di pensiero e procedi con la chiamata dello strumento. MA, se uno dei valori per un parametro richiesto manca, NON invocare la funzione (nemmeno con riempitivi per i parametri mancanti) e invece, chiedi all'utente di fornire i parametri mancanti. NON chiedere ulteriori informazioni sui parametri opzionali se non vengono fornite.

​
Modalità JSON

Puoi utilizzare gli strumenti per far produrre a Claude un output JSON che segue uno schema, anche se non hai intenzione di eseguire quell’output attraverso uno strumento o una funzione.

Quando utilizzi gli strumenti in questo modo:

  • Di solito vuoi fornire un singolo strumento
  • Dovresti impostare tool_choice (vedi Forzare l’utilizzo di strumenti) per istruire il modello a utilizzare esplicitamente quello strumento
  • Ricorda che il modello passerà l’input allo strumento, quindi il nome dello strumento e la descrizione dovrebbero essere dal punto di vista del modello.

Quanto segue utilizza uno strumento record_summary per descrivere un’immagine seguendo un formato particolare.

#!/bin/bash
IMAGE_URL="https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
IMAGE_MEDIA_TYPE="image/jpeg"
IMAGE_BASE64=$(curl "$IMAGE_URL" | base64)

curl https://api.anthropic.com/v1/messages \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --data \
'{
    "model": "claude-3-sonnet-20240229",
    "max_tokens": 1024,
    "tools": [{
        "name": "record_summary",
        "description": "Registra il riepilogo di un'immagine utilizzando JSON ben strutturato.",
        "input_schema": {
            "type": "object",
            "properties": {
                "key_colors": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
"r": { "type": "number", "description": "valore rosso [0.0, 1.0]" },
"g": { "type": "number", "description": "valore verde [0.0, 1.0]" },
"b": { "type": "number", "description": "valore blu [0.0, 1.0]" },
"name": { "type": "string", "description": "Nome del colore leggibile dall'uomo in snake_case, ad esempio \"olive_green\" o \"turquoise\"" }
                        },
                        "required": [ "r", "g", "b", "name" ]
                    },
                    "description": "Colori chiave nell'immagine. Limitare a meno di quattro."
                },
                "description": {
                    "type": "string",
                    "description": "Descrizione dell'immagine. Una o due frasi al massimo."
                },
                "estimated_year": {
                    "type": "integer",
                    "description": "Anno stimato in cui è stata scattata l'immagine, se è una foto. Impostare solo se l'immagine sembra essere non fittizia. Stime approssimative vanno bene!"
                }
            },
            "required": [ "key_colors", "description" ]
        }
    }],
    "tool_choice": {"type": "tool", "name": "record_summary"},
    "messages": [
        {"role": "user", "content": [
            {"type": "image", "source": {
                "type": "base64",
                "media_type": "'$IMAGE_MEDIA_TYPE'",
                "data": "'$IMAGE_BASE64'"
            }},
            {"type": "text", "text": "Descrivi questa immagine."}
        ]}
    ]
}'
PanoramicaPrezzi e token per l'uso degli strumenti