agent-suporte

Especificação completa do agente de Suporte.

Resumo executivo

Resolve dúvidas e problemas de clientes via WhatsApp usando RAG da knowledge base. Reduz 60-80% dos casos repetitivos sem chegar em humano. Quando precisa escalar, fornece contexto completo. Modelo de receita: redução de equipe humana de atendimento.

Mercado e ICP

Setores ideais

• E-commerce com 100+ atendimentos/mês
• SaaS com base de clientes ativos
• Educação online (suporte pedagógico técnico)
• Telecom e energia (segunda via, status, dúvidas)
• Planos de saúde particulares (rede credenciada, autorizações simples)
• Financeiro (consulta de saldo, segunda via, etc)

Cliente NÃO ideal

• Volume muito baixo (< 50/mês não justifica)
• Casos sempre únicos e complexos (advocacia, M&A)
• Setor que exige humano por regulação (alguns casos médicos)

Casos de uso típicos

Caso 1: E-commerce (Petisco Alimentos)

• Cliente quer rastrear pedido
• Agente consulta sistema → retorna status
• Cliente reclama produto vencido
• Agente abre ticket + pede informações + escala

Caso 2: SaaS (Triadeflow MCP server cliente)

• Cliente não consegue logar
• Agente pergunta erro específico
• Identifica caso → envia tutorial
• Se persistir, abre ticket técnico

Caso 3: Educação (Reverso Academy)

• Aluno não recebe email de acesso
• Agente verifica plataforma → reenvia
• Aluno tem dúvida sobre módulo
• Agente busca no material → responde com link

Estrutura específica do código

agent-suporte/
├── src/
│   ├── prompts/
│   │   ├── system_base.md
│   │   └── fragments/
│   │       ├── tom_acolhedor.md
│   │       ├── tom_tecnico.md
│   │       ├── escalonamento.md
│   │       └── csat.md
│   │
│   ├── tools/
│   │   ├── consultar_pedido.py
│   │   ├── consultar_assinatura.py
│   │   ├── abrir_ticket.py
│   │   ├── segunda_via.py
│   │   ├── consultar_garantia.py
│   │   ├── agendar_assistencia.py
│   │   ├── enviar_tutorial.py
│   │   ├── solicitar_csat.py
│   │   └── _registry.py
│   │
│   ├── flows/
│   │   ├── triagem.py                ← Identifica tipo de problema
│   │   ├── self_service.py           ← Resolve sem humano
│   │   ├── consulta_dados.py         ← Pedido, assinatura
│   │   ├── escalonamento.py          ← N1 → N2 → N3
│   │   └── csat.py                   ← Pesquisa pós-atendimento
│   │
│   └── config/
│       └── default_config.yaml
│
└── tenants/_template/
    └── knowledge/
        ├── faq.md                    ← OBRIGATÓRIO E EXTENSO
        ├── tutoriais.md              ← Passo a passo de tarefas comuns
        ├── politicas.md              ← Garantia, devolução, etc
        ├── escalonamento.md          ← Quando ir pra humano
        ├── glossario.md              ← Termos técnicos
        └── problemas_conhecidos.md   ← Bugs/issues + workaround

Tools específicas

src/tools/consultar_pedido.py

@tool
@trace_tool("consultar_pedido")
async def consultar_pedido(
    cliente_id: str,
    numero_pedido: Optional[str] = None,
    *,
    tenant: dict
) -> str:
    """
    Consulta status de pedido no sistema do cliente.

    USE QUANDO: cliente pergunta sobre rastreio, prazo, status.
    NÃO USE QUANDO: cliente está reclamando do produto.
    """
    erp = ERPFactory.create(tenant)

    if numero_pedido:
        pedido = await erp.get_order(numero_pedido)
    else:
        # Busca último pedido do cliente
        pedidos = await erp.search_orders_by_customer(cliente_id, limit=1)
        if not pedidos:
            return "Nenhum pedido encontrado para este cliente."
        pedido = pedidos[0]

    return f"""
Pedido {pedido.numero}:
- Status: {pedido.status}
- Data do pedido: {pedido.data}
- Previsão de entrega: {pedido.previsao}
- Rastreamento: {pedido.codigo_rastreio or 'Ainda não disponível'}
- Itens: {', '.join(i.nome for i in pedido.itens)}
""".strip()


# src/tools/abrir_ticket.py
@tool
@trace_tool("abrir_ticket")
async def abrir_ticket(
    cliente_id: str,
    titulo: str,
    descricao: str,
    categoria: Literal["produto", "logistica", "pagamento", "tecnico", "outro"],
    prioridade: Literal["baixa", "media", "alta", "urgente"] = "media",
    *,
    tenant: dict
) -> str:
    """
    Abre ticket no helpdesk do cliente para escalação humana.

    USE QUANDO: problema requer humano, mas não é emergência.
    NÃO USE QUANDO: você consegue resolver via tutorial.
    """
    helpdesk = HelpdeskFactory.create(tenant)

    ticket = await helpdesk.create_ticket(
        title=titulo,
        description=descricao,
        category=categoria,
        priority=prioridade,
        customer_id=cliente_id,
        source="whatsapp_agent"
    )

    return f"Ticket #{ticket.id} aberto. Time entrará em contato em até {ticket.sla} min."


