Módulo 1.3 — Loop ReAct: ouvir, pensar, agir

Conteúdo detalhado

👂 Etapa 1 — Ouvir

Tudo começa com o que entra: mensagem do usuário, histórico curto, custom fields e contexto do canal. Um agente que ouve mal age errado — não importa quão bom seja o modelo.

🎧 O que entra no "ouvir"

O input nunca é só a última mensagem. É um pacote contextual:

•Mensagem atual do usuário (já normalizada)
•Últimas N trocas resumidas
•Custom fields do CRM (nome, plano, lead score)
•Metadados do canal (WhatsApp, web, voz)

💡 Higiene de input

Antes de gastar tokens com um modelo top, garanta que o input está limpo. Erros de encoding, emojis duplicados ou HTML cru entrando no prompt é fonte #1 de bug que parece "do modelo".

🤔 Etapa 2 — Pensar

O reasoning é onde o modelo decide se responde direto, chama tool, pede esclarecimento ou escala. É também onde a maioria dos bugs de comportamento mora.

✓ Sinais de bom reasoning

✓Escolhe tools coerentes com a intenção
✓Pede esclarecimento quando falta parâmetro
✓Não chama tool quando já sabe a resposta
✓Encadeia tools em ordem lógica

✗ Sinais de reasoning ruim

✗Chama 5 tools para responder "oi"
✗Inventa parâmetros que o usuário não deu
✗Ignora tool óbvia e responde de memória
✗Trava em loop chamando a mesma tool

⚡ Etapa 3 — Agir

Agir é onde o valor aparece — e onde o bug aparece. A tool é executada, devolve resultado (ou erro) e o modelo precisa interpretar antes de falar com o usuário.

// Estrutura típica de um tool call + observation

[Tool call]
{
  "name": "buscar_imoveis",
  "args": {"cidade": "SP", "quartos": 2, "max_preco": 500000}
}

[Observation]
{
  "resultados": [
    {"id": 1023, "endereco": "R. Vergueiro 1500", "preco": 480000},
    {"id": 1108, "endereco": "R. Loefgren 900", "preco": 495000}
  ]
}

[Resposta ao usuário]
"Achei 2 opções na sua faixa, Marina. Quer ver detalhes?"

💡 Tool output

Sempre devolva ao modelo um JSON estruturado, não texto livre. Modelo lê estruturado melhor e cita campos com mais precisão.

🔄 Loops aninhados

Tarefas reais raramente cabem em 1 chamada. O agente roda múltiplas iterações até resolver: chama tool, lê resultado, decide próxima, chama de novo.

Iteração 1

Cliente pede imóvel → chama buscar_imoveis → 3 resultados.

Iteração 2

Cliente escolhe o segundo → chama detalhar_imovel(id=1108) → ficha completa.

Iteração 3

Cliente quer visitar → chama listar_slots(id=1108) → 4 horários.

Iteração 4

Cliente escolhe slot → chama agendar_visita → confirmação.

🛑 Condições de parada

Sem parada explícita, o agente vira fatura impagável de tokens. Defina quando o loop fecha — e o que acontece nos casos extremos.

Resposta final

Modelo emite mensagem sem nova tool call. Caso mais comum.

Max iterations

Bate teto de turns (ex: 8). Devolve resposta parcial + escala.

Erro de tool

Tool quebrou. Tenta 1x mais, se falhar, escala humano.

Timeout

Sessão passou de X segundos. Avisa lentidão e pede contato.

🐞 Debugando o loop

Quem ajusta prompt sem ler trace está consertando no escuro. Cada turn deve gerar log estruturado: input, reasoning, tools chamadas, observations e resposta final.

📊 O que monitorar em produção

Tool call rate — qual % das sessões chama cada tool
Iterações médias — se passa de 4, tem problema de prompt
% de loops cortados por max — meta < 2%
Latência por etapa — onde o tempo está indo
Custo por sessão — tokens × preço do modelo

⚠️ Logs próprios

Não use o painel do provedor como única fonte de verdade. Salve seus próprios logs em cold storage. Provedor muda política de retenção do dia para a noite e você fica sem histórico para debug.

📌 Resumo do módulo

✓

Etapa 1 — Ouvir — input é pacote, não mensagem solta

✓

Etapa 2 — Pensar — reasoning é onde a inteligência aparece (ou some)

✓

Etapa 3 — Agir — ação executa e devolve observation estruturada

✓

Loops aninhados — multi-step é o padrão, não a exceção

✓

Condições de parada — definir parada evita conta surpresa

✓

Debugando o loop — trace estruturado é a única forma de tunar bem

Trilha 2 — Construção (Módulo 2.1)

← Anterior Próximo →

🔁 Loop ReAct: ouvir, pensar, agir