Abertura

O bot de atendimento de uma empresa de software começou com uma ferramenta para buscar usuário. Depois veio outra para buscar usuário por e-mail. Uma para procurar cliente por CPF. Uma para pesquisar usuários por texto livre. Get account. Get account versão dois. E uma exportação para planilha que alguém colocou, para o time de dados.

Sete nomes. Quatro jeitos de achar a mesma pessoa.

Agora um pedido simples. Qual é o plano da Maria? Aqui está o CPF dela.

O modelo pesquisa usuários por Maria, e recebe quarenta linhas.

Depois busca o usuário com o primeiro id da lista.

Depois pede a conta, com um id de usuário onde devia ir um id de conta. Três chamadas. Nenhum plano. E a ferramenta de exportação? Zero chamadas em noventa dias de traces.

Nesta aula, você vai fundir essa lista até sobrar o que o modelo realmente consegue escolher, com segurança, e sem mudar uma linha do seu backend.

A ideia

A solução é simples de dizer. Funda as ferramentas que fazem a mesma coisa numa só, com parâmetros claros. E tire as que os seus traces mostram que ninguém usa.

Tem um detalhe revelador dos times que constroem agentes a sério. Alguns gastam mais tempo desenhando as ferramentas do que o prompt. Uma lista longa de nomes que se sobrepõem é o contrário disso. O modelo lê sete descrições vagas, e chuta.

Antes e depois

Antes, sete ferramentas, com quatro jeitos de achar a mesma pessoa, e duas versões da mesma consulta de conta.

Depois, o mesmo pedido chega, e o modelo vê uma lista curta, com descrições que dizem quando usar cada ferramenta.

Uma ferramenta só acha o cliente, com a chave como parâmetro. Por id, por e-mail ou por CPF.

E a próxima ferramenta deixa claro que depende do resultado anterior. Ela pede um id de cliente, com esse nome.

Aqui está a lista nova. Find customer. Por id, e-mail ou CPF. Use antes de qualquer pergunta sobre plano, cobrança ou conta. Devolve o id, o nome, o plano e o status.

E get account. Dados de cobrança. Precisa do id de cliente devolvido por find customer.

Então a pergunta da Maria vira: find customer, por CPF. Volta o plano dela. Se o plano já responde a pergunta, o modelo para. Se precisa de faturas, chama get account, com o id de cliente dela. Nada de lista com quarenta Marias. Nada de consulta de conta com o tipo errado de id.

Por que funciona

O modelo escolhe ferramentas lendo nomes e descrições. Quando várias opções descrevem a mesma coisa com palavras diferentes, a escolha vira chute. Uma ferramenta por intenção tira o chute. A decisão deixa de ser qual destas quatro, e vira qual valor vai no campo by. E o schema restringe isso.

Tirar as ferramentas sem uso tem um efeito extra. O prompt encolhe em toda chamada. Aquela ferramenta de exportação no schema é ruído que você paga em toda conversa, inclusive nas que nunca exportam.

E existe um limite. Se você fundiu os sinônimos, tirou os fantasmas, e ainda tem quarenta ferramentas com boas descrições, o próximo passo não é outra fusão. É expor um subconjunto por intenção, com um roteador, ou revelando as ferramentas aos poucos.

Um desafio

Uma pergunta para você. Um colega propõe uma ferramenta única de cliente, com um parâmetro chamado action. Os valores são get, search, export ou delete. Ele chama isso de consolidar. É?

Não. Ler, pesquisar, exportar e apagar são intenções diferentes. Agora o modelo escolhe entre valores de action tão vagos quanto os sete nomes antigos. E um delete mal escolhido tem efeito colateral. Isso não é consolidar. É esconder a bagunça dentro de uma função.

Consolidar funde o que responde a mesma pergunta. Quem é este cliente? Delete não é um jeito de achar cliente.

Passo a passo seguro

Passo zero, medir. Rode o eval do agente e anote a taxa de conclusão, os passos por tarefa e a taxa de chamada errada. Uma ferramenta que devolveu erro de argumento, ou foi seguida por uma parecida.

Junte o uso real. Em sessenta a noventa dias de traces, conte quantas vezes cada ferramenta foi chamada, e a taxa de erro dela. Zero chamadas faz dela candidata a sair, não a ser fundida.

Agrupe por intenção. Ferramentas que respondem a mesma pergunta vão para o mesmo grupo. E leitura e escrita nunca se misturam no mesmo grupo.

Desenhe uma ferramenta por grupo. Um parâmetro de escolha com lista fechada de valores, uma descrição que diz quando usar e o que volta, e um nome de verbo mais substantivo. E construa em cima do código antigo. A ferramenta nova chama as funções que já existiam. Nada muda no backend.

Tire as ferramentas sem uso numa mudança separada, para conseguir reverter uma sem a outra.

Atualize os casos do eval que citavam as ferramentas antigas pelo nome. Digamos que depois da fusão a taxa de conclusão cai, porque o eval antigo ainda chama get account com um id de usuário. Não aceite os dois nomes de parâmetro para o eval ficar verde. Isso traz a ambiguidade de volta. Quem está desatualizado é o eval. Corrija o dataset primeiro, depois compare.

E meça de novo. Conclusão igual ou maior, menos passos, menos chamadas erradas e menos tokens de entrada por chamada.

Riscos

Alguns riscos. Uma ferramenta grande demais. Fundir coisas diferentes numa ferramenta com dez parâmetros opcionais recria a confusão lá dentro. Se os parâmetros dependem uns dos outros, tipo se a ação for estorno o valor é obrigatório, são duas ferramentas.

Um fluxo raro quebrado. A ferramenta de exportação teve zero chamadas em noventa dias. Aí o time de dados diz que usa no fechamento do trimestre, que caiu fora da janela. Zero na janela não prova que não é usada. Confirme com o dono do fluxo, deixe a remoção reversível e, se ela sair, tire numa mudança só dela.

Semântica alterada. Se a versão dois devolvia campos que a um não devolvia, a ferramenta fundida precisa devolver. Senão você simplificou apagando dado.

E permissões misturadas. Nunca funda uma ferramenta de leitura com uma de escrita, mesmo quando elas usam a mesma chave. Ver a fatura e emitir um estorno usam os dois um id de pedido. Fundir os dois deixa o modelo a um chute de mandar dinheiro, quando ele só queria ver a fatura.

Prática

Vamos praticar com um agente de RH. Quatro ferramentas. Saldo de férias. Dias de férias restantes. Consultar folga remunerada. E pedir férias. Uma delas não deveria ser fundida com as outras. Qual?

As três primeiras respondem a mesma pergunta, e viram uma ferramenta de leitura. Saldo de férias, por id do funcionário ou por e-mail. Use antes de sugerir datas.

E pedir férias tem efeito colateral. Ela fica separada, de preferência atrás de uma confirmação. A descrição dela diz que só cria um pedido para o gestor aprovar, só depois que o funcionário confirma as datas, e não aprova nada sozinha.

Fechamento

Então, a ideia para levar. Conte o que é usado de verdade, funda o que responde a mesma pergunta e mantenha efeitos colaterais em ferramentas próprias. Construa sobre o código que você já tem, remova em passos separados e deixe o eval provar que o modelo agora acerta de primeira.

Na próxima aula, a gente trata o que sobra quando a lista continua longa, porque o agente cobre muitos assuntos de verdade: o tool router. Até lá.