@falai/agent 3.4.5 → 4.0.0-alpha.2

package/docs/guides/compaction.md

@@ -1,170 +1,75 @@
 ---
 title: "Compaction"
-description: "Keep prompts within token limits across long sessions by layering tool-result budgeting, micro-compaction, and LLM summarization in cost order."
+description: "Keep a long history inside the model's window: three layers in cost order, applied once per turn to what both calls see."
 type: guide
-order: 8
+order: 10
 ---
 
 # Compaction
 
-> **Where this is introduced:** [Errors](./error-handling.md)
-
-Long-running sessions accumulate history. Tool calls return verbose
-JSON, turns pile up, and at some point the next provider call runs
-out of token budget. Compaction is the framework's answer: a layered
-strategy that trims and summarizes `session.history` before each turn
-so the prompt fits without dropping anything load-bearing. Layers run
-in cost order — character-level truncation first, an LLM summarization
-call only when nothing cheaper closes the gap.
-
-This guide is task-shaped: enable compaction, choose a budget, and
-understand which layer fires when.
-
-## Enable compaction
-
-Compaction is opt-in. Set `AgentOptions.compaction` and the agent
-validates the config at construction time, then runs the engine
-deterministically at end-of-turn finalize on every `respond()` /
-`chat()` / `stream()` call — and additionally whenever a message is
-appended via `session.addMessage()`. Since v2.4 the finalize run is
-guaranteed, so respond-only integrations that never call
-`addMessage()` get bounded history too (previously compaction only
-ran inside `addMessage()`).
-
-```typescript
-import { createAgent, GeminiProvider } from "@falai/agent";
-
-const agent = createAgent({
-  name: "Concierge",
-  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
-  schema: { /* ... */ },
-  flows: [/* ... */],
-
-  compaction: {
-    maxTokens: 32_000,           // total token budget for the prompt
-    compactionThreshold: 0.8,    // fire when history hits 80% of maxTokens (default)
-    preserveRecentCount: 4,      // never touch the last 4 history items (default)
-    maxToolResultChars: 5_000,   // global cap per tool message (default)
-    // enabled: true,            // default true when `compaction` is provided
-  },
+A long conversation grows a long history. `compaction` trims the copy the model reads once the history passes a token budget you set.
+
+```ts
+import { falai, GeminiProvider } from "@falai/agent";
+
+const f = falai().fields({});
+
+const agent = f.agent({
+  name: "Ana",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  idle: { prompt: "Responda pela empresa." },
+  compaction: { maxTokens: 2000 },
 });
