Tool Orchestration

Quando conectei pela primeira vez uma busca na base de conhecimento ao agente de solicitações de suporte que estava construindo, cometi um erro que levou um dia inteiro para diagnosticar. A chamada de ferramenta funcionou — a busca na KB retornou resultados — mas a resposta final do agente foi pior do que antes de eu adicionar a ferramenta.

O problema não era a ferramenta em si. Era a contaminação de contexto. Eu estava alimentando resultados brutos da KB diretamente no próximo prompt sem controlar como o modelo os interpretaria. O agente começou a tratar artigos da KB como instruções autoritativas em vez de material de referência, e suas respostas desviaram. Eu havia adicionado uma capacidade sem entender o que aterrissaria no contexto de conversa compartilhado como resultado.

Essa falha me ensinou a lição real por trás da orquestração de ferramentas: não se trata de quantas ferramentas você conecta, ou quão inteligentemente você roteia entre elas. Trata-se do que aterra no contexto compartilhado após cada chamada de ferramenta, e se o modelo pode raciocinar claramente a partir dessa imagem acumulada.

Esta é a tese anti-multi-agente no nível das ferramentas. Chamadas paralelas de ferramentas que escrevem em contextos isolados falham pela mesma razão que agentes paralelos falham — cada chamada faz suposições que as outras não conseguem ver. Um padrão sequencial de uso de ferramentas onde cada resultado é acrescentado ao histórico de conversa compartilhado é quase sempre mais confiável, mesmo quando é mais lento.

Pense nas ferramentas como tomadas elétricas em uma oficina. A tomada não se importa com o que você conecta, mas o que você conecta determina tudo sobre o trabalho. Uma tomada bem posicionada alimentando a ferramenta certa supera seis tomadas conectadas às coisas erradas.

Antes de conectar ferramentas ao agente de suporte, quero mostrar a forma real da API, porque o modelo mental importa tanto quanto o código. O fluxo de uso de ferramentas do SDK da Anthropic tem três etapas.

Cada etapa é uma chamada de API separada, e cada chamada estende a lista messages compartilhada. O modelo nunca chama sua função diretamente — ele emite uma solicitação estruturada para que você a chame, e você alimenta o resultado de volta como uma mensagem. Esse design é deliberado: o único contato do modelo com o mundo exterior é através das mensagens que envia e recebe. Tudo que ele sabe sobre o que a ferramenta retornou está nessa lista.

Primeiro, você envia uma mensagem com definições de ferramentas anexadas. Segundo, o modelo responde com um bloco tool_use que nomeia a ferramenta e fornece seus inputs. Terceiro, você chama a função real, depois envia o resultado de volta como um bloco tool_result. O modelo termina com uma resposta em texto simples na próxima chamada.

A coisa crítica a internalizar é a etapa três: você sempre é quem executa a função. O modelo nunca tem acesso direto ao seu código ou à sua infraestrutura. Ele produz uma solicitação estruturada; você a executa; você retorna a saída. Essa fronteira é o que torna os agentes aumentados por ferramentas inspecionáveis — cada chamada de ferramenta e seu resultado é uma mensagem visível no histórico de conversa.

Aqui está o baseline mínimo — uma chamada regular sem ferramentas, para ancorar a forma antes de adicionarmos complexidade:

O objeto de resposta carrega stop_reason, usage e uma lista content. Para uma resposta em texto simples, content[0] é um TextBlock e stop_reason é "end_turn". Esses dois valores ancoram tudo que segue: stop_reason diz o que o modelo quer fazer a seguir, e content diz o que ele produziu neste turno.

Agora adicione uma definição de ferramenta. O SDK da Anthropic usa input_schema — não parameters — para descrever os inputs esperados da ferramenta:

Os campos description não são metadados decorativos. O modelo lê a descrição da ferramenta e cada descrição de propriedade ao decidir se chama a ferramenta e qual valor passar. Uma descrição vaga produz inputs inconsistentes; "Consulta de busca derivada do conteúdo do ticket" ancora o modelo ao texto do ticket.

O agente de suporte precisa de duas ferramentas: busca na KB para encontrar artigos relevantes e histórico de tickets para ver o que aconteceu com este cliente antes. Ter ambas permite ao modelo triangular — uma resposta correta da KB combinada com se esse problema exato já surgiu antes.

Aqui está a segunda definição de ferramenta, seguindo o mesmo formato input_schema:

Quando stop_reason == "tool_use", o modelo nomeou uma ferramenta e forneceu seus inputs. Você extrai esse bloco, chama sua função, depois acrescenta o bloco tool_use do modelo e seu tool_result à lista de mensagens antes da próxima chamada:

A ordem de acréscimo importa. A mensagem assistant carregando response.content vai primeiro, depois a mensagem user carregando o tool_result. Isso preserva a estrutura de papel alternado que a API requer. O tool_use_id no bloco tool_result é como o modelo corresponde cada resultado à chamada que o produziu.

Montando tudo: o loop do agente chama ferramentas conforme necessário, acrescentando cada resultado ao contexto compartilhado, até que o modelo produza uma resposta final "end_turn":

Pause e preveja: se a busca na KB retornar três artigos e o histórico de tickets mostrar que o cliente abriu o mesmo problema duas vezes no mês passado, o que o modelo sabe ao entrar em sua resposta final?

Ele sabe ambos. Esse é o ponto. A lista messages acumula tudo — o ticket original, quais ferramentas foram chamadas, o que elas retornaram — e o modelo raciocina a partir do quadro completo.

Chamadas sequenciais de ferramentas com contexto compartilhado não é uma limitação de desempenho a contornar. É a arquitetura que funciona.

O agente de suporte que construí acabou com exatamente duas ferramentas — busca na KB e histórico de tickets — porque adicionar mais ferramentas aumentou a incerteza na seleção de ferramentas sem melhorar a qualidade das respostas. O modelo estava gastando tokens decidindo qual das oito ferramentas chamar em vez de chamar as duas que precisava.

Duas ferramentas focadas com descrições claras e resultados formatados. Esse foi o padrão que funcionou.

O próximo módulo adiciona um revisor humano a este mesmo agente: quando a confiança do modelo é baixa após consultar as ferramentas, uma pessoa intervém antes de a resposta ser enviada. Esse padrão de escalação constrói diretamente sobre o loop de uso de ferramentas que você tem aqui — o contexto compartilhado que se acumula entre as chamadas de ferramentas é exatamente o que o revisor humano irá ler.