Principal Primeiros passos Como escrever a descrição e as instruções de um Agente Especialista

Como escrever a descrição e as instruções de um Agente Especialista

Última atualização em Oct 14, 2026

Quando usar

  • Você vai escrever um novo Agente Especialista (rastrear pedido, consultar crédito, remarcar agendamento, qualificar lead etc.)
  • Você está revisando um especialista e quer alinhar com o padrão atual
  • Você está migrando um Fluxo Controlado para um especialista

Sobre este artigo

Os Agentes Especialistas são acionados pelo Supervisor. Cada especialista recebe o pedido em linguagem natural, consulta os sistemas pelas ferramentas dele e devolve o resultado ao Supervisor, que redige a resposta para o cliente.

Cada especialista tem dois textos:

  • Descrição: lida pelo Judge e pelo Supervisor para decidir se e quando este especialista atende
  • Instruções de comportamento: lidas pelo próprio especialista quando ele é acionado

O especialista nunca fala diretamente com o cliente. Ele não vê a conversa inteira: recebe só o que o Supervisor contou e devolve o resultado para o Supervisor. Frases prontas para o cliente dentro das instruções competem com o tom de voz do Supervisor.

Além desses dois textos, o comportamento do especialista depende das descrições das ferramentas e dos parâmetros que ele usa. Elas estão em Boas práticas para criar um Agente Especialista.

Antes de escrever: autônomo ou determinístico?

Tipo Quando usar Template
Autônomo Os passos dependem do que o cliente responde e existe mais de um caminho válido 02
Determinístico Sequência conhecida, não negociável, com verificação etapa por etapa 03
Nenhum dos dois Fluxo 100% procedural, sem nenhum ponto de interpretação Use um Fluxo Controlado

Se o fluxo é quase todo fixo, mas tem um ou dois pontos de interpretação, use o determinístico: o template prevê isso.

Os templates prontos para copiar estão em Templates para escrever um Agente Especialista.

Ordem de escrita

  1. Descrição do especialista. Vem primeiro porque obriga a ter clareza de escopo.
  2. Descrições das ferramentas e dos parâmetros. Boa parte do que iria para as instruções resolve-se aqui.
  3. Instruções de comportamento. Com as duas etapas anteriores feitas, elas ficam curtas.
  4. Tom de voz do Supervisor, só se o projeto for novo. É um por projeto, não por especialista.

A descrição

A descrição é a superfície de roteamento. Use este formato:

[Uma frase dizendo o que este especialista resolve.]

EXECUTA
- [ação de negócio]

NÃO EXECUTA
- [ação vizinha] → é de [destino]

ACIONE QUANDO
- [situação, na linguagem que o cliente usa]

NÃO ACIONE QUANDO
- [caso de fronteira] → vai para [destino]

TESTE FINAL
[Uma pergunta de sim ou não que decide os casos duvidosos.]

Exemplo — especialista de rastreamento:

Consulta onde está um pedido já feito e quando ele deve chegar.

EXECUTA
- consultar o status e a previsão de entrega de um pedido
- informar o código e o link de rastreio da transportadora

NÃO EXECUTA
- cancelar, trocar ou devolver → é do especialista de Trocas e Devoluções
- alterar endereço de entrega → é do especialista de Alteração de Pedido
- reembolso → é do especialista Financeiro

ACIONE QUANDO
- o cliente quer saber onde está o pedido ou quando chega
- o cliente pergunta se o produto já foi enviado
- o cliente diz que o pedido está atrasado

NÃO ACIONE QUANDO
- o cliente recebeu o produto com defeito → vai para Trocas e Devoluções
- o cliente ainda não fez a compra e quer saber o prazo → vai para a base de conhecimento

TESTE FINAL
O cliente está perguntando sobre a entrega de um pedido que já existe?

Boas práticas:

  • Use a linguagem do cliente. Se o cliente diz "quero cancelar" e a descrição diz "fluxo de retenção de churn", o roteamento falha.
  • Declare as fronteiras com destino. Para cada assunto vizinho, diga para onde ele vai.
  • Se o especialista depende de um dado (número do pedido, CPF), diga em ACIONE QUANDO que o pedido já precisa trazer esse dado. Assim o Supervisor coleta antes de acionar, em vez de acionar, receber "falta dado" e acionar de novo.
  • Teste com dez frases reais: cinco que devem cair aqui e cinco que não devem. Lendo só a descrição, você conseguiria decidir cada uma? Detalhes em Como o Supervisor decide qual Agente Especialista responde.

O que nunca entra na descrição: como executar, regra de negócio, formato de resposta, nome técnico de ferramenta ou de endpoint.

As instruções de comportamento