-```
 
-The four knobs map onto the
-[`AgentCompactionConfig`](../reference/create-agent.md) interface.
-`maxTokens` is the only required field; the rest fall back to the
-defaults shown above. The agent calls `validateOptions` synchronously
-at construction, so misvalued thresholds (`compactionThreshold` outside
-`[0.5, 0.95]`, `preserveRecentCount < 2`, `maxToolResultChars <= 0`)
-throw immediately rather than silently no-oping at runtime.
-
-A second knob lives on every `Tool`: `maxResultSizeChars`. That value
-is enforced by the tool executor the moment a tool returns, before the
-result enters history at all. It and the agent-level `maxToolResultChars`
-work together — per-tool first, global later.
-
-## How a turn checks the budget
-
-At the end of every turn (and on each `session.addMessage()`), the
-engine runs
-`CompactionEngine.checkAndCompact(session.history, options)`. The
-compacted history is what gets persisted and carried into the next
-turn's prompt. The engine estimates the current token count using a
-character-based heuristic (~4 characters per token), compares against
-`maxTokens * compactionThreshold`, and applies the cheapest layer that
-brings history below the threshold. If even the most expensive layer
-cannot, an aggressive truncation fallback removes the oldest items
-until the budget fits.
-
-`preserveRecentCount` is honored by every layer. The trailing N items
-of `session.history` are never modified, summarized, or removed —
-recent turns are the one piece of context the engine refuses to spend.
-
-## Layer 1 — tool-result budgeting
-
-`tool_result_budget` is the cheapest layer. It walks history, finds
-items with `role: "tool"`, and truncates any whose stringified content
-exceeds `maxToolResultChars`. Truncated items get a deterministic
-notice appended:
-
-```text
-[Truncated: 12834 chars total, showing first 5000]
+const history = Array.from({ length: 400 }, (_, i) => ({ role: "user" as const, content: `mensagem antiga número ${i}` }));
+const r = await agent.turn({ sessionId: "demo", history, message: "oi" });
+console.log(r.llmCalls); // 2: one call to summarize the old messages, one to reply
 ```
 
-Character-level and synchronous — no LLM call, no network. It fires
-whenever history crosses the threshold and at least one tool message
-is oversized. For agents that orchestrate verbose APIs (search, SQL,
-web fetches) this layer alone usually keeps the prompt in budget.
-
-The per-tool counterpart is `Tool.maxResultSizeChars`. Set it on
-high-volume tools to truncate at execution time, before the result
-ever lands in history. Combine the two: a tight per-tool cap on a
-known-chatty tool, plus a global ceiling at the agent level.
-
-## Layer 2 — micro-compaction
-
-If `tool_result_budget` is not enough, `micro_compact` runs over the
-already-budgeted history. It compresses verbose tool outputs inline
-by collapsing whitespace runs to a single space and trimming the
-edges. Tool results are the only target — user, assistant, and system
-messages pass through unchanged.
-
-Still LLM-free and deterministic. Most effective on tool results that
-contain pretty-printed JSON or multiline text where formatting is
-whitespace-heavy. The recent-N tail (`preserveRecentCount`) is
-preserved verbatim during this pass; the cutoff is `history.length -
-preserveRecentCount`, and only items before that cutoff are
-compressed.
-
-## Layer 3 — LLM summarization
-
-When neither character-level layer brings the prompt under threshold,
-`auto_compact` dispatches a single `provider.generateMessage` call
-asking the agent's own LLM to summarize the older portion. The result
-becomes one synthetic system message:
-
-```text
-[Conversation Summary]
-<summary text from the provider>
-```
+With `maxTokens: 2000` the turn compacts when the history is estimated at 1600 tokens or more (80% of 2000). These 400 short messages estimate at close to 3000, so the oldest ones are summarized before the reply is phrased, and that summary is one model call. Below the threshold nothing happens and nothing is spent.
+
+## The option
+
+`AgentCompactionConfig`, from `src/types/agent.ts`; the defaults are applied in `src/core/Agent.ts`:
+
+| Field | Meaning | Default |
+|---|---|---|
+| `maxTokens` | the token budget for the history | required |
+| `compactionThreshold` | compact when the estimate reaches this share of `maxTokens`; between 0.5 and 0.95 | `0.8` |
+| `preserveRecentCount` | the newest messages are never changed or removed; at least 2 | `4` |
+| `maxToolResultChars` | characters kept of a tool result before it is cut; more than 0 | `5000` |
+| `enabled` | `false` turns compaction off without removing the config | `true` when the config is present |
+
+A value out of range throws at construction, as a plain `Error`: `compactionThreshold must be between 0.5 and 0.95, got 2`, `preserveRecentCount must be >= 2, got 1`, `maxToolResultChars must be > 0, got 0`.
+
+## When it runs
+
+Once per turn, before the understand call and before the speak call, so both read the same trimmed history. The framework reads `input.history`, or `session.history` when the host passes none, and only acts when there is one. The trimmed copy lives for that turn: your stored history is never rewritten by the framework. The next turn compacts again from whatever you pass.
+
+Tokens are estimated, not counted: the characters of every message's content, plus its `name` when it has one (a tool result always does), plus 4 per message for its role, divided by 4 and rounded up. The estimate is deterministic, so the same history compacts the same way every time.
+
+## The three layers, cheapest first
+
+The engine tries each layer in order and stops at the first one that brings the estimate under the threshold. Under the threshold it runs none of them and reports `none`. The newest `preserveRecentCount` messages stay untouched through all three.
+
+| Strategy | What it does | Model calls |
+|---|---|---|
+| `tool_result_budget` | cuts every tool result longer than `maxToolResultChars`, appending `[Truncated: N chars total, showing first M]` | 0 |
+| `micro_compact` | collapses runs of whitespace inside older tool results | 0 |
+| `auto_compact` | asks the model to summarize every message older than the preserved window, and replaces them with one `system` item that starts with `[Conversation Summary]` | 1 |
+
+The first two layers touch tool results only, because that is where a history gets long without saying much. A conversation of plain user and assistant text goes straight to `auto_compact` when it passes the threshold.
+
+`auto_compact` is one model call and adds one to `result.llmCalls`. It is the only call in a turn that is neither understand nor speak; the summary prompt is sent with no `schemaName`. When that call fails, the engine drops the oldest messages instead until the rest fit, without another call; the turn goes on and the failed call still counts.
+
+The preserved window is a target, not a hard cut: its left edge moves left when it would otherwise open on a tool result whose calling assistant message was cut away, because providers reject such a history at the next request.
+
+## Turning it off
+
+Leave `compaction` out, or set `enabled: false`. Either way the model sees the full history you pass, and the `context` kind of `ProviderError` is what tells you the window overflowed; see [error handling](./error-handling.md).
+
+## What compaction is not
+
+It is not memory. The collected fields live in `session.data` and are never compacted; the model is told what is already known on every call a talk step makes (the idle speaker's prompt does not restate them). It is not persistence: what you store is up to you, and the summary the engine writes is not kept anywhere unless you keep the trimmed history yourself.
 
-That synthetic item replaces every history item before the
-`preserveRecentCount` tail. The recent tail is appended unchanged. If
-the provider call fails — quota, network, any caught exception — the
-engine falls back to `aggressiveTruncate`: walk older messages newest
-to oldest, keep as many as fit under `maxTokens * compactionThreshold`,
-drop the rest. The strategy field on the result still reads
-`"auto_compact"` so callers can see that summarization was attempted.
-
-This layer costs a real provider round-trip. It only fires when
-character-level layers cannot close the gap — in practice, sessions
-with hundreds of long turns or tools that return narrative prose
-rather than structured data.
-
-## When each layer fires
-
-The `compactionThreshold` ratio is the gate for all three layers. Below
-threshold, `checkAndCompact` returns `strategy: "none"` and history
-passes through untouched. At or above threshold, the engine attempts
-each layer in order and stops as soon as the result drops below the
-threshold:
-
-| Estimated tokens | Strategy that fires |
-|------------------|---------------------|
-| `< maxTokens * compactionThreshold` | `none` |
-| `≥ threshold`, oversized tool messages exist | `tool_result_budget` |
-| `≥ threshold` after budgeting | `micro_compact` |
-| `≥ threshold` after micro-compaction | `auto_compact` (LLM call) |
-| LLM call failed | `auto_compact` (truncation fallback) |
-
-The result's `messagesCompacted` count and optional `summary` field
-are logged at `info` level so production logs show which layer fired
-on which turn.
-
-A practical defaults sketch: set `maxTokens` to ~80% of the model's
-context window, leave `compactionThreshold` at the 0.8 default, and
-put a tight per-tool `maxResultSizeChars` on any tool that talks to
-a search API or a database. Pick the budget, set the caps, let the
-layers absorb the noise.
-
-**Next:** [Architecture](../concepts/architecture.md)
+See [the pipeline](../concepts/pipeline.md) for where the compaction step sits among the eight phases.

package/docs/guides/conditions.md

@@ -1,181 +1,217 @@
 ---
-title: "When and if"
-description: "Pick between AI-evaluated `when` strings and code-evaluated `if` predicates, and combine them to save tokens."
+title: "Conditions"
+description: "if is a question your code answers for free; when is a question the model answers inside a model call."
 type: guide
-order: 1
+order: 2
 ---
 
-# When and if
+# Conditions
 
-Conditions decide whether a flow activates, a step runs, an instruction applies, or a branch fires. v2 splits them into two distinct fields with different evaluators:
+Two words, two judges. `if` is a question your code answers. `when` is a question the model answers from what the customer just said.
 
-- `when` — strings the LLM evaluates against intent and the conversation. Costs tokens.
-- `if` — TypeScript predicates the engine evaluates locally. Free.
+The smallest condition is an `if` step:
 
-The split is the same everywhere: `Flow`, `Step`, `Instruction`, and `BranchEntry` all expose `when?` and `if?` with identical semantics. This guide shows how to pick between them, how arrays combine, and what happens when both are set. If you are migrating from v1, the [v1 → v2 migration guide](../migration/v1-to-v2.md) covers the renamed condition fields.
+```ts
+import { falai, GeminiProvider } from "@falai/agent";
 
