Uso di strumenti con Claude

Claude è in grado di interagire con strumenti e funzioni, permettendoti di estendere le capacità di Claude per eseguire una varietà più ampia di compiti.

Impara tutto quello che ti serve per padroneggiare l’uso degli strumenti con Claude come parte dei nostri nuovi corsi! Per favore 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-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
      {
        "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"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What is the weather like in San Francisco?"
      }
    ]
  }'

Come funziona l’uso degli strumenti

Claude supporta due tipi di strumenti:

Strumenti client: Strumenti che vengono eseguiti sui tuoi sistemi, che includono:
- Strumenti personalizzati definiti dall’utente che crei e implementi
- Strumenti definiti da Anthropic come uso del computer e editor di testo che richiedono implementazione client
Strumenti server: Strumenti che vengono eseguiti sui server di Anthropic, come gli strumenti ricerca web e recupero web. Questi strumenti devono essere specificati nella richiesta API ma non richiedono implementazione da parte tua.

Gli strumenti definiti da Anthropic utilizzano tipi versionati (ad esempio, web_search_20250305, text_editor_20250124) per garantire compatibilità tra le versioni del modello.

Strumenti client

Integra gli strumenti client con Claude in questi passaggi:

Fornisci a Claude strumenti e un prompt utente

Definisci gli strumenti client con nomi, descrizioni e schemi di input nella tua richiesta API.
Includi un prompt utente che potrebbe richiedere questi strumenti, ad esempio, “Com’è il tempo a San Francisco?”

Claude decide di utilizzare uno strumento

Claude valuta se qualche strumento può aiutare con la query dell’utente.
Se sì, Claude costruisce una richiesta di uso strumento formattata correttamente.
Per gli strumenti client, la risposta API ha un stop_reason di tool_use, segnalando l’intenzione di Claude.

Esegui lo strumento e restituisci i risultati

Estrai il nome dello strumento e l’input dalla richiesta di Claude
Esegui il codice dello strumento sul tuo sistema
Restituisci i risultati in un nuovo messaggio user contenente un blocco di contenuto tool_result

Claude utilizza il risultato dello strumento per formulare una risposta

Claude analizza i risultati dello strumento per creare la sua risposta finale al prompt utente originale.

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

Strumenti server

Gli strumenti server seguono un flusso di lavoro diverso:

Fornisci a Claude strumenti e un prompt utente

Gli strumenti server, come ricerca web e recupero web, hanno i loro parametri.
Includi un prompt utente che potrebbe richiedere questi strumenti, ad esempio, “Cerca le ultime notizie sull’IA” o “Analizza il contenuto a questo URL.”

Claude esegue lo strumento server

Claude valuta se uno strumento server può aiutare con la query dell’utente.
Se sì, Claude esegue lo strumento, e i risultati vengono automaticamente incorporati nella risposta di Claude.

Claude utilizza il risultato dello strumento server per formulare una risposta

Claude analizza i risultati dello strumento server per creare la sua risposta finale al prompt utente originale.
Non è necessaria alcuna interazione utente aggiuntiva per l’esecuzione dello strumento server.

Esempi di uso degli strumenti

Ecco alcuni esempi di codice che dimostrano vari modelli e tecniche di uso 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.

Esempio di strumento singolo

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-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [{
        "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"]
        }
    }],
    "messages": [{"role": "user", "content": "What is the weather like in San Francisco?"}]
}'

Claude restituirà una risposta simile a:

JSON

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-1-20250805",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll check the current weather in San Francisco for you."
    },
    {
      "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-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
        {
            "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"]
            }
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What is the weather like in San Francisco?"
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I'll check the current weather in San Francisco for you."
                },
                {
                    "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 degrees"
                }
            ]
        }
    ]
}'

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

JSON

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-1-20250805",
  "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!"
    }
  ]
}

Uso di strumenti paralleli

Esempio di 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 get_time, insieme a una query utente che chiede 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-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [{
        "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"]
        }
    },
    {
        "name": "get_time",
        "description": "Get the current time in a given time zone",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "The IANA time zone name, e.g. America/Los_Angeles"
                }
            },
            "required": ["timezone"]
        }
    }],
    "messages": [{
        "role": "user",
        "content": "What is the weather like right now in New York? Also what time is it there?"
    }]
}'

In questo caso, Claude può:

Utilizzare gli strumenti sequenzialmente (uno alla volta) — chiamando prima get_weather, poi get_time dopo aver ricevuto il risultato meteorologico
Utilizzare chiamate di strumenti paralleli — producendo più blocchi tool_use in una singola risposta quando le operazioni sono indipendenti

Quando Claude effettua chiamate di strumenti paralleli, devi restituire tutti i risultati degli strumenti in un singolo messaggio user, con ogni risultato nel proprio blocco tool_result.

Informazioni mancanti

Se il prompt dell’utente non include abbastanza informazioni per riempire tutti i parametri richiesti per uno strumento, Claude Opus è molto più propenso a riconoscere che un parametro manca e a chiederlo. Claude Sonnet può chiedere, specialmente quando viene sollecitato a pensare prima di produrre una richiesta di strumento. Ma può anche fare del suo meglio per inferire un valore ragionevole.Ad esempio, utilizzando lo strumento get_weather sopra, se chiedi a Claude “Com’è il tempo?” senza specificare una posizione, Claude, in particolare Claude Sonnet, può fare una supposizione sui parametri 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. Se Claude Opus non ha abbastanza contesto per riempire i parametri richiesti, è molto più probabile che risponda con una domanda di chiarimento invece di effettuare una chiamata di strumento.

Strumenti sequenziali

Alcuni compiti possono 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 sollecitato a chiamare tutti gli strumenti contemporaneamente, Claude è probabile che indovini i parametri per gli strumenti più a valle se dipendono dai risultati degli strumenti per gli strumenti più a monte.Ecco un esempio di utilizzo di uno strumento get_location per ottenere la posizione dell’utente, quindi passare quella 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-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_location",
            "description": "Get the current user location based on their IP address. This tool has no parameters or arguments.",
            "input_schema": {
                "type": "object",
                "properties": {}
            }
        },
        {
            "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"]
            }
        }
    ],
    "messages": [{
        "role": "user",
        "content": "What is the weather like where I am?"
    }]
}'

In questo caso, Claude chiamerebbe prima lo strumento get_location per ottenere la posizione dell’utente. Dopo che restituisci la posizione in un tool_result, Claude chiamerebbe poi get_weather con quella posizione per ottenere la risposta finale.La conversazione completa potrebbe apparire così:

Ruolo	Contenuto
User	Com’è il tempo dove mi trovo?
Assistant	Troverò prima la tua posizione attuale, poi controllerò il tempo lì. [Uso strumento per get_location]
User	[Risultato strumento per get_location con id corrispondente e risultato di San Francisco, CA]
Assistant	[Uso strumento per get_weather con il seguente input]{ “location”: “San Francisco, CA”, “unit”: “fahrenheit” }
User	[Risultato strumento per get_weather con id corrispondente e risultato di “59°F (15°C), per lo più nuvoloso”]
Assistant	Basandomi sulla tua posizione attuale a San Francisco, CA, il tempo in questo momento è 59°F (15°C) e per lo più nuvoloso. È una giornata abbastanza fresca e coperta in città. Potresti voler portare una giacca leggera se stai uscendo.

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

Claude prima si rende conto che ha bisogno della posizione dell’utente per rispondere alla domanda meteorologica, quindi chiama lo strumento get_location.
L’utente (cioè il codice client) esegue la funzione get_location effettiva e restituisce il risultato “San Francisco, CA” in un blocco tool_result.
Con la posizione ora conosciuta, Claude procede a chiamare lo strumento get_weather, passando “San Francisco, CA” come parametro location (così come un parametro unit indovinato, poiché unit non è un parametro richiesto).
L’utente esegue di nuovo la funzione get_weather effettiva con gli argomenti forniti e restituisce i dati meteorologici in un altro blocco tool_result.
Infine, Claude incorpora i dati meteorologici in una risposta in linguaggio naturale alla domanda originale.

Uso di strumenti con catena di pensiero

Modalità JSON

Puoi utilizzare gli strumenti per far produrre a Claude output JSON che segue uno schema, anche se non hai intenzione di eseguire quell’output attraverso uno strumento o funzione.Quando utilizzi gli strumenti in questo modo:

Di solito vuoi fornire un singolo strumento
Dovresti impostare tool_choice (vedi Forzare l’uso degli 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 dalla prospettiva del modello.

Il seguente 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-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [{
        "name": "record_summary",
        "description": "Record summary of an image using well-structured JSON.",
        "input_schema": {
            "type": "object",
            "properties": {
                "key_colors": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
"r": { "type": "number", "description": "red value [0.0, 1.0]" },
"g": { "type": "number", "description": "green value [0.0, 1.0]" },
"b": { "type": "number", "description": "blue value [0.0, 1.0]" },
"name": { "type": "string", "description": "Human-readable color name in snake_case, e.g. \"olive_green\" or \"turquoise\"" }
                        },
                        "required": [ "r", "g", "b", "name" ]
                    },
                    "description": "Key colors in the image. Limit to less than four."
                },
                "description": {
                    "type": "string",
                    "description": "Image description. One to two sentences max."
                },
                "estimated_year": {
                    "type": "integer",
                    "description": "Estimated year that the image was taken, if it is a photo. Only set this if the image appears to be non-fictional. Rough estimates are okay!"
                }
            },
            "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": "Describe this image."}
        ]}
    ]
}'

Prezzi

Tool use requests are priced based on:

The total number of input tokens sent to the model (including in the tools parameter)
The number of output tokens generated
For server-side tools, additional usage-based pricing (e.g., web search charges per search performed)

Client-side tools are priced the same as any other Claude API request, while server-side tools may incur additional charges based on their specific usage. The additional tokens from tool use come from:

The tools parameter in API requests (tool names, descriptions, and schemas)
tool_use content blocks in API requests and responses
tool_result content blocks in API requests

When you use tools, we also automatically include a special system prompt for the model which enables tool use. The number of tool use tokens required for each model are listed below (excluding the additional tokens listed above). Note that the table assumes at least 1 tool is provided. If no tools are provided, then a tool choice of none uses 0 additional system prompt tokens.

Model	Tool choice	Tool use system prompt token count
Claude Opus 4.1	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Opus 4	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 4	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 3.7	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 3.5 (Oct) (deprecated)	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 3.5 (June) (deprecated)	`auto`, `none` `any`, `tool`	294 tokens 261 tokens
Claude Haiku 3.5	`auto`, `none` `any`, `tool`	264 tokens 340 tokens
Claude Opus 3 (deprecated)	`auto`, `none` `any`, `tool`	530 tokens 281 tokens
Claude Sonnet 3	`auto`, `none` `any`, `tool`	159 tokens 235 tokens
Claude Haiku 3	`auto`, `none` `any`, `tool`	264 tokens 340 tokens

These token counts are added to your normal input and output tokens to calculate the total cost of a request. Fai riferimento alla nostra tabella di panoramica dei modelli per i prezzi attuali per modello. Quando invii un prompt di uso strumento, proprio come qualsiasi altra richiesta API, la risposta produrrà sia i conteggi dei token di input che di output come parte delle metriche usage riportate.

Prossimi Passi

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

Strumento Calcolatrice

Impara come integrare un semplice strumento calcolatrice con Claude per calcoli numerici precisi.

Agente Servizio Clienti

Costruisci un bot di servizio clienti reattivo che sfrutta gli strumenti client per migliorare il supporto.

Estrattore JSON

Vedi come Claude e l’uso degli strumenti possono estrarre dati strutturati da testo non strutturato.

Primi passi

Modelli e prezzi

Scopri Claude

Funzionalità

Strumenti

Model Context Protocol (MCP)

Casi d'uso

Ingegneria dei prompt

Testa e valuta

Rafforza le protezioni

Centro legale

Uso di strumenti con Claude

Come funziona l’uso degli strumenti

Strumenti client

Strumenti server

Esempi di uso degli strumenti

Prezzi

Prossimi Passi

Strumento Calcolatrice

Agente Servizio Clienti

Estrattore JSON

Primi passi

Modelli e prezzi

Scopri Claude

Funzionalità

Strumenti

Model Context Protocol (MCP)

Casi d'uso

Ingegneria dei prompt

Testa e valuta

Rafforza le protezioni

Centro legale

​Come funziona l’uso degli strumenti

​Strumenti client

​Strumenti server

​Esempi di uso degli strumenti

​Prezzi

​Prossimi Passi

Strumento Calcolatrice

Agente Servizio Clienti

Estrattore JSON

Come funziona l’uso degli strumenti

Strumenti client

Strumenti server

Esempi di uso degli strumenti

Prezzi

Prossimi Passi