How It Works

This page walks through exactly what happens when a customer sends a message through your preferred chat interface.

Chat interface flow

Customer opens your website — the chat widget loads and connects to Aelio Server over WebSocket at /widget/ws.

Widget sends an init frame with customerId + authToken. The server responds with a ready frame that includes chat history.

Customer types: "What is my order status?" — the widget sends a message frame.

Aelio Server runs processTurn():

Recalls relevant customer facts from memory
LLM decides to call getOrderStatus tool
Safety gate: read action → auto-allowed
Server sends invoke frame to your SDK (WebSocket /sdk)

Your SDK handler runs locally:

return await db.orders.findOne({ id: orderId, userId: ctx.customerId })

SDK sends a result frame back to the server.

Server synthesizes a natural-language reply and sends a message frame to the widget: "Your order #A123 is shipped!"

Write action flow (with confirmation)

When the customer asks to cancel an order:

LLM decides to call cancelOrder (safety: write).

Safety gate triggers — write action requires user confirmation. Server pauses execution.

Widget shows a confirmation prompt: "Cancel order #A123? Reply yes to confirm."

Customer clicks Confirm (or types "yes") — server executes the tool via SDK invoke.

Handler runs: db.orders.cancel(orderId, ctx.customerId)

Reply: "Done! Order #A123 has been cancelled."

SDK connection model

The SDK dials out to the server. Your backend initiates the connection:

Your Backend                          Aelio Server
     │                                     │
     │──── WebSocket connect /sdk ────────▶│
     │     Authorization: Bearer secret    │
     │                                     │
     │──── register frame ────────────────▶│  (functions, states, policies)
     │                                     │
     │◀─── invoke frame ──────────────────│  (LLM wants getOrderStatus)
     │                                     │
     │──── result frame ──────────────────▶│  (handler return value)
     │                                     │
     │◀─── ping ──────────────────────────│  (keepalive every 30s)
     │──── pong ──────────────────────────▶│

Key point

The server never calls your REST API. It sends tool invocations over the WebSocket you opened.

Memory and intelligence

After every turn, the analytical agent runs in the background:

Turn completes — the analytical agent wakes up.

Extract durable facts — e.g. "customer prefers express shipping".

Embed fact as a vector and store it in SQLite + sqlite-vec.

Next conversation — relevant facts are injected into the LLM prompt automatically via top-K similarity search.

Pipeline onboarding flow

When you register a pipeline YAML manifest, Aelio guides new customers through staged onboarding automatically:

New customer — starts at initial_stage (e.g. unverified). Only tools allowed in that stage are available.

Active flow step — the engine resolves the current step: deliver content, collect an attribute, or invoke a tool.

Attribute collection — the LLM asks conversationally; Aelio saves the value to profile memory. The widget may show quick-reply chips.

Tool step — the runtime invokes your SDK tool directly (e.g. listOrders). Tool steps can chain in the same turn after attribute collection.

Flow completes — if the stage defines next, the customer advances to the next global stage (e.g. onboarding → active).

Try the ShopCo demo: pnpm start in the repo, then open http://localhost:3010/demo.html with a new customer id.

Lifecycle enforcement

Your SDK declares customer states — either via a pipeline manifest or aelio.state(). Pipeline stages automatically become lifecycle states at register time.

You can also push state manually when business events happen:

// Customer adds item to cart
await aelio.setCustomerState(customerId, 'cart_building');

// Now only cart-related tools are available
// checkout_cart is allowed, but list_invoices is blocked

State-gated tools

Tools not permitted in the current lifecycle state are blocked at the safety gate — the LLM cannot invoke them regardless of what the customer asks.

Channel-agnostic

The same SDK tools work across all channels. A customer can start on one chat interface and continue on another — Aelio resolves identity and recalls memory across channels.

What you build vs what Aelio handles

You build	Aelio handles
Business logic (tool handlers)	LLM orchestration and tool selection
Database queries	Safety gates and write confirmations
User authentication	Customer identity resolution
Chat interface placement	WebSocket connection and reconnect
Channel webhook (if BYO)	Memory extraction and recall
Lifecycle state management	Channel delivery
	Proactive messaging guardrails
	Harness turn engine (plan → execute → synthesize)

On this page