-## Pick the right field
+interface Ctx {
+  lead: { tags: string[] };
+}
 
-Reach for `if` first. It's free, deterministic, and reads clearly in code review.
+const f = falai<Ctx>().fields({});
+
+const agent = f.agent({
+  name: "Ana",
+  // Set GEMINI_API_KEY in your environment before running this.
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  flows: [
+    f.flow({
+      id: "boas-vindas",
+      name: "Boas-vindas",
+      steps: [
+        { id: "vip", if: ({ context }) => context.lead.tags.includes("vip"), then: "tapete", else: "oi" },
+        { id: "tapete", say: "Bem-vindo de volta. Já avisei seu gerente de conta.", then: "end" },
+        { id: "oi", say: "Oi. Posso ajudar em algo?" },
+      ],
+    }),
+  ],
+});
 
-| Question to answer                                              | Use      |
-| --------------------------------------------------------------- | -------- |
-| Is this user authenticated? Is `data.tier === 'pro'`?           | `if`     |
-| Is the feature flag on? Is the order older than 90 days?        | `if`     |
-| Did the user ask about pricing? Are they expressing frustration? | `when`   |
-| Is the user describing a refund scenario in their own words?    | `when`   |
+const r = await agent.turn({ sessionId: "s1", context: { lead: { tags: ["vip"] } }, start: { flow: "boas-vindas", key: "signup:1" } });
+console.log(r.messages[0]?.text); // "Bem-vindo de volta. Já avisei seu gerente de conta."
+console.log(r.llmCalls); // 0
+```
 
-If the answer lives in `data`, `context`, or `session`, it's `if`. If the answer requires reading the user's intent from natural language, it's `when`.
+Code answered the question, so the turn cost no model call.
 
-## `when` — AI strings
+## `if`: code, free
 
-`when` accepts a string or an array of strings. Functions are rejected at construction time with `FlowConfigurationError`.
+An `if` is a `Pred`: a function that returns a boolean, or the same thing written as JSON (a `ConditionSpec`). Both see the same context.
 
-```typescript
-{
-  title: "Refund",
-  when: "the user is requesting a refund",
-}
-```
+| `PredCtx` field | What it is |
+|---|---|
+| `context` | the host context passed to this `turn()` |
+| `data` | the collected fields so far, `Partial<D>` |
+| `input` | the run's input: an event payload, a start input, a mention's extract; `unknown` |
+| `run` | the run being judged; absent only for an agent-level instruction while the idle speaker answers |
+| `silenced` | the host's reason the assistant cannot speak now; absent when it can |
+| `now` | the agent's clock |
 
-Multiple non-`!` strings combine with **OR** semantics — any clause may pass for the condition to match. Use the array form for alternative natural-language expressions of the same intent:
+### As a function
 
-```typescript
-{
-  title: "Address",
-  when: [
-    "the user asked about the address",
-    "the user asked where we are located",
-  ],
-}
+```ts fragment
+if: ({ context, data, now }) => context.lead.owner === "ai" && data.nome !== undefined && now.getHours() < 18
 ```
 
