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. Conversa atual: qual é o estado atual da conversa?
2. Histórico da conversa: o que foi dito anteriormente?
3. Informações do usuário: quem é o usuário e o que ele quer?

Essas informações são armazenadas em um banco de dados de chave-valor (D1 + KV) e são recuperadas em ~80ms.

Estágio 3 — Seleciona skills (D2, ~20ms)

O agente precisa decidir qual skill (função) deve ser executada para responder à mensagem do usuário. Isso é feito consultando o banco de dados de skills (D2) e selecionando a skill mais adequada.

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

O agente precisa decidir qual é a próxima ação a ser executada. Isso é feito consultando o banco de dados de ações (D3) e selecionando a ação mais adequada.

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

O agente executa a ação selecionada, mas com guard-rails para evitar erros. Isso é feito consultando o banco de dados de guard-rails (D4) e executando a ação com os guard-rails necessários.

Estágio 6 — Persiste memória (D5, ~2ms)

O agente persiste a memória da conversa para que possa ser recuperada em futuras interações. Isso é feito consultando o banco de dados de memória (D5) e persistindo a memória da conversa.

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:

• Verifica se a skill está disponível e habilitada.
• Executa a skill com os parâmetros fornecidos.
• Verifica se a skill retornou com sucesso.
• Se sim, retorna a resposta ao cliente.
• Se não, retorna um erro ao cliente.

Isso garante que as skills sejam executadas de forma segura e controlada, evitando possíveis erros ou problemas.

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

Por que isso importa? Porque o modelo nunca fabrica o resultado. Se o calendário retornar [10h, 11h], é exatamente 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". 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 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 (usuário + assistente + chamadas de ferramenta + 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 (inquilino 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 €
• 1-2 lookups em D1:
  • Tempo de resposta: 10-50 ms
  • Custo: 0,0005-0,001 €
• Total:
  • Tempo de resposta: 110-250 ms
  • Custo: 0,0105-0,023 €