Hoe 'n Gesprek KI-Agent van Binne Werk

Hoe 'n Gesprek-KI-Agent van Binne Werk (OpenClaw-Argitektuur)

Hoe werk 'n gesprek-KI-agent in die praktyk, beurt vir beurt? Hierdie pos open die swart boks van OpenClaw: van die oomblik dat die kliënt se boodskap op WhatsApp aankom tot die teks wat die agent terugskryf. Dit gaan tegnies wees. Dit is die moeite werd as jy produkargitektuur besluit, as jy 'n oplossing gaan koop en die diepte wil evalueer, of as jy daarvan hou om te weet wat agter die gesprek aangaan.

TL;DR: elke beurt gaan deur 6 stadiums — inname, konteks oplos, vaardighede kies, volgende aksie besluit, uitvoer met veiligheidslyne, geheue stoor. Die hele siklus loop in <2 sekondes op Cloudflare se rand, sonder vaste bediener.

---

Waarom argitektuur saak maak

Gesprek-agent wat lyk asof dit in 'n demo werk maar in produksie breek, het gewoonlik een van hierdie 4 probleme:

1. Hoë latensie — kliënt wag 8 sekondes vir 'n antwoord, gesprek sterf.
2. Onbeheerde hallusinasie — agent dink prys, tyd, beleid uit.
3. Verlore konteks — kliënt kom terug na 2 dae en agent "vergeet" alles.
4. Onbeheerde koste — elke lang gesprek vul die prompt en jy betaal 'n fortuin in tokens.

Al 4 is argitektuurkeuses, nie modelbeperkings nie. OpenClaw is gebou om al 4 te vermy — en die pad om te verstaan is om na die siklus van 'n beurt te kyk.

---

Die siklus van 'n beurt (6 stadiums)

Stel jou voor dat die kliënt pas die boodskap "wil Saterdagoggend bespreek" gestuur het. Wat gebeur tussen die "ontvang" en die agent se antwoord?

Stadium 1 — Inname (rand-werker, <50ms)

Die WhatsApp-boodskap kom via Meta se webhook direk by 'n Cloudflare Worker by die naaste geografiese teenwoordigheidspunt (PoP) aan. In Brasilië beteken dit São Paulo of Rio, netwerklatensie < 20ms.

Die werker doen drie dinge:

1. Valideer die handtekening van die webhook (HMAC teen WABA-geheim).
2. Identifiseer die huurder deur die telefoonnommer van die ontvanger (multi-huurder per to_number).
3. Normaliseer die vrag — klank word transkripsie, beeld word beskrywing, ligging word {lat,lng}, teks bly soos dit is.

Aan die einde van stadium 1 het jy 'n {tenant_id, conversation_id, user_message}-objek gereed vir die volgende stap.

Stadium 2 — Konteks oplos (D1 + KV, ~80ms)

Die agent benodig 3 stukke konteks voordat hy besluit:

• Onlangse geskiedenis van die gesprek (laaste N relevante beurte).
• Langtermyngeheue van die kliënt (voorkeure, aankoopgeskiedenis, notas).
• Agenttoestand (persona, geaktiveerde vaardighede, reëls).

Almal kom van D1 (Cloudflare se verspreide SQLite). D1 vervang tradisionele Postgres/Mongo — geen databasisserver om te onderhou nie, toegang in 'n paar ms vanaf die worker, multi-tenant deur tenant_id.

Sleutelpunt: ons laai nie die hele gesprek in die prompt nie. OpenClaw se Memory Manager v2 (beskryf in ons interne dokumentasie) kies slegs die relevante beurte vir die huidige beurt (laaste N + N van hoë semantiese relevansie). Dit hou die token-koste voorspelbaar selfs in gesprekke van 100+ beurte.

Stadium 3 — Vaardigheidskeuse (policy engine, ~20ms)

Elke agent het 'n stel vaardighede beskikbaar — funksies wat hy kan aanroep. Voorbeelde: consultar_calendario, criar_evento, gerar_link_pagamento, consultar_pedido, chamar_humano.

Gegewe die boodskap "quero marcar pra sábado de manhã", filtreer die policy engine:

• Vaardighede versoenbaar met die opgespeurde bedoeling (skedulering).
• Vaardighede toegelaat vir hierdie fase van die gesprek (nie elke vaardigheid is altyd beskikbaar nie).
• Vaardighede wat hierdie tenant geaktiveer het (kalender verskyn slegs as die tenant geïntegreer het).

Aan die einde het jy 'n klein substel vaardighede wat aan die model deurgegee word — nie die 50 moontlike nie, slegs die 4 wat hier sin maak. Dit verminder drasties die kans dat die model die verkeerde vaardigheid aanroep.

Stadium 4 — Besluit (LLM call, 400-1200ms)

Nou tree die model in. OpenClaw maak 'n enkele oproep na 'n grens-LLM (Anthropic Claude, OpenAI GPT, Google Gemini — konfigueerbaar per tenant) met:

• System prompt = agent se persona + reëls + beskikbare vaardighede.
• History = beurte gekies in stadium 2.
• User message = boodskap van die huidige beurt.

Die model reageer met een van twee dinge:

• Finale antwoord (direkte teks vir die kliënt).
• Tool call (versoek om 'n spesifieke vaardigheid met parameters uit te voer).

In die voorbeeld "quero marcar pra sábado de manhã", gee die model tipies terug:

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

Stadium 5 — Uitvoering met guard-rails (wisselend, ~100-500ms)

Die vaardigheid hardloop nie in die model nie. Dit hardloop in ons kode, wat:

1. Valideer parameters (het date_range die korrekte formaat? is dit binne die reëls van die tenant?).
2. Kontroleer toestemming (het hierdie agent die reg om hierdie kalender te raadpleeg?).
3. Voer die oproep uit (Google Calendar API in hierdie geval).
4. Gee gestruktureerde resultaat terug aan die model.

Hoekom maak dit saak? Want die model versin nooit die resultaat nie. As die kalender [10h, 11h] teruggee, is dit presies wat na die volgende oproep gaan. As die skill misluk, weet die model dat dit misluk het. Nul risiko dat die agent "uitdink" dat daar 'n tyd om 9h is wanneer daar nie is nie.

Vir gevalle wat sensitiewe inligting behels (prys, sperdatum, kliëntnaam), dwing die pyplyn tool call — dit laat nie die model toe om uit sy eie "kennis" te antwoord nie. Dit elimineer die klas van hallusinasie wat die algemeenste is in kommersiële agente.

Stadium 6 — Respons en volharding (~50ms)

Met die resultaat van die skill in die hand, maak die model die tweede oproep — nou om die finale respons vir die kliënt te vorm. Bv:

"Ek het Saterdag om 10h en 11h. Watter verkies jy?"

Terselfdertyd, die worker:

1. Stuur die boodskap terug via die WhatsApp API.
2. Stoor die volledige beurt (user + assistant + tool calls + duur) in D1.
3. Werk die langtermyngeheue by as die beurt 'n nuwe feit opgelewer het (bv: "kliënt verkies Saterdag").
4. Stuur waarneembaarheidsgebeurtenis uit (latensie-metriek, token-koste, eskalasiekoers).

Al hierdie dinge loop parallel. Die volharding blokkeer nie die stuur van die boodskap nie — kliënt wag nie vir D1 nie.

---

Waar is die verdediging teen hallusinasie

Agent wat in produksie hallusineer verloor vinnig vertroue. Die OpenClaw het 4 verdedigingslyne:

1. Gedwonge bron-van-waarheid. Feitelike data (prys, tyd, naam) kom altyd van skill, nooit van die model alleen nie.
2. Dubbele verifikasie by sensitiewe data. Afspraak word met die kliënt bevestig voor dit gestoor word. Betaling word bevestig voor toegang verleen word.
3. Eksplisiete negatiewe reëls. Persona van elke agent sluit in "moenie ooit X, Y, Z uitdink nie" — die model gehoorsaam.
4. Terugval na mens. Wanneer geen skill die vraag dek nie, sê die agent "laat my met die span nagaan" en open 'n kaartjie — raai nie.

In oudits wat ons die afgelope 6 maande gedoen het (werklike gesprekke handmatig hersien), was die feitelike hallusinasiekoers onder 0,3% van die beurte — en byna al die gevalle was weens konfigurasie (tenant het vergeet om relevante skill te aktiveer), nie modelfoute nie.

---

Die koste per gesprek

Goeie argitektuur is onsigbaar totdat jy na die rekening kyk. Gegewe dat elke beurt 1-2 LLM-oproepe + opsoekings in D1 maak, is die tipiese koste per volledige gesprek (10-15 beurte):