Fluxo de Decisão

Objetivos

• Construir agentes orientados a tarefas
• Visualizar pipeline end-to-end

Uma pergunta, muitos caminhos

"Meu pedido já saiu?" parece simples. Na prática, o agente precisa decidir:

• Tenho número do pedido?
• Preciso chamar tool ou só conversar?
• O pedido existe?
• Como formular resposta com dado real?

Esta aula é o mapa desse labirinto — para você implementar sem adivinhar no meio do código.

Caso: "Meu pedido já saiu?"

1. Usuário envia mensagem
2. Backend carrega histórico + system prompt
3. LLM analisa intenção
4. LLM percebe: falta ID → pede ao usuário (sem tool ainda)
5. Usuário: "8842"
6. LLM chama buscar_pedido(8842)
7. Backend executa GET /orders/8842 (autorizado)
8. Retorno: { status: "shipped", tracking: "BR123" }
9. LLM gera: "Seu pedido 8842 foi enviado. Rastreio: BR123."
10. Salva assistant no histórico

Note os dois turnos: primeiro coleta informação, depois age. Agente bom não chuta — pergunta o que falta.

Diálogo real:

Usuário: "Meu pedido já saiu?"
Agente: "Claro! Qual o número do pedido?"
Usuário: "8842"
Agente: "Pedido 8842 enviado. Rastreio BR123."

Diagrama

┌─────────┐     ┌─────────┐     ┌──────────┐     ┌─────────┐
│ Usuário │────▶│ Backend │────▶│   LLM    │────▶│  Tool   │
└─────────┘     └─────────┘     └──────────┘     └─────────┘
                     ▲                │                │
                     └────────────────┴────────────────┘
                           resultado da tool

O backend está no centro — não o modelo. Quem persiste histórico, autoriza tool e escala humano é sempre seu código.

Árvore de decisão (simplificada)

Mensagem recebida
├─ Contém ID pedido ou contexto anterior com ID?
│   ├─ Sim → buscar_pedido
│   └─ Não → LLM pergunta número (texto puro)
├─ Pergunta sobre produto?
│   └─ listar_produtos ou buscar_faq
├─ Reclamação grave / jurídico?
│   └─ criar_ticket + mensagem empática
└─ Small talk
    └─ Resposta direta, sem tool

Parte disso o LLM infere; parte você reforça no system prompt. Não espere que o modelo adivinhe políticas da empresa — documente no PCORS.

System prompt para fluxo

Fluxo de pedidos:
1. Se usuário perguntar status e você tiver pedido_id, use buscar_pedido.
2. Se não tiver ID, peça o número do pedido — não invente status.
3. Se buscar_pedido retornar not_found, oriente verificar e-mail de confirmação.
4. Nunca exponha dados de outro cliente.

Prompt + tools + executor = comportamento previsível.

Fallback humano

if (result.requiresHuman || userMessage.includes('processo') || result.not_found >= 2) {
  await createTicket(sessionId, transcript);
  return 'Encaminhei para nossa equipe. Protocolo #9921.';
}

Escalar para humano não é falha do agente — é feature. Cliente irritado com pedido não encontrado duas vezes prefere pessoa real a loop infinito com bot.

Tom da mensagem:

"Entendo sua frustração. Encaminhei para nossa equipe — protocolo #9921. Alguém retorna em até 2 horas."

Métricas do fluxo

• % mensagens resolvidas sem humano
• % tool calls bem-sucedidas
• Tempo médio por conversa
• Taxa de "not_found" em pedidos

Métrica guia onde melhorar: prompt, tool ou fallback humano.

Resumo

• Agente = pipeline com ramificações, não resposta única
• Tool só quando há dado/action necessário
• Peça informação faltante antes de chutar
• Escala humana é feature, não falha

Fluxo mapeado — hora de entregar. Na próxima aula, o projeto final que consolida tudo em um sistema publicável.