@falai/agent 3.4.5 → 4.0.0-alpha.2

package/docs/guides/flows-from-json.md

@@ -0,0 +1,224 @@
+---
+title: "Flows from JSON"
+description: "Store flows as rows, let an editor draw them or a model write them: FlowSpec is the same object as a Flow, with no functions in it."
+type: guide
+order: 11
+---
+
+# Flows from JSON
+
+A flow written as JSON is a `FlowSpec`. `f.fromSpec(spec)` turns it into a typed flow, and the agent checks it when it is built.
+
+```ts
+import { falai, GeminiProvider, type FlowSpec } from "@falai/agent";
+
+const f = falai().fields({
+  nome: { type: "string", ask: "Pergunte o nome." },
+});
+
+// A rule someone typed in a chat, stored as a row.
+const concorrente: FlowSpec = {
+  id: "concorrente",
+  name: "Lead falou de concorrente",
+  on: [{ mention: ["o lead cita um concorrente"] }],
+  steps: [{ id: "tag", kind: "do", do: "add_tags", with: { tags: ["concorrente"] } }],
+};
+
+const agent = f.agent({
+  name: "Ana",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  actions: {
+    add_tags: f.action({ parameters: { tags: { type: "array", items: { type: "string" } } }, run: () => ({ ok: true }) }),
+  },
+  idle: { prompt: "Responda pela empresa, sem inventar preços." },
+  flows: [f.fromSpec(concorrente)],
+});
+
+const r = await agent.turn({ sessionId: "demo", message: "a Acme cobra metade disso" });
+console.log(r.started.map((s) => s.flowId)); // [ 'concorrente' ]
+```
+
+The customer mentions a competitor. The understand call detects it, the `do` step tags the customer beside the conversation, and the idle speaker answers. The row is the flow: nothing here behaves differently from a flow written in code.
+
+## The JSON form
+
+A `FlowSpec` is a `Flow` with two differences: every step is flat and carries a `kind`, and every predicate is in its JSON form (`ConditionSpec`). There are no functions anywhere, so it survives `JSON.stringify`, a database column and a model's output.
+
+```ts fragment
+interface FlowSpec {
+  id: string;
+  name: string;
+  description?: string;
+  on?: TriggerSpec[];          // Trigger with `if` as a ConditionSpec
+  anchor?: string;
+  while?: ConditionSpec;
+  clearOnStart?: string[];
+  steps: StepSpec[];           // flat, each with `kind`
+  onEnd?: "end" | "stay" | "reset";
+  instructions?: InstructionSpec[];  // Instruction with `if` as a ConditionSpec
+  tools?: string[];
+}
+
+type StepKind = "prompt" | "collect" | "say" | "do" | "wait" | "waitEvent" | "if";
+```
+
+How each step maps, from `src/core/FlowSpec.ts`:
+
+| In code | `kind` | Rule |
+|---|---|---|
+| `{ prompt }` | `prompt` | a guideline alone |
+| `{ collect, prompt? }` | `collect` | whenever there is a `collect` list, with or without a prompt beside it |
+| `{ say, media?, once? }` | `say` | |
+| `{ do, with?, onFail? }` | `do` | |
+| `{ wait: "2d", else?, branches?, businessHours? }` | `wait` | `wait` is a duration string |
+| `{ wait: { event, upTo? }, else? }` | `waitEvent` | `wait` is an object |
+| `{ if, else? }` | `if` | `if` must be a `ConditionSpec` |
+
+Everything else on a step (`id`, `label`, `then`, `ui`, `ask`, `maxAsks`, `branches`, `tools`, `instructions`) keeps its name. A `ConditionSpec` is an object where every key must hold: `equals` (fields equal these values), `known` (these fields are known), `silenced` (the host gate is closed), and any other key names one of the agent's conditions with its argument. See [conditions](./conditions.md).
+
+## `fromSpec` and `toSpec`
+
+`fromSpec(spec)` drops the `kind` from each step and returns a `Flow`. It treats `null` as "not set" for every optional value, because the generation schema below says null where the type says optional. The types it returns are a promise, not a proof: the field slugs and the action names inside came out of storage as plain strings, and `validateFlow` is what checks them. Use `f.fromSpec` from a bound toolkit so `C` and `D` are filled in.
+
+`toSpec(flow)` goes the other way and never writes `null`, so `toSpec(fromSpec(spec))` is `spec` with its nulls dropped. It throws `FlowConfigurationError` when the flow carries a function predicate, because a function cannot be stored:
+
+```ts
+import { falai, FlowConfigurationError, toSpec } from "@falai/agent";
+
+const f = falai().fields({
+  nome: { type: "string", ask: "Pergunte o nome." },
+  confirmado: { type: "boolean", ask: "Pergunte se está tudo certo." },
+});
+
+const ok = f.flow({
+  id: "triagem",
+  name: "Triagem",
+  on: [{ message: ["quer um orçamento"] }],
+  steps: [
+    { id: "quem", prompt: "Descubra quem é.", collect: ["nome"] },
+    { id: "confirma", collect: ["confirmado"] },
+    { id: "gate", if: { equals: { confirmado: true } }, else: { step: "quem", clear: ["confirmado"] } },
+  ],
+});
+console.log(JSON.stringify(toSpec(ok).steps[0])); // {"id":"quem","kind":"collect","collect":["nome"],"prompt":"Descubra quem é."}
+
+const notStorable = f.flow({
+  id: "vip",
+  name: "VIP",
+  on: [{ message: ["quer atendimento vip"], if: ({ data }) => data.nome === "Ana" }],
+  steps: [{ id: "p", prompt: "Dê boas-vindas." }],
+});
+try {
+  toSpec(notStorable);
+} catch (error) {
+  if (error instanceof FlowConfigurationError) console.log(error.message);
+  // [FlowConfigurationError] flow "vip", trigger #1 if: is a function, which cannot be stored as JSON. Write it as a condition …
+}
+```
+
+## `validateFlow(spec, registries)`
+
+`Registries` is the part of the agent's options a flow's names resolve against: `fields`, `actions`, `events`, `conditions`, `tools`. Run it when a row is saved, so the person who typed the rule sees the problem, not the customer. The agent runs it again on every flow at construction.
+
+```ts
+import { falai, FlowConfigurationError, validateFlow, type FlowSpec, type Registries } from "@falai/agent";
+
+const f = falai().fields({
+  nome: { type: "string", ask: "Pergunte o nome." },
+});
+
+const registries: Registries = {
+  fields: f.fields,
+  actions: {
+    notify: f.action({ parameters: { recipient: { type: "string" }, message: { type: "string" } }, run: () => ({ ok: true }) }),
+  },
+};
+
+const spec: FlowSpec = {
+  id: "avisa",
+  name: "Avisa o dono",
+  on: [{ message: ["quer falar com uma pessoa"] }],
+  steps: [
+    { id: "quem", kind: "collect", collect: ["nome"] },
+    { id: "n", kind: "do", do: "notify", with: { recipient: "owner", message: "{{data.nome}} quer falar com alguém" } },
+  ],
+};
+
+console.log(validateFlow(spec, registries).warnings); // []
+
+try {
+  validateFlow({ ...spec, steps: [{ id: "x", kind: "do", do: "send_email", with: {} }] }, registries);
+} catch (error) {
+  if (error instanceof FlowConfigurationError) console.log(error.message);
+  // [FlowConfigurationError] flow "avisa", step "x": unknown action "send_email". Register it in actions or fix the name.
+}
+```
+
+It throws `FlowConfigurationError` on the first problem that would break at runtime:
+
+- no flow id, no `steps` list, triggers with no steps
+- a step with no id, the reserved id `"end"`, or a duplicate id
+- an unknown field in `collect`, `ask`, `clearOnStart`, a `clear` list or an `equals`
+- an `equals` value of the wrong type for its field (values are not coerced)
+- an unknown action, or a `with` that misses a required parameter, gives one the wrong type, or names one the action does not have
+- an unknown event in a trigger or a `wait`
+- an unknown condition in any `if` or `while`; a malformed `equals`, `known` or `silenced`
+- an unknown tool in `tools`
+- a duration that does not parse, in `wait`, `upTo`, `silence`, `after` or `repeat.cooldown`
+- a `then`, `else`, `onFail` or branch pointing at a step that does not exist
+- a branch with neither `when` nor `if`
+- an `if` step that jumps backward with no `else`
+
+And it returns warnings for what runs but probably not as intended:
+
+- a `then`, `else` or branch that jumps back to an earlier step without `clear`: the fields collected since stay known and those steps skip
+- a `collect` step with no `prompt` and no `ask` on any of its fields: the model has nothing to go on
+
+## Letting a model write a flow
+
+`flowSpecSchema(registries)` is the JSON schema of a `FlowSpec` for this agent: field slugs, action names with their parameter schemas, event names and condition names are enums. Every object is closed and every property required, with `null` standing for "not set", so Gemini and OpenAI strict mode both accept it as a response schema. Steps are an `anyOf` discriminated by `kind`, one `do` variant per action.
+
+Use it as the response schema of your own generation call, then validate. The schema shapes the answer; `validateFlow` proves it.
+
+```ts
+import { falai, flowSpecSchema, GeminiProvider, validateFlow, type FlowSpec, type Registries, type StructuredSchema } from "@falai/agent";
+
+const f = falai().fields({
+  nome: { type: "string", ask: "Pergunte o nome." },
+});
+
+const registries: Registries = {
+  fields: f.fields,
+  actions: {
+    notify: f.action({ parameters: { recipient: { type: "string" }, message: { type: "string" } }, run: () => ({ ok: true }) }),
+    add_tags: f.action({ parameters: { tags: { type: "array", items: { type: "string" } } }, run: () => ({ ok: true }) }),
+  },
+};
+
+// Your call to a model, with any SDK. The schema is plain JSON Schema.
+declare function generateJson<T>(prompt: string, schema: StructuredSchema): Promise<T>;
+
+const spec = await generateJson<FlowSpec>(
+  "Write a flow, as JSON, for this request: 'quando o lead pedir para falar com uma pessoa, avise o dono e marque a tag humano'. Write the texts in Brazilian Portuguese.",
+  flowSpecSchema(registries),
+);
+
+const { warnings } = validateFlow(spec, registries); // throws FlowConfigurationError when the model wrote something the agent cannot run
+console.log(spec.id, warnings);
+
+const provider = new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" });
+const agent = f.agent({ name: "Ana", provider, ...registries, flows: [f.fromSpec(spec)] });
+console.log(agent.options.flows?.length); // 1
+```
+
+The agent's own provider serves as the generator too: `provider.generateMessage<undefined, FlowSpec>({ prompt, history: [], context: undefined, parameters: { jsonSchema: flowSpecSchema(registries), schemaName: "flow" } })` and read `.structured`, as `examples/09-flows-from-json.ts` does.
+
+Left out of the schema on purpose, because a model should not write them: `ui`, `tools`, step-level `instructions` and `ask`, a mention trigger's `extract`, and the `input` of `{ flow }`. A variant with an empty registry is left out too: with no actions there is no `do` step, with no events no `event` trigger and no `waitEvent`. Condition arguments are typed loosely (string, number, boolean or list of strings) because conditions carry no argument schema.
+
+## Rows into the agent
+
+The agent is immutable: `f.agent({ flows })` reads the flows once. Load the rows, `f.fromSpec` each one, build the agent, and serve every session with that one instance. When a row changes, build a new agent. A row that no longer validates fails the build with the message above, which is the moment to show it in the editor rather than at the customer's next message.
+
+A run in a stored session that points at a flow you removed does not crash: it ends with `code: 'flow-gone'`. See [outcomes](../reference/outcomes.md).
+
+See [the flow spec reference](../reference/flow-spec.md) for every type, and [triggers](./triggers.md) for what a `mention` with `extract` can do.

