As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Uso da ferramenta Anthropic Claude
**Atenção**
Várias funções abaixo são oferecidas na versão beta, conforme indicado. Esses recursos são disponibilizados para você como um “Serviço Beta”, conforme definido nos Termos do AWS Serviço. Está sujeito ao seu Contrato AWS e aos Termos AWS de Serviço e ao modelo de EULA aplicável.
Com os modelos Claude da Anthropic, você pode especificar uma ferramenta que o modelo pode usar para responder a uma mensagem. Por exemplo, você pode especificar uma ferramenta que obtenha a música mais tocada em uma estação de rádio. Se o usuário transmitir a mensagem *Qual é a música mais tocada na WZPZ?*, o modelo determinará que a ferramenta especificada pode ajudar a responder à pergunta. Na resposta, o modelo solicita a você executar a ferramenta em seu nome. Em seguida, você executa a ferramenta e passa o resultado da ferramenta para o modelo, que gera uma resposta para a mensagem original. Para obter mais informações, consulte [Tool use (function calling)](https://docs.anthropic.com/en/docs/tool-use) na documentação do Claude da Anthropic.
**dica**
É recomendável usar a API Converse para integrar o uso de ferramentas à aplicação. Para obter mais informações, consulte [Use uma ferramenta para concluir uma resposta do modelo do Amazon Bedrock](tool-use.md).
**Importante**
O Claude Sonnet 4.5 agora preserva a formatação intencional nos parâmetros da string de chamada da ferramenta. Antes, as novas linhas finais nos parâmetros de string às vezes eram incorretamente removidas. Essa correção garante que as ferramentas que exigem formatação precisa (como editores de texto) recebam os parâmetros exatamente como pretendido. Essa é uma melhoria subjacente e não requer alterações na API. No entanto, as ferramentas com parâmetros de string agora podem receber valores com novas linhas à direita que foram removidas anteriormente.
**nota**
O Claude Sonnet 4.5 inclui otimizações automáticas para melhorar o desempenho do modelo. Essas otimizações podem adicionar pequenas quantidades de tokens às solicitações, mas você não recebe cobranças por esses tokens adicionados pelo sistema.
Você especifica as ferramentas que deseja disponibilizar para um modelo no campo `tools`. O exemplo a seguir é de uma ferramenta que obtém as músicas mais tocadas em uma estação de rádio.
```
[
{
"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 precisa de uma ferramenta para gerar uma resposta a uma mensagem, o modelo retorna informações sobre a ferramenta solicitada, e a entrada para a ferramenta no campo `content` da mensagem. Ele também define o motivo da interrupção da resposta para `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"
}
```
No código, você chama a ferramenta em nome das ferramentas. Em seguida, você passa o resultado da ferramenta (`tool_result`) em uma mensagem do usuário para o modelo.
```
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_bdrk_01SnXQc6YVWD8Dom5jz7KhHy",
"content": "Elemental Hotel"
}
]
}
```
Na resposta, o modelo usa o resultado da ferramenta a fim de gerar uma resposta para a mensagem original.
```
{
"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 de ferramentas
Fine-grained o streaming de ferramentas é um recurso de Anthropic Claude modelo disponível com Claude Sonnet 4.5Claude Haiku 4.5,Claude Sonnet 4, e Claude Opus 4. Com o streaming refinado de ferramentas, os desenvolvedores do Claude podem transmitir parâmetros de uso de ferramentas sem os armazenar em buffer ou sem validação JSON, reduzindo a latência para começar a receber parâmetros grandes.
**nota**
Ao usar o streaming refinado de ferramentas, é possível que você receba entradas JSON inválidas ou parciais. Considere esses casos extremos em seu código.
Para usar esse recurso, basta adicionar o cabeçalho `fine-grained-tool-streaming-2025-05-14` a uma solicitação de uso de ferramentas.
Veja aqui um exemplo de como especificar o cabeçalho de streaming refinado de ferramentas:
```
{
"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"
]
}
}
]
}
```
Neste exemplo, o streaming refinado de ferramentas permite que o Claude transmita as estrofes de um longo poema à chamada de ferramenta `make_file` sem os armazenar em buffer para validar se o parâmetro `lines_of_text` é um JSON válido. Isso significa que você pode ver o fluxo de parâmetros à medida que ele chega, sem precisar esperar que todo o parâmetro seja armazenado em buffer e validado.
Com o streaming refinado de ferramentas, os fragmentos de uso de ferramentas começam a ser transmitidos mais depressa e geralmente são mais longos e contêm menos quebras de palavra. Isso se deve a diferenças no comportamento de fragmentação.
Por exemplo, sem streaming refinado (atraso de 15 s):
```
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'
...
```
Com streaming refinado (atraso de 3 s):
```
Chunk 1: '{"query": "TypeScript 5.0 5.1 5.2 5.3'
Chunk 2: ' new features comparison'
```
**nota**
Como o streaming refinado envia parâmetros sem os armazenar em buffer ou sem validação JSON, não há garantia de que o fluxo resultante será concluído em uma string JSON válida. Mais especificamente, se o motivo de interrupção `max_tokens` for atingido, o fluxo poderá terminar no meio de um parâmetro e ficar incompleto. Geralmente, é necessário escrever um suporte específico para lidar com situações em que `max_tokens` é atingido.
## Computer Use (Beta)
O uso do computador é uma família de Anthropic Claude ferramentas (em versão beta) para automatizar tarefas de interface gráfica do usuário (GUI). Para obter uma visão geral, o formato de Bedrock-specific solicitação da Amazon e um exemplo completo, consulte. [Use ferramentas de uso do computador para automatizar tarefas de GUI com modelos Amazon Bedrock](computer-use.md) Para descobrir quais modelos oferecem suporte ao uso do computador em cada endpoint, consulte a tabela *Capacidades e Recursos* em cada um[Visão geral dos modelos](model-cards.md).
Para habilitar o uso do computador em uma solicitação, `anthropic_beta` defina como uma versão de uso do computador e inclua uma entrada de ferramenta que `type` corresponda a essa versão. Os pares válidos são:
| Cabeçalho beta | Tipo de ferramenta de computador |
| --- | --- |
| computer-use-2025-11-24 | computer\_20251124 |
| computer-use-2025-01-24 | computer\_20250124 |
| computer-use-2024-10-22 | computer\_20241022 |
Cada tipo de ferramenta funciona somente com um subconjunto específico de modelos. O envio de um tipo de ferramenta que um modelo não suporta retorna um `400 invalid_request_error` com uma mensagem como`'claude-opus-4-7' does not support tool types: computer_20241022`. Confirme o suporte na tabela de *capacidades e recursos* do modelo antes de enviar solicitações.
Para obter o protocolo da ferramenta subjacente, o vocabulário de ação completo e as diretrizes de engenharia imediata, consulte [Uso do computador na documentação](https://docs.anthropic.com/en/docs/build-with-claude/computer-use). Anthropic
## Anthropic ferramentas definidas
Anthropicfornece um conjunto de ferramentas predefinidas que Claude os modelos podem usar para interagir com computadores. Ao especificar uma ferramenta Anthropic definida, os `tool_schema` campos `description` e não são necessários nem permitidos. O modelo não executa essas ferramentas automaticamente; você deve executar cada ação solicitada e retornar um `tool_result` paraClaude. Para descobrir quais dessas ferramentas cada modelo aceita, consulte a tabela *Capacidades e Características* no modelo[Visão geral dos modelos](model-cards.md); enviar um tipo de ferramenta que um modelo não suporta retorna a. `400 invalid_request_error`
| Ferramenta | Observações |
| --- | --- |
| {
"type": "computer_20251124",
"name": "computer"
} | Ferramenta de uso de computador mais recente. Use com o `"anthropic_beta": ["computer-use-2025-11-24"]`. |
| {
"type": "computer_20250124",
"name": "computer"
} | Use com o `"anthropic_beta": ["computer-use-2025-01-24"]`. |
| {
"type": "computer_20241022",
"name": "computer"
} | Legado. Use com o `"anthropic_beta": ["computer-use-2024-10-22"]`. |
| {
"type": "text_editor_20250124",
"name": "str_replace_based_edit_tool"
} | Atualize para a `str_replace_editor` ferramenta existente. Use com `"anthropic_beta": ["computer-use-2025-01-24"]` ou`["computer-use-2025-11-24"]`. |
| {
"type": "text_editor_20241022",
"name": "str_replace_editor"
} | Legado. Use com o `"anthropic_beta": ["computer-use-2024-10-22"]`. |
| {
"type": "bash_20250124",
"name": "bash"
} | Use com `"anthropic_beta": ["computer-use-2025-01-24"]` ou`["computer-use-2025-11-24"]`. |
| {
"type": "bash_20241022",
"name": "bash"
} | Legado. Use com o `"anthropic_beta": ["computer-use-2024-10-22"]`. |
O `type` campo identifica a ferramenta e seus parâmetros para fins de validação; o `name` campo é o nome da ferramenta exposto ao modelo.
Se você quiser solicitar que o modelo use uma dessas ferramentas, poderá indicar explicitamente a ferramenta por meio do campo `name`. O `name` campo deve ser exclusivo na lista de ferramentas; você não pode definir uma ferramenta com a `name` mesma ferramenta Anthropic definida na mesma chamada de API.
## Limpeza automática de chamadas de ferramenta (beta)
**Atenção**
A ferramenta automática de compensação de chamadas é disponibilizada como um “Serviço Beta”, conforme definido nos Termos AWS de Serviço.
**nota**
Atualmente, esse recurso é suportado no Claude Sonnet 4.5, no Claude Haiku 4/4 4.5 e no Claude Opus. 4/4 1/4.5.
A compensação automática de chamadas de ferramentas é um recurso do modelo Anthropic Claude (em versão beta). Com esse recurso, Claude pode apagar automaticamente os resultados de uso de ferramentas antigas à medida que você se aproxima dos limites dos tokens, permitindo um gerenciamento de contexto mais eficiente em cenários de uso de ferramentas de vários turnos. Para usar a limpeza de uso de ferramentas, você precisa adicionar `context-management-2025-06-27` à lista de cabeçalhos beta no parâmetro de solicitação anthropic\_beta. Você também precisará especificar o uso `clear_tool_uses_20250919` e escolher entre as seguintes opções de configuração.
Esses são os controles disponíveis para a estratégia de gerenciamento de contexto `clear_tool_uses_20250919`. Todos são opcionais ou têm padrões:
| **Opção de configuração** | **Descrição** |
| --- | --- |
| `trigger`
padrão: 100.000 tokens de entrada | Define quando a estratégia de edição de contexto é ativada. Quando o prompt ultrapassar esse limite, a limpeza começará. É possível especificar esse valor em input\_tokens ou tool\_uses. |
| `keep`
padrão: 3 usos de ferramentas | Define quantos use/result pares de ferramentas recentes devem ser mantidos após a limpeza. A API remove primeiro as interações mais antigas da ferramenta, preservando as mais recentes. Útil quando o modelo precisa acessar interações recentes da ferramenta para continuar a conversa de forma eficaz. |
| `clear_at_least` (opcional) | Garante que um número mínimo de tokens seja liberado cada vez que a estratégia é ativada. Se a API não conseguir liberar pelo menos o valor especificado, a estratégia não será aplicada. Isso é útil para determinar se vale a pena invalidar o armazenamento em cache de prompts para limpar o contexto. |
| `exclude_tools` (opcional) | Lista de nomes cujos usos e resultados da ferramenta nunca devem ser apagados. Útil para preservar um contexto importante. |
| `clear_tool_inputs`: (opcional; padrão: false) | Controla se os parâmetros de chamada da ferramenta são apagados com os resultados da ferramenta. Por padrão, somente os resultados da ferramenta são apagados, mantendo as chamadas de ferramenta originais do Claude visíveis para que o Claude veja quais operações foram realizadas mesmo após a remoção dos resultados. |
**nota**
A limpeza de ferramenta invalidará o cache se os prefixos contiverem suas ferramentas.
**Importante**
A ferramenta de `web_search_20250305` servidor Anthropic não é compatível com o Amazon Bedrock.
------
#### [ Request ]
```
from anthropic import AnthropicBedrock
client = AnthropicBedrock()
response = client.beta.messages.create(
betas=["context-management-2025-06-27"],
model="claude-sonnet-4-20250514",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Create a simple command line calculator app using Python"
}
],
tools=[
{
"type": "text_editor_20250728",
"name": "str_replace_based_edit_tool",
"max_characters": 10000
}
],
extra_body={
"context_management": {
"edits": [
{
"type": "clear_tool_uses_20250919",
# The below parameters are OPTIONAL:
# Trigger clearing when threshold is exceeded
"trigger": {
"type": "input_tokens",
"value": 30000
},
# Number of tool uses to keep after clearing
"keep": {
"type": "tool_uses",
"value": 3
},
# Optional: Clear at least this many tokens
"clear_at_least": {
"type": "input_tokens",
"value": 5000
},
# Exclude these tools uses from being cleared
"exclude_tools": ["str_replace_based_edit_tool"]
}
]
}
}
)
```
------
#### [ Response ]
```
{
"id": "msg_123",
"type": "message",
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "toolu_456",
"name": "data_analyzer",
"input": {
"data": "sample data"
}
}
],
"context_management": {
"applied_edits": [
{
"type": "clear_tool_uses_20250919",
"cleared_tool_uses": 8, # Number of tool use/result pairs that were cleared
"cleared_input_tokens": 50000 # Total number of input tokens removed from the prompt
}
]
}
"stop_reason": "tool_use",
"usage": {
"input_tokens": 150,
"output_tokens": 50
}
}
```
------
#### [ Streaming Response ]
```
data: {"type": "message_start", "message": {"id": "msg_123", "type": "message", "role": "assistant"}}
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "tool_use", "id": "toolu_456", "name": "data_analyzer", "input": {}}}
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "input_json_delta", "partial_json": "{\"data\": \"sample"}}
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "input_json_delta", "partial_json": " data\"}"}}
data: {"type": "content_block_stop", "index": 0}
data: {"type": "message_delta", "delta": {"stop_reason": "tool_use"}}
data: {"type": "message_stop"}
{
"type": "message_delta",
"delta": {
"stop_reason": "end_turn",
"stop_sequence": null,
},
"usage": {
"output_tokens": 1024
},
"context_management": {
"applied_edits": [...],
}
}
```
------
**nota**
Atualmente, o Bedrock não oferece suporte ao gerenciamento de `clear_tool_uses_20250919` contexto na CountTokens API.
## Ferramenta de memória (beta)
**Atenção**
O Memory Tool é disponibilizado como um “Serviço Beta”, conforme definido nos Termos do AWS Serviço.
O Claude Sonnet 4.5 inclui uma nova ferramenta de memória. Essa ferramenta fornece uma maneira de gerenciar a memória nas conversas. Com esse recurso, você pode permitir que Claude recupere informações fora da janela de contexto fornecendo acesso a um diretório local. Esse recurso está disponível na versão beta. Para usar esse recurso, você deve incluir `context-management-2025-06-27` no `anthropic_beta` parâmetro.
Definição da ferramenta:
```
{
"type": "memory_20250818",
"name": "memory"
}
```
Exemplo de solicitação:
```
{
"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?"}]
}
]
}
```
Exemplo de resposta:
```
{
"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": []
}
}
```
## Considerações sobre custo para uso de ferramentas
O preço das solicitações de uso de ferramentas é baseado nos seguintes fatores:
1. O número total de tokens de entrada enviados ao modelo (inclusive no parâmetro tools).
1. Número de tokens de saída gerados.
As ferramentas têm o mesmo preço de todas as outras solicitações de API do Claude, mas incluem tokens adicionais por solicitação. Os tokens adicionais de uso de ferramentas provêm do seguinte:
+ Inclua o parâmetro `tools` nas solicitações de API. Por exemplo, nomes, descrições e esquemas de ferramenta.
+ Qualquer bloco de conteúdo de `tool_use` em solicitações e respostas de API.
+ Qualquer bloco de conteúdo de `tool_result` em solicitações de API.
Quando você usa ferramentas, os modelos da Anthropic incluem automaticamente um prompt especial do sistema que permite usar a ferramenta. O número de tokens de uso de ferramentas necessários para cada modelo está listado na tabela a seguir. Essa tabela exclui os tokens adicionais descritos anteriormente. Observe que essa tabela pressupõe que pelo menos uma ferramenta seja fornecida. Se nenhuma ferramenta for fornecida e se for escolhido nenhuma para a opção de ferramenta, não será usado nenhum token de prompt adicional do sistema.
| Modelo | Escolha da ferramenta | Contagem de tokens de prompt do sistema de uso de ferramentas |
| --- | --- | --- |
| Claude Opus4.5
Claude Opus4.1
Claude Opus 4
Claude Sonnet 4.5
Claude Haiku 4.5
Claude Sonnet 4
Claude 3.7 Sonnet
Claude 3.5 Sonnet v2 | auto ou none | 346 |
| Claude Opus4.5
Claude Opus4.1
Claude Opus 4
Claude Sonnet 4.5
Claude Haiku 4.5
Claude Sonnet 4
Claude 3.7 Sonnet
Claude 3.5 Sonnet v2 | any ou tool | 313 |
| Claude 3.5 Sonnet | auto ou none | 294 |
| Claude 3.5 Sonnet | any ou tool | 261 |
| Claude 3 Opus | auto ou none | 530 |
| Claude 3 Opus | any ou tool | 281 |
| Claude 3 Sonnet | auto ou none | 159 |
| Claude 3 Sonnet | any ou tool | 235 |
| Claude 3 Haiku | auto ou none | 264 |
| Claude 3 Haiku | any ou tool | 340 |
## Ferramenta de pesquisa de ferramentas (beta)
A ferramenta de pesquisa de ferramentas Claude permite trabalhar com centenas ou até milhares de ferramentas sem carregar todas as suas definições na janela de contexto antecipadamente. Em vez de declarar todas as ferramentas imediatamente, você pode marcá-las com`defer_loading: true`, Claude localizar e carregar somente as ferramentas necessárias por meio do mecanismo de busca de ferramentas.
Para acessar esse recurso, você deve incluir `tool-search-tool-2025-10-19` no `anthropic_beta` parâmetro. Observe que atualmente esse recurso está disponível apenas por meio das [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)APIs [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)e.
Definição da ferramenta:
```
{
"type": "tool_search_tool_regex",
"name": "tool_search_tool_regex"
}
```
Exemplo de solicitação:
```
{
"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?"
}]
}
```
Exemplo de resposta
```
{
"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"
}
```
Exemplo de 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
}
```
**Ferramentas personalizadas de pesquisa de ferramentas**
Você pode implementar ferramentas personalizadas de pesquisa de ferramentas (por exemplo, usando incorporações) definindo uma ferramenta que retorna `tool_reference` blocos. A ferramenta personalizada deve ter, `defer_loading: false` enquanto outras ferramentas deveriam ter`defer_loading: true`. Quando você define sua própria ferramenta de pesquisa de ferramentas, ela deve retornar um resultado da ferramenta contendo blocos de `tool_reference` conteúdo que apontam para as ferramentas que você Claude deseja usar.
O formato esperado de resposta dos resultados da Ferramenta de Pesquisa de Ferramentas definido pelo 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_name`Deve corresponder a uma ferramenta definida na solicitação com`defer_loading: true`. Claude então terá acesso aos esquemas completos dessas ferramentas.
**Ferramentas de pesquisa personalizadas - Exemplo detalhado**
Você pode implementar ferramentas personalizadas de pesquisa de ferramentas (por exemplo, usando incorporações ou pesquisa semântica) definindo uma ferramenta que retorna `tool_reference` blocos. Isso permite mecanismos sofisticados de descoberta de ferramentas além da correspondência de regex.
Exemplo de solicitação com TST personalizado:
```
{
"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?"
}]
}
```
Claudeda resposta (chamando o TST personalizado):
```
{
"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 resultado da ferramenta**
Depois de realizar uma pesquisa semântica na biblioteca de ferramentas, o cliente retorna as referências de ferramentas correspondentes:
```
{
"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"
}]
}
}]
}
```
Claudeacompanhamento (usando a ferramenta descoberta)
```
{
"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"
}
```
**Tratamento de erros**
+ A configuração `defer_loading: true` de todas as ferramentas (incluindo a Ferramenta de Pesquisa de Ferramentas) gerará um erro 400.
+ Passar um `tool_reference` sem uma definição de ferramenta correspondente gerará um erro 400
## Exemplos de uso de ferramentas (beta)
Claude Opus4.5 oferece suporte a exemplos fornecidos pelo usuário em definições de ferramentas para aumentar o desempenho Claude do uso da ferramenta. Você pode fornecer exemplos como chamadas de função completas, formatadas exatamente como seriam as saídas reais do LLM, sem precisar de tradução para outro formato. Para usar esse recurso, você deve incluir `tool-examples-2025-10-29` no `anthropic_beta` parâmetro.
Exemplo de definição de ferramenta:
```
{
"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"
}
]
}
```
**Regras de validação**
+ Conformidade do esquema: cada exemplo em `input_examples` deve ser válido de acordo com a ferramenta. `input_schema`
+ Os campos obrigatórios devem estar presentes em pelo menos um exemplo.
+ Os tipos de campo devem corresponder ao esquema.
+ Os valores de enumeração devem ser do conjunto permitido.
+ Se a validação falhar, retorne um erro 400 com detalhes sobre qual exemplo falhou na validação.
+ Requisitos de matriz: `input_examples` deve ser uma matriz (pode estar vazia).
+ `[]`A matriz vazia é válida e equivale a omitir o campo.
+ Um único exemplo ainda deve ser agrupado em uma matriz: `[{...}]`
+ Limite de comprimento: comece com um limite de 20 exemplos por definição de ferramenta.
Exemplos de erros:
```
// 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"
}
```