Tool Runner (SDK)

O "tool runner" (executor de ferramentas) lida com o loop agêntico, encapsulamento de erros e segurança de tipos para que você não precise fazer isso. Quando você precisar de aprovação humana no loop, logging personalizado ou execução condicional, use o loop manual em vez disso.

Em vez de lidar manualmente com chamadas de ferramentas, resultados de ferramentas e gerenciamento de conversas, 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 tipos e validação



Uso básico

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

Dependendo da assinatura de ferramenta do SDK, uma ferramenta retorna seu resultado como uma string ou como blocos de conteúdo (blocos de texto, imagem ou documento), de modo que uma ferramenta pode retornar resultados multimodais. Uma string retornada se torna um único bloco de conteúdo de texto. Para retornar dados estruturados, como um objeto JSON ou um número, codifique-os como uma string primeiro.



Iterando sobre o tool runner

O tool runner é um iterável que produz mensagens de Claude. Em cada iteração, o runner verifica se Claude solicitou um uso de ferramentas. Se sim, ele executa a ferramenta e envia o resultado de volta para Claude automaticamente, então produz a próxima mensagem de Claude para continuar seu loop.

Você pode encerrar o loop em qualquer iteração com uma instrução break. O runner executa em loop até que Claude retorne uma mensagem sem um uso de ferramentas, ou até atingir max_iterations se você o definir.

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



Uso avançado

Dentro do loop, você pode ler cada mensagem de resposta e modificar o estado do runner antes da próxima chamada de API. Cada iteração segue este ciclo de vida:

1. O runner envia uma requisição para a Messages API com seu estado atual.
2. O runner produz a mensagem de resposta para o corpo do seu loop.
3. O corpo do seu loop é executado. Você pode ler a mensagem e, opcionalmente, modificar o estado do runner.
4. Quando o corpo do seu loop retorna, o runner verifica se você modificou seu histórico de mensagens.
   • Se você não modificou o histórico de mensagens: O runner anexa a mensagem do assistente ao seu estado. Se a mensagem contiver chamadas de ferramentas, o runner as executa e anexa os resultados. Se não houver chamadas de ferramentas, o loop é encerrado.
   • Se você modificou o histórico de mensagens: O runner pula seu anexo automático e usa seu estado sem alterações. Consulte Assumindo o controle do histórico de mensagens.



Assumindo o controle do histórico de mensagens

Por padrão, o runner gerencia o estado da conversa para você: após cada turno, ele anexa a mensagem do assistente e quaisquer resultados de ferramentas ao seu próprio histórico de mensagens. Você assume o controle do histórico de mensagens quando quer repetir um turno (descartar a resposta e reenviar), injetar uma mensagem de acompanhamento ou construir o resultado da ferramenta você mesmo.

Você assume o controle modificando as mensagens do runner de dentro do corpo do loop. O método exato depende do SDK. Consulte as abas por linguagem a seguir.

Quando você assume o controle em uma iteração, o runner não anexa a mensagem do assistente nem os resultados de ferramentas daquele turno. Você se torna responsável por manter a conversa válida: anexe a mensagem do assistente e um resultado de ferramenta você mesmo (se quiser que o turno conte), modifique o estado condicionalmente para que o loop ainda possa ser encerrado quando não houver chamadas de ferramentas, e passe max_iterations para limitar o loop. Todos os sete SDKs suportam max_iterations.



Gerenciamento automático de contexto

Para tarefas agênticas de longa duração, os tool runners de Python, TypeScript e Ruby suportam compactação automática, que gera resumos quando o uso de tokens excede um limite para que a conversa possa continuar além dos limites da janela de contexto. Todos os três SDKs descontinuaram essa opção do lado do cliente em favor da edição de contexto do lado do servidor, que está disponível em todos os SDKs. Os tool runners de Go, Java, C# e PHP não incluem compactação do lado do cliente.



Depurando a 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. O resultado da ferramenta carrega a mensagem da exceção (em Python, seu tipo e mensagem), não o stack trace completo.

O que o SDK registra em log é específico de cada linguagem. O SDK Python registra a exceção completa, incluindo seu stack trace, através do módulo padrão logging sempre que uma ferramenta lança uma exceção não tratada. Os SDKs Python, TypeScript e Java leem a variável de ambiente ANTHROPIC_LOG para ativar o logging do SDK, que inclui detalhes de requisição e resposta:

# Registra no nível info
export ANTHROPIC_LOG=info

# Registra no nível debug para saída mais detalhada
export ANTHROPIC_LOG=debug

Os SDKs Go, Ruby, C# e PHP não leem ANTHROPIC_LOG. Fora do Python, nenhum SDK registra em log uma ferramenta que falhou: para ver por que uma ferramenta falhou, capture e registre a exceção dentro da função da ferramenta antes de retornar ou relançá-la.



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 tratá-los de forma diferente, por exemplo, para interromper a execução antecipadamente ou implementar tratamento de erros personalizado.

Nos SDKs Python e TypeScript, use o método de resposta de ferramenta (generate_tool_call_response() em Python, generateToolResponse() em TypeScript) para interceptar resultados de ferramentas e verificar erros antes que sejam enviados para Claude. Os outros SDKs não expõem esse hook. Suas abas descrevem a alternativa mais próxima:



Modificando resultados de ferramentas

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

Nos SDKs Python e TypeScript, use o método de resposta de ferramenta para obter o resultado da ferramenta e, em seguida, modifique-o antes que o runner prossiga. Se você anexa explicitamente o resultado modificado ou o muta no local depende do SDK. Consulte os comentários de código em cada aba.



Streaming

Habilite streaming para processar a resposta de cada turno incrementalmente. Cada iteração produz um objeto de stream que você pode iterar para obter eventos.



Próximos passos