Uso da ferramenta Anthropic Claude

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) na documentação do Claude da Anthropic.

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.

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'

Computer Use (Beta)

O uso do computador é uma família de Anthropic Claude ferramentas (em beta) para automatizar as tarefas da interface gráfica do usuário (GUI). Para obter uma visão geral, o formato da Bedrock-specific solicitação da Amazon e um exemplo de ponta a ponta, consulte. Use ferramentas de uso do computador para automatizar tarefas de GUI com modelos Amazon Bedrock Para descobrir quais modelos suportam o uso do computador em cada endpoint, consulte a tabela Capacidades e Recursos em cada umModelos em resumo.

Para habilitar o uso do computador em uma solicitação, anthropic_beta defina como uma versão para uso do computador e inclua uma entrada de ferramenta que type corresponda a essa versão. Os pares válidos são:

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 Capacidades e Características do modelo antes de enviar as solicitações.

Para obter o protocolo da ferramenta subjacente, o vocabulário completo de ações e as diretrizes de engenharia imediata, consulte Uso do computador na documentação. Anthropic

Conjuntos de ferramentas do cliente

Alguns Claude modelos aceitam dois conjuntos de ferramentas de cliente agrupados como tools[].type valores. Um conjunto de ferramentas agrupa um grupo relacionado de ferramentas de cliente em um único tipo, para que você não precise declarar cada ferramenta individualmente. Nenhum anthropic_beta valor é necessário.

Assim como acontece com as ferramentas individuais do cliente, o modelo solicita ações, mas não as executa. Você executa cada ação solicitada e retorna umtool_result. O envio de um tipo de conjunto de ferramentas que um modelo não suporta retorna a. 400 invalid_request_error Para confirmar quais conjuntos de ferramentas um modelo aceita, consulte a seção Capacidades e recursos no cartão do modelo do modelo.

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 por -, 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 modeloModelos em resumo; enviar um tipo de ferramenta que um modelo não suporta retorna a. 400 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" 
}

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 o mesmo name que uma ferramenta Anthropic definida por -na mesma chamada de API.

Limpeza automática de chamadas de ferramenta (beta)

A compensação automática de chamadas de ferramentas é um recurso do modelo Anthropic Claude (em versão beta). Com esse recurso, Claude pode limpar automaticamente os resultados de uso de ferramentas antigas à medida que você se aproxima dos limites de token, permitindo um gerenciamento de contexto mais eficiente em cenários de uso de ferramentas em 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:

Ferramenta de memória (beta)

O Claude Sonnet 4.5 inclui uma nova ferramenta de memória. Essa ferramenta fornece uma maneira de gerenciar a memória em todas as 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:

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:

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.

Ferramenta de busca 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 com antecedência. Em vez de declarar todas as ferramentas imediatamente, você pode marcá-lasdefer_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, no momento, esse recurso só está disponível por meio das InvokeModelWithResponseStream APIs InvokeModel 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 de pesquisa de ferramentas personalizadas

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 terdefer_loading: true. Quando você define sua própria ferramenta de pesquisa de ferramentas, ela deve retornar um resultado de 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"
        }
    ]
}

Eles tool_name devem corresponder a uma ferramenta definida na solicitação comdefer_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"
            }]
        }
    }]
}

Claudede acompanhamento (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"
}

Exemplos de uso de ferramentas (beta)

Claude Opus4.5 suporta exemplos fornecidos pelo usuário nas definições de ferramentas para aumentar o desempenho Claude de uso da ferramenta. Você pode fornecer exemplos como chamadas de funções 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"
        }
    ]
}

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

Mid-conversation mudanças de ferramentas (Beta)

O Claude Opus 5 suporta a adição e remoção de ferramentas no meio da conversa tool_addition e de blocos de tool_removal conteúdo nas role: "system" mensagens, em vez de reenviar a tools matriz completa de nível superior (o que invalidaria o cache de prompts).

Forma da solicitação

tool_additione tool_removal os blocos aparecem na content matriz de uma role: "system" mensagem, ao lado dos text blocos opcionais. Cada bloco faz referência a uma ferramenta por meio de seu tool campo. Vários blocos são permitidos e processados na ordem do conteúdo.

{
  "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."}
  ]
}

Ambos os tipos de blocos oferecem cache_control suporte ao cache imediato.

Variantes de referência da ferramenta

O tool campo é uma união discriminada emtype:

tool_referencenão aceita o {server}_{name} formulário composto atribuído às MCP-resolved ferramentas; use uma das variantes do MCP para elas.

Semântica

Respostas de erro (400 invalid_request_error)

Uso forçado de ferramentas

O Claude Fable 5.1 e o Claude Mythos 5.1 não suportam o uso forçado de ferramentas. Uma solicitação que define tool_choice {"type": "any"} ou {"type": "tool", "name": "..."} retorna um400 invalid_request_error:

tool_choice: type "tool" and "any" are not supported for this model.

Isso se aplica às CountTokens operações InvokeModelInvokeModelWithResponseStream, e. Os tool_choice valores padrão {"type": "auto"} e S não {"type": "none"} são afetados e funcionam como antes. Na API Converse, as toolChoice configurações equivalentes (tooleany) apresentam o mesmo erro.