package/docs/guides/instructions.md

@@ -1,219 +1,183 @@
 ---
 title: "Instructions"
-description: "Shape how the agent talks with must / never / should at agent, flow, and step scope, and read back exactly which ones fired."
+description: "Rules the model follows while it speaks: must, never and should, at agent, flow or step scope, switched on by the model or by code."
 type: guide
-order: 4
+order: 6
 ---
 
 # Instructions
 
-Use `Instruction` when the agent should always confirm dates, never quote prices it has not looked up, or — only inside the booking flow — try to compare two options before committing. One primitive covers all three. Severity comes from `kind`. Reach comes from where you declare the instruction. The framework reports back which instructions actually rendered on each turn, so the behavior surface is observable, not guessed.
+An instruction is one sentence the model reads before it writes a reply. You put it on the agent, on a flow or on a step, and it applies while that scope is speaking.
 
-This guide assumes a `createAgent` scaffold. If you need one, start from [Your first agent](../start/02-first-agent.md).
+```ts
+import { falai, GeminiProvider } from "@falai/agent";
 
-## Instruction shape
+const f = falai().fields({});
 
-An `Instruction` is a plain object with one required field — `prompt` — and a handful of optional ones. The full contract lives in the [Instruction reference](../reference/instruction.md); the working subset for this guide is:
+const agent = f.agent({
+  name: "Bia",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  instructions: [{ kind: "never", prompt: "Nunca invente preços ou prazos." }],
+  idle: { prompt: "Responda pela Loja Azul." },
+});
+
+const r = await agent.turn({ sessionId: "demo", message: "quanto custa o plano pro?" });
+console.log(r.messages[0]?.text);
+```
 
