@falai/agent 1.2.8 → 2.0.1

package/docs/start/04-add-tools.md

@@ -0,0 +1,276 @@
+---
+title: "Add tools"
+description: "Extend the booking agent with tools that book the room, gate eligibility, and redirect on failure."
+type: tutorial
+order: 4
+---
+
+# Add tools
+
+So far the agent talks. Now it acts. You will add a tool that books a hotel room and a tool that checks whether the user is allowed to book at all. Along the way you will see how `ctx.dispatch` and `ToolResult.directive` both land on the same directive bus, and why most tools only need an `id` and a `handler` to start.
+
+So far the agent only collects fields. This page adds two tools:
+
+- `book_hotel` — runs once the required fields are in, returns a
+  booking id, and (optionally) finishes the flow with a directive.
+- `check_eligibility` — runs early and redirects to a denial flow
+  when the caller is not allowed. You'll see both forms of
+  redirection: imperative (`ctx.dispatch`) and declarative
+  (`ToolResult.directive`).
+
+You'll also meet the optional metadata fields — `isReadOnly`,
+`validateInput`, `checkPermissions` — that let tools opt into safer
+defaults when you need them.
+
+> Tool surface used here is the canonical [Tool reference](../reference/tool.md).
+> `Tool.id` is the sole identifier — there's no separate `name`.
+
+## Recap: where we left off
+
+`docs/start/03-collect-data.md` left us with a `Book Hotel` flow that
+collects `destination`, `checkIn`, and `guests`, and a `confirm` step
+that waits until all three are populated. We'll hand the `confirm`
+step a tool that actually books the room, plus an eligibility check
+to gate it.
+
+```typescript
+interface BookingData {
+  destination: string;
+  checkIn: string;
+  guests: number;
+  bookingId?: string;
+}
+```
+
+## 1. Add `book_hotel`
+
+A tool is an object with an `id`, an optional `description` and
+`parameters` schema, and a `handler` that returns the result the AI
+will see. The handler receives a `ToolContext` (`ctx`) — the read
+surface over `data`, `context`, and the session.
+
+```typescript
+import type { Tool } from "@falai/agent";
+
+const bookHotel: Tool<unknown, BookingData, { bookingId: string }> = {
+  id: "book_hotel",
+  description: "Reserve the hotel for the collected destination, dates, and guest count.",
+  parameters: {
+    type: "object",
+    properties: {
+      destination: { type: "string" },
+      checkIn:     { type: "string" },
+      guests:      { type: "number" },
+    },
+    required: ["destination", "checkIn", "guests"],
+  },
+  async handler(ctx, args) {
+    const bookingId = await reserve(args);
+    return {
+      data: { bookingId },
+      dataUpdate: { bookingId },
+    };
+  },
+};
+```
+
+The handler returns a `ToolResult`:
+
+- `data` is what the AI sees as the tool result (used to compose the
+  next assistant message).
+- `dataUpdate` is shallow-merged into `session.data`, so the booking
+  id sticks for the rest of the conversation.
+
+Wire the tool to the `confirm` step:
+
+```typescript
+{
+  id: "confirm",
+  prompt: "Confirm the trip and call book_hotel.",
+  requires: ["destination", "checkIn", "guests"],
+  tools: [bookHotel],
+}
+```
+
+The AI now has the tool available on `confirm`. Once the three
+fields are set, it can call `book_hotel`, get the id back, and
+confirm the booking in the reply.
+
+### Optional: finish the flow declaratively
+
+If you want the tool itself to close the flow — instead of relying
+on the next turn to notice `requiredFields` are satisfied — return a
+`directive` alongside the data:
+
+```typescript
+async handler(ctx, args) {
+  const bookingId = await reserve(args);
+  return {
+    data: { bookingId },
+    directive: {
+      complete: { reason: "reservation confirmed" },
+      dataUpdate: { bookingId },
+    },
+  };
+}
+```
+
+`ToolResult.directive` is the **declarative** form of redirection: a
+directive returned with the result. Whatever you can say with
+`ctx.dispatch` mid-handler, you can say with `directive` on return.
+They merge identically. See [Directives](../concepts/directives.md)
+for the full shape.
+
+## 2. Add `check_eligibility` — imperative form
+
+Some destinations are off-limits for some users. We want a tool that
+runs before the AI starts pitching options, decides whether the
+caller can proceed, and — when not — bails out into a denial flow.
+
+The imperative form uses `ctx.dispatch` to emit a directive
+mid-handler:
+
+```typescript
+const checkEligibilityImperative: Tool<{ userId: string }, BookingData, { ok: boolean }> = {
+  id: "check_eligibility",
+  description: "Verify the caller is allowed to book this destination.",
+  isReadOnly: () => true,
+  async handler(ctx) {
+    const ok = await isEligible(ctx.context.userId, ctx.data.destination);
+
+    if (!ok) {
+      // Stop reasoning down this path — jump to the denial flow.
+      ctx.dispatch({
+        goTo: "Denial",
+        reply: "Sorry — you're not eligible to book that destination.",
+      });
+      return { ok: false };
+    }
+
+    return { ok: true };
+  },
+};
+```
+
+What just happened:
+
+- `ctx.dispatch(directive)` puts the directive on this turn's
+  directive bus. Algorithm 4 picks it up alongside any other
+  emissions.
+- `goTo: "Denial"` redirects to a sibling flow named `"Denial"`.
+- `reply` is the verbatim assistant utterance — the LLM call this
+  turn is skipped and the literal string is what the user sees.
+- The handler still returns `{ ok: false }` so the trace is honest
+  about what the tool did.
+
+For the redirect to work, the agent needs a `Denial` flow. It can
+be as small as:
+
+```typescript
+{
+  title: "Denial",
+  steps: [{ id: "explain",
+            prompt: "Explain why the booking is not possible and offer help." }],
+},
+```
+
+Wire the eligibility check on the `confirm` step (or earlier — your
+call):
+
+```typescript
+{
+  id: "confirm",
+  prompt: "Confirm the trip and call book_hotel.",
+  requires: ["destination", "checkIn", "guests"],
+  tools: [checkEligibilityImperative, bookHotel],
+}
+```
+
+## 3. Same tool — declarative form
+
+Many handlers don't need to dispatch mid-flight. They can compute
+the answer, build the directive, and return it on the result.
+`ToolResult.directive` is identical in effect to `ctx.dispatch` —
+same merge, same precedence, same shape.
+
+```typescript
+const checkEligibilityDeclarative: Tool<{ userId: string }, BookingData, { ok: boolean }> = {
+  id: "check_eligibility",
+  description: "Verify the caller is allowed to book this destination.",
+  isReadOnly: () => true,
+  async handler(ctx) {
+    const ok = await isEligible(ctx.context.userId, ctx.data.destination);
+
+    if (!ok) {
+      return {
+        data: { ok: false },
+        directive: {
+          goTo: "Denial",
+          reply: "Sorry — you're not eligible to book that destination.",
+        },
+      };
+    }
+
+    return { data: { ok: true } };
+  },
+};
+```
+
+When to reach for which:
+
+- **Imperative** — you need to dispatch before the handler is done
+  (e.g. an early branch decides the rest of the work is moot but
+  the result payload still has to be computed for the trace).
+- **Declarative** — single return point, directive next to the data
+  it goes with. Easier to read; preferred when there's no reason to
+  split.
+
+Both forms can co-exist. Multiple `dispatch` calls plus a `directive`
+on the return value all land on the same bus and merge identically
+(see [Directives](../concepts/directives.md)).
+
+## 4. Optional metadata, briefly
+
+Every metadata field on `Tool` is optional. Reach for them only when
+you want the safer default they buy you.
+
+```typescript
+isReadOnly: () => true;                                                 // safe to cache and parallelize
+validateInput: (input) => ({ valid: typeof input.guests === "number" }); // repair or reject bad args
+checkPermissions: (_, ctx) => ({ allowed: !!ctx.context.userId });       // gate access; handler skipped on deny
+```
+
+Four more live on the same surface — `isConcurrencySafe`,
+`isDestructive`, `interruptBehavior`, `maxResultSizeChars`. See the
+[Tool reference](../reference/tool.md) for the full list and exact
+contracts.
+
+## 5. Run it
+
+A user message like
+
+> "Book me a room in Lisbon for 2 adults, checking in March 14."
+
+now flows through:
+
+1. **Pre-extraction.** The router pulls `destination: "Lisbon"`,
+   `checkIn: "March 14"`, `guests: 2` out of the message in one shot.
+2. **Step selection.** The `ask` step is satisfied — every `collect`
+   field is set — so the engine skips it and enters `confirm`.
+3. **Eligibility.** The AI calls `check_eligibility`. If allowed,
+   the tool returns `{ ok: true }` and we move on. If not, the
+   dispatched directive jumps to the `Denial` flow and the verbatim
+   `reply` becomes the assistant message — no LLM call this turn.
+4. **Booking.** The AI calls `book_hotel`, gets a `bookingId`, and
+   composes the confirmation reply.
+5. **Completion.** With every required field present (and a
+   `bookingId` in `data`), the flow finishes.
+
+## What's next
+
+You have an agent that collects data, runs tools, gates access, and
+redirects on failure. The remaining concern is shipping it: swapping
+`MemoryAdapter` for `PrismaAdapter`, streaming responses, and
+dropping the agent behind an HTTP endpoint.
+
+**Next:** [Go to production](./05-go-to-production.md)

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

