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! Ti preghiamo di continuare 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-sonnet-4-5",
    "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:
  1. 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
  2. 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:
1

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?”
2

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

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
4

Claude utilizza il risultato dello strumento per formulare una risposta

  • Claude analizza i risultati dello strumento per creare la sua risposta finale al prompt originale dell’utente.
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:
1

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.”
2

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

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 originale dell’utente.
  • Non è necessaria alcuna interazione aggiuntiva dell’utente 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. 
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-sonnet-4-5",
    "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-sonnet-4-5",
  "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-sonnet-4-5",
    "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-sonnet-4-5",
  "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!"
    }
  ]
}
Claude può chiamare più strumenti in parallelo all’interno di una singola risposta, il che è utile per compiti che richiedono più operazioni indipendenti. Quando si utilizzano strumenti paralleli, tutti i blocchi tool_use sono inclusi in un singolo messaggio assistente, e tutti i blocchi tool_result corrispondenti devono essere forniti nel messaggio utente successivo.
Importante: I risultati degli strumenti devono essere formattati correttamente per evitare errori API e garantire che Claude continui a utilizzare strumenti paralleli. Consulta la nostra guida all’implementazione per i requisiti di formattazione dettagliati e esempi di codice completi.
Per esempi completi, script di test e migliori pratiche per implementare chiamate di strumenti paralleli, consulta la sezione uso parallelo degli strumenti nella nostra guida all’implementazione.
Puoi fornire a Claude più strumenti tra cui scegliere in una singola richiesta. Ecco un esempio con entrambi gli strumenti get_weather e 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-sonnet-4-5",
    "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.
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.
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, poi 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-sonnet-4-5",
    "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ì:
RuoloContenuto
UtenteCom’è il tempo dove mi trovo?
AssistenteTroverò prima la tua posizione attuale, poi controllerò il tempo lì. [Uso strumento per get_location]
Utente[Risultato strumento per get_location con id corrispondente e risultato di San Francisco, CA]
Assistente[Uso strumento per get_weather con il seguente input]{ “location”: “San Francisco, CA”, “unit”: “fahrenheit” }
Utente[Risultato strumento per get_weather con id corrispondente e risultato di “59°F (15°C), prevalentemente nuvoloso”]
AssistenteBasandomi sulla tua posizione attuale a San Francisco, CA, il tempo in questo momento è 59°F (15°C) e prevalentemente nuvoloso. È una giornata piuttosto 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:
  1. Claude prima si rende conto che ha bisogno della posizione dell’utente per rispondere alla domanda meteorologica, 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. 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).
  4. L’utente esegue nuovamente la funzione get_weather effettiva con gli argomenti forniti e restituisce i dati meteorologici in un altro blocco tool_result.
  5. Infine, Claude incorpora i dati meteorologici in una risposta in linguaggio naturale alla domanda originale.
Per impostazione predefinita, Claude Opus è sollecitato a pensare prima di rispondere a una query di uso strumento per determinare al meglio se uno strumento è necessario, quale strumento utilizzare e i parametri appropriati. Claude Sonnet e Claude Haiku sono sollecitati a cercare di utilizzare gli strumenti il più possibile e sono più propensi a chiamare uno strumento non necessario o inferire parametri mancanti. Per sollecitare Sonnet o Haiku a valutare meglio la query dell’utente prima di effettuare chiamate di strumenti, può essere utilizzato il seguente prompt:Prompt catena di pensieroRispondi alla richiesta dell'utente utilizzando strumenti pertinenti (se sono disponibili). Prima di chiamare uno strumento, fai un'analisi. Primo, pensa a quale degli strumenti forniti è lo strumento pertinente per rispondere alla richiesta dell'utente. Secondo, esamina ciascuno dei parametri richiesti dello strumento pertinente e determina se l'utente ha fornito direttamente o dato abbastanza informazioni per inferire un valore. Quando decidi se il parametro può essere inferito, considera attentamente tutto il contesto per vedere se supporta un valore specifico. Se tutti i parametri richiesti sono presenti o possono essere ragionevolmente inferiti, 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 più informazioni sui parametri opzionali se non vengono forniti.
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 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-sonnet-4-5",
    "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:
  1. The total number of input tokens sent to the model (including in the tools parameter)
  2. The number of output tokens generated
  3. 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.
ModelTool choiceTool use system prompt token count
Claude Opus 4.1auto, none
any, tool		346 tokens
313 tokens
Claude Opus 4auto, none
any, tool		346 tokens
313 tokens
Claude Sonnet 4.5auto, none
any, tool		346 tokens
313 tokens
Claude Sonnet 4auto, none
any, tool		346 tokens
313 tokens
Claude Sonnet 3.7 (deprecated)auto, none
any, tool		346 tokens
313 tokens
Claude Haiku 4.5auto, none
any, tool		346 tokens
313 tokens
Claude Haiku 3.5auto, none
any, tool		264 tokens
340 tokens
Claude Opus 3 (deprecated)auto, none
any, tool		530 tokens
281 tokens
Claude Sonnet 3auto, none
any, tool		159 tokens
235 tokens
Claude Haiku 3auto, 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 strumento 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 strumenti client per migliorare il supporto.

Estrattore JSON

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