A plataforma já entrega ao especialista um conjunto fixo de regras. As instruções existem para o que só você sabe sobre o seu negócio, e por isso têm quatro conteúdos:

  1. Fronteira do domínio. O que está coberto e o que não está, com o destino de cada assunto vizinho.
  2. Regras de interpretação. O que concluir de cada resultado das ferramentas. Exemplo: "previsão de entrega anterior a hoje significa pedido atrasado".
  3. Critério de ação. Quando cada ferramenta se aplica e quais desfechos ela devolve.
  4. O que entregar ao Supervisor. O desfecho, os dados com a origem, o que ficou pendente e a recomendação de próximo passo.

Na ordem: domínio e fronteira, dados necessários, ações disponíveis, regras de negócio, desambiguação, retenção e transbordo, entrega ao Supervisor.

O que a plataforma já garante (não reescreva)

O especialista já recebe estas regras da plataforma:

  • Usar só as informações que vêm das ferramentas, sem conhecimento geral nem suposição
  • "Não tenho essa informação" é uma resposta correta
  • Não prometer ação que nenhuma ferramenta executa
  • A resposta vai para o Supervisor, não para o cliente
  • Transferir para humano é recomendação: quem executa é o Supervisor

Reescrever essas regras com outras palavras atrapalha. A sua versão passa a competir com a da plataforma, e o especialista começa a escolher entre as duas de forma diferente a cada conversa. Blocos longos de "NUNCA invente" ou "BLOQUEANTE" costumam fazer o especialista se recusar a usar as próprias ferramentas.

Boas práticas de escrita

  • Escreva regras como ação: "quando X, faça Y", e não proibições genéricas
  • Explique o porquê da regra. "Acima de R$ 1.000, porque abaixo disso o frete não compensa" funciona melhor nos casos de borda do que só o número
  • Dê um veredito para cada caso ambíguo. Nenhum caso conhecido deve ficar em aberto
  • Nomeie todos os desfechos de cada ferramenta, inclusive os ruins: encontrou vários, não encontrou, status inesperado, dado que contradiz o relato do cliente
  • Não infle a ênfase. Maiúsculas em série e "NUNCA" repetido dezenas de vezes diluem o que importa

O que não entra nas instruções

  • Tom de voz, saudação e despedida: são do Supervisor
  • Ordem obrigatória entre ferramentas: se uma sequência é sempre a mesma, ela deve virar uma ferramenta só
  • Tabelas de conversão entre texto e valor de sistema, regras de formato de dado e "use só o campo X, ignore o resto": são trabalho da ferramenta ou da descrição do parâmetro
  • Regras de roteamento: ficam na descrição

Especialista determinístico

Quando o processo é uma sequência fixa, a ordem e a validação das etapas ficam numa ferramenta de controle, e não no texto. O especialista faz três coisas a cada acionamento:

  1. Identifica se a mensagem do cliente responde à etapa pendente, traz um assunto novo ou corrige algo já informado
  2. Chama a ferramenta de controle com o que tem
  3. Leva ao Supervisor o que a ferramenta devolveu

As instruções precisam dizer o que fazer quando o cliente corrige um dado no meio do fluxo, quando traz outro assunto (relatar ao Supervisor sem forçar a etapa), quando responde fora do formato (repetir a etapa, não transferir) e qual é o limite de tentativas na mesma etapa.

Por que a sequência não fica no texto: quando as instruções descrevem dezenas de passos em ordem, o modelo pula ou funde etapas. O agente fica não determinístico mesmo quando o processo é determinístico. Veja Quando usar Fluxo Controlado ou Agentes Especialistas.

Retenção e transbordo

Todo especialista precisa de um bloco que diga quando ele não deve recomendar transferência. Sem esse bloco, diante de um resultado que ninguém previu, o caminho mais cauteloso para o especialista é recomendar humano, e o Supervisor cumpre.

O bloco padrão está nos templates e a explicação completa está em Como funciona a transferência para humano nos Agentes Especialistas.

Usando o AI Companion

O AI Companion gera a descrição e as instruções a partir de uma explicação em linguagem natural, migra um Fluxo Controlado existente ou revisa um especialista já criado. Mesmo usando o Companion, vale conferir o resultado com este artigo. Veja Como criar agentes com linguagem natural (AI Companion).

Erros comuns

  • Descrição que se sobrepõe à do vizinho. Quando dois especialistas poderiam atender o mesmo caso, o roteamento oscila.
  • Ação prometida na descrição sem ferramenta que a execute. Se a descrição diz "trata cancelamento", precisa existir ferramenta de cancelamento.
  • Frases prontas para o cliente nas instruções. O especialista entrega fatos; o Supervisor redige.
  • Lógica de conversa no especialista. Retenção do cliente insistente, reformulação e tom são do Supervisor. O especialista faz a mesma coisa na primeira e na quinta chamada.
  • Sequência de etapas escrita como texto. Vai para a ferramenta.
  • Transferência por leitura emocional ("se o cliente estiver frustrado"). A regra de transferência precisa se apoiar num dado que a ferramenta devolve.

Observações