-```typescript
-import type { Instruction } from "@falai/agent";
+The rule reaches every reply the agent phrases. Here no flow is running, so the reply comes from `idle` — the speaker that answers when nothing holds the floor. It costs no extra model call: it is text inside the speak call the turn already makes.
 
-const ins: Instruction = {
-  kind: "must",                                     // 'must' | 'never' | 'should' (default 'should')
-  when: "User asks about pricing",                  // optional AI-evaluated activation
-  if: (ctx) => ctx.context.tier === "pro",          // optional code-evaluated activation
-  prompt: "Quote only rates fetched from the live API this turn.",
-};
+## The shape
+
+`Instruction` is defined in `src/types/flow.ts`:
+
+```ts fragment
+interface Instruction<C, D> {
+  id?: string;
+  kind?: "must" | "never" | "should";   // default "should"
+  when?: string | string[];             // judged by the model, inside the speak call
+  if?: Pred<C, D>;                      // judged by code, before the call
+  prompt: Template;                     // the rule; {{data.x}}, {{context.x}} and {{input.x}} are filled in
+}
 ```
 
-`prompt` is the behavioral text. `kind` declares severity. `when` and `if` gate the instruction by activation, with `if` running first and `when` only evaluated if `if` passes. Everything else (`id`, `enabled`, `tags`, `metadata`) is bookkeeping you can ignore until you need it.
+| Field | What it does |
+|---|---|
+| `kind` | `must` is always done, `never` is a prohibition, `should` is a nudge. Default `should`. |
+| `when` | A condition in words. The model decides whether it holds, from the conversation. One string or a list; any one of the list is enough. |
+| `if` | A code predicate: a function of `PredCtx`, or its JSON form (`{ equals }`, `{ known }`, `{ silenced }`, or a named condition). Free. |
+| `prompt` | The rule itself. Templates render against the collected data, the host context and the run's input. |
+| `id` | Yours. The framework carries it and never reads it. |
 
-## The three `kind` values
+An instruction with neither `when` nor `if` always applies.
 
-`kind` answers *how strict is this?* Three values, no inheritance, no ordering:
+## Three scopes and the idle speaker
 
-| `kind` | Use it for | Example |
-|--------|------------|---------|
-| `must` | Absolute do. The agent is required to follow it whenever rendered. | `"Validate dates are in the future before booking."` |
-| `never` | Absolute don't. The agent is forbidden from doing it. | `"Promise rates you have not looked up."` |
-| `should` | Conditional nudge. Default kind. The agent should try, but it's not a hard line. | `"Offer to compare two options before committing."` |
+| Where | Applies while |
+|---|---|
+| `agent.instructions` | any talk step speaks, and the idle speaker answers |
+| `flow.instructions` | a talk step of that flow speaks |
+| `step.instructions` | that talk step speaks |
+| `idle.instructions` | the idle speaker answers (no run holds the floor) |
 
-Default is `should`. Reach for `must` or `never` only when the behavior is non-negotiable — they are louder in the prompt and less forgiving in tone. If three flows each need the same `must`, declare it once at the agent scope; if it only matters for one flow, declare it there.
+The speak call gets them in this order: agent, then flow, then step. For the idle speaker: agent, then idle. Only talk steps (`prompt` / `collect`) and the idle speaker phrase text, so only they carry instructions; a `say` step goes out verbatim and a `do` step never speaks.
 
-## Agent vs flow vs step scope
+```ts
+import { falai, GeminiProvider } from "@falai/agent";
 