-Prefix a string with `!` to make it an exclusion. Exclusions also combine with OR semantics: if any exclusion matches, the condition is inhibited. A negative-only `when` means "active unless this exclusion matches."
+A function is the most direct form. It cannot be stored: `toSpec` refuses a flow that carries one with a `FlowConfigurationError`. For a flow that lives in a database, write the JSON form.
 
-```typescript
-{
-  title: "Checkout",
-  when: [
-    "the user is ready to buy",
-    "!the user is asking for support",
-  ],
-}
-```
+### As JSON
 
-The strings are sent to the LLM as part of the routing or activation prompt. For instructions, the string is appended to the instruction bullet so the response model can apply the instruction conditionally. Keep conditions short, intent-shaped, and free of code-style boolean expressions — `"the user wants to cancel"` lands; `"data.cancelRequested === true"` does not.
+A `ConditionSpec` is an object whose keys are conditions. Every listed key must hold. Three are built in:
 
-## `if` — code predicates
+| Key | Holds when | Example |
+|---|---|---|
+| `equals` | each listed field equals the given value | `{ equals: { confirmado: true } }` |
+| `known` | each listed field has a value (not `undefined`, `null` or `''`) | `{ known: ['nome', 'empresa'] }` |
+| `silenced` | `true`: the host said the assistant cannot speak; `false`: it can | `{ silenced: true }` |
 