@@ -0,0 +1,216 @@
+---
+title: "Go to production"
+description: "Add durable persistence, streaming responses, and an HTTP endpoint to ship the booking agent."
+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 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.
+
+You will:
+
+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.
+
+By the end you have the same booking agent — same flow, same tools — running behind an HTTP API with persistent state.
+
+## 1. Persist sessions with Prisma
+
+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.
+
+Add Prisma to the project:
+
+```bash
+bun add @prisma/client
+bun add -d prisma
+bunx prisma init
+```
+
+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.
+
+```prisma
+// prisma/schema.prisma
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model AgentSession {
+  id                String    @id
+  userId            String?
+  agentName         String?
+  status            String    @default("active")
+  currentFlow       String?
+  currentStep       String?
+  collectedData     Json?
+  pendingDirective  Json?
+  signals           Json?
+  messageCount      Int       @default(0)
+  lastMessageAt     DateTime?
+  completedAt       DateTime?
+  createdAt         DateTime  @default(now())
+  updatedAt         DateTime  @updatedAt
+}
+
+model AgentMessage {
+  id        String   @id @default(cuid())
+  sessionId String
+  role      String
+  content   String
+  createdAt DateTime @default(now())
+
+  @@index([sessionId, createdAt])
+}
+```
+
+Push the schema and generate the client:
+
+```bash
+bunx prisma db push
+bunx prisma generate
+```
+
+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",
+  },
+});
+```
+
+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.
+
+```typescript
+const session = await agent.session.getOrCreate("user_123:thread_abc");
+
+const response = await agent.respond({
+  history: [{ role: "user", content: "Hi again" }],
+  session,
+});
+```
+
+Unknown ids start fresh against that id; there is no "not found" error path.
+
+For the full schema migration story (renaming `pending_transition` to `pendingDirective`, adding the `signals` column) see [persistence adapters reference](../reference/adapters.md#prismaadapter).
+
+## 2. Stream responses
+
+`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.
+
+```typescript
+const stream = agent.respondStream({
+  history: [{ role: "user", content: "Book me a hotel in Lisbon for two nights." }],
+});
+
+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);
+  }
+}
+```
+
+Two fields land only on the terminal chunk (`done: true`):
+
+- `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.
+
+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.
+
+To cancel mid-stream — say, the user hits Stop — pass an `AbortSignal`:
+
+```typescript
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 5000);
+
+const stream = agent.respondStream({
+  history,
+  signal: controller.signal,
+});
+```
+
+## 3. A session-keyed HTTP endpoint
+
+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.
+
+```typescript
+import { agent } from "./agent";
+
+Bun.serve({
+  port: 3000,
+  async fetch(req) {
+    if (req.method !== "POST" || new URL(req.url).pathname !== "/chat") {
+      return new Response("Not found", { status: 404 });
+    }
+
+    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" } }
+    );
+  },
+});
+```
+
+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 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.
+
+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.
+
+**Next:** [How-to guides](../guides/conditions.md)

package/examples/01-quickstart.ts

@@ -0,0 +1,20 @@
+/** @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";
+
+if (!process.env.GEMINI_API_KEY) throw new Error("Set GEMINI_API_KEY");
+
+const agent = createAgent({
+    name: "Greeter",
+    provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY, model: "gemini-3.1-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 response = await agent.respond({ history: [{ role: "user", content: "Hi, I'm Alice" }] });
+console.log(response.message);

package/examples/02-data-extraction.ts

@@ -0,0 +1,90 @@
+/**
+ * Data extraction — schema, collect, skip, requires, requiredFields; pre-extraction in action.
+ * Run with the message "I want X for Y people on Z" and watch all three fields populate from one turn.
+ * Read after: docs/start/03-collect-data.md
+ */
+
+import { createAgent, GeminiProvider } from "@falai/agent";
+
+// ─── Schema ──────────────────────────────────────────────────────────────────
+
+interface BookingData {
+    roomType: "single" | "double" | "suite";
+    guests: number;
+    checkIn: string;
+}
+
+const schema = {
+    type: "object" as const,
+    properties: {
+        roomType: {
+            type: "string" as const,
+            enum: ["single", "double", "suite"],
+            description: "Type of room requested",
+        },
+        guests: {
+            type: "number" as const,
+            description: "Number of guests",
+        },
+        checkIn: {
+            type: "string" as const,
+            description: "Check-in date in YYYY-MM-DD format",
+        },
+    },
+    required: ["roomType", "guests", "checkIn"],
+};
+
+// ─── Agent ───────────────────────────────────────────────────────────────────
+
+const agent = createAgent<Record<string, never>, BookingData>({
+    name: "Booking Agent",
+    provider: new GeminiProvider({
+        apiKey: process.env.GEMINI_API_KEY!,
+        model: "gemini-3.1-flash-lite",
+    }),
+    schema,
+    flows: [
+        {
+            title: "Book a room",
+            when: "The user wants to book a hotel room",
+            requiredFields: ["roomType", "guests", "checkIn"],
+            steps: [
+                {
+                    id: "ask_room",
+                    prompt: "What type of room would you like? (single, double, or suite)",
+                    collect: ["roomType"],
+                    skip: [({ data }) => data.roomType !== undefined],
+                },
+                {
+                    id: "ask_guests",
+                    prompt: "How many guests will be staying?",
+                    collect: ["guests"],
+                    requires: ["roomType"],
+                    skip: [({ data }) => data.guests !== undefined],
+                },
+                {
+                    id: "ask_checkin",
+                    prompt: "When would you like to check in?",
+                    collect: ["checkIn"],
+                    requires: ["roomType", "guests"],
+                    skip: [({ data }) => data.checkIn !== undefined],
+                },
+            ],
+        },
+    ],
+});
+
+// ─── Run ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+    // Pre-extraction: all three fields are extracted from a single message.
+    const response = await agent.respond({
+        history: [{ role: "user", content: "I want a double for 2 people on 2025-03-15" }],
+    });
+
+    console.log(response.message);
+    console.log("Collected:", response.session?.data);
+    console.log("Complete:", response.isFlowComplete);
+}
+
+main();