Tool Runner (SDK)

Tool Runner lida com o loop agentico, encapsulamento de erros e segurança de tipo para que você não tenha que fazer isso. Use o loop manual apenas quando você precisar de aprovação humana no loop, logging customizado ou execução condicional. Disponível em Python, TypeScript e Ruby SDKs.

O tool runner fornece uma solução pronta para executar ferramentas com Claude. Em vez de lidar manualmente com chamadas de ferramentas, resultados de ferramentas e gerenciamento de conversa, o tool runner automaticamente:

• Executa ferramentas quando Claude as chama
• Lida com o ciclo de requisição/resposta
• Gerencia o estado da conversa
• Fornece segurança de tipo e validação

Use o tool runner para a maioria das implementações de uso de ferramentas.

Uso básico

Defina ferramentas usando os helpers do SDK e, em seguida, use o tool runner para executá-las.

A função de ferramenta deve retornar um bloco de conteúdo ou array de blocos de conteúdo, incluindo texto, imagens ou blocos de documento. Isso permite que ferramentas retornem respostas ricas e multimodais. Strings retornadas serão convertidas para um bloco de conteúdo de texto. Se você quiser retornar um objeto JSON estruturado para Claude, codifique-o como uma string JSON antes de retorná-lo. Números, booleanos ou outros primitivos não-string também devem ser convertidos para strings.

Iterando sobre o tool runner

O tool runner é um iterável que produz mensagens do Claude. Isso é frequentemente referido como um "tool call loop". A cada iteração, o runner verifica se Claude solicitou um uso de ferramenta. Se sim, ele chama a ferramenta e envia o resultado de volta para Claude automaticamente, depois produz a próxima mensagem do Claude para continuar seu loop.

Você pode encerrar o loop em qualquer iteração com uma instrução break. O runner fará loop até que Claude retorne uma mensagem sem um uso de ferramenta.

Se você não precisar de mensagens intermediárias, você pode obter a mensagem final diretamente:

Uso avançado

Dentro do loop, você pode personalizar completamente a próxima requisição do tool runner para a API de Mensagens. O runner automaticamente anexa resultados de ferramentas ao histórico de mensagens, então você não precisa gerenciá-los manualmente. Você pode opcionalmente inspecionar o resultado da ferramenta para logging ou debugging, e modificar os parâmetros de requisição antes da próxima chamada de API.

Debugging de execução de ferramentas

Quando uma ferramenta lança uma exceção, o tool runner a captura e retorna o erro para Claude como um resultado de ferramenta com is_error: true. Por padrão, apenas a mensagem de exceção é incluída, não o rastreamento de pilha completo.

Para visualizar rastreamentos de pilha completos e informações de debug, defina a variável de ambiente ANTHROPIC_LOG:

# View info-level logs including tool errors
export ANTHROPIC_LOG=info

# View debug-level logs for more verbose output
export ANTHROPIC_LOG=debug

Quando habilitado, o SDK registra detalhes completos de exceção (usando o módulo logging do Python, o console em TypeScript ou o logger do Ruby), incluindo o rastreamento de pilha completo quando uma ferramenta falha.

Interceptando erros de ferramentas

Por padrão, erros de ferramentas são passados de volta para Claude, que pode então responder apropriadamente. No entanto, você pode querer detectar erros e lidar com eles de forma diferente, por exemplo, para parar a execução antecipadamente ou implementar tratamento de erro customizado.

Use o método de resposta de ferramenta para interceptar resultados de ferramentas e verificar erros antes de serem enviados para Claude:

Modificando resultados de ferramentas

Você pode modificar resultados de ferramentas antes de serem enviados de volta para Claude. Isso é útil para adicionar metadados como cache_control para habilitar prompt caching em resultados de ferramentas, ou para transformar a saída da ferramenta.

Use o método de resposta de ferramenta para obter o resultado da ferramenta, depois modifique-o antes do runner prosseguir. Se você explicitamente anexa o resultado modificado ou o muta no local depende do SDK; veja os comentários de código em cada aba.

Streaming

Habilite streaming para receber eventos conforme chegam. Cada iteração produz um objeto de stream que você pode iterar para eventos.

Próximos passos

• Para controle manual sobre o tool-call loop, veja Handle tool calls.
• Para executar múltiplas ferramentas concorrentemente, veja Parallel tool use.
• Para o fluxo de trabalho completo de tool-use, veja Define tools.