# src/tools/enviar_tutorial.py
@tool
@trace_tool("enviar_tutorial")
async def enviar_tutorial(
    topico: str,
    *,
    tenant: dict
) -> str:
    """
    Busca tutorial relevante na knowledge base e envia ao cliente.

    USE QUANDO: problema tem solução documentada.
    NÃO USE QUANDO: tutorial é genérico e cliente já tentou óbvio.
    """
    rag = RAGRetriever(collection=tenant.rag.collection)
    results = await rag.search(
        query=topico,
        filter={"tipo": "tutorial"},
        top_k=1
    )

    if not results:
        return f"Sem tutorial específico para '{topico}'. Considere abrir ticket."

    tutorial = results[0]
    return f"Encontrado: {tutorial.title}\n\n{tutorial.content}\n\nIsso resolve?"

System prompt template

# Identidade
Você é {{agente_nome}}, {{agente_cargo}} da {{nome_empresa}}.
Atende clientes via WhatsApp de forma {{tom}} (técnico mas acolhedor).

# Empresa
{{empresa_descricao}}

# Seu objetivo
Resolver a dúvida ou problema do cliente o mais rápido possível, sem precisar de humano. Quando não conseguir, escalar com contexto completo.

# Como você atua
1. Identifique o tipo de problema (consulta, dúvida, reclamação)
2. Confirme dados necessários (número de pedido, email, etc)
3. Use a tool apropriada para buscar informação ou resolver
4. Apresente solução clara
5. Confirme se resolveu
6. Solicite avaliação CSAT pós-resolução

# Suas ferramentas
- **consultar_pedido**: status, rastreamento, prazo
- **consultar_assinatura**: plano, próxima cobrança
- **segunda_via**: gera segunda via de boleto/NF
- **consultar_garantia**: verifica elegibilidade
- **agendar_assistencia**: marca atendimento técnico
- **enviar_tutorial**: link contextual de ajuda
- **abrir_ticket**: escalação para humano N2/N3
- **solicitar_csat**: pesquisa de satisfação
- **handoff_humano**: para reclamações graves

# Categorização de problemas

| Categoria | Ação |
|-----------|------|
| Consulta de pedido | consultar_pedido |
| Cobrança indevida | abrir_ticket(prioridade=alta) |
| Produto defeituoso | consultar_garantia → abrir_ticket |
| Erro técnico/login | enviar_tutorial → abrir_ticket se persistir |
| Cancelamento | handoff_humano (sempre) |
| Reclamação grave | handoff_humano (sempre) |

# Hierarquia de resolução
1. Primeiro: tente resolver com tools (self-service)
2. Segundo: envie tutorial se aplicável
3. Terceiro: abra ticket se requer humano
4. Último: handoff direto se urgente/grave

# Regras invioláveis
- Nunca prometa solução que não pode garantir
- Sempre confirme dados antes de fazer ação irreversível
- Se cliente irritado: handoff imediato com prioridade alta
- Cancelamentos sempre vão pra humano (legal/comercial)

# Tom
{{include: fragments/tom_acolhedor.md}}

Configuração default

agent_type: suporte
default_model: claude-haiku-4-5    # MAIORIA dos casos é simples e Haiku resolve
fallback_model: claude-sonnet-4-7   # Para casos complexos

modelo_por_categoria:
  consulta_simples: claude-haiku-4-5
  reclamacao: claude-sonnet-4-7      # Mais delicado
  tecnico_complexo: claude-sonnet-4-7

rag:
  default_top_k: 3
  default_threshold: 0.75            # Suporte precisa ser preciso

sla:
  primeira_resposta_segundos: 60
  resolucao_simples_minutos: 5
  escalonamento_apos_minutos: 30

helpdesk:
  tipo: asana                         # asana | zendesk | freshdesk
  categorias_padrao:
    - produto
    - logistica
    - pagamento
    - tecnico
    - outro

csat:
  solicitar_apos_resolucao: true
  perguntar_motivo_se_nao_resolveu: true
  formato: nps                        # nps | csat | binary

KPIs

Métrica	Como medir	Meta
Taxa de resolução automática	% atendimentos sem humano	> 65%
Tempo médio de resolução	Min entre 1ª msg e fechamento	< 5 min
CSAT pós-atendimento	Nota média	> 4.5/5
Taxa de reabertura	% tickets abertos novamente	< 10%
Custo por atendimento	Tokens / atendimentos	Variável
Taxa de escalação	% casos que viraram humano	20-35%

Pricing

Item	Faixa
Setup	R$ 4.000 a R$ 7.000
Mensalidade	R$ 1.000 a R$ 1.800
Volume API	Pass-through + 30% (geralmente baixo, Haiku)

Tempo de implementação

Fase	Duração
Levantamento de FAQ + tutoriais	5 dias
Ingestão massiva no Qdrant	3 dias
Integração com sistemas (ERP, helpdesk)	5 dias
Mapear escalonamento	2 dias
Customização de prompts	3 dias
Testes com casos reais	5 dias
Calibração inicial	7 dias
Total primeiro cliente	3-4 semanas
Clientes seguintes	1-2 semanas