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 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 <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, <ms)

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 <0ms.

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:

1. Qual é o estado atual da conversa? (D1)
2. Quais são as preferências do cliente? (KV)
3. Quais são as regras de negócios? (KV)

O agente usa essas informações para criar um contexto único para a conversa.

Estágio 3 — Seleciona skills (D2 + KV, ~80ms)

O agente precisa decidir qual skill (função) deve ser executada para responder à mensagem do cliente. Isso depende do contexto da conversa e das preferências do cliente.

O agente usa as informações do contexto e das preferências do cliente para selecionar a skill certa.

Estágio 4 — Decide próxima ação (D3 + KV, ~80ms)

O agente precisa decidir qual é a próxima ação a ser executada para responder à mensagem do cliente. Isso depende da skill selecionada e do contexto da conversa.

O agente usa as informações da skill e do contexto para decidir a próxima ação.

Estágio 5 — Executa com guard-rails (D4 + KV, ~80ms)

O agente executa a próxima ação com guard-rails (restrições) para garantir que a resposta seja segura e consistente.

O agente usa as informações da próxima ação e do contexto para executar a resposta.

Estágio 6 — Persiste memória (D5 + KV, ~80ms)

O agente persiste a memória da conversa para garantir que as informações sejam preservadas e possam ser acessadas em futuras interações.

O agente usa as informações da conversa para persistir a memória.

---

Todo o ciclo roda em <segundos na edge da Cloudflare, sem servidor fixo.

• 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 (a data_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:

• 1-2 chamadas de LLM:
  • Tempo de resposta: 100-200 ms
  • Custo: 0,01-0,02 USD
• 1-2 lookups em D1:
  • Tempo de resposta: 10-50 ms
  • Custo: 0,0005-0,001 USD
• Total:
  • Tempo de resposta: 110-250 ms
  • Custo: 0,0105-0,023 USD