-The same shape attaches at three positions:
+interface Ctx {
+  plano: "gratis" | "pro";
+  horaLocal: number;
+}
+
+const f = falai<Ctx>().fields({
+  duvida: { type: "string", ask: "Pergunte qual é a dúvida, em uma frase." },
+});
 
-```typescript
-createAgent({
-  instructions: [/* agent scope — every turn, every flow */],
+const agent = f.agent({
+  name: "Bia",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  instructions: [
+    { kind: "never", prompt: "Nunca invente preços ou prazos." },
+    { kind: "must", when: "a pessoa está irritada", prompt: "Reconheça o problema antes de explicar qualquer coisa." },
+    { kind: "should", if: ({ context }) => context.horaLocal >= 18 || context.horaLocal < 9, prompt: "Avise que o suporte humano volta às 9h." },
+  ],
   flows: [
-    {
-      title: "Booking",
-      instructions: [/* flow scope — only when 'Booking' is active */],
+    f.flow({
+      id: "duvidas",
+      name: "Dúvidas",
+      on: [{ message: [] }],
+      instructions: [{ kind: "should", prompt: "Responda em até três frases." }],
       steps: [
+        { id: "qual", collect: ["duvida"] },
         {
-          id: "payment",
-          instructions: [/* step scope — only when 'payment' is the current step */],
+          id: "resposta",
+          prompt: "Responda a dúvida.",
+          instructions: [{ kind: "must", prompt: "Termine perguntando se ficou claro." }],
         },
       ],
-    },
+    }),
   ],
 });
-```
-
-Reach narrows as you nest. Agent-scope instructions render on every turn for every flow. Flow-scope instructions render only while that flow is active. Step-scope instructions render only while that step is current. Conditions apply on top: `if` removes an instruction locally when its predicate fails, while `when` is rendered with the instruction so the model can decide whether the natural-language condition applies.
-
-The composer renders the resolved set under a single `## Instructions` heading and tags each line with a scope caption so the model can read both *what* and *where from* in one pass:
-
-| Scope | Caption | When it appears |
-|-------|---------|-----------------|
-| Agent | `[Always]` | Every turn. |
-| Flow | `[In: <FlowTitle>]` | While the named flow is active. |
-| Step | `[Step: <stepId>]` | While the named step is current. |
-
-## Rendering format
-
-Each eligible instruction lands in the prompt as a single bullet:
-
-```
-- [<kind>] [<scope>] <prompt> (apply only when: <when-clause> OR <when-clause>; do not apply when: <exclusion-clause>)
-```
-
-The condition suffix is omitted when `when` is not set. A composed block looks like this:
-
-```
-## Instructions
 
-- [must] [Always] Validate dates are in the future before booking.
-- [never] [Always] Promise rates you have not looked up.
-- [should] [In: Booking] Offer to compare two options before committing. (apply only when: the user is comparing hotel options)
-- [must] [Step: payment] If the card is declined, never retry without confirmation.
+const r = await agent.turn({ sessionId: "demo", context: { plano: "gratis", horaLocal: 21 }, message: "quanto custa?" });
+console.log(r.messages[0]?.text);
 ```
 
