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 post abre a caixa preta do OpenClaw: do momento que a mensagem do cliente chega no WhatsApp até o texto que o agente escreve de volta. Vai ser técnico. Vale a pena se você decide arquitetura de produto, se vai comprar uma solução e quer avaliar o fundo, ou se curte saber o que está acontecendo 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 roda em <2 segundos na edge da Cloudflare, sem servidor fixo.

---

Por que a arquitetura importa

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

1. Latência alta — cliente espera 8 segundos pra 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 você paga fortuna em token.

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

---

O ciclo de um turno (6 estágios)

Imagine que o cliente acabou de mandar a mensagem "quero marcar pra 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 direto 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 receptor (multi-tenant por to_number).
3. Normaliza o payload — áudio vira transcrição, imagem vira descrição, localização vira {lat,lng}, texto fica como está.

No fim do estágio 1 você tem um objeto {tenant_id, conversation_id, user_message} pronto pro 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 banco pra manter, acesso em poucos ms a partir do worker, multi-tenant por tenant_id.

Ponto-chave: a gente não carrega a conversa inteira no prompt. O Memory Manager v2 do OpenClaw (descrito em nossa documentação interna) seleciona só os turnos relevantes pro turno atual (últimos N + N de alta relevância semântica). Isso 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 pra sábado de manhã", o policy engine filtra:

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

No fim você tem um subconjunto pequeno de skills passado pro modelo — não as 50 possíveis, só as 4 que fazem sentido aqui. Isso reduz drasticamente a chance do modelo invocar 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 pro cliente).
• Tool call (pedido pra executar uma skill específica com parâmetros).

No exemplo "quero marcar pra 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 roda no modelo. Ela roda num código nosso, que:

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

Por que isso importa? Porque o modelo nunca fabrica o resultado. Se o calendário retornar [10h, 11h], é exatamente isso que vai pra 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.

Pra 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". Isso 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 pra formar a resposta final pro 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. Atualiza a memória de longo prazo se o turno produziu fato novo (ex: "cliente prefere sábado").
4. Emite evento de observabilidade (métrica de latência, custo de token, taxa de escalação).

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

---

Onde está a defesa contra alucinação

Agente que alucina em produção perde confiança rápido. 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 pra humano. Quando nenhuma skill cobre a pergunta, o agente diz "deixa eu checar com o time" e abre um ticket — não chuta.

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 config (tenant esqueceu de habilitar skill relevante), não erro do modelo.

---

O custo por conversa

Arquitetura boa é invisível até você 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:

Modelo	Custo médio/conversa
Claude Haiku	~R$ 0,02
Claude Sonnet	~R$ 0,12
GPT-4 turbo	~R$ 0,18

A escolha do modelo é por tenant e por skill. Tarefas simples (dúvida FAQ) podem rodar em modelo barato. Tarefas que exigem raciocínio (negociação de agendamento complexo) usam modelo top. O OpenClaw expõe essa configuração sem fricção.

---

Por que Cloudflare e não AWS

A escolha de rodar 100% na stack Cloudflare (Workers + D1 + KV + R2) foi deliberada:

• Latência de edge — worker roda no PoP mais próximo, não num us-east-1 a 200ms de distância.
• Zero servidor pra manter — não tem EC2, RDS, VPC. Tudo é serverless de verdade.
• Custo linear com uso — não pagamos por conversas que não acontecem.
• Multi-tenant nativo — D1 cria banco por tenant de graça; isolamento forte sem gambiarra.
• SSL automático pra domínios de cliente — Cloudflare for SaaS provisiona cert em ~30s pro agente.marca.com.br do cliente.

A desvantagem é que você fica preso ao ecossistema da Cloudflare. Pra esse produto, foi o trade-off certo.

---

O que isso significa pra você

Se você é engenheiro avaliando a solução: o código do worker e da camada de memória está coberto por testes; você consegue inspecionar todo o fluxo via observability padrão (logs + metrics no painel).

Se você é decisor de compra: as 4 linhas de defesa contra alucinação e o fallback obrigatório pra humano são o que permite que você deixe o agente respondendo sem supervisão contínua.

Se você é curioso técnico: a arquitetura descrita aqui é replicável. O padrão "LLM decide, skills executam, dados vêm de source-of-truth" é o caminho pra agentes de produção — dá uma olhada na documentação de tool use da Anthropic e na arquitetura de agentes da Cloudflare pra ver o mesmo padrão em versões diferentes.

---

Perguntas frequentes

Qual LLM o OpenClaw usa?

Configurável por tenant. Hoje suportamos Claude (Anthropic), GPT (OpenAI) e Gemini (Google). Cada skill pode usar um modelo diferente.

E se o LLM ficar fora do ar?

Fallback automático pra segundo provedor configurado. Se todos falharem, agente manda uma mensagem neutra e cria ticket pra humano.

Quanto tempo leva um turno no 95º percentil?

1.8 segundos fim-a-fim (webhook até resposta enviada) em produção no Brasil. O pico é a chamada de LLM (700-1200ms); o resto fica em ruído.

Vocês rodam LLM próprio (self-hosted)?

Não. A economia de escala dos provedores comerciais é imbatível pra nosso caso de uso. Fica mais caro e mais lento rodar LLM próprio.

Como a memória de longo prazo funciona?

Uma camada separada de embeddings + resumo, atualizada assíncronamente depois de cada turno relevante. A seleção do que entra na memória é baseada em relevância (fatos específicos do cliente) + utilidade (coisas que o agente vai consultar de novo).

Posso ver o prompt que foi enviado pro modelo?

Sim. Cada turno no painel mostra o prompt completo + resposta do modelo + tool calls executadas. Útil pra depurar quando o agente erra.

---

Próximos passos

• Se você quer ver isso rodando, crie um agente em 10 minutos.
• Se quer ver exemplos concretos dos 6 estágios em ação, veja 5 conversas que o agente resolve sozinho.
• Se quer entender o posicionamento ("agente não substitui o time, multiplica"), lê essa tese.

Experimentar o OpenClaw →