Principal Primeiros passos Boas práticas para criar um Agente Especialista

Boas práticas para criar um Agente Especialista

Última atualização em Oct 14, 2026

Quando usar

  • Você está montando seu primeiro Agente Especialista e quer evitar os erros mais comuns
  • Você está revisando especialistas existentes e quer um checklist
  • Você quer entender o que vai nas ferramentas e o que vai no texto

Pré-requisitos

Sobre este artigo

A maior parte dos problemas de especialistas não vem de texto mal escrito. Vem de instrução escrita no lugar errado: regra de escolha de ferramenta nas instruções, sequência de etapas no texto, tom de voz dentro do especialista. Este artigo mostra onde cada coisa deve morar e traz o checklist de revisão.

O princípio que organiza tudo

Julgamento de linguagem fica no modelo. Sequência, validação e estado ficam na ferramenta.

O modelo é ótimo para entender o que o cliente quis dizer, reconhecer uma correção e lidar com mudança de assunto. Ele não é confiável para executar dezenas de passos sempre na mesma ordem, validar formato ou comparar valores de forma idêntica em toda conversa.

Por isso, quando a regra é "sempre faça A, depois B, depois C" ou "se o campo X for maior que Y", ela funciona melhor dentro da ferramenta (na sua API, no servidor MCP ou no fluxo usado como ferramenta) do que escrita nas instruções. Regra na ferramenta executa sempre igual, muda sem reabrir o teste do especialista e fica auditável no retorno.

As cinco superfícies de escrita

Existem cinco lugares onde o texto que você escreve muda o comportamento do sistema. Cada um tem um leitor diferente:

Superfície Onde fica Quem lê O que entra O que nunca entra
Descrição do especialista Campo Descrição do especialista Judge e Supervisor, ao decidir quem atende O que executa, o que não executa, quando acionar, quando não acionar, teste final Como executar, regra de negócio, formato de resposta
Tom de voz Campo Instruções gerais e tom de voz do Supervisor Supervisor, ao redigir para o cliente Identidade, como fala, como não fala, exemplos, critério de transbordo Regras de operação e de roteamento
Instruções do especialista Campo Instruções de comportamento O especialista, ao ser acionado Fronteira, regras de interpretação, critério de ação, o que entregar O que a plataforma já garante, tom de voz, sequência de etapas
Descrição da ferramenta Descrição da ferramenta O especialista, ao escolher a ferramenta O que faz, quando usar, quando não usar, o que devolve Nome técnico de endpoint, ordem em relação a outra ferramenta
Descrição do parâmetro Descrição de cada parâmetro da ferramenta A plataforma, ao preencher o campo O que é o dado, o formato, de onde tirar Regra de negócio

Regra de decisão rápida

Antes de escrever qualquer instrução, pergunte onde ela pertence:

  • É critério para escolher este especialista? → Descrição do especialista
  • É como o cliente deve ser tratado? → Tom de voz do Supervisor
  • É critério para escolher esta ferramenta? → Descrição da ferramenta
  • É o que preencher num campo? → Descrição do parâmetro
  • É sequência, validação, conversão ou cálculo? → Dentro da ferramenta
  • É conhecimento do assunto ou como interpretar um resultado? → Instruções do especialista

Ferramentas

Descrição da ferramenta

É o texto que o especialista lê para escolher a ferramenta certa, na hora certa, com os dados certos. Revisar as descrições das ferramentas costuma render mais do que reescrever as instruções, e é a superfície mais esquecida.

Use uma frase de propósito e três blocos curtos:

Consulta os pedidos de um cliente a partir do CPF ou do número do pedido.

Quando usar: o cliente quer saber status, previsão de entrega ou rastreio de um
pedido já feito.

Quando não usar: para alterar ou cancelar pedido (use "Alterar pedido").

O que devolve: um pedido encontrado; vários pedidos encontrados (lista para o
cliente escolher); nenhum pedido encontrado; CPF sem cadastro.
  • Escreva em linguagem de negócio, não "chama o endpoint /orders"
  • Nomeie os desfechos, não o formato técnico: encontrou um, encontrou vários, não encontrou, cliente não existe
  • Não repita só o nome da ferramenta: "Consulta pedido" não acrescenta nada

Descrição do parâmetro

Diz à plataforma o que preencher em cada campo. Quando o dado já está na conversa, ela o extrai sozinha.

Documento do titular da conta, apenas dígitos, sem pontuação. Usar o documento
informado pelo próprio cliente na conversa, não o de terceiros mencionados.