-The format is fixed. The kind prefix is always present (defaulting to `[should]`), the scope caption is always present, and the prompt text follows verbatim. When present, non-`!` `when` clauses are joined with `OR`; `!`-prefixed clauses are stripped and appended as `do not apply when` exclusions for the model to evaluate.
+On this turn the step `qual` speaks. Its prompt carries all three agent rules: the `never`, the `must` with its `when` appended for the model to judge, and the `should`, because it is 21h. The flow's three-sentence rule goes in beside them. The `resposta` step's rule waits for its own step.
 
-## `appliedInstructions` on the response
+## `if` runs first, in code
 
-Every `respond()` call returns an `appliedInstructions` array listing exactly which instructions were rendered into that turn's prompt. The set is deterministic — it comes from the prompt composer, not the model — so you can use it for observability, audits, and tests. For an instruction with `when`, inclusion means the conditional instruction reached the model; it does not claim that the model judged the condition true:
+Before the speak call, the framework drops every instruction whose `if` is false. This happens in code, with no model call. The predicate sees a `PredCtx`:
 
-```typescript
-const response = await agent.respond({
-  history: [{ role: "user", content: "I want to book a room." }],
-});
-
-for (const a of response.appliedInstructions ?? []) {
-  console.log(`${a.scope}${a.scopeRef ? `:${a.scopeRef}` : ""} → ${a.id}`);
+```ts fragment
+interface PredCtx<C, D, P> {
+  context: C;          // the host context passed to turn()
+  data: Partial<D>;    // the collected data so far
+  input: P;            // the speaking run's input; undefined for the idle speaker
+  run?: Run;           // the speaking run; absent for the idle speaker
+  silenced?: string;   // the host's reason the assistant cannot speak, when it cannot
+  now: Date;
 }
