Uso dello strumento Anthropic Claude

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"
}

Fine-grained streaming degli strumenti

Fine-grained lo streaming degli strumenti è una funzionalità Anthropic Claude del modello disponibile con Claude Sonnet 4.5Claude 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)

Computer use è una famiglia di Anthropic Claude strumenti (in versione beta) per automatizzare le attività dell'interfaccia utente grafica (GUI). Per una panoramica, la forma della Bedrock-specific richiesta di Amazon e un esempio completo, consulta. Usa strumenti di utilizzo del computer per automatizzare le attività della GUI con i modelli Amazon Bedrock Per scoprire quali modelli supportano l'uso del computer su ciascun endpoint, consulta la tabella Funzionalità e caratteristiche di ciascuno. I modelli a colpo d'occhio

Per consentire l'uso del computer su richiesta, impostate una versione anthropic_beta per computer e includete una voce dello strumento che type corrisponda a quella versione. Gli abbinamenti validi sono:

Ogni tipo di utensile funziona solo con un sottoinsieme specifico di modelli. L'invio di un tipo di utensile non supportato da un modello restituisce 400 invalid_request_error un messaggio come. 'claude-opus-4-7' does not support tool types: computer_20241022 Conferma il supporto nella tabella Capacità e caratteristiche del modello prima di inviare le richieste.

Per il protocollo dello strumento sottostante, il vocabolario completo delle azioni e le linee guida ingegneristiche rapide, vedi Uso del computer nella documentazione. Anthropic

Anthropic strumenti definiti

Anthropicfornisce una serie di strumenti predefiniti che Claude i modelli possono utilizzare per interagire con i computer. Quando si specifica uno strumento Anthropic definito, i tool_schema campi description e non sono necessari o consentiti. Il modello non esegue questi strumenti automaticamente; è necessario eseguire ogni azione richiesta e restituire un atool_result. Claude Per scoprire quali di questi strumenti sono accettati da ciascun modello, consultate la tabella Capacità e caratteristiche del modelloI modelli a colpo d'occhio; l'invio di un tipo di strumento non supportato da un modello restituisce un400 invalid_request_error.

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

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

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

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

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

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

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

Il type campo identifica lo strumento e i relativi parametri a fini di convalida; il name campo è 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 name campo deve essere univoco all'interno dell'elenco degli strumenti; non è possibile definire uno strumento con lo stesso valore di uno strumento name definito in modalità «Anthropic-defined» nella stessa chiamata API.

Cancellazione automatica delle chiamate allo strumento (Beta)

La cancellazione automatica delle chiamate degli utensili è 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 degli strumenti 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. Dovrai 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. Questo strumento offre un modo per gestire la memoria tra le conversazioni. Con questa funzione, puoi consentire a Claude di recuperare informazioni al di fuori della finestra di contesto fornendo l'accesso a una directory locale. Questa funzionalità è disponibile in versione beta. Per utilizzare questa funzionalità, è necessario includerla context-management-2025-06-27 nel anthropic_beta parametro.

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 consente di Claude 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, puoi contrassegnarli condefer_loading: true, e Claude trova e carica solo gli strumenti necessari tramite il meccanismo di ricerca degli strumenti.

Per accedere a questa funzionalità, è necessario includerla tool-search-tool-2025-10-19 nel anthropic_beta parametro. Tieni presente che questa funzionalità è attualmente disponibile solo tramite le InvokeModelWithResponseStream API InvokeModel and.

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 personalizzati (ad esempio, utilizzando gli incorporamenti) definendo uno strumento che restituisca tool_reference blocchi. Lo strumento personalizzato deve avere, defer_loading: false mentre gli altri strumenti dovrebbero averlodefer_loading: true. Quando definisci il tuo Tool Search Tool, dovrebbe restituire un risultato contenente blocchi di tool_reference contenuto che rimandano agli strumenti che desideri Claude utilizzare.

Il formato di risposta previsto per i risultati di Tool Search Tool definito 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 personalizzati (ad esempio, utilizzando incorporamenti o ricerca semantica) definendo uno strumento che tool_reference restituisca blocchi. Ciò consente sofisticati meccanismi di individuazione degli strumenti che vanno oltre la corrispondenza con le espressioni regolari.

Richiedi un esempio 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 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"
}

Customer-provided risultato dello strumento

Dopo aver eseguito una ricerca semantica sulla libreria degli strumenti, il cliente restituisce i riferimenti allo strumento 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 dagli utenti nelle definizioni degli strumenti per aumentare le prestazioni Claude di utilizzo degli strumenti. È possibile fornire esempi sotto forma di chiamate complete, formattate esattamente come sarebbero i veri output LLM, senza bisogno di essere tradotti in un altro formato. Per utilizzare questa funzionalità, è necessario tool-examples-2025-10-29 includerla nel parametro. anthropic_beta

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"
}

Mid-conversation modifiche agli strumenti (Beta)

Claude Opus 5 supporta l'aggiunta e la rimozione di strumenti durante la conversazione tool_addition e di blocchi di tool_removal contenuto sui role: "system" messaggi, invece di inviare nuovamente l'intero tools array di primo livello (il che invaliderebbe la cache dei prompt).

Richiedi forma

tool_additione tool_removal i blocchi vengono visualizzati nell'contentarray di un role: "system" messaggio, insieme ai text blocchi opzionali. Ogni blocco fa riferimento a uno strumento attraverso il relativo tool campo. Sono consentiti più blocchi e vengono elaborati in base all'ordine dei contenuti.

{
  "role": "system",
  "content": [
    {"type": "tool_removal", "tool": {"type": "tool_reference", "name": "get_weather"}},
    {"type": "tool_addition", "tool": {"type": "tool_reference", "name": "search_docs"}},
    {"type": "text", "text": "Tool set updated for phase 2."}
  ]
}

Entrambi i tipi di blocco supportano cache_control il prompt caching.

Varianti di riferimento degli strumenti

Il tool campo è un'unione discriminata sutype:

tool_referencenon accetta il {server}_{name} modulo composto assegnato agli MCP-resolved strumenti; utilizza una delle varianti MCP per questi.

Semantica

Risposte di errore (400 invalid_request_error)