Utilizzo degli strumenti

Con i modelli Anthropic Claude, è possibile specificare uno strumento che il modello può utilizzare per rispondere a un messaggio. Ad esempio, è possibile specificare uno strumento che riproduca il brano più popolare su una stazione radio. Se l’utente trasmette il messaggio Qual è il brano più popolare su WZPZ?, il modello determina che lo strumento specificato può aiutare a rispondere alla domanda. Nella sua risposta, il modello richiede l’esecuzione dello strumento per suo conto. Quindi esegui lo strumento e passa il risultato dello strumento al modello, che a sua volta genera una risposta per il messaggio originale. Per ulteriori informazioni, consulta Utilizzo dello strumento (chiamata della funzione) nella documentazione Anthropic Claude.

Puoi specificare gli strumenti che vuoi rendere disponibili per un modello nel campo tools. L’esempio seguente è per uno strumento che riproduce i brani più popolari su una stazione radio.

[
    {
        "name": "top_song",
        "description": "Get the most popular song played on a radio station.",
        "input_schema": {
            "type": "object",
            "properties": {
                "sign": {
                    "type": "string",
                    "description": "The call sign for the radio station for which you want the most popular song. Example calls signs are WZPZ and WKRP."
                }
            },
            "required": [
                "sign"
            ]
        }
    }
]

Quando il modello necessita di uno strumento per generare una risposta a un messaggio, restituisce le informazioni sullo strumento richiesto e l’input allo strumento nel campo content del messaggio. Imposta inoltre il motivo dell’arresto della risposta a tool_use.

{
    "id": "msg_bdrk_01USsY5m3XRUF4FCppHP8KBx",
    "type": "message",
    "role": "assistant",
    "model": "claude-3-sonnet-20240229",
    "stop_sequence": null,
    "usage": {
        "input_tokens": 375,
        "output_tokens": 36
    },
    "content": [
        {
            "type": "tool_use",
            "id": "toolu_bdrk_01SnXQc6YVWD8Dom5jz7KhHy",
            "name": "top_song",
            "input": {
                "sign": "WZPZ"
            }
        }
    ],
    "stop_reason": "tool_use"
}

Nel codice, chiami lo strumento per conto degli strumenti. Quindi passa lo strumento result (tool_result) in un messaggio utente al modello.

{
    "role": "user",
    "content": [
        {
            "type": "tool_result",
            "tool_use_id": "toolu_bdrk_01SnXQc6YVWD8Dom5jz7KhHy",
            "content": "Elemental Hotel"
        }
    ]
}

Nella sua risposta, il modello utilizza il risultato dello strumento per generare una risposta per il messaggio originale.

{
    "id": "msg_bdrk_012AaqvTiKuUSc6WadhUkDLP",
    "type": "message",
    "role": "assistant",
    "model": "claude-3-sonnet-20240229",
    "content": [
        {
            "type": "text",
            "text": "According to the tool, the most popular song played on radio station WZPZ is \"Elemental Hotel\"."
        }
    ],
    "stop_reason": "end_turn"
}

Streaming granulare degli strumenti

Lo streaming granulare degli strumenti è una funzionalità del modello Anthropic Claude disponibile con Claude Sonnet 4.5, Claude Haiku 4.5, Claude Sonnet 4 e Claude Opus 4. Con lo streaming granulare degli strumenti, gli sviluppatori Claude possono trasmettere in streaming i parametri di utilizzo degli strumenti senza buffering o convalida JSON, riducendo la latenza necessaria per iniziare a ricevere parametri di grandi dimensioni.

Per utilizzare questa funzionalità, è sufficiente aggiungere l’intestazione fine-grained-tool-streaming-2025-05-14 a una richiesta di utilizzo dello strumento.

Ecco un esempio di come specificare l’intestazione di streaming granulare dello strumento:

{
  "anthropic_version": "bedrock-2023-05-31",
  "max_tokens": 1024,
  "anthropic_beta": ["fine-grained-tool-streaming-2025-05-14"],
  "messages": [
    {
      "role": "user",
      "content": "Can you write a long poem and make a file called poem.txt?"
    }
  ],
  "tools": [
    {
      "name": "make_file",
      "description": "Write text to a file",
      "input_schema": {
        "type": "object",
        "properties": {
          "filename": {
            "type": "string",
            "description": "The filename to write text to"
          },
          "lines_of_text": {
            "type": "array",
            "description": "An array of lines of text to write to the file"
          }
        },
        "required": [
          "filename",
          "lines_of_text"
        ]
      }
    }
  ]
}