-`if` accepts a function or an array of functions. Each predicate receives a `TemplateContext`-shaped argument (`{ context, data, session, history, helpers }`) and returns `boolean | Promise<boolean>`.
+Any other key names one of the agent's `conditions` and carries its argument:
 
-```typescript
-{
-  title: "Enterprise",
-  if: ({ context }) => context.tier === "enterprise",
-}
-```
+```ts
+import { falai, GeminiProvider } from "@falai/agent";
 
-Arrays combine with **AND** semantics — every predicate must return truthy.
+interface Ctx {
+  lead: { tags: string[] };
+}
 
-```typescript
-{
-  if: [
-    ({ context }) => context.authenticated,
-    ({ data }) => (data.cartTotal ?? 0) > 100,
+const f = falai<Ctx>().fields({
+  nome: { type: "string", ask: "Pergunte o nome." },
+  confirmado: { type: "boolean", ask: "Resuma o que anotou e pergunte se está certo." },
+});
+
+const agent = f.agent({
+  name: "Ana",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  conditions: {
+    // Used by name in JSON: { tagsAny: ["vip", "parceiro"] }. The argument comes from JSON unchecked, so test it.
+    tagsAny: f.condition((ctx, tags: string[]) => Array.isArray(tags) && tags.some((t) => ctx.context.lead.tags.includes(t))),
+  },
+  flows: [
+    f.flow({
+      id: "fechamento",
+      name: "Fechamento",
+      on: [{ message: ["quer fechar o contrato"], if: { tagsAny: ["vip", "parceiro"] } }],
+      steps: [
+        { id: "quem", collect: ["nome"] },
+        { id: "confirma", collect: ["confirmado"] },
+        { id: "ok", if: { equals: { confirmado: true } }, else: { step: "quem", clear: ["confirmado", "nome"] } },
+        { id: "tchau", prompt: "Agradeça e diga que um vendedor continua daqui." },
+      ],
+    }),
   ],
-}
+});
 ```
 
-Predicates that throw or reject are caught, logged, and treated as `false` for that evaluation. They never corrupt the session — the worst case is the condition fails to match.
+`f.condition` gives the check its argument type; the JSON side stays a plain object. When the agent is built, `validateFlow` checks every JSON condition and throws `FlowConfigurationError` on the first problem:
 
-### What's in the predicate context
+- `equals` must be an object; each key must be a field; each value must have the field's exact type (`"3"` is not a number, nothing is coerced) and be in its `enum` unless it is a template such as `"{{context.plano}}"`.
+- `known` must be a list of field slugs.
+- `silenced` must be a boolean.
+- Any other key must be a registered condition, or the error names it: `unknown condition "tagsAny"`.
 
-Predicates receive a context object with the same shape used everywhere templates and conditions evaluate. The fields you'll reach for most:
+Keys with an `undefined` value are skipped. An empty object `{}` always holds.
 
-| Field      | Type                     | Notes                                                            |
-| ---------- | ------------------------ | ---------------------------------------------------------------- |
-| `data`     | `Partial<TData>`         | Collected schema fields. Null-check anything not in `requires`.  |
-| `context`  | `TContext`               | Agent-level ambient context (user, env, services).               |
-| `session`  | `SessionState<TData>`    | Current flow id, current step id, full history.                  |
-| `history`  | `Event[]`                | Read-only conversation history.                                  |
+## `when`: judged by the model
 
-Predicates can be `async`. Awaiting a database lookup or feature-flag service is supported, but remember: every predicate runs every time its host primitive is evaluated. Keep them cheap, or memoize the work in a hook upstream.
+A `when` is a sentence about the customer's latest message. It appears in two places:
 
-```typescript
-{
-  if: async ({ context, data }) =>
-    await context.flags.isEnabled("v2_pricing", data.userId),
-}
-```
+- **A branch on a talk step.** The understand call answers it true or false while the step is asking. The first branch that holds moves the run. See [Branching](branching.md).
+- **An instruction.** The sentence is rendered into the speak prompt for the model to apply itself: "when the customer is upset, apologise once". It is guidance, not a gate; code never evaluates it.
 
-## When both are set
+```ts
+import { falai } from "@falai/agent";
 
-Setting both `when` and `if` on the same primitive runs `if` **first**, free. `when` is only sent to the LLM when every `if` predicate passes. The order is deliberate: predicates short-circuit the LLM call when the answer is already disqualified.
+const f = falai().fields({
+  pedido: { type: "string", ask: "Pergunte o número do pedido." },
+});
 
-```typescript
-{
-  title: "US Pricing",
-  if: ({ context }) => context.country === "US" && context.flags.usPricing,
-  when: "the user is asking about pricing",
-}
+const suporte = f.flow({
+  id: "suporte",
+  name: "Suporte a pedidos",
+  on: [{ message: ["problema com um pedido"] }],
+  instructions: [{ kind: "must", when: "o cliente está irritado", prompt: "Peça desculpa uma vez e vá direto à solução." }],
+  steps: [
+    {
+      id: "dados",
+      collect: ["pedido"],
+      branches: [{ when: "a pessoa pede para falar com um humano", then: { flow: "humano" } }],
+    },
+    { id: "resolve", prompt: "Explique o próximo passo para o pedido {{data.pedido}}." },
+  ],
+});
 ```
 
-In the snippet above, non-US users skip the AI evaluation entirely. The `when` string costs tokens only when the predicate already says "this user is in scope, ask the AI whether they're asking about pricing."
+What a `when` costs: the understand call happens at most once per turn, and every `when` branch rides in it. When that call would not happen otherwise (a single message flow, nothing to extract, no mention flows), a `when` branch alone makes the turn spend it. An instruction's `when` costs nothing extra: it is text inside the speak prompt.
 
-This pattern is the recommended shape any time a condition has both a cheap precondition and an intent classification. Lead with `if` to gate. Use `when` to interpret.
+A `when` only makes sense where there is fresh customer text. Branches on a `wait` step are judged when the customer replies, by code only: an `if` branch there works, a `when` branch is listed by the type but never asked.
 
-## Where the split lives
+## Where each is allowed
 
-The same `when` / `if` shape attaches to four primitives. Semantics are identical in each location:
+| Place | `if` | `when` |
+|---|---|---|
+| Trigger (`on[].if`) | yes: the run starts only if it holds; also the flow's default `while` | no: the phrases in `message` and `mention` are the model's part |
+| Flow `while` | yes: re-checked whenever the run moves | no |
+| Branch on a talk step | yes, code | yes, the understand call |
+| Branch on a `wait` step | yes, when the customer replies | never judged |
+| `if` step | yes, required | no |
+| Instruction (agent, flow or step) | yes: the instruction is dropped from the prompt when it fails | yes: rendered into the prompt |
 
-| Primitive       | Field path              | What it gates                                      |
-| --------------- | ----------------------- | -------------------------------------------------- |
-| Flow            | `FlowOptions.when/if`   | Whether the router selects this flow this turn     |
-| Step            | `StepOptions.when/if`   | Whether the step is reachable in the current flow  |
-| Instruction     | `Instruction.when/if`   | Whether the instruction applies to the response    |
-| BranchEntry     | `BranchEntry.when/if`   | Whether this branch entry matches inside `step.branches` |
+## Which one to write
 
-```typescript
-// Flow scope — gate flow selection
-{ title: "Refund", when: "user wants a refund", if: ({ context }) => context.authenticated }
+Ask where the answer already is.
 
-// Step scope — gate step reachability
-{ id: "verify_payment", when: "user is confirming the order", if: ({ data }) => !!data.cardToken }
+- In `context`, `data` or the input: `if`. It is free and deterministic.
+- In what the customer just said, and you need code to act on it: a `when` branch.
+- In what the customer just said, and it is a yes or no you will keep: collect a boolean field with `extract: 'asked'` and gate on it with an `if` step. The speak envelope of that step fills the field; there is no extra call. The confirmation pattern in [Collection](../concepts/collection.md) is this.
+- Both: a `when` branch on the step and an `if` on the flow. Each is judged by its own judge.
 
-// Instruction scope — render only when relevant
-{ kind: "should", when: "user mentions a discount code", prompt: "Validate the code before applying it." }
+## JSON flows
 
-// Branch scope — pick a successor
-branches: [
-  { if: ({ data }) => data.tier === "enterprise", when: "user wants pricing", then: "enterprise_pricing" },
-  { then: "default_pricing" },
-]
-```
-
-## `step.skip` is the OR companion
+A stored flow carries only the JSON form. `f.fromSpec` types it, and the agent checks the names when it is built:
 
-One adjacent field rounds out the picture. `step.skip` is **function-only** with **OR** semantics — when any predicate returns truthy, the step is bypassed. Use it for "skip when this field already exists" cases:
+```ts
+import { falai, GeminiProvider } from "@falai/agent";
+import type { FlowSpec } from "@falai/agent";
 
-```typescript
-{
-  id: "ask_email",
-  collect: ["email"],
-  skip: ({ data }) => !!data.email,
+interface Ctx {
+  lead: { stageId: string };
 }
-```
 
-`skip` does not accept strings. There is no AI counterpart — skipping is a code decision by design.
-
-## Quick reference
+const f = falai<Ctx>().fields({});
+
+const spec: FlowSpec = {
+  id: "proposta",
+  name: "Acompanhar proposta",
+  on: [{ event: "stage_entered", after: "1h", if: { inStage: "proposta" } }],
+  while: { inStage: "proposta" },
+  steps: [{ id: "p", kind: "prompt", prompt: "Pergunte se a proposta chegou bem e se há dúvidas." }],
+};
+
+const agent = f.agent({
+  name: "Ana",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  events: { stage_entered: f.event<{ stageId: string }>() },
+  conditions: {
+    inStage: f.condition((ctx, stageId: string) => ctx.context.lead.stageId === stageId),
+  },
+  flows: [f.fromSpec(spec)],
+});
+```
 
-A short checklist before shipping a condition:
+Remove `inStage` from `conditions` and `f.agent` throws `[FlowConfigurationError] flow "proposta": unknown condition "inStage" in while. Register it in conditions or use equals, known, silenced.` The flow's `while` is checked before its triggers, so that is the line you see first. More in [Flows from JSON](flows-from-json.md).
 
-- Does it read a field, flag, or context value? Use `if`.
-- Does it interpret natural language? Use `when`.
-- Multiple natural-language alternatives where any may match? Put them in `when` — non-`!` entries use OR.
-- Need an AI-evaluated exclusion? Prefix that `when` entry with `!`.
-- Multiple code predicates that must all pass? Put them in `if` — arrays use AND.
-- Need to skip when a value is already collected? `step.skip` (OR semantics).
-- Both fields set? `if` runs first, free; `when` only fires if `if` passes.
+## Read next
 
-**Next:** [Branching](./branching.md)
+- [Branching](branching.md): `when` and `if` branches, the `if` step, `clear`.
+- [Flow control](flow-control.md): `while` and the premise check.
+- [Actions, events and conditions reference](../reference/actions-events-conditions.md): `Condition`, `ConditionSpec`, `PredCtx`.