Principal Primeiros passos O que preparar antes de montar um Agente Especialista

O que preparar antes de montar um Agente Especialista

Última atualização em Oct 14, 2026

Quando usar

  • Você vai criar um Agente Especialista novo, sozinho ou junto com o time da Cloud Humans
  • Você vai revisar um especialista que já está no ar
  • Você quer adiantar o trabalho antes de uma reunião de configuração

Sobre este artigo

Um bom especialista depende menos do texto das instruções e mais do que existe por trás dele: um processo bem definido, as integrações que executam as ações e as regras que dizem quando o caso precisa de uma pessoa.

Este artigo lista o que reunir antes de escrever qualquer linha. Quando esse material chega completo, montar o especialista vira um trabalho de revisão. Quando falta, as instruções tentam compensar a lacuna e o especialista fica instável.

Instrução não conserta escopo indefinido. Se algum item abaixo ainda não tem resposta, vale resolver antes de começar a escrever.

1. O caso

  • O que o especialista resolve, em uma frase. Se você precisar de "e" para ligar duas responsabilidades diferentes, provavelmente são dois especialistas.
  • Quais ações ele executa, em linguagem de negócio: "consultar o status do pedido", "remarcar a entrega". Não use nome de sistema ou de endpoint.
  • Quais especialistas já existem no projeto e podem ser confundidos com este.
  • Dez frases reais de clientes: cinco que devem cair neste especialista e cinco que não devem, de preferência casos de fronteira. Elas servem para escrever e para testar a descrição.

2. Sistemas e APIs

Toda ação do especialista precisa de uma ferramenta que a execute. Se não existe ferramenta, a ação não existe: ou ela é construída, ou sai do escopo.

Para cada sistema que o especialista vai consultar ou alterar, reúna:

  • Como acessar: documentação da API (endpoints, método, autenticação, parâmetros), o app correspondente em Integrações ou o endereço de um servidor MCP
  • Ambiente de teste, se existir
  • Todos os resultados possíveis de cada consulta, incluindo os ruins: encontrou um registro, encontrou vários, não encontrou, encontrou com um status inesperado, sistema fora do ar
  • Quais campos do retorno o atendimento realmente usa
  • Sequências obrigatórias, se houver. Exemplo: "primeiro busca o cliente pelo CPF, depois busca os pedidos dele"

Não envie tokens ou senhas de produção por conversa. As credenciais são cadastradas direto na tela de Ferramentas, por quem administra o projeto.

3. Regras de negócio

  • Documentação do processo: políticas, prazos, exceções e o passo a passo que o time humano segue hoje
  • O que fazer com cada resultado das consultas. Exemplo: "pedido com data de previsão anterior a hoje conta como atraso"
  • Casos ambíguos e o veredito de cada um. Se hoje o time decide "no feeling", vale escrever a regra
  • Se o processo é uma sequência fixa e não negociável (checklist regulatório, verificação de identidade em etapas). Isso muda o tipo de especialista; veja Quando usar Fluxo Controlado ou Agentes Especialistas

4. Quando transferir para humano

Liste apenas os casos em que a regra de negócio exige uma pessoa, escritos a partir de um dado que o sistema devolve:

  • ✅ "Se o status do pedido for 'extraviado', transferir."
  • ❌ "Se o cliente estiver irritado, transferir."

A primeira regra dá para testar e auditar. A segunda varia a cada conversa. Se não houver nenhum caso de transferência para este assunto, diga isso: lista vazia é uma resposta válida.

Detalhes em Como funciona a transferência para humano nos Agentes Especialistas.

5. Tom de voz (uma vez por projeto)

Só é necessário no primeiro especialista do projeto, porque o tom de voz mora no Supervisor e vale para todos:

  • Tratamento (você, senhor/senhora, nome do cliente), nível de formalidade, tamanho das mensagens, uso de emoji
  • Expressões que a marca não usa
  • Três frases reais que representam bem a marca, incluindo uma em que é preciso dar uma notícia ruim ou negar um pedido

6. Exemplos reais

  • 10 a 20 conversas reais desse assunto, atendidas hoje pelo time, com dados pessoais removidos
  • Se for uma revisão: conversas em que o especialista atual errou e o que deveria ter acontecido em cada uma

Checklist rápido

  • [ ] O que o especialista resolve, em uma frase
  • [ ] Ações que ele executa e a ferramenta de cada uma
  • [ ] Especialistas vizinhos que podem ser confundidos com ele
  • [ ] Dez frases reais (cinco que caem aqui, cinco que não caem)
  • [ ] Documentação das APIs ou apps, com todos os resultados possíveis
  • [ ] Regras de negócio e vereditos dos casos ambíguos
  • [ ] Casos de transferência ancorados em dado (ou "nenhum")
  • [ ] Tom de voz, se for o primeiro especialista do projeto
  • [ ] Conversas reais de exemplo

Observações