@falai/agent 1.2.8 → 2.0.0

package/docs/start/02-first-agent.md

@@ -0,0 +1,196 @@
+---
+title: "Your first agent"
+description: "Build a 16-line agent that responds to a user message, and meet the seven primitives that shape every @falai/agent program."
+type: tutorial
+order: 2
+---
+
+# Your first agent
+
+You are about to write an agent that fits on one screen. One schema, one flow, one step, one turn — and from it the full mental model unfolds. The framework's seven primitives all participate in this single call, even though only three appear as syntax. The page names all seven so the rest of the tutorial can reference them without introduction.
+
+This page builds the smallest agent that does real work — sixteen lines of TypeScript, one `respond` call, one greeting back from the model. The point is not the greeting. The point is to put every primitive of the framework on the page at once, in the smallest possible shape, so the rest of the tutorial extends a scaffold you can already read in full.
+
+By the end of this page you will have a runnable file, an expected output, and a working mental map of the [seven primitives](../concepts/architecture.md). The next page extends this same file into a data-collecting agent.
+
+Keep [Install](./01-install.md) finished and your `GEMINI_API_KEY` ready in `.env` before you continue.
+
+## The whole agent
+
+Drop this into `src/index.ts`:
+
+```typescript
+import { createAgent, GeminiProvider } from "@falai/agent";
+
+const agent = createAgent({
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
+  schema: { type: "object", properties: { name: { type: "string" } } },
+  flows: [{
+    title: "Greet",
+    requiredFields: ["name"],
+    steps: [{ id: "ask_name", prompt: "What's your name?", collect: ["name"] }],
+  }],
+});
+
+const response = await agent.respond("Hi, I'm Alice");
+console.log(response.message);
+```
+
+That is the whole program. No persistence config, no tools, no branches, no signals. Three primitives appear by name (`Agent`, `Flow`, `Step`) and four more sit one decision away (`Tool`, `Instruction`, `Directive`, `PreDirective`). The next sections walk through every line.
+
+## Walk it line by line
+
+### Imports
+
+```typescript
+import { createAgent, GeminiProvider } from "@falai/agent";
+```
+
+`createAgent` is the level-1 factory — sugar over `new Agent(options)` — and the recommended construction path for application code. Its signature and full options surface live in the [`createAgent` reference](../reference/create-agent.md).
+
+`GeminiProvider` is one of four built-in [providers](../reference/providers.md). Swap to `OpenAIProvider`, `AnthropicProvider`, or `OpenRouterProvider` by changing this single import — the agent itself stays vendor-agnostic.
+
+### `createAgent({ ... })`
+
+```typescript
+const agent = createAgent({ /* ... */ });
+```
+
+`createAgent` accepts one options object. Generic inference flows from `schema` through every `flows[].steps[].collect` reference, so the type of `session.data` and tool-handler arguments is derived once and propagates everywhere. Misuse — duplicate flow ids, an unknown key in `collect`, a malformed signal — surfaces as `FlowConfigurationError` synchronously, before any turn runs.
+
+### `provider`
+
+```typescript
+provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
+```
+
+The provider is the strategy plug between the agent and the model vendor. Every provider implements the same `AiProvider` interface, so the agent talks to Gemini today and to a different vendor tomorrow with one line changed. See [Providers](../reference/providers.md) for the full options surface — `model`, `backupModels`, `config`, `retryConfig`.
+
+### `schema`
+
+```typescript
+schema: { type: "object", properties: { name: { type: "string" } } },
+```
+
+The schema is the single source of truth for `TData` — the typed shape of everything the agent collects across the whole conversation. It lives at the agent level, not the flow level. Every `collect` site in every step references keys defined here, and TypeScript verifies the references at compile time.
+
+This shape is why pre-extraction works: when a user message arrives, the engine extracts every collectable field it can in one pass, then skips any step whose `collect` set is already satisfied. The next tutorial page leans on this property hard. For the framing, see [the schema-first principle](../concepts/architecture.md#the-schema-first-principle).
+
+### `flows`
+
+```typescript
+flows: [{
+  title: "Greet",
+  requiredFields: ["name"],
+  steps: [/* ... */],
+}],
+```
+
+A [`Flow`](../reference/flow.md) is one conversational goal — booking a hotel, escalating a complaint, greeting a stranger. The router selects exactly one flow per turn. This agent has only one flow, so the router has nothing to choose between; later tutorials add more.
+
+`title` is the human-readable name (also used in the `Directive.goTo` shorthand). `requiredFields` declares which schema keys must be present in `session.data` before the engine fires the flow's completion path. The greeter's only required field is `name`.
+
+### Step `prompt` and `collect`
+
+```typescript
+steps: [{ id: "ask_name", prompt: "What's your name?", collect: ["name"] }],
+```
+
+A [`Step`](../reference/step.md) is a single node inside a flow. This step has the simplest LLM-step shape: an `id` for routing and logs, a `prompt` that becomes the engine's instruction to the model, and a `collect` set that names the schema fields this step is responsible for extracting from the user message.
+
+When the user writes `"Hi, I'm Alice"`, the engine routes into `Greet`, lands on `ask_name`, runs pre-extraction against the schema, and lifts `name: "Alice"` into `session.data`. The step's `collect` set is now satisfied — and because `name` is the flow's only `requiredField`, the flow is complete on this very turn.
+
+### `requiredFields`
+
+```typescript
+requiredFields: ["name"],
+```
+
+`requiredFields` is the completion gate. The flow is **done** the moment every key in this array is present in `session.data`. Completion is a state transition, not a message — the framework never speaks on its own. Anything the user reads at completion comes from the model's response on the same turn or from a `reply` step on the next turn.
+
+For this agent, completion happens on the first turn. For a longer flow, the gate would force more steps before the model wraps up.
+
+### `agent.respond(message)`
+
+```typescript
+const response = await agent.respond("Hi, I'm Alice");
+console.log(response.message);
+```
+
+`respond(message)` runs one turn end to end: load (or create) the session, route to a flow, extract data, walk auto-step chains, call the LLM, deliver the assistant message, persist. It returns an `AgentResponse` with the fields you usually want on hand:
+
+| Field | Type | What it is |
+|-------|------|------------|
+| `message` | `string` | The assistant's reply for this turn. |
+| `session` | `SessionState<TData>` | The updated session — including `session.data` with the extracted fields. |
+| `isFlowComplete` | `boolean` | `true` once `requiredFields` are all satisfied. |
+| `appliedInstructions` | `AppliedInstruction[]` | Instructions that rendered into this turn's prompt (deterministic, not self-reported). |
+| `triggeredSignals` | `SignalFiring[]` | Any signals that fired this turn. |
+
+`response.message` is the only field this minimal program reads. The rest become useful as the agent grows.
+
+## The seven primitives
+
+Three primitives appear by name in the code above: [`Agent`](../concepts/architecture.md#agent), [`Flow`](../concepts/architecture.md#flow), and [`Step`](../concepts/architecture.md#step). Four more shape every program of any size, and you will meet them in the pages ahead:
+
+- [`Agent`](../concepts/architecture.md#agent) — the top-level handle. Owns the schema, provider, flows, tools, signals, and persistence.
+- [`Flow`](../concepts/architecture.md#flow) — one conversational goal. Owns its steps, scoped tools, instructions, and completion semantics.
+- [`Step`](../concepts/architecture.md#step) — one node inside a flow. Asks a question, collects fields, calls tools, runs hooks, or speaks a verbatim line.
+- [`Tool`](../concepts/architecture.md#tool) — a typed function the AI can call. May redirect the conversation by emitting a directive. Added on page [04](./04-add-tools.md).
+- [`Instruction`](../concepts/architecture.md#instruction) — a `must` / `never` / `should` behavioral statement at agent, flow, or step scope.
+- [`Directive`](../concepts/architecture.md#directive) — a flat object any tool, hook, or branch returns to write state, change position, or speak verbatim.
+- [`PreDirective`](../concepts/architecture.md#predirective) — a `Directive` plus per-turn shaping (`appendPrompt`, `injectTools`, `halt`) returned from `onEnter` and `prepare` hooks.
+
+Read [Architecture](../concepts/architecture.md) end to end when you want the full mental model — what each primitive owns, how they reference each other, and why the set is exactly seven.
+
+## Run it
+
+Make sure `.env` has `GEMINI_API_KEY` set, then run the file:
+
+```bash
+bun run src/index.ts
+```
+
+Or with Node 20+:
+
+```bash
+node --env-file=.env --experimental-strip-types src/index.ts
+```
+
+You should see a single line of greeting prose, something like:
+
+```
+Hi Alice, nice to meet you! How can I help today?
+```
+
+The exact words come from the model — they will not match across runs — but the shape is stable: one assistant message, addressed to Alice by name, written in the tone the model defaults to. If the call fails, double-check that `GEMINI_API_KEY` is exported and that your `.env` is being loaded (Bun loads it automatically; Node needs `--env-file`).
+
+## What just happened
+
+In one turn, the engine:
+
+1. Created a fresh session keyed by an auto-generated id (the default `MemoryAdapter` keeps it in process).
+2. Ran the flow router. With one flow on the agent, `Greet` wins by default.
+3. Pre-extracted `name: "Alice"` from the user message in a single pass against the schema, before any step ran.
+4. Skipped `ask_name` because its `collect` set was already satisfied — the engine never re-asks for data it already has.
+5. Called the LLM once with the active prompt, the typed `session.data`, and the conversation history.
+6. Returned the assistant message with `isFlowComplete: true` because `requiredFields` were already met.
+
+This sequence — pre-extract, then skip-then-execute, then check completion — is the [turn pipeline](../concepts/pipeline.md), and it runs on every `respond` call regardless of flow size.
+
+## When something goes wrong
+
+A few common failure modes and where to look:
+
+- **`Missing API key`** or a 401 from Gemini — `GEMINI_API_KEY` is unset or your `.env` did not load. Bun loads `.env` automatically; Node needs `--env-file=.env`.
+- **`FlowConfigurationError: collect references unknown key 'foo'`** — the schema does not declare `foo` as a property. Add it to `schema.properties` or fix the `collect` array.
+- **`FlowConfigurationError: duplicate flow id` / `duplicate step id`** — two flows or two steps share the same auto-derived id. Set explicit `id` values to disambiguate.
+- **The LLM call hangs** — check the `model` (Gemini's free tier expects `"models/gemini-2.5-pro"` or `"models/gemini-2.5-flash"`) and your network. Provider errors surface as `ResponseGenerationError`.
+
+The full set of typed errors and the `[<ErrorClass>] <what>: <why>. <how to fix>.` format contract live in the [Errors reference](../reference/errors.md).
+
+## Where this leaves you
+
+You have a runnable agent, an expected-shape output, and the names of every primitive that will appear in the rest of the tutorial. The next page swaps the trivial `name` schema for a structured booking schema and three steps that each `collect` one field. The same single message — *"I want a hotel in Lisbon for two people next Friday"* — populates all three fields at once and lands the agent on the confirmation step on the first turn.
+
+**Next:** [Collect data](./03-collect-data.md)

package/docs/start/03-collect-data.md

@@ -0,0 +1,222 @@
+---
+title: "Collect data"
+description: "Use the agent's schema to extract city, dates, and party size from one message — without asking three questions in a row."
+type: tutorial
+order: 3
+---
+
+# Collect data
+
+One schema, three steps, one completion gate. The engine extracts what it can in a single pass, skips steps whose data is already present, and finishes the flow the moment every required field lands. This page shows the pattern end to end — from a user who types everything in one sentence to a user who answers one field at a time.
+
+In [Your first agent](./02-first-agent.md), the agent answered a single message. This page extends that scaffold into something more useful: a hotel-booking agent that lifts structured fields out of a user's message and skips any question it already has the answer to.
+
+You will define a schema, write three steps that each `collect` one field, gate the confirmation step with `requires`, bypass already-answered steps with `skip`, and seal the flow with `requiredFields`. By the end of the page, a single sentence — *"I want a hotel in Lisbon for two people next Friday"* — will populate every field in one turn and land the agent on the confirmation step before the user types again.
+
+Keep the file from the previous tutorial open. Everything here is one continuous edit.
+
+## Define the schema
+
+The schema is the single source of truth for everything the agent collects across the whole conversation. It lives at the agent level, not the flow level, and every `collect` site below references keys defined here.
+
+Add a `BookingData` type and pass a matching `schema` to `createAgent`:
+
+```typescript
+import { createAgent, GeminiProvider } from "@falai/agent";
+
+interface BookingData {
+  city: string;
+  checkIn: string;
+  guests: number;
+}
+
+const agent = createAgent<unknown, BookingData>({
+  name: "BookingBot",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
+  schema: {
+    type: "object",
+    properties: {
+      city: {
+        type: "string",
+        description: "Destination city the user wants to stay in.",
+      },
+      checkIn: {
+        type: "string",
+        description: "Check-in date as ISO yyyy-mm-dd.",
+      },
+      guests: {
+        type: "integer",
+        description: "Number of people staying. Defaults to 1 if not stated.",
+      },
+    },
+  },
+  flows: [/* added in the next section */],
+});
+```
+
+The `description` strings inside `properties` are not decoration. The provider sees them on every turn and uses them to extract fields from the user's message. Spend a sentence on each one — it pays back at extraction time. Especially for ambiguous fields (a date format, an ID prefix, a unit), the description is the only place you can tell the extractor what "valid" looks like.
+
+Two type parameters flow through `createAgent`: `TContext` (ambient data, ignored here) and `TData` (the booking shape). They propagate to every step's `collect` array and every tool handler. Misspell a key in `collect: ["citi"]` and the type checker objects at the call site.
+
+## Collect one field per step
+
+A `Step` declares which schema fields it is responsible for through its `collect` array. The engine reads that array on every turn — if any listed key is already populated in `session.data`, the step is skipped automatically. That is the core of pre-extraction: the engine will not ask a question whose answer it already has.
+
+Add a `Booking` flow with three collection steps:
+
+```typescript
+flows: [
+  {
+    title: "Booking",
+    description: "Book a hotel by collecting destination, date, and party size.",
+    when: "the user wants to book a hotel",
+    requiredFields: ["city", "checkIn", "guests"],
+    steps: [
+      {
+        id: "ask_city",
+        prompt: "Find out which city the user wants to stay in.",
+        collect: ["city"],
+      },
+      {
+        id: "ask_check_in",
+        prompt: "Find out which date the user wants to check in.",
+        collect: ["checkIn"],
+        requires: ["city"],
+      },
+      {
+        id: "ask_guests",
+        prompt: "Find out how many people are travelling.",
+        collect: ["guests"],
+        requires: ["city", "checkIn"],
+        skip: ({ data }) => typeof data.guests === "number",
+      },
+      {
+        id: "confirm",
+        prompt:
+          "Read back the city, check-in date, and guest count. Ask the user to confirm.",
+        requires: ["city", "checkIn", "guests"],
+      },
+    ],
+  },
+],
+```
+
+Three things deserve a closer look.
+
+`collect` is an instruction to the extractor, not a question gate. When the user message contains a city, the extractor populates `city` and the engine moves past `ask_city` whether or not that step ran a prompt. The step exists for the case where the field is still missing on entry — it asks the question that produces the value.
+
+`requires` is the prerequisite gate. The engine refuses to enter a step until every key listed in `requires` is present in `session.data`. Without `requires: ["city"]` on `ask_check_in`, a user who messages "next Friday" first would stall the flow — the engine would extract `checkIn`, see no `city`, and have nothing to do.
+
+`skip` is the bypass. It accepts a code predicate that runs on every turn; when it returns `true`, the step is skipped regardless of whether its `collect` set is satisfied. The example above demonstrates the pattern but is functionally redundant — the `collect: ["guests"]` already covers the same case. Use `skip` when the bypass condition is *not* about a `collect` field — for example, "skip the verification step if the user is already authenticated."
+
+## Gate completion with `requiredFields`
+
+The flow's `requiredFields` is the contract for "this flow is done." When every field listed there is present in `session.data`, the engine fires the flow's completion path on the next turn boundary. Pre-extraction, sequential steps, and one-shot collection all converge on the same gate.
+
+The `confirm` step in the snippet above does not collect anything — it only requires. Its job is to read the booking back to the user before the flow completes. This pattern is common: collection steps populate the schema, a final non-collecting step closes the loop.
+
+```typescript
+{
+  id: "confirm",
+  prompt:
+    "Read back the city, check-in date, and guest count. Ask the user to confirm.",
+  requires: ["city", "checkIn", "guests"],
+},
+```
+
+The flow ends here implicitly. There is no terminus marker, no end-of-flow constant, no return value — the last step in `steps[]` is the implicit terminus. When `requiredFields` is satisfied, the flow completes; if a flow with no `requiredFields` reaches its last step, the same path runs.
+
+A field that the flow can use but does not need belongs in `optionalFields` instead. It is descriptive only — never gates completion, but appears alongside `requiredFields` in re-entry resets if the flow is reentrant. For this tutorial, every field is required, so `optionalFields` stays empty.
+
+## The data fields at a glance
+
+Three field-related properties show up in the snippets above. They look similar but answer different questions:
+
+| Property | Lives on | Question it answers | Cost |
+|----------|----------|---------------------|------|
+| `schema.properties` | Agent | What can be extracted at all? | One extraction call per turn. |
+| `step.collect` | Step | Which fields does this step want this turn? | Free — engine inspects `session.data`. |
+| `step.requires` | Step | Which fields must already be present to enter this step? | Free — engine inspects `session.data`. |
+| `step.skip` | Step | Should this step be bypassed regardless of `collect`? | Free — code predicate. |
+| `flow.requiredFields` | Flow | When is the flow done? | Free — engine inspects `session.data`. |
+
+The pattern is consistent: the schema describes the universe of possible data, every other property describes a slice over that universe. Pre-extraction is what stitches them together — without it, every step would have to ask its question regardless of what the user already said.
+
+## Watch pre-extraction work
+
+Run the file with a single message that contains all three fields:
+
+```typescript
+const session = { id: "demo-session" };
+
+const response = await agent.respond(
+  "I want a hotel in Lisbon for two people next Friday.",
+  session,
+);
+
+console.log(response.message);
+console.log(response.data);
+console.log(response.currentStep?.id);
+```
+
+The output is roughly:
+
+```
+> Just to confirm: a hotel in Lisbon, checking in 2025-11-21, for 2 guests. Shall I book it?
+{ city: "Lisbon", checkIn: "2025-11-21", guests: 2 }
+confirm
+```
+
+Three things happened in one turn:
+
+1. **Pre-extraction ran first.** Before any step prompt or LLM step call, the extractor read the user message against the agent's schema and populated `city`, `checkIn`, and `guests` in `session.data`. The check-in date was normalized to the ISO format the schema described.
+2. **The first three steps skipped.** `ask_city`, `ask_check_in`, and `ask_guests` each have a `collect` array whose every key was already present after extraction. The engine skipped them in order without calling the LLM for any of them.
+3. **The engine landed on `confirm`.** Its `requires` were satisfied, its `collect` was empty, and its prompt asked for confirmation. That is the only LLM step that ran for the turn.
+
+Try a message with one missing field:
+
+```typescript
+await agent.respond("Book me a hotel in Lisbon next Friday.", session);
+```
+
+The extractor populates `city` and `checkIn`. `ask_city` and `ask_check_in` both skip — their `collect` keys are present. `ask_guests` does *not* skip — `guests` is undefined — so the engine enters it and the assistant asks how many people are travelling.
+
+Try the inverse: a message with only one field.
+
+```typescript
+await agent.respond("I'd like to go to Lisbon.", session);
+```
+
+The extractor populates `city` only. `ask_city` skips, `ask_check_in` enters next (its `requires: ["city"]` is satisfied), and the assistant asks for the check-in date. Three turns later, the same `confirm` step runs.
+
+The same flow handles every shape of message — one field at a time, three at once, two-then-one — because `collect`, `requires`, and `skip` describe what the step needs rather than how many turns the conversation will take.
+
+### Routing skip
+
+One detail worth knowing: when pre-extraction populates a field listed in the *current* step's `collect`, the engine treats that as confirmation that the user is answering this step rather than asking for something new. It skips the flow router entirely for that turn and stays in the active flow. The tradeoff is small — if the user both answers the step and signals new intent in the same message, the new intent is recovered on the next turn. In return, a user who is mid-form does not get bounced into a different flow because their answer happened to share a few words with another flow's `when`.
+
+## Why this works
+
+`TData` is agent-level. The schema is declared once and every `collect` site references it; the extractor sees the full schema on every turn and lifts whatever it can in a single pass. Steps then act as filters over `session.data`: a step whose `collect` set is satisfied vanishes from the conversation, and a step whose `requires` set is missing refuses to run.
+
+The split between AI work and code work is visible at every site:
+
+- **Extraction** (AI): given a user message and the schema, populate as many fields as possible.
+- **Skip / require / completion** (code): given the populated `session.data`, decide whether each step runs, whether the flow continues, and whether `requiredFields` is satisfied.
+
+The framework spends one extraction call per turn on the AI side and pure data inspection on the code side. There is no separate "form mode" or "completion check" — the same step shape works whether the user fills the form one field at a time or pastes a full request in a single sentence.
+
+## Recap
+
+You added four things to the agent from the previous tutorial:
+
+- A typed `BookingData` schema, declared at the agent level.
+- Three collection steps, each with its own `collect` array.
+- A `requires` chain to gate the order in which steps may enter.
+- A `requiredFields` list on the flow to define completion.
+
+The pre-extraction property is what makes the rest worthwhile. A user who knows what they want types one sentence; a user who needs guidance types one field at a time; the same flow handles both because every step describes its own contract over `session.data` rather than its position in a conversation.
+
+Two things are missing from the booking flow before it can do anything in the real world. There is no booking action — `confirm` ends with the user agreeing, and nothing happens. There is also no way to redirect when something goes wrong (the user is not eligible, the inventory is empty, the date is in the past). The next page adds tools to handle both.
+
+**Next:** [Add tools](./04-add-tools.md)