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)

O Claude Sonnet 4.5 é compatível com um novo recurso beta que limpa 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 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 de clear_tool_uses_20250919 e escolher entre as opções de configuração a seguir.

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:

Ao usar o Claude Sonnet 4.5 com a limpeza automática de chamadas de ferramentas, a resposta incluirá informações adicionais de gerenciamento de contexto:

{
    "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
    "type": "message",
    "role": "assistant",
    "content": [...],
    ...
    "usage": {...},
    "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
            }
        ]
    }
}

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.