-// global → ins_validate_dates
-// global → ins_no_unquoted_prices
-// flow:Booking → ins_offer_two_options
 ```
 
-Each `AppliedInstruction` carries the firing instruction's `id`, the originating `scope`, and a `scopeRef` that is the `flowTitle` for flow scope, the `stepId` for step scope, and `undefined` for agent scope. If you want stable ids in the report, set `id` on the instructions you care about — otherwise the framework auto-generates them.
+The JSON form works too, and it is the only form a flow stored as JSON can carry (see [flows from JSON](./flows-from-json.md)):
 
-The same array lands on the final chunk of `respondStream`:
+```ts
+import { falai, GeminiProvider } from "@falai/agent";
 
-```typescript
-for await (const chunk of agent.respondStream({
-  history: [{ role: "user", content: "I want to book a room." }],
-})) {
-  if (chunk.done) {
-    console.log("rendered:", chunk.appliedInstructions);
-  }
+interface Ctx {
+  lead: { tags: string[] };
 }
-```
-
-`appliedInstructions` is empty on intermediate chunks and populated only when `done: true`.
-
-## Recipe: agent-level absolutes
-
-Two house rules every flow must respect:
 
-```typescript
-const agent = createAgent({
-  name: "BookingBot",
-  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
-  instructions: [
-    { id: "ins_validate_dates", kind: "must",  prompt: "Validate dates are in the future before booking." },
-    { id: "ins_no_unquoted",    kind: "never", prompt: "Promise rates you have not looked up." },
-  ],
-  flows: [/* ... */],
+const f = falai<Ctx>().fields({
+  nome: { type: "string", ask: "Pergunte o nome." },
 });
-```
-
-These render with caption `[Always]` on every turn, regardless of which flow is active.
-
-## Recipe: flow-level conditional
-
-A flow-scope nudge that only fires when the user is comparison shopping:
 
-```typescript
-const booking = {
-  title: "Booking",
+const agent = f.agent({
+  name: "Ana",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  conditions: {
+    tagsAny: f.condition((ctx, tags: string[]) => tags.some((t) => ctx.context.lead.tags.includes(t))),
+  },
   instructions: [
-    {
-      id: "ins_offer_two_options",
-      kind: "should",
-      when: "User is comparing options or asking which is better",
-      prompt: "Offer to compare two options side by side before recommending one.",
-    },
+    { kind: "should", if: { tagsAny: ["vip"] }, prompt: "Ofereça falar com o gerente." },
+    { kind: "should", if: { known: ["nome"] }, prompt: "Chame a pessoa pelo nome." },
   ],
-  steps: [/* ... */],
-};
-```
-
-While `Booking` is active, the line renders with caption `[In: Booking]` only on turns where the AI condition resolves true. On other turns the entry stays out of the prompt and out of `appliedInstructions`.
-
-## Recipe: step-level reminder
-
-A `must` that scopes to a specific step, gated by a code condition:
+  idle: { prompt: "Responda pela empresa." },
+});
 
