كيف يعمل وكيل الذكاء الاصطناعي المحادثي من الداخل

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. Tenant: qual é o perfil do cliente?
2. Conversa: qual é o histórico da conversa?
3. Usuário: qual é o perfil do usuário?

O agente usa o D1 (banco de dados) e o KV (cache) para recuperar essas informações.

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

O agente precisa decidir qual é a skill (função) que deve ser executada para responder à mensagem do cliente.

O agente usa o D2 (banco de dados) e o KV (cache) para recuperar as informações necessárias para selecionar a skill.

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

O agente precisa decidir qual é a próxima ação que deve ser executada para responder à mensagem do cliente.

O agente usa o D3 (banco de dados) e o KV (cache) para recuperar as informações necessárias para decidir a próxima ação.

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

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

O agente usa o D4 (banco de dados) e o KV (cache) para recuperar as informações necessárias para executar a próxima ação com guard-rails.

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

O agente precisa persistir a memória da conversa para garantir que a resposta seja consistente e segura.

O agente usa o D5 (banco de dados) e o KV (cache) para recuperar as informações necessárias para persistir a memória da conversa.

---

Por que o OpenClaw é diferente

O OpenClaw foi construído para evitar os 4 problemas comuns dos agentes conversacionais:

1. Latência alta: o OpenClaw é executado em tempo real, sem servidor fixo.
2. Alucinação não controlada: o OpenClaw usa guard-rails para garantir que as respostas sejam seguras e consistentes.
3. Contexto perdido: o OpenClaw persiste a memória da conversa para garantir que as respostas sejam consistente e segura.
4. Custo descontrolado: o OpenClaw é projetado para ser escalável e eficiente, sem custos descontrolados.

O OpenClaw é uma solução inovadora para os desafios dos agentes conversacionais. Se você está procurando por uma solução para seus problemas de conversação, o OpenClaw pode ser a resposta certa.

• 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 para o cliente.
• Se não, retorna um erro para o cliente.

Essa abordagem permite que o modelo seja treinado para tomar decisões complexas, enquanto mantém a segurança e a estabilidade do sistema.

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 booda wixiil ah inkaa aad u baahdo, hadii aad u soo diri kartaa fataata. Dadaamaadka, markii horey ka dhex bixiso 1-2 duubista LLM + lookups ka dhex bixiso D1, markii ugu dhaqan leh, wixiilka ka dhex bixiso kala duubista (10-15 markii horey) waxay ahayd:

• 1-2 duubista LLM + lookups D1 = 1-2 * 0.1-0.2 USD = 0.1-0.4 USD
• 10-15 markii horey = 10-15 * 0.1-0.4 USD = 1-6 USD
• 1-6 USD = 0.1-0.6 USD (dhaqanka)
• 0.1-0.6 USD = 0.1-0.6 USD (dhaqanka)

Wixiilka ka dhex bixiso kala duubista (10-15 markii horey) waxay ahayd 0.1-0.6 USD.