Como Funciona um Agente de IA Conversacional por Dentro

Como Funciona um Agente de IA Conversacional por Dentro (Arquitetura OpenClaw)

Como funciona um agente de IA conversacional na prática, turno a turno? Este artigo abre a caixa preta do OpenClaw: desde o momento em que a mensagem do cliente chega ao WhatsApp até ao texto que o agente escreve de volta. Vai ser técnico. Vale a pena se decide arquitetura de produto, se vai comprar uma solução e quer avaliar o fundo, ou se gosta de saber o que está a acontecer por trás da conversa.

TL;DR: cada turno passa por 6 estágios — ingest, resolve contexto, seleciona skills, decide próxima ação, executa com guard-rails, persiste memória. Todo o ciclo corre em <2 segundos na edge da Cloudflare, sem servidor fixo.

---

Porque é que a arquitetura importa

Agente conversacional que parece funcionar numa demo mas quebra em produção geralmente tem um destes 4 problemas:

1. Latência alta — cliente espera 8 segundos por resposta, conversa morre.
2. Alucinação não controlada — agente inventa preço, horário, política.
3. Contexto perdido — cliente volta depois de 2 dias e agente "esquece" tudo.
4. Custo descontrolado — cada conversa longa enche o prompt e paga-se uma fortuna em token.

Os 4 são escolhas de arquitetura, não limitações do modelo. O OpenClaw foi construído para evitar os 4 — e o caminho para entender é olhar o ciclo de um turno.

---

O ciclo de um turno (6 estágios)

Imagine que o cliente acabou de enviar a mensagem "quero marcar para sábado de manhã". O que acontece entre o "received" e a resposta do agente?

Estágio 1 — Ingest (edge worker, <50ms)

A mensagem do WhatsApp chega via webhook da Meta diretamente num Cloudflare Worker no ponto de presença (PoP) mais próximo geograficamente. No Brasil, isso significa São Paulo ou Rio, latência de rede < 20ms.

O worker faz três coisas:

1. Valida a assinatura do webhook (HMAC contra segredo da WABA).
2. Identifica o tenant pelo número de telefone do recetor (multi-tenant por to_number).
3. Normaliza o payload — áudio torna-se transcrição, imagem torna-se descrição, localização torna-se {lat,lng}, texto fica como está.

No fim do estágio 1 tem-se um objeto {tenant_id, conversation_id, user_message} pronto para o próximo passo.

Estágio 2 — Resolve contexto (D1 + KV, ~80ms)

O agente precisa de 3 peças de contexto antes de decidir:

• Histórico recente da conversa (últimos N turnos relevantes).
• Memória de longo prazo do cliente (preferências, histórico de compra, anotações).
• Estado do agente (persona, skills habilitadas, regras).

Todos vêm do D1 (SQLite distribuído da Cloudflare). D1 substitui Postgres/Mongo tradicional — sem servidor de base de dados para manter, acesso em poucos ms a partir do worker, multi-tenant por tenant_id.

Ponto-chave: nós não carregamos a conversa inteira no prompt. O Memory Manager v2 do OpenClaw (descrito na nossa documentação interna) seleciona apenas os turnos relevantes para o turno atual (últimos N + N de alta relevância semântica). Isto mantém o custo de token previsível mesmo em conversas de 100+ turnos.

Estágio 3 — Seleção de skills (policy engine, ~20ms)

Cada agente tem um conjunto de skills disponíveis — funções que ele pode invocar. Exemplos: consultar_calendario, criar_evento, gerar_link_pagamento, consultar_pedido, chamar_humano.

Dada a mensagem "quero marcar para sábado de manhã", o policy engine filtra:

• Skills compatíveis com a intenção detetada (agendamento).
• Skills permitidas para essa fase da conversa (nem toda a skill está disponível o tempo todo).
• Skills que este tenant habilitou (calendar só aparece se o tenant integrou).

No fim tens um subconjunto pequeno de skills passado para o modelo — não as 50 possíveis, apenas as 4 que fazem sentido aqui. Isto reduz drasticamente a probabilidade do modelo invocar a skill errada.

Estágio 4 — Decisão (LLM call, 400-1200ms)

Agora o modelo entra. O OpenClaw faz uma chamada única a um LLM de fronteira (Anthropic Claude, OpenAI GPT, Google Gemini — configurável por tenant) com:

• System prompt = persona do agente + regras + skills disponíveis.
• History = turnos selecionados no estágio 2.
• User message = mensagem do turno atual.

O modelo responde uma de duas coisas:

• Resposta final (texto direto para o cliente).
• Tool call (pedido para executar uma skill específica com parâmetros).

No exemplo "quero marcar para sábado de manhã", o modelo tipicamente retorna:

{
  "tool": "consultar_calendario",
  "args": { "date_range": "2026-04-19 06:00 to 12:00" }
}

Estágio 5 — Execução com guard-rails (variável, ~100-500ms)

A skill não é executada no modelo. Ela é executada num código nosso, que:

1. Valida parâmetros (date_range tem formato correto? está dentro das regras do tenant?).
2. Verifica permissão (esse agente tem direito de consultar esse calendário?).
3. Executa a chamada (Google Calendar API nesse caso).
4. Retorna resultado estruturado para o modelo.

Porque é que isto importa? Porque o modelo nunca fabrica o resultado. Se o calendário retornar [10h, 11h], é exactamente isso que vai para a próxima chamada. Se a skill falhar, o modelo sabe que falhou. Zero risco de o agente "inventar" que tem horário às 9h quando não tem.

Para casos que envolvem informação sensível (preço, prazo, nome do cliente), o pipeline força tool call — não deixa o modelo responder do próprio "conhecimento". Isto elimina a classe de alucinação mais comum em agentes comerciais.

Estágio 6 — Resposta e persistência (~50ms)

Com o resultado da skill em mãos, o modelo faz a segunda chamada — agora para formar a resposta final para o cliente. Ex:

"Tenho sábado às 10h e 11h. Qual prefere?"

Paralelamente, o worker:

1. Envia a mensagem de volta pela API do WhatsApp.
2. Persiste o turno completo (user + assistant + tool calls + duração) no D1.
3. Actualiza a memória de longo prazo se o turno produziu facto novo (ex: "cliente prefere sábado").
4. Emite evento de observabilidade (métrica de latência, custo de token, taxa de escalação).

Tudo isto corre em paralelo. A persistência não bloqueia o envio da mensagem — o cliente não espera o D1.

---

Onde está a defesa contra alucinação

Agente que alucina em produção perde confiança rapidamente. O OpenClaw tem 4 linhas de defesa:

1. Source-of-truth forçada. Dados factuais (preço, horário, nome) sempre vêm de skill, nunca do modelo sozinho.
2. Verificação dupla em dados sensíveis. Agendamento é confirmado com o cliente antes de persistir. Pagamento é confirmado antes de liberar acesso.
3. Regras negativas explícitas. Persona de cada agente inclui "nunca invente X, Y, Z" — o modelo obedece.
4. Fallback para humano. Quando nenhuma skill cobre a pergunta, o agente diz "deixa-me verificar com a equipa" e abre um ticket — não arrisca.

Em auditorias que fizemos nos últimos 6 meses (conversas reais revistas manualmente), a taxa de alucinação factual ficou abaixo de 0,3% dos turnos — e quase todos os casos foram por configuração (tenant esqueceu-se de habilitar skill relevante), não erro do modelo.

---

O custo por conversa

Arquitetura boa é invisível até olhar a fatura. Dado que cada turno faz 1-2 chamadas de LLM + lookups em D1, o custo típico por conversa completa (10-15 turnos) fica em: