@falai/agent 3.4.5 → 4.0.0-alpha.10

package/docs/start/05-go-to-production.md

@@ -1,219 +1,237 @@
 ---
 title: "Go to production"
-description: "Add durable persistence, streaming responses, and an HTTP endpoint to ship the booking agent."
+description: "Run Ana on a real channel: keep sessions in a store, save before you send, put timers in a queue, and bring 3.x sessions over."
 type: tutorial
 order: 5
 ---
 
 # Go to production
 
-The framework stays the same shape from prototype to production; only the adapter and the call site change. This page adds `PrismaAdapter` for durable sessions, `respondStream` for real-time output, and a session-keyed POST endpoint that any chat client can call. Same seven primitives, same booking flow — now with persistence and streaming on top.
+The framework never sends a message, never sleeps and never saves. Every turn returns what to send, when to wake up and the new state; the program that calls `turn()` does the rest. This page calls that program the host. Its loop is short:
 
-The booking agent from [04 — Add tools](./04-add-tools.md) runs end to end, but it forgets every conversation the moment the process exits, hands replies back as one final string, and lives in a script. Production has three more requirements: durability, real-time output, and a way for clients to talk to it. This page wires up all three.
+1. Load the session for this conversation.
+2. Call `agent.turn()` with the input.
+3. If `r.changed`, save `r.session` with the version you loaded. If another turn saved first, the save throws; run the same input again.
+4. Only then send `r.messages` and put `r.schedule` in a queue.
+5. When a queued job fires, call `turn()` with `{ wake: key }`.
 
-You will:
+## A store
 
-1. Swap the implicit `MemoryAdapter` for `PrismaAdapter` so sessions survive restarts.
-2. Switch the call site from `agent.respond` to `agent.respondStream` and consume chunks as they arrive.
-3. Wrap the agent in a session-keyed POST endpoint that any chat client can call.
+A store keeps sessions. It has two methods, `load(id)` and `save(session, expectedVersion)`, and the framework never calls either. Start in memory:
 
-By the end you have the same booking agent — same flow, same tools — running behind an HTTP API with persistent state.
+```ts
+import { MemoryStore } from "@falai/agent";
 
-## 1. Persist sessions with Prisma
+const store = new MemoryStore();
+console.log(await store.load("demo")); // null: no session yet
+```
 
-By default `createAgent` uses `MemoryAdapter`, an in-process map that vanishes with the process. Production needs storage that outlives a deploy. `PrismaAdapter` rides on top of any Prisma-supported database; you own the schema, the adapter does the reads and writes.
+`MemoryStore` forgets everything when the process stops. For production, PostgreSQL — the driver is yours to install: `bun add pg`.
 
-Add Prisma to the project:
+```ts
+import { Pool } from "pg";
+import { PostgresStore } from "@falai/agent";
 
-```bash
-bun add @prisma/client
-bun add -d prisma
-bunx prisma init
+const store = new PostgresStore({ client: new Pool({ connectionString: process.env.DATABASE_URL }) });
+await store.initialize();
 ```
 
-Open the generated `prisma/schema.prisma` and add the `AgentSession` and `AgentMessage` models. Two columns matter most: `pendingDirective` and `signals`. The agent serializes its [`Directive`](../reference/directive.md) and signal state into them at the end of every turn and reads them back at the start of the next.
+`initialize()` creates the table when it is missing. One row per session:
 
-```prisma
-// prisma/schema.prisma
-generator client {
-  provider = "prisma-client-js"
-}
+```sql
+CREATE TABLE IF NOT EXISTS agent_sessions (
+  id VARCHAR(255) PRIMARY KEY,
+  version INTEGER NOT NULL,
+  blob JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+)
+```
 
-datasource db {
-  provider = "postgresql"
-  url      = env("DATABASE_URL")
-}
+`tables: { sessions: "ana_sessions" }` renames it. If you have a 3.x `agent_sessions` table, point the store at a fresh name: the columns are different, and a v4 store reading a 3.x row throws. The last section moves the old rows over.
+
+`PrismaStore`, `RedisStore`, `MongoStore`, `SQLiteStore` and `OpenSearchStore` take their own clients and behave the same. [Persistence](../guides/persistence.md) has each one's setup.
+
+## The loop
+
+Here is Ana behind a channel and a queue. The agent is the one from the last page; the tool and the action slot in unchanged and are left out for space.
+
+```ts
+import { Pool } from "pg";
+import {
+  falai,
+  GeminiProvider,
+  PostgresStore,
+  SessionConflictError,
+  type DataOf,
+  type History,
+  type OutboundMessage,
+  type ScheduleEntry,
+  type Silenced,
+  type TurnKind,
+} from "@falai/agent";
+
+const f = falai().fields({
+  nome: { type: "string", ask: "Pergunte o nome da pessoa, sem tom de formulário." },
+  empresa: { type: "string", ask: "Pergunte de qual empresa a pessoa fala." },
+  tamanho: {
+    type: "string",
+    enum: ["1-10", "11-50", "51-200", "200+"],
+    ask: "Pergunte quantas pessoas trabalham lá e ofereça as faixas.",
+  },
+  confirmado: { type: "boolean", ask: "Resuma em uma frase o que anotou e pergunte se está tudo certo." },
+});
+type Data = DataOf<typeof f>;
+
+const agent = f.agent({
+  name: "Ana",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  flows: [
+    f.flow({
+      id: "triagem",
+      name: "Triagem",
+      on: [{ message: [] }],
+      steps: [
+        { id: "quem", prompt: "Descubra quem é e de onde fala.", collect: ["nome", "empresa"] },
+        { id: "porte", collect: ["tamanho"], maxAsks: 2 },
+        { id: "confirma", collect: ["confirmado"] },
+        { id: "ok", if: { equals: { confirmado: true } }, else: { step: "quem", clear: ["confirmado"] } },
+        { id: "tchau", prompt: "Agradeça e diga que um vendedor continua daqui." },
+      ],
+    }),
+  ],
+});
 
-model AgentSession {
-  id                String    @id
-  userId            String?
-  agentName         String?
-  status            String    @default("active")
-  currentFlow       String?
-  currentStep       String?
-  collectedData     Json?
-  pendingDirective  Json?
-  signals           Json?
-  version           Int?
-  messageCount      Int       @default(0)
-  lastMessageAt     DateTime?
-  completedAt       DateTime?
-  createdAt         DateTime  @default(now())
-  updatedAt         DateTime  @updatedAt
+// Yours: the channel, the queue and the transcript.
+declare function sendWhatsApp(sessionId: string, message: OutboundMessage): Promise<void>;
+declare function enqueueWake(sessionId: string, entry: ScheduleEntry): Promise<void>;
+declare function loadHistory(sessionId: string): Promise<History>;
+
+const store = new PostgresStore<Data>({ client: new Pool({ connectionString: process.env.DATABASE_URL }) });
+await store.initialize();
+
+/** One input in. Messages and wakes go out only after the save. */
+async function handle(input: TurnKind & { sessionId: string; silenced?: Silenced }): Promise<void> {
+  while (true) {
+    const session = await store.load(input.sessionId);
+    const history = await loadHistory(input.sessionId);
+    const r = await agent.turn({ ...input, session: session ?? undefined, history });
+    if (!r.changed) return;
+    try {
+      await store.save(r.session, session?.version ?? 0);
+    } catch (error) {
+      if (error instanceof SessionConflictError) continue; // someone saved first: replay the same input
+      throw error;
+    }
+    for (const message of r.messages) await sendWhatsApp(input.sessionId, message);
+    for (const entry of r.schedule) await enqueueWake(input.sessionId, entry);
+    return;
+  }
 }
 
-model AgentMessage {
-  id        String   @id @default(cuid())
-  sessionId String
-  role      String
-  content   String
-  createdAt DateTime @default(now())
-
-  @@index([sessionId, createdAt])
-}
+// The channel delivered a message:
+await handle({ sessionId: "5511999990000", message: "oi, quero saber como funciona", id: "wamid.HBgL" });
 ```
 
-Push the schema and generate the client:
+Line by line:
 
-```bash
-bunx prisma db push
-bunx prisma generate
-```
+**`store.load(sessionId)`** returns the session or `null`. The session id is your conversation id: a phone number, a chat id.
 
-Now wire the adapter into the booking agent. The only change from the previous tutorial is the new `persistence` field — every flow, step, tool, and instruction stays exactly the same.
-
-```typescript
-import { PrismaClient } from "@prisma/client";
-import { createAgent, GeminiProvider, PrismaAdapter } from "@falai/agent";
-import { bookingFlow, bookingTools, bookingInstructions, schema } from "./booking";
-
-const prisma = new PrismaClient();
-
-export const agent = createAgent({
-  name: "BookingBot",
-  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
-  schema,
-  flows: [bookingFlow],
-  tools: bookingTools,
-  instructions: bookingInstructions,
-  persistence: {
-    adapter: new PrismaAdapter({ prisma }),
-    userId: "user_123",
-  },
-});
-```
+**`agent.turn({ ...input, session, history })`** runs the turn. `session` is `undefined` on a first message; the framework starts a fresh one.
 
-To resume a conversation by id, hydrate the session from the adapter and pass it through. `agent.session.getOrCreate(sessionId)` loads the stored `SessionState` (collected data, flow position, `pendingDirective`, signals state) — or creates a fresh one with that id if nothing exists yet.
+**`if (!r.changed) return`** is the whole handling of a no-op. The framework says nothing changed when a message `id` was already seen, when a wake is stale, or when nothing moved. Save nothing, send nothing.
 
-```typescript
-const session = await agent.session.getOrCreate("user_123:thread_abc");
+**`store.save(r.session, session?.version ?? 0)`** is a compare-and-swap. `0` means "insert; fail if a row exists". Any other number means "update the row that still has this version". Every store bumps the version by one on success.
 
-const response = await agent.respond({
-  history: [{ role: "user", content: "Hi again" }],
-  session,
-});
-```
+**`SessionConflictError`** means another turn on the same session saved first: a wake and a message arrived at once, or two webhooks raced. Nothing has been sent yet, so the fix is to throw the result away and go around the loop: load the new version, run the same input again. The replay produces the same message and action keys, so nothing reaches the customer twice. The only cost is the lost turn's model calls.
 
-Unknown ids start fresh against that id; there is no "not found" error path.
+**Send, then schedule.** Messages and wakes leave only after the save, so a lost race never sends twice.
 