In questo esempio, lo streaming granulare dello strumento consente a Claude di trasmettere le righe di una lunga poesia nella chiamata allo strumento make_file senza buffering per verificare se il parametro lines_of_text è JSON valido. Ciò significa che è possibile visualizzare il flusso di parametri non appena arriva, senza dover attendere che l’intero parametro venga memorizzato nel buffer e convalidato.

Con lo streaming granulare dello strumento, i blocchi di utilizzo dello strumento iniziano a trasmettere più velocemente, sono spesso più lunghi e contengono meno interruzioni di parole. Ciò è dovuto alle differenze nel comportamento della suddivisione in blocchi.

Ad esempio, senza streaming granulare (ritardo di 15 secondi):

Chunk 1: '{"'
Chunk 2: 'query": "Ty'
Chunk 3: 'peScri'
Chunk 4: 'pt 5.0 5.1 '
Chunk 5: '5.2 5'
Chunk 6: '.3'
Chunk 8: ' new f'
Chunk 9: 'eatur'
...

Con streaming granulare (ritardo di 3 secondi):

Chunk 1: '{"query": "TypeScript 5.0 5.1 5.2 5.3'
Chunk 2: ' new features comparison'

Utilizzo del computer (Beta)

L’utilizzo del computer è una funzionalità del modello Anthropic Claude (in versione beta) disponibile con Claude 3.5 Sonnet v2, Claude Sonnet 4.5, Claude Haiku 4.5, Claude 3.7 Sonnet, Claude Sonnet 4 e Claude Opus 4. Con l’utilizzo del computer, Claude può aiutarti ad automatizzare le attività tramite azioni GUI di base.

L’API per l’utilizzo del computer mette a disposizione diversi strumenti predefiniti di utilizzo del computer. Puoi quindi creare un prompt con la tua richiesta, ad esempio “invia un’e-mail a Ben con le note della mia ultima riunione” e uno screenshot (quando richiesto). La risposta contiene un elenco di azioni tool_use in formato JSON (ad esempio, scroll_down, left_button_press, screenshot). Il codice esegue le azioni del computer e fornisce a Claude schermate che mostrano gli output (quando richiesto).

Dalla versione Claude 3.5 v2, il parametro tools è stato aggiornato per accettare tipi di strumenti polimorfici; è stata aggiunta una proprietà tool.type per distinguerli. type è opzionale; se omesso, si presume che lo strumento sia uno strumento personalizzato (in precedenza era l’unico tipo di strumento supportato). Per accedere all’utilizzo del computer, è necessario utilizzare il parametro anthropic_beta, con un enum corrispondente, il cui valore dipende dalla versione del modello in uso. Per ulteriori informazioni, consulta la tabella seguente.

Solo le richieste effettuate con questo parametro ed enum possono utilizzare gli strumenti di utilizzo del computer. È possibile specificare quanto segue: "anthropic_beta": ["computer-use-2025-01-24"].

Per ulteriori informazioni, consulta Utilizzo del computer (beta) nella documentazione di Anthropic.

Di seguito è riportato un esempio di risposta che presuppone che la richiesta contenga uno screenshot del desktop con l’icona di Firefox.

{
    "id": "msg_123",
    "type": "message",
    "role": "assistant",
    "model": "anthropic.claude-3-5-sonnet-20241022-v2:0",
    "content": [
        {
            "type": "text",
            "text": "I see the Firefox icon. Let me click on it and then navigate to a weather website."
        },
        {
            "type": "tool_use",
            "id": "toolu_123",
            "name": "computer",
            "input": {
                "action": "mouse_move",
                "coordinate": [
                    708,
                    736
                ]
            }
        },
        {
            "type": "tool_use",
            "id": "toolu_234",
            "name": "computer",
            "input": {
                "action": "left_click"
            }
        }
    ],
    "stop_reason": "tool_use",
    "stop_sequence": null,
    "usage": {
        "input_tokens": 3391,
        "output_tokens": 132
    }
}

Strumenti Anthropic definiti

Anthropic fornisce una serie di strumenti per consentire a determinati modelli Claude di utilizzare efficacemente i computer. Quando si specifica uno strumento Anthropic definito, i campi description e tool_schema non sono necessari o consentiti. Gli strumenti definiti Anthropic sono definiti da Anthropic, ma è necessario valutare esplicitamente i risultati dello strumento e restituire tool_results a Claude. Come con qualsiasi strumento, il modello non esegue automaticamente lo strumento. Ogni strumento Anthropic definito ha versioni ottimizzate per modelli Claude 3.5 Sonnet (nuovi) e Claude 3.7 Sonnet specifici:

{ 
    "type": "text_editor_20250124", 
    "name": "str_replace_based_edit_tool" 
}

