Manual: como criar um agente eficiente no A2P Labs

Guia prático para o time operacional. Se você só ler uma coisa, leia a seção Base de conhecimento.

Ambiente: labs.a2pchat.com.br URL pública deste guia: labs.a2pchat.com.br/docs/criar-agente Entrada usual: CRM → Agentes de IA v2 → Labs

1. Regra de ouro (grave isso)

Prompt = comportamento. Base = fatos.

Se misturar os dois, o agente fica confuso, inventa resposta ou ignora o que você subiu.

2. O que é o Labs (em 30 segundos)

O Labs cria, testa e executa o agente. Ele não envia WhatsApp sozinho — a resposta volta para o CRM/A2P, que entrega no canal.

Para o agente atender de verdade em produção, precisa:

1. Status Ativo
2. Uma versão Publicada (não só rascunho)
3. Se usar RAG: base vinculada + documentos com status completed + Habilitar RAG ligado

3. Passo a passo: criar o agente

Passo 0 — Workspace

1. Entre pelo CRM (SSO) ou pelo painel do Labs.
2. Em Trocar workspace, escolha a empresa (tenant) e a filial/conexão (subtenant).
3. Só depois crie ou selecione o agente. Agente no tenant errado = dor de cabeça depois.

Passo 1 — Criar com o assistente

Vá em Criar novo agente (/agents/new). São 5 etapas:

1) Template

Escolha o tipo certo. Não invente “sob medida” se um template já cobre o caso.

2) Identidade

Preencha só o mínimo:

• Nome interno (painel)
• Como se apresenta ao cliente (“Ana, assistente da Empresa X”)
• Nome da empresa
• Tagline opcional (uma linha)

Não cole aqui catálogo, tabela de preços ou FAQ.

3) Comportamento

• Tom de voz (profissional / amigável / técnico / consultivo)
• Quando transferir para humano (reclamação grave, cancelamento, etc.)
• Limites (“não prometer desconto”, “não inventar prazo”)
• Perguntas específicas do template

De novo: sem produtos e FAQs.

4) Config

• Modelo: gpt-4o-mini costuma bastar; use gpt-4o se o caso for mais complexo.
• Temperatura: comece em 0.7. Mais baixo = mais previsível; mais alto = mais criativo (e mais risco de inventar).
• Fuso: America/Sao_Paulo na maioria dos casos.
• Usar Base de Conhecimento (RAG): deixe ligado se o agente precisa de fatos (quase sempre).

5) Gerar e criar

1. Clique em Gerar prompt com IA.
2. Leia o resumo. Confira se não entrou lista de produto/FAQ no prompt.
3. Criar agente.

O agente nasce em rascunho com a versão 1 já publicada. Ainda falta a base de conhecimento e os testes.

4. Base de conhecimento — o que o time mais erra

4.1 Por que “subir um monte de merda” quebra o agente

O Labs não “lê o PDF inteiro” a cada mensagem. Ele:

1. Extrai o texto do arquivo
2. Corta em pedaços (~1000 caracteres) com sobreposição
3. Guarda esses pedaços como vetores
4. Na conversa, busca os até 8 trechos mais parecidos com a pergunta

Se o arquivo for lixo, o pedaço recuperado é lixo — e o agente responde com lixo (ou inventa).

4.2 O que pode subir

Texto extraído com menos de ~10 caracteres → documento falha.

4.3 Checklist antes de qualquer upload

Responda sim a tudo:

• ☐O arquivo tem texto selecionável (dá para copiar/colar no Word/Preview)?
• ☐Fala de um assunto (ou poucos assuntos relacionados)?
• ☐Está atualizado (preços, prazos, políticas de hoje)?
• ☐Está em português claro, sem tabelas monstruosas ilegíveis?
• ☐Removi capa, índice inútil, rodapé repetido, “confidencial”, prints?
• ☐Não é o mesmo conteúdo já existente em outro arquivo?

Se alguma resposta for não, não suba. Arrume o arquivo primeiro.

4.4 Como organizar a base (faça assim)

Bom

• faq-entrega.md — só perguntas de entrega
• politica-troca.txt — só troca e devolução
• produtos-linha-x.md — só aquela linha, com nome, preço, o que inclui
• Entrada manual: “Horário de atendimento” → texto curto e direto

Ruim

• TUDO_DA_EMPRESA_2023_FINAL_v7.pdf (300 páginas)
• Apresentação comercial com slides, imagens e pouco texto
• Planilha exportada com 40 colunas e abreviações internas
• Copiar o site inteiro em HTML
• Subir 15 versões do mesmo PDF “por precaução”
• Colar FAQ no prompt e também na base (duplicado e conflitante)

4.5 Formato ideal de conteúdo

Escreva como se fosse para um humano novo no time:

## Entrega

Prazo padrão: 5 a 8 dias úteis para capitais.
Frete grátis acima de R$ 199.
Não entregamos em Caixa Postal.

## Troca

Prazo para solicitar troca: 7 dias corridos após o recebimento.
Produto precisa estar lacrado e sem uso.

Ou FAQ:

P: Qual o prazo de entrega?
R: De 5 a 8 dias úteis para capitais. Interior pode levar até 12 dias úteis.

P: Vocês parcelam?
R: Sim, em até 3x sem juros no cartão acima de R$ 150.

Dicas:

• Um tema por documento (ou por entrada manual).
• Títulos claros (##, negrito, perguntas objetivas).
• Frases completas — o corte em chunks prefere quebras em parágrafo e pontuação.
• Preços e regras explícitas; evite “conforme tabela anexa” sem a tabela.
• Se algo mudou, atualize ou desative o documento antigo. Não deixe duas verdades.

4.6 Fluxo na tela Conhecimento

1. Abra o agente → menu Conhecimento.
2. Se não houver base: criar → vincular → marcar Habilitar RAG no runtime.
3. Em Documentos: faça upload ou use Adicionar conteúdo manual para textos curtos.
4. Espere o status ir para completed (passa por pending → processing).
5. Se ficar failed: o texto provavelmente veio vazio/escaneado — corrija o arquivo e suba de novo.
6. Vá em Testar busca e digite perguntas reais do cliente.
7. Só depois vá em Testar (chat) e converse com o agente.

Testar busca é obrigatório. Se a busca não achar o trecho certo, o chat também não vai.

4.7 O que fazer quando a busca vem errada

1. A pergunta do teste é parecida com a do cliente?
2. O trecho certo existe na base com palavras claras?
3. Há documento antigo contradizendo? Desative/remova.
4. O PDF virou lixo na extração? Troque por .txt / .md.
5. Conteúdo misturado demais num arquivo só? Separe por tema.
6. Em Chunks, revise pedaços ruins e edite/desative se necessário.

5. Depois de criar: checklist de qualidade

Faça nesta ordem:

1. Conhecimento vinculado + RAG ligado + docs completed
2. Testar busca com 5–10 perguntas reais
3. Testar conversa no Labs (cenários felizes e “não sei”)
4. Ajustar no Builder se o tom/fluxo estiver estranho → Salvar rascunho → Publicar versão
5. Configurações: telefone allowlist (se houver), tag de handoff no CRM, áudio, timezone
6. Tools só se precisar de webhook/API (nome só a-z0-9_, descrição clara)
7. Confirmar agente Ativo e versão publicada
8. Validar no canal real (WhatsApp etc.) com o time de implantação

Lembrete crítico

Mudança no Builder não vai para produção até Publicar versão. Salvar rascunho ≠ publicar.

6. Como escrever um bom prompt (Builder)

Campos e para que servem:

Bom fallback (exemplo):

Se a informação não estiver nos trechos da base de conhecimento, diga que não tem essa informação confirmada e ofereça transferir para um atendente. Nunca invente preço, prazo ou política.

Ruim:

Aqui está nossa lista de 40 produtos com preço… (isso é base, não prompt)

7. Orquestrador (quando usar)

Use orquestrador só se houver vários especialistas (ex.: vendas + suporte + financeiro).

1. Crie os agentes especialistas primeiro (cada um com sua base, se fizer sentido).
2. Crie o orquestrador em /agents/new/orchestrator.
3. Vincule especialistas com descrição de roteamento clara e prioridade.
4. A descrição de roteamento deve dizer quando mandar para aquele especialista — não o FAQ inteiro.

8. Comportamentos do runtime que o time precisa saber

• Mensagens picadas no WhatsApp (“oi” + “tudo bem” + “quero preço”) podem ser agrupadas (~2,5s de espera, até ~8s / 12 msgs) antes do agente responder. Isso é normal.
• O histórico recente (últimas mensagens) entra no contexto; mesmo assim, fatos vêm da base.
• Se o RAG falhar, o agente pode seguir sem trechos — por isso fallback e “não invente” são obrigatórios.
• Handoff: o agente sinaliza transferência; o CRM aplica a tag/fluxo humano.

9. Anti-padrões (proibido na prática)

1. Subir PDF escaneado “porque é o manual oficial”.
2. Subir o mesmo conteúdo 5 vezes com nomes diferentes.
3. Colar catálogo no prompt e na base.
4. Ligar RAG sem documento nenhum.
5. Publicar sem Testar busca.
6. Editar o Builder e esquecer de Publicar versão.
7. Usar temperatura alta + base vazia = alucinação garantida.
8. Base com informação desatualizada “porque depois a gente atualiza”.
9. Um único arquivo de 200 páginas com tudo misturado.
10. Pedir para o agente “ser criativo” com preço e política.

10. Mini-roteiro de 15 minutos (agente FAQ/suporte)

1. Criar agente template FAQ ou Suporte Geral, RAG ligado.
2. Criar/vincular base.
3. Subir 2–5 arquivos limpos (ou entradas manuais) por tema.
4. Esperar completed.
5. Testar busca: “prazo de entrega”, “troca”, “horário”.
6. Testar chat com as mesmas perguntas + uma pergunta que não está na base (deve admitir e/ou transferir).
7. Ajustar tom no Builder se preciso → Publicar.
8. Ativar e validar no canal.

Se no passo 5 a busca já falha, pare. Não adianta “melhorar o prompt” — o problema é a base.

11. Quem chama quando

12. Resumo em uma frase

Crie o agente pelo wizard pensando só em comportamento; alimente a base com poucos documentos limpos e atualizados; teste a busca antes do chat; publique a versão; nunca use a base como lixeira de PDF. )