-```typescript
-const paymentStep = {
-  id: "payment",
-  prompt: "Take payment.",
-  instructions: [
-    {
-      id: "ins_no_retry_on_decline",
-      kind: "must",
-      if: (ctx) => ctx.data.lastChargeStatus === "declined",
-      prompt: "If the card is declined, never retry without explicit user confirmation.",
-    },
-  ],
-};
+const r = await agent.turn({ sessionId: "demo", context: { lead: { tags: ["vip"] } }, message: "oi" });
+console.log(r.llmCalls); // 1
 ```
 
-Renders with caption `[Step: payment]` only while `payment` is the current step *and* the most recent charge was declined. Move off the step or change `lastChargeStatus`, and it drops out cleanly.
+A named condition the agent does not register fails with a `FlowConfigurationError`. On a flow or a step it fails when you build the agent. On the agent itself it fails on the first turn that phrases a reply.
 
-## Recipe: reading `appliedInstructions` in a test
+Use `if` for anything the code already knows: the plan, the hour, a tag, a field being known. Use `when` only for what needs the conversation to judge: tone, intent, a topic. One form never fires here: `{ silenced: true }` is always false on an instruction, because a silenced turn phrases nothing and reads no instruction at all. Put it on a trigger, an `if` step or a branch instead — those still run while the gate is closed.
 
-Because the set is deterministic, you can assert against it directly:
+## `when` goes to the model as text
 
-```typescript
-import { test, expect } from "bun:test";
+An instruction that survives `if` is rendered into one section of the speak prompt:
 
-// Seed the condition state at construction — `initialData` pre-populates
-// session.data before the first turn.
-const agent = createAgent({
-  /* ...same scaffold, with the payment step configured as above... */
-  initialData: { lastChargeStatus: "declined" },
-});
+```text
+## Instructions
+- [never] [Always] Nunca invente preços ou prazos.
+- [must] [Always] Reconheça o problema antes de explicar qualquer coisa. (apply only when: a pessoa está irritada)
+- [should] [Always] Avise que o suporte humano volta às 9h.
+- [should] [Always] Responda em até três frases.
+```
 
-test("payment step renders the no-retry rule when the card was declined", async () => {
-  const response = await agent.respond({
-    history: [{ role: "user", content: "Try again." }],
-  });
+One line per instruction: the kind in brackets, the rule, and `when` appended as `(apply only when: …)`. A list of `when` strings is joined with ` OR `. Templates are filled in before rendering; an instruction whose prompt renders to nothing is left out.
 
-  const ids = response.appliedInstructions?.map(a => a.id) ?? [];
-  expect(ids).toContain("ins_no_retry_on_decline");
-});
-```
+Two consequences:
 
-No fixtures, no LLM mocks — the rendered set is computable from configuration and condition state.
+- Instructions reach the speak call only. The understand call (routing, mentions, extraction) never sees them. A turn that phrases nothing, because it is silenced or because a `say` step already answered, renders none of them and spends nothing on them.
+- The framework does not report which `when` clauses the model judged true. If you need to see what reached the prompt, drive the agent with a scripted provider and read the prompt it received (see [testing](./testing.md)).
 
-## Where this fits
+## Where instructions are not the tool
 
-`Instruction` shapes how the agent *talks*. To shape what it *does* — redirect, complete, abort — return a [Directive](../reference/directive.md) from a tool or hook (covered in [Flow control](./flow-control.md)). The two surfaces compose: an instruction nudges the model to confirm dates, a tool's directive completes the flow once the booking is written.
+- A fixed sentence that must go out word for word is a `say` step, not a `must`.
+- A decision the code can make is an `if` step or a branch, not a `should`. Movement belongs to the flow; see [flow control](./flow-control.md).
+- Who the agent is and what it wants live in `persona` and `goal` on the agent; facts it should know live in `knowledgeBase`. Instructions are for how it behaves in a situation.
 
-**Next:** [Persistence](./persistence.md)
+See [the instruction reference](../reference/instruction.md) for the type as exported, and [conditions](./conditions.md) for `when` versus `if` across triggers, branches and steps.