{ 
    "type": "computer_20250124", 
    "name": "computer" 
}

{ 
    "type": "text_editor_20250124", 
    "name": "str_replace_editor"
}

{ 
    "type": "bash_20250124", 
    "name": "bash" 
}

{ 
    "type": "text_editor_20241022", 
    "name": "str_replace_editor"
}

{ 
    "type": "bash_20241022", 
    "name": "bash"
}

{ 
    "type": "computer_20241022", 
    "name": "computer"
}

Il campo type identifica lo strumento e i suoi parametri a fini di convalida, il campo name è il nome dello strumento esposto al modello.

Per richiedere l’utilizzo di uno degli strumenti da parte del modello, è possibile fare riferimento esplicito al relativo campo name. Il campo name deve essere univoco all’interno dell’elenco degli strumenti; non è possibile definire uno strumento con lo stesso name come uno strumento Anthropic definito nella stessa chiamata API.

Cancellazione automatica delle chiamate allo strumento (Beta)

La cancellazione automatica delle chiamate agli strumenti è una funzionalità del modello Anthropic Claude (in versione beta). Con questa funzionalità, Claude può cancellare automaticamente i vecchi risultati di utilizzo degli strumenti man mano che si avvicinano i limiti dei token, consentendo una gestione più efficiente del contesto in scenari di utilizzo di utensili a più turni. Per utilizzare la funzionalità di cancellazione delle chiamate agli strumenti, devi aggiungere context-management-2025-06-27 all’elenco delle intestazioni beta il parametro di richiesta anthropic_beta. Dovrete inoltre specificare l'uso clear_tool_uses_20250919 e scegliere tra le seguenti opzioni di configurazione.

Questi sono i controlli disponibili per la strategia di gestione del contesto clear_tool_uses_20250919. Sono tutti opzionali o hanno dei valori predefiniti:

Strumento di memoria (Beta)

Claude Sonnet 4.5 include un nuovo strumento di memoria che offre ai clienti un modo per gestire la memoria tra le conversazioni. Con questa funzionalità, i clienti possono consentire a Claude di recuperare informazioni al di fuori della finestra contestuale fornendo l’accesso a una directory locale. Questa funzionalità sarà disponibile come funzionalità beta. Per utilizzare questa funzionalità, è necessario utilizzare l’intestazione context-management-2025-06-27 beta.

Definizione dello strumento:

{
  "type": "memory_20250818",
  "name": "memory"
}

Richiesta di esempio:

{
    "max_tokens": 2048,
    "anthropic_version": "bedrock-2023-05-31",
    "anthropic_beta": ["context-management-2025-06-27"],
    "tools": [{
        "type": "memory_20250818",
        "name": "memory"
    }],
    "messages": [
        {
            "role": "user",
            "content": [{"type": "text", "text": "Remember that my favorite color is blue and I work at Amazon?"}]
        }
    ]
}

Risposta di esempio:

{
    "id": "msg_vrtx_014mQ5ficCRB6PEa5k5sKqHd",
    "type": "message",
    "role": "assistant",
    "model": "claude-sonnet-4-20250514",
    "content": [
        {
            "type": "text",
            "text": "I'll start by checking your memory directory and then record this important information about you."
        },
        {
            "type": "tool_use",
            "id": "toolu_vrtx_01EU1UrCDigyPMRntr3VYvUB",
            "name": "memory",
            "input": {
                "command": "view",
                "path": "/memories"
            }
        }
    ],
    "stop_reason": "tool_use",
    "stop_sequence": null,
    "usage": {
        "input_tokens": 1403,
        "cache_creation_input_tokens": 0,
        "cache_read_input_tokens": 0,
        "output_tokens": 87
    },
    "context_management": {
        "applied_edits": []
    }
}

Considerazioni sui costi per l’uso dello strumento

I prezzi delle richieste di utilizzo degli strumenti sono basati sui seguenti fattori:

Gli strumenti hanno lo stesso prezzo di tutte le altre richieste API Claude, ma includono token aggiuntivi per richiesta. I token aggiuntivi derivanti dall’utilizzo degli strumenti provengono:

Quando si utilizzano gli strumenti, i modelli Anthropic includono automaticamente uno speciale prompt di sistema che consente l’utilizzo dello strumento. Il numero di token per l’utilizzo dello strumento richiesti per ogni modello è elencato nella tabella seguente. Questa tabella esclude i token aggiuntivi descritti in precedenza. Tieni presente che questa tabella presuppone che venga fornito almeno uno strumento. Se non vengono forniti strumenti, allora la scelta dello strumento “none” utilizza 0 token aggiuntivi nel prompt di sistema.

