Uso de ferramentas

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

Streaming refinado de ferramentas

O streaming refinado de ferramentas é um recurso do modelo Claude da Anthropic disponível no Claude Sonnet 4.5, Claude 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)

Computer Use é um recurso do modelo Claude da Anthropic (em beta) disponível no Claude 3.5 Sonnet v2, Claude Sonnet 4.5, Claude Haiku 4.5, Claude 3.7 Sonnet, Claude Sonnet 4 e Claude Opus 4. Com o Computer Use, o Claude pode ajudar a automatizar tarefas por meio de ações básicas da GUI.

A API Computer Use oferece várias ferramentas Computer User predefinidas para você usar. É possível criar um prompt com sua solicitação, como “enviar um e-mail para Ben com as anotações da minha última reunião” e uma captura de tela (quando necessário). A resposta contém uma lista de ações de tool_use no formato JSON (por exemplo, scroll_down, left_button_press, screenshot). Seu código executa as ações do computador e fornece ao Claude uma captura de tela mostrando as saídas (quando solicitado).

Desde o lançamento do Claude 3.5 v2, o parâmetro tools foi atualizado para aceitar tipos de ferramentas polimórficas; a propriedade tool.type foi adicionada para diferenciá-las. type é opcional; se omitida, a ferramenta será considerada uma ferramenta personalizada (anteriormente o único tipo de ferramenta compatível). Para acessar a Computer Use, você deve usar o parâmetro anthropic_beta, com uma enumeração correspondente, cujo valor depende da versão do modelo em uso. Consulte a tabela a seguir para obter mais informações.

Somente solicitações feitas com esse parâmetro e enum podem usar as ferramentas Computer Use. Ele pode ser especificado da seguinte forma: "anthropic_beta": ["computer-use-2025-01-24"].

Para obter mais informações, consulte Computer Use (beta) na documentação da Anthropic.

Esta é uma resposta de exemplo que pressupõe que a solicitação continha uma captura de tela da área de trabalho com um ícone do 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
    }
}

Ferramentas definidas do Anthropic

A Anthropic oferece um conjunto de ferramentas para permitir que determinados modelos Claude usem computadores de forma eficaz. Ao especificar uma ferramenta definida da Anthropic, os campos description e tool_schema não são necessários nem permitidos. As ferramentas definidas da Anthropic são definidas pela Anthropic, mas você deve avaliar explicitamente os resultados da ferramenta e retornar os tool_results para o Claude. Tal como ocorre com qualquer ferramenta, o modelo não executa automaticamente a ferramenta. Cada ferramenta definida da Anthropic tem versões otimizadas para modelos Claude 3.5 Sonnet (novos) e Claude 3.7 Sonnet específicos:

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

O campo type identifica a ferramenta e os respectivos parâmetros para fins de validação, enquanto o campo name é 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 campo name deve ser exclusivo na lista de ferramentas. Não é possível definir uma ferramenta com o mesmo name de uma ferramenta definida da Anthropic 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 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:

Ferramenta de memória (beta)

O Claude Sonnet 4.5 inclui uma nova ferramenta de memória que oferece aos clientes uma maneira de gerenciar a memória em todas as conversas. Com esse recurso, os clientes podem permitir que o Claude recupere informações fora da janela de contexto fornecendo acesso a um diretório local. Isso estará disponível como um recurso beta. Para usar esse recurso, você deve usar o cabeçalho beta context-management-2025-06-27.

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 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 comdefer_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 usar o cabeçalho betatool-search-tool-2025-10-19. Observe que atualmente esse recurso está disponível apenas por meio do InvokeModelInvokeModelWithResponseStream APIse.

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

Resultado da ferramenta fornecida pelo cliente

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

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 passar o cabeçalho betatool-examples-2025-10-29.

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