-The `version Int?` column enables optimistic locking: when two writers race on one session (parallel webhooks, a double-send), the stale save throws `SessionConflictError` instead of silently overwriting — reload the session and retry. See [Concurrent writers](../guides/persistence.md#concurrent-writers-optimistic-locking).
+## Sending messages
 
-For the full schema migration story (renaming `pending_transition` to `pendingDirective`, adding the `signals` column) see [persistence adapters reference](../reference/adapters.md#prismaadapter).
+Each `OutboundMessage` has:
 
-## 2. Stream responses
+| Field | Use it for |
+|---|---|
+| `text` | The message. |
+| `kind` | `"ai"` phrased by the model, `"verbatim"` from a `say` step. |
+| `afterMs` | Wait this long before sending. It comes from a `wait` of 10 seconds or less placed before the message; a pause between two bubbles. |
+| `key` | `${runId}:${stepId}:${visit}`, the same on a replay. Store it with the outgoing message and skip a key you already sent. |
+| `runId`, `stepId` | The run and step that produced the message. Absent on a reply from the idle speaker (its `key` is `idle:<message id>`). |
+| `media` | `{ slug }` from a `say` step, when it has one. |
 
-`agent.respond` returns one final `AgentResponse` after the LLM and any tools have finished. That works for batch jobs, but a chat UI feels dead until the first character lands. `agent.respondStream` returns an `AsyncGenerator<AgentResponseStreamChunk>` — every chunk has the latest `delta` and `accumulated` text, plus a `done` flag.
+Pass the channel's message id as `id` on every inbound message. It goes into the run id and every key, and a second delivery of the same id is ignored with `changed: false`.
 
-```typescript
-const stream = agent.respondStream({
-  history: [{ role: "user", content: "Book me a hotel in Lisbon for two nights." }],
-});
+## Timers
 
-for await (const chunk of stream) {
-  if (chunk.delta) {
-    process.stdout.write(chunk.delta);
-  }
-  if (chunk.done) {
-    console.log("\n---");
-    console.log("Applied instructions:", chunk.appliedInstructions);
-    console.log("Triggered signals:", chunk.triggeredSignals);
-    console.log("Flow complete:", chunk.isFlowComplete);
-  }
+A `wait` longer than 10 seconds, a `silence` trigger or an `event` trigger with `after` does not sleep. The turn returns a `ScheduleEntry`; for a step `w1` with `wait: "3d"` it looks like this:
+
+```ts fragment
+{ key: "triagem#wamid.HBgL:w1:1790244000000", at: new Date("2026-09-24T10:00:00.000Z") }
+```
+
+A `silence` trigger's wake also carries `replaces`: the earlier silence wake it supersedes. Put the entry in your queue with the key and the session id in the payload, under a job id made from the key: every key contains `:`, and BullMQ refuses a custom job id with a `:` in it unless it splits into exactly three parts, so encode it as `encodeURIComponent(key)`. When `replaces` is set, remove the job whose id is `encodeURIComponent(replaces)`; it is best effort, a stale wake is harmless. When the job fires:
+
+```ts fragment
+await handle({ sessionId: job.data.sessionId, wake: job.data.key });
+```
+
+Only the run still waiting on that exact key honours the wake. Anything else returns `changed: false` with one line in `r.outcomes`: `code: 'stale-wake'` for a wait that a reply already resolved, `code: 'silence-broken'` when the customer wrote after the silence wake was set, `code: 'no-session'` when there is no session. So you do not have to cancel jobs: fire every one and the framework drops the stale ones.
+
+### When the queue loses its jobs
+
+A flushed Redis, or sessions lifted from 3.x by `migrateSession`, leave conversations waiting on wakes nobody will fire. `agent.pendingWakes({ session, context })` returns every wake a saved session waits on: each parked run's, and each silence flow's counted from `lastAssistantAt`, with the trigger's `if` and `repeat` judged on the `context` and `claims` you pass, as a turn would. It changes nothing and spends no model call. Enqueue what it returns as you would a turn's `schedule[]`:
+
+```ts fragment
+for (const wake of agent.pendingWakes({ session, context })) {
+  await queue.add("wake", { sessionId: session.id, key: wake.key }, {
+    jobId: encodeURIComponent(wake.key),
+    delay: Math.max(0, wake.at.getTime() - Date.now()),
+  });
 }
 ```
 
-Two fields land only on the terminal chunk (`done: true`):
+Running it twice is safe: BullMQ ignores a job whose id is already queued, and a wake that fires twice is dropped the second time as stale.
 
-- `appliedInstructions` — the [instructions](../reference/instruction.md) whose conditions passed and were rendered into this turn's prompt. Deterministic; derived from rendering, not from LLM self-report.
-- `triggeredSignals` — the signals (if any) that fired during this turn, in fire order.
+`fakeClock` and `MemoryScheduler` are the test doubles for this: [Testing](../guides/testing.md) plays a two-day follow-up in one test.
 
-Use them for telemetry, audit logs, or showing the user which guardrails ran. They mirror the same fields on the non-streaming `AgentResponse`, so swapping between APIs does not change observability.
+## On every input
 
-To cancel mid-stream — say, the user hits Stop — pass an `AbortSignal`:
+**`history`** is everything said before this input, as `{ role, content }` items, ending with Ana's last reply. Do not add the message you are passing now: the framework quotes it in the prompt itself, so it would reach the model twice. The framework does not keep it; you do, and you pass it on every input, wakes included. A wake carries no text, so the history is all the model knows about the conversation when Ana speaks first after a timer. `userMessage` and `assistantMessage` build the items:
 
-```typescript
-const controller = new AbortController();
-setTimeout(() => controller.abort(), 5000);
+```ts
+import { assistantMessage, userMessage, type History } from "@falai/agent";
 
-const stream = agent.respondStream({
-  history,
-  signal: controller.signal,
-});
+const history: History = [
+  userMessage("oi, quero saber como funciona"),
+  assistantMessage("Oi! Com quem eu falo, e de qual empresa?"),
+];
 ```
 
-## 3. A session-keyed HTTP endpoint
+**`silenced`** is the reason Ana must not speak right now: a human took the conversation, the channel's 24-hour window is closed, the account has no credits. Pass it on any input, as a string or as `{ reason, understand: true }`. A plain string spends zero model calls and sends nothing; `do` steps still run.
 
-The agent is now durable and streaming. The last piece is exposing it. Any HTTP framework works — Express, Bun.serve, Fastify, Hono. The pattern is the same: accept a `sessionId` and `message`, look up history, stream chunks back to the client. This Bun example is one screenful.
+A run that was already asking stays asking and speaks when the gate opens. A run that reaches a new talk step while silenced ends, and the log says `code: 'silenced'` with your reason in `detail`. Keep calling `turn()` for every inbound even while a human owns the customer, so waits resolve and the state stays true. `silenced: { reason, understand: true }` still spends the understand call, so fields keep landing while nothing is said.
 
-```typescript
-import { agent } from "./agent";
+**`context`** is the per-turn data your flows and actions read, such as the customer record. It is typed once, `falai<Ctx>()`, and passed on every input. Ana has none. [Agent](../reference/agent.md) has the full `TurnInput`.
 
-Bun.serve({
-  port: 3000,
-  async fetch(req) {
-    if (req.method !== "POST" || new URL(req.url).pathname !== "/chat") {
-      return new Response("Not found", { status: 404 });
-    }
+## Sessions from before v4
 
-    const { sessionId, message } = await req.json() as {
-      sessionId: string;
-      message: string;
-    };
-
-    const session = await agent.session.getOrCreate(sessionId);
-
-    const stream = agent.respondStream({
-      history: [{ role: "user", content: message }],
-      session,
-    });
-
-    return new Response(
-      new ReadableStream({
-        async start(controller) {
-          for await (const chunk of stream) {
-            controller.enqueue(
-              new TextEncoder().encode(
-                `data: ${JSON.stringify({
-                  delta: chunk.delta,
-                  done: chunk.done,
-                  isFlowComplete: chunk.isFlowComplete,
-                })}\n\n`
-              )
-            );
-          }
-          controller.close();
-        },
-      }),
-      { headers: { "Content-Type": "text/event-stream" } }
-    );
-  },
-});
+A 3.x session blob has `currentFlow`, `currentStep` and `signals`. Convert it once, where you read the row, and save it into the new table:
+
+```ts
+import { migrateSession, type Session } from "@falai/agent";
+
+function readRow(sessionId: string, blob: unknown): Session {
+  return migrateSession(blob, { sessionId, flowIdOf: (id) => id });
+}
 ```
 
-The shape that matters: `sessionId` is the contract between client and server. The same id on every request keeps the user pinned to the same conversation; the adapter loads the right `pendingDirective` and `signals`, the agent picks up exactly where the last turn ended. No per-request setup, no global state.
+A v4 blob passes through checked. A 3.x blob becomes one run at the same step id, plus a claim for every 3.x signal that fired and every flow that completed, so nothing fires twice. `flowIdOf` maps an old flow id or signal key to the v4 flow id; `(id) => id` when you kept the ids. The result has `version: 0`, so the usual `store.save(session, 0)` is the insert into the new table. Anything that is neither v4 nor a recognisable 3.x blob throws `InvalidSessionError`: a broken row is a loud error, never a fresh conversation that re-asks everything. [v3 → v4](../migration/v3-to-v4.md) has the full recipe.
+
+## Streaming
 
-A real chat backend adds auth, rate limits, and persistent message storage — but the core glue is the four lines that build `agent`, the four lines that read `request.json()`, and the loop that pipes stream chunks into Server-Sent Events.
+`agent.turnStream(input)` yields `{ delta }` chunks while the model writes, then one `{ done: true, result }`. The `result` is the same `TurnResult`, and the loop above applies to it unchanged. [Streaming](../guides/streaming.md) shows it.
 
-That is the full path: a 12-line `createAgent` call in [02 — Your first agent](./02-first-agent.md), data extraction in [03](./03-collect-data.md), tools in [04](./04-add-tools.md), and now durable, streaming, HTTP-served. The framework stays the same shape from prototype to production — only the adapter and the call site change.
+## Where next
 
-**Next:** [How-to guides](../guides/conditions.md)
+Ana works. To understand what you built, read [Architecture](../concepts/architecture.md) and [The turn](../concepts/pipeline.md). To make her start a conversation on her own, read [Triggers](../guides/triggers.md): `silence` brings back a customer who went quiet, `event` reacts to your system. For the exact shape of every option, start at [Agent](../reference/agent.md).

package/examples/01-quickstart.ts

@@ -1,20 +1,30 @@
-/** @intent Minimal agent: one flow, one step, one response.
- *  @teaches createAgent, GeminiProvider, Flow, Step, respond
- *  @readAfter docs/start/02-first-agent.md */
-import { createAgent, GeminiProvider } from "../src/index.js";
+/**
+ * Quickstart: one field, one flow, one turn.
+ *
+ * Run: GEMINI_API_KEY=... bun run examples/01-quickstart.ts
+ */
 
-if (!process.env.GEMINI_API_KEY) throw new Error("Set GEMINI_API_KEY");
+import { falai, GeminiProvider } from "@falai/agent";
 
-const agent = createAgent({
-    name: "Greeter",
-    provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY, model: "gemini-3.5-flash-lite" }),
-    schema: { type: "object", properties: { name: { type: "string" } } },
-    flows: [{
-        title: "Greet",
-        requiredFields: ["name"],
-        steps: [{ id: "ask_name", prompt: "What's your name?", collect: ["name"] }],
-    }],
+const f = falai().fields({
+  nome: { type: "string", ask: "Pergunte o nome da pessoa, sem tom de formulário." },
 });
 
-const response = await agent.respond({ history: [{ role: "user", content: "Hi, I'm Alice" }] });
-console.log(response.message);
+const agent = f.agent({
+  name: "Ana",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  flows: [
+    f.flow({
+      id: "boas-vindas",
+      name: "Boas-vindas",
+      on: [{ message: [] }],
+      steps: [
+        { id: "nome", collect: ["nome"] },
+        { id: "ajuda", prompt: "Agradeça pelo nome e pergunte como pode ajudar." },
+      ],
+    }),
+  ],
+});
+
+const r = await agent.turn({ sessionId: "demo", message: "oi" });
+console.log(r.messages[0]?.text);

package/examples/02-fields.ts

@@ -0,0 +1,75 @@
+/**
+ * Fields: authored once, asked in any order, each with its own wording.
+ *
+ * Teaches: `ask`, `enum`, `extract: 'asked'`, `maxAsks`, a step's own `ask`,
+ * confirmation as a collected boolean behind an `if`, `clearOnStart`.
+ * Read next: docs/concepts/collection.md
+ *
+ * Run: GEMINI_API_KEY=... bun run examples/02-fields.ts
+ */
+
+import { falai, GeminiProvider, type DataOf } from "@falai/agent";
+
+const f = falai().fields({
+  nome: { type: "string", ask: "Pergunte o nome de um jeito leve, sem tom de formulário." },
+  empresa: { type: "string", ask: "Pergunte de qual empresa a pessoa fala." },
+  tamanho: {
+    type: "string",
+    enum: ["1-10", "11-50", "51-200", "200+"],
+    ask: "Pergunte quantas pessoas trabalham lá e ofereça as faixas.",
+  },
+  orcamento: { type: "number", ask: "Pergunte a faixa de investimento, dizendo que é só para orientar." },
+  // Booleans are harvested only from the reply to the step that asks them,
+  // so a stray "sim" elsewhere never confirms anything.
+  confirmado: { type: "boolean", ask: "Resuma em uma frase o que anotou e pergunte se está tudo certo." },
+});
+
+type Data = DataOf<typeof f>;
+// Data = { nome: string; empresa: string; tamanho: '1-10' | '11-50' | '51-200' | '200+'; orcamento: number; confirmado: boolean }
+
+const triagem = f.flow({
+  id: "triagem",
+  name: "Triagem",
+  description: "Quando alguém chega querendo saber se o produto serve para a empresa dele.",
+  on: [{ message: ["quer saber como funciona", "pede um orçamento"], repeat: "always" }],
+  // A second run starts clean; the other fields stay known.
+  clearOnStart: ["confirmado"],
+  steps: [
+    // A step ends when its fields are known. If the first message already
+    // said "sou a Ana, da Acme", this step is skipped without a model call.
+    { id: "quem", prompt: "Descubra quem é e de onde fala.", collect: ["nome", "empresa"] },
+    // No prompt: the fields' own `ask` texts drive the question.
+    { id: "porte", collect: ["tamanho"] },
+    // Step wording wins over the field's; give up after two tries.
+    {
+      id: "grana",
+      collect: ["orcamento"],
+      ask: { orcamento: "Pergunte quanto {{data.empresa}} pensa em investir por mês; aceite 'não sei'." },
+      maxAsks: 2,
+    },
+    { id: "confirma", collect: ["confirmado"] },
+    // A "no" clears the confirmation and starts over from the first step.
+    { id: "ok", if: { equals: { confirmado: true } }, else: { step: "quem", clear: ["confirmado"] } },
+    { id: "tchau", prompt: "Agradeça e diga que um vendedor continua daqui." },
+  ],
+});
+
+const agent = f.agent({
+  name: "Ana",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  flows: [triagem],
+});
+
+// Two turns. Fields land in whatever order the customer gives them.
+const first = await agent.turn({ sessionId: "demo", message: "Oi, sou a Ana da Acme, quero um orçamento" });
+console.log(first.messages[0]?.text);
+
+const second = await agent.turn({
+  sessionId: "demo",
+  session: first.session,
+  message: "Somos 30 pessoas",
+});
+console.log(second.messages[0]?.text);
+
+const data: Partial<Data> = second.session.data;
+console.log(data); // { nome: 'Ana', empresa: 'Acme', tamanho: '11-50' }