Strumento di ricerca degli strumenti (beta)

Tool Search Tool Claude consente di lavorare con centinaia o addirittura migliaia di strumenti senza caricare in anticipo tutte le loro definizioni nella finestra contestuale. Invece di dichiarare immediatamente tutti gli strumenti, è possibile contrassegnarli condefer_loading: true, e Claude trovare e caricare solo gli strumenti necessari attraverso il meccanismo di ricerca degli strumenti.

Per accedere a questa funzionalità è necessario utilizzare l'tool-search-tool-2025-10-19intestazione beta. Tieni presente che questa funzionalità è attualmente disponibile solo tramite InvokeModele InvokeModelWithResponseStream APIs.

Definizione dello strumento:

{
    "type": "tool_search_tool_regex",
    "name": "tool_search_tool_regex"
}

Esempio di richiesta:

{
    "anthropic_version": "bedrock-2023-05-31",
    "anthropic_beta": [
        "tool-search-tool-2025-10-19"
    ],
    "max_tokens": 4096,
    "tools": [{
            "type": "tool_search_tool_regex",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get current weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"]
                    }
                },
                "required": ["location"]
            },
            "defer_loading": true
        },
        {
            "name": "search_files",
            "description": "Search through files in the workspace",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string"
                    },
                    "file_types": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    }
                },
                "required": ["query"]
            },
            "defer_loading": true
        }
    ],
    "messages": [{
        "role": "user",
        "content": "What's the weather in Seattle?"
    }]
}

Esempio di risposta

{
    "role": "assistant",
    "content": [{
            "type": "text",
            "text": "I'll search for the appropriate tools to help with this task."
        },
        {
            "type": "server_tool_use",
            "id": "srvtoolu_01ABC123",
            "name": "tool_search_tool_regex",
            "input": {
                "pattern": "weather"
            }
        },
        {
            "type": "tool_search_tool_result",
            "tool_use_id": "srvtoolu_01ABC123",
            "content": {
                "type": "tool_search_tool_search_result",
                "tool_references": [{
                    "type": "tool_reference",
                    "tool_name": "get_weather"
                }]
            }
        },
        {
            "type": "text",
            "text": "Now I can check the weather."
        },
        {
            "type": "tool_use",
            "id": "toolu_01XYZ789",
            "name": "get_weather",
            "input": {
                "location": "Seattle",
                "unit": "fahrenheit"
            }
        }
    ],
    "stop_reason": "tool_use"
}

Esempio di streaming

# Event 1: content_block_start(with complete server_tool_use block) {
    "type": "content_block_start",
    "index": 0,
    "content_block": {
        "type": "server_tool_use",
        "id": "srvtoolu_01ABC123",
        "name": "tool_search_tool_regex"
    }
}

# Event 2: content_block_delta(input JSON streamed) {
    "type": "content_block_delta",
    "index": 0,
    "delta": {
        "type": "input_json_delta",
        "partial_json": "{\"regex\": \".*weather.*\"}"
    }
}

# Event 3: content_block_stop(tool_use complete) {
    "type": "content_block_stop",
    "index": 0
}

# Event 4: content_block_start(COMPLETE result in single chunk) {
    "type": "content_block_start",
    "index": 1,
    "content_block": {
        "type": "tool_search_tool_result",
        "tool_use_id": "srvtoolu_01ABC123",
        "content": {
            "type": "tool_search_tool_search_result",
            "tool_references": [{
                "type": "tool_reference",
                "tool_name": "get_weather"
            }]
        }
    }
}

# Event 5: content_block_stop(result complete) {
    "type": "content_block_stop",
    "index": 1
}

Strumenti di ricerca personalizzati

È possibile implementare strumenti di ricerca di strumenti personalizzati (ad esempio, utilizzando gli incorporamenti) definendo uno strumento che restituisca tool_reference i blocchi. Lo strumento personalizzato deve avere defer_loading: false mentre altri strumenti dovrebbero averedefer_loading: true. Quando definite il vostro strumento di ricerca strumenti, questo dovrebbe restituire un risultato contenente blocchi di tool_reference contenuto che rimandano agli strumenti che desiderate Claude utilizzare.

Il formato di risposta ai risultati di Tool Search Tool previsto dal cliente:

{
    "type": "tool_result",
    "tool_use_id": "toolu_01ABC123",
    "content": [{
            "type": "tool_reference",
            "tool_name": "get_weather"
        },
        {
            "type": "tool_reference",
            "tool_name": "weather_forecast"
        }
    ]
}

