Uso de ferramentas

Com Anthropic Claude modelos, 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 passar a mensagem Qual é a música mais popular no WZPZ? , o modelo determina 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 de ferramentas refinado

O streaming de ferramentas refinado é um recurso de Anthropic Claude modelo disponível comClaude Sonnet 4.5, Claude Haiku 4.5Claude Sonnet 4, e 4. Claude Opus Com o streaming de ferramentas refinado, Claude os desenvolvedores podem transmitir parâmetros de uso da ferramenta sem buffer ou validação de 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 da ferramenta.

Aqui está um exemplo de como especificar o cabeçalho refinado de streaming da ferramenta:

{
  "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 Claude transmita as linhas de um poema longo para a chamada da ferramenta make_file sem armazenar em buffer para validar se o parâmetro é um JSON válido. lines_of_text 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 de ferramentas refinado, os fragmentos de uso de ferramentas começam a ser transmitidos mais rapidamente, geralmente são mais longos e contêm menos quebras de palavras. Isso se deve às diferenças no comportamento de fragmentação.

Por exemplo, sem streaming refinado (atraso de 15s):

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 3s):

Chunk 1: '{"query": "TypeScript 5.0 5.1 5.2 5.3'
Chunk 2: ' new features comparison'

Computer Use (Beta)

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

A API de uso do computador oferece várias ferramentas predefinidas de uso do computador 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 da versão Claude 3.5 v2, o parâmetro tools foi atualizado para aceitar tipos de ferramentas polimórficas; uma tool.type propriedade foi adicionada para diferenciá-los. typeé opcional; se omitida, a ferramenta é considerada uma ferramenta personalizada (anteriormente o único tipo de ferramenta suportado). Para acessar o uso do computador, você deve usar o anthropic_beta parâmetro, 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 de uso do computador. 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
    }
}

Anthropicferramentas definidas

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

{ 
    "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 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, você pode referenciar explicitamente a ferramenta pelo name campo. 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.

Compensação automática de chamadas de ferramentas (Beta)

O Claude Sonnet 4.5 oferece suporte a um novo recurso beta que limpa 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 da ferramenta, 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 clear_tool_uses_20250919 contexto. 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 inclui 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 fornece aos clientes uma maneira de gerenciar a memória em todas as conversas. Com esse recurso, os clientes podem permitir que 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 context-management-2025-06-27 beta.

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 de custo para uso de ferramentas

Os preços das solicitações de uso de ferramentas são calculados com base nos seguintes fatores:

As ferramentas têm o mesmo preço de todas as outras solicitações de Claude API, mas incluem tokens adicionais por solicitação. Os tokens adicionais do uso da ferramenta vêm do seguinte:

Quando você usa ferramentas, os Anthropic modelos incluem automaticamente um prompt especial do sistema que permite o uso da ferramenta. O número de tokens de uso da ferramenta 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, uma opção de ferramenta sem opção usará 0 tokens adicionais de prompt do sistema.