Diga o que é, o formato quando importa e de onde tirar quando há mais de uma origem possível na conversa.

Como desenhar as ferramentas

  • Consolide o que sempre roda junto. Quatro consultas que acontecem sempre em sequência não são quatro decisões do especialista: são uma decisão e três execuções. Exponha como uma ferramenta só.
  • Unifique a leitura do mesmo registro por chaves diferentes. "Buscar por e-mail" e "buscar por telefone" são uma ferramenta com dois parâmetros opcionais.
  • Separe leitura de escrita. Consultar e alterar (aplicar etiqueta, atualizar cadastro) ficam em ferramentas diferentes, porque têm riscos e permissões diferentes.
  • Devolva só o que o especialista usa. Filtre o retorno na ferramenta em vez de instruir o especialista a ignorar campos.
  • Devolva desfechos nomeados, como encontrou_varios, nao_encontrado e erro_consulta, em vez de códigos de status.
  • Faça o erro dizer o próximo passo: "coletar outro identificador" em vez de "falha na consulta".
  • Quando possível, a ferramenta devolve o veredito de transferência junto com o dado. Exemplo: além do status do pedido, ela devolve se aquele caso exige atendimento humano e por quê.
  • Evite listas longas de ferramentas por especialista. A tela recomenda até 15 ferramentas liberadas por agente.

Erros conhecidos

  • Linguagem interna na descrição. Se o cliente diz "quero cancelar" e a descrição diz "fluxo de retenção de churn", o roteamento falha.
  • Descrições vizinhas que se sobrepõem. Quando dois especialistas poderiam atender o mesmo caso, o roteamento oscila entre eles.
  • Regras de roteamento repetidas no Supervisor. A descrição já faz esse trabalho. Repetir cria duas fontes de verdade.
  • Reescrever o que a plataforma já garante, como "não invente dados" ou "não prometa ações". A sua versão compete com a da plataforma.
  • Frases prontas para o cliente nas instruções do especialista. Conflitam com o tom do Supervisor.
  • Sequência de etapas e árvores de decisão no texto. "Se X, faça Y; se não, verifique Z" é frágil. Vai para a ferramenta.
  • "Use a ferramenta Y só depois da X" nas instruções. Se a ordem é obrigatória, as duas viram uma ferramenta.
  • Ferramenta sem descrição ou com descrição que só repete o nome.
  • Transferência por leitura emocional. Ver Como funciona a transferência para humano.
  • Mudar instruções, ferramenta e descrição ao mesmo tempo. Depois ninguém sabe o que funcionou.

Checklist de revisão

Onde cada coisa está

  • Nenhuma instrução repete o que a plataforma já garante
  • As instruções não têm tom de voz, saudação ou despedida
  • Nenhuma regra de formato de dado está nas instruções quando poderia estar na descrição do parâmetro ou na ferramenta
  • Nenhuma tabela de conversão e nenhuma ordem entre ferramentas está nas instruções

Descrição do especialista

  • Tem os blocos executa, não executa, acione quando, não acione quando e teste final
  • Usa a linguagem do cliente e descreve ação de negócio, não ferramenta
  • Declara as fronteiras com os especialistas vizinhos, com destino
  • Dez frases reais (cinco que caem aqui, cinco que não caem) são decididas corretamente lendo só a descrição

Instruções do especialista

  • O domínio cabe numa frase, sem "e" ligando duas responsabilidades
  • Toda ação mencionada tem uma ferramenta que a executa
  • Todos os desfechos de cada ferramenta têm tratamento, inclusive não encontrou, encontrou vários, status inesperado e relato que contradiz o sistema
  • Os casos ambíguos têm veredito
  • Existe o bloco de retenção e transbordo
  • A entrega ao Supervisor diz quais fatos, com origem, e qual recomendação

Ferramentas e parâmetros

  • Cada ferramenta tem descrição com o que faz, quando usar, quando não usar e o que devolve
  • Nenhuma ferramenta é sempre chamada junto com outra (se é, consolide)
  • Cada retorno devolve só o que o especialista usa
  • As mensagens de erro dizem o que fazer em seguida
  • Cada parâmetro tem descrição com o que é, o formato e de onde tirar

Antes de ligar em produção

  • Existem casos de teste com o resultado esperado, cobrindo os desfechos ruins e não só o caminho feliz
  • Os três casos de transferência foram testados: relato que contradiz o sistema (esperado: N1), caso da regra de negócio (esperado: transferência) e cliente irritado sem caso de regra (esperado: N1)
  • Está definido o que vai ser medido e em quanto tempo

Observações