tool_nameDeve corrispondere a uno strumento definito nella richiesta con. defer_loading: true Claude avrà quindi accesso agli schemi completi di quegli strumenti.

Strumenti di ricerca personalizzati - Esempio dettagliato

È possibile implementare strumenti di ricerca di strumenti personalizzati (ad esempio, utilizzando incorporamenti o ricerca semantica) definendo uno strumento che tool_reference restituisca blocchi. Ciò consente sofisticati meccanismi di scoperta degli strumenti oltre alla corrispondenza con espressioni regolari.

Esempio di richiesta con TST personalizzato:

{
    "model": "claude-sonnet-4-5-20250929",
    "anthropic_version": "bedrock-2023-05-31",
    "anthropic_beta": ["tool-search-tool-2025-10-19"],
    "max_tokens": 4096,
    "tools": [{
            "name": "semantic_tool_search",
            "description": "Search for available tools using semantic similarity. Returns the most relevant tools for the given query.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Natural language description of what kind of tool is needed"
                    },
                    "top_k": {
                        "type": "integer",
                        "description": "Number of tools to return (default: 5)"
                    }
                },
                "required": ["query"]
            },
            "defer_loading": false
        },
        {
            "name": "get_weather",
            "description": "Get current weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"]
                    }
                },
                "required": ["location"]
            },
            "defer_loading": true
        },
        {
            "name": "search_flights",
            "description": "Search for available flights between locations",
            "input_schema": {
                "type": "object",
                "properties": {
                    "origin": {
                        "type": "string"
                    },
                    "destination": {
                        "type": "string"
                    },
                    "date": {
                        "type": "string"
                    }
                },
                "required": ["origin", "destination", "date"]
            },
            "defer_loading": true
        }
    ],
    "messages": [{
        "role": "user",
        "content": "What's the weather forecast in Seattle for the next 3 days?"
    }]
}

Clauderisposta (chiamata al TST personalizzato):

{
    "role": "assistant",
    "content": [{
            "type": "text",
            "text": "I'll search for the appropriate tools to help with weather information."
        },
        {
            "type": "tool_use",
            "id": "toolu_01ABC123",
            "name": "semantic_tool_search",
            "input": {
                "query": "weather forecast multiple days",
                "top_k": 3
            }
        }
    ],
    "stop_reason": "tool_use"
}

risultato dell'utensile fornito dal cliente

Dopo aver eseguito la ricerca semantica nella libreria degli strumenti, il cliente restituisce i riferimenti agli strumenti corrispondenti:

{
    "role": "user",
    "content": [{
        "type": "tool_search_tool_result",
        "tool_use_id": "toolu_01ABC123",
        "content": {
            "type": "tool_search_tool_search_result",
            "tool_references": [{
                "type": "tool_reference",
                "tool_name": "get_weather"
            }]
        }
    }]
}

Claudeil follow-up (utilizzando lo strumento scoperto)

{
    "role": "assistant",
    "content": [{
            "type": "text",
            "text": "I found the forecast tool. Let me get the weather forecast for Seattle."
        },
        {
            "type": "tool_use",
            "id": "toolu_01DEF456",
            "name": "get_weather",
            "input": {
                "location": "Seattle, WA"
            }
        }
    ],
    "stop_reason": "tool_use"
}

Esempi di utilizzo degli strumenti (beta)

Claude Opus4.5 supporta esempi forniti dall'utente nelle definizioni degli strumenti per aumentare le prestazioni Claude di utilizzo degli strumenti. È possibile fornire esempi come chiamate di funzioni complete, formattate esattamente come sarebbero i veri output LLM, senza bisogno di traduzione in un altro formato. Per utilizzare questa funzionalità è necessario passare l'intestazione beta. tool-examples-2025-10-29

Esempio di definizione dello strumento:

{
    "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": "Temperature unit"
            }
        },
        "required": ["location"]
    },
    "input_examples": [{
            "location": "San Francisco, CA",
            "unit": "fahrenheit"
        },
        {
            "location": "Tokyo, Japan",
            "unit": "celsius"
        },
        {
            "location": "New York, NY"
        }
    ]
}

Esempi di errore:

// Invalid: Example doesn't match schema (missing required field)
{
    "type": "invalid_request_error",
    "message": "Tool 'get_weather' input_examples[0] is invalid: Missing required property 'location'"
}

// Invalid: Example has wrong type for field
{
    "type": "invalid_request_error",
    "message": "Tool 'search_products' input_examples[1] is invalid: Property 'filters.price_range.min' must be a number, got string"
}

// Invalid: input_examples on server-side tool
{
    "type": "invalid_request_error",
    "message": "input_examples is not supported for server-side tool"
}