@falai/agent 1.2.7 → 2.0.0

package/examples/03-tools.ts

@@ -0,0 +1,136 @@
+/**
+ * Tools — defining tools, imperative dispatch, declarative directives, and metadata.
+ * Teaches: Tool, ctx.dispatch, ToolResult.directive, isReadOnly.
+ * Read next: docs/reference/tool.md
+ */
+
+import {
+    createAgent,
+    GeminiProvider,
+    createSession,
+    type Tool,
+    type ToolResult,
+    type Directive,
+} from "@falai/agent";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+interface AppContext { userId: string }
+
+interface AppData {
+    city: string;
+    checkIn: string;
+    checkOut: string;
+    confirmationId: string;
+}
+
+// ─── Tool 1: Read-only lookup (metadata: isReadOnly) ─────────────────────────
+
+const checkAvailability: Tool<AppContext, AppData> = {
+    id: "check_availability",
+    description: "Check hotel room availability for the given dates.",
+    parameters: {
+        type: "object",
+        properties: {
+            city: { type: "string" },
+            checkIn: { type: "string" },
+            checkOut: { type: "string" },
+        },
+        required: ["city", "checkIn", "checkOut"],
+    },
+    // Metadata: this tool only reads data — safe to run concurrently.
+    isReadOnly: () => true,
+
+    async handler(_ctx, args) {
+        const { city, checkIn, checkOut } = args as Record<string, string>;
+        const available = city !== "atlantis";
+        return { data: { city, checkIn, checkOut, available } };
+    },
+};
+
+// ─── Tool 2: Imperative dispatch (ctx.dispatch) ──────────────────────────────
+
+const bookRoom: Tool<AppContext, AppData> = {
+    id: "book_room",
+    description: "Book a hotel room. Requires availability check first.",
+    parameters: {
+        type: "object",
+        properties: {
+            city: { type: "string" },
+            checkIn: { type: "string" },
+            checkOut: { type: "string" },
+        },
+        required: ["city", "checkIn", "checkOut"],
+    },
+
+    async handler(ctx, args) {
+        const { city } = args as Record<string, string>;
+
+        // Imperative: emit directives mid-handler via ctx.dispatch
+        ctx.dispatch({ dataUpdate: { confirmationId: `CONF-${Date.now()}` } });
+        ctx.dispatch({ complete: true });
+
+        return { data: { booked: true, city } };
+    },
+};
+
+// ─── Tool 3: Declarative directive via ToolResult.directive ──────────────────
+
+const cancelBooking: Tool<AppContext, AppData> = {
+    id: "cancel_booking",
+    description: "Cancel the current booking and reset the flow.",
+
+    async handler(ctx): Promise<ToolResult<{ cancelled: boolean }, AppContext, AppData>> {
+        if (!ctx.getField("confirmationId")) {
+            return { success: false, error: "No active booking to cancel." };
+        }
+        // Declarative: return a directive as part of the tool result
+        const directive: Directive<AppContext, AppData> = {
+            reset: { clearData: true, reason: "Booking cancelled by user" },
+            reply: "Your booking has been cancelled. Let me know if you'd like to start over.",
+        };
+        return { data: { cancelled: true }, directive };
+    },
+};
+
+// ─── Agent ───────────────────────────────────────────────────────────────────
+
+const agent = createAgent<AppContext, AppData>({
+    name: "BookingAgent",
+    provider: new GeminiProvider({
+        apiKey: process.env.GEMINI_API_KEY!,
+        model: "models/gemini-2.5-flash",
+    }),
+    schema: {
+        type: "object",
+        properties: {
+            city: { type: "string" },
+            checkIn: { type: "string" },
+            checkOut: { type: "string" },
+            confirmationId: { type: "string" },
+        },
+    },
+    tools: [checkAvailability, bookRoom, cancelBooking],
+    flows: [
+        {
+            title: "Book a Room",
+            when: "User wants to book a hotel room",
+            requiredFields: ["city", "checkIn", "checkOut"],
+            steps: [
+                { id: "gather", prompt: "Ask for city, check-in, and check-out dates.", collect: ["city", "checkIn", "checkOut"] },
+                { id: "confirm", prompt: "Confirm the booking details and use the book_room tool." },
+            ],
+        },
+    ],
+});
+
+// ─── Run ─────────────────────────────────────────────────────────────────────
+
+const session = createSession<AppData>("tools-demo");
+
+const response = await agent.respond({
+    history: [{ role: "user", content: "Book me a room in Tokyo from Jan 5 to Jan 8" }],
+    session,
+});
+
+console.log(response.message);

package/examples/04-instructions.ts

@@ -0,0 +1,100 @@
+/**
+ * Instructions — behavioral rules at agent, flow, and step scope.
+ * Teaches: Instruction, kind (must / never / should), conditional `when`.
+ * Read next: docs/guides/instructions.md
+ */
+
+import { createAgent, GeminiProvider } from "../src";
+
+if (!process.env.GEMINI_API_KEY) throw new Error("Set GEMINI_API_KEY");
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+interface SupportData {
+    issue: string;
+    category: string;
+    resolution: string;
+}
+
+// ─── Agent with instructions at every scope ──────────────────────────────────
+
+const agent = createAgent<unknown, SupportData>({
+    name: "SupportBot",
+    provider: new GeminiProvider({
+        apiKey: process.env.GEMINI_API_KEY,
+        model: "models/gemini-2.5-flash",
+    }),
+    schema: {
+        type: "object",
+        properties: {
+            issue: { type: "string" },
+            category: { type: "string" },
+            resolution: { type: "string" },
+        },
+    },
+
+    // ── Agent-scope instructions (apply to every flow and step) ──────────
+    instructions: [
+        // "must" — absolute rule, always enforced
+        { kind: "must", prompt: "Always greet the user by name if it appears in the message." },
+        // "never" — absolute prohibition
+        { kind: "never", prompt: "Share internal ticket IDs or system error codes with the user." },
+        // "should" — behavioral nudge, conditionally active
+        {
+            kind: "should",
+            prompt: "Suggest the FAQ article link before escalating to a human.",
+            when: "User is asking a common question",
+        },
+    ],
+
+    flows: [
+        {
+            title: "Resolve Issue",
+            when: "User reports a problem or asks for help",
+            requiredFields: ["issue", "category", "resolution"],
+
+            // ── Flow-scope instructions (active only in this flow) ────────
+            instructions: [
+                { kind: "must", prompt: "Classify the issue into a category before proposing a resolution." },
+                {
+                    kind: "should",
+                    prompt: "Ask clarifying questions if the issue description is under ten words.",
+                    when: "The user's issue description is vague or very short",
+                },
+            ],
+
+            steps: [
+                {
+                    id: "identify",
+                    prompt: "Ask the user to describe their issue.",
+                    collect: ["issue", "category"],
+
+                    // ── Step-scope instructions (active only in this step) ─
+                    instructions: [
+                        { kind: "never", prompt: "Suggest a resolution before the issue is fully described." },
+                        {
+                            kind: "should",
+                            prompt: "Offer example categories to help the user classify their problem.",
+                            when: "User seems unsure how to categorize",
+                        },
+                    ],
+                },
+                {
+                    id: "resolve",
+                    prompt: "Propose a resolution based on the identified issue and category.",
+                    collect: ["resolution"],
+                },
+            ],
+        },
+    ],
+});
+
+// ─── Run ─────────────────────────────────────────────────────────────────────
+
+const response = await agent.respond({
+    history: [{ role: "user", content: "Hey, my login page keeps showing a blank screen." }],
+});
+
+console.log(response.message);
+// The appliedInstructions array shows which instructions were active this turn.
+console.log("Applied:", response.appliedInstructions);

package/examples/05-branching.ts

@@ -0,0 +1,140 @@
+/** @intent Demonstrates step.branches — source-local forks with if, when, and Directive targets.
+ *  @teaches BranchEntry, BranchMap, if-only fork, when-only fork, combined if+when, mixed targets
+ *  @readAfter docs/guides/branching.md */
+import { createAgent, GeminiProvider } from "../src";
+import type { BranchMap, Directive, FlowOptions, StepOptions } from "../src";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+interface Context { tier: "free" | "pro" | "enterprise" }
+interface Data { intent: string; query: string; answer: string }
+
+// ─── Provider ────────────────────────────────────────────────────────────────
+
+const provider = new GeminiProvider({
+    apiKey: process.env.GEMINI_API_KEY!,
+    model: "models/gemini-2.5-flash",
+});
+
+// ─── Steps with branches ─────────────────────────────────────────────────────
+
+// 1. if-only fork — pure code predicate, zero LLM cost
+const triageStep: StepOptions<Context, Data> = {
+    id: "triage",
+    prompt: "What can I help you with today?",
+    collect: ["intent"],
+    branches: [
+        {
+            label: "pro-fast-track",
+            if: ({ context }) => context.tier === "pro" || context.tier === "enterprise",
+            then: "priority_queue",   // resolves as step id in same flow
+        },
+        {
+            label: "free-default",
+            then: "general_help",     // unconditional fallback (last entry)
+        },
+    ] satisfies BranchMap<Context, Data>,
+};
+
+// 2. when-only fork — AI-evaluated condition (costs tokens)
+const classifyStep: StepOptions<Context, Data> = {
+    id: "general_help",
+    prompt: "Let me look into that for you.",
+    collect: ["query"],
+    branches: [
+        {
+            label: "billing",
+            when: "The user is asking about billing, invoices, or payments",
+            then: "billing_flow",     // resolves as flow id (cross-flow jump)
+        },
+        {
+            label: "technical",
+            when: "The user is asking a technical or API question",
+            then: "tech_support",     // resolves as step id
+        },
+        {
+            label: "fallback",
+            then: "tech_support",
+        },
+    ] satisfies BranchMap<Context, Data>,
+};
+
+// 3. Combined if + when — code runs first (free), AI only if code passes
+const priorityStep: StepOptions<Context, Data> = {
+    id: "priority_queue",
+    prompt: "You have priority support. What do you need?",
+    collect: ["query"],
+    branches: [
+        {
+            label: "enterprise-escalation",
+            if: ({ context }) => context.tier === "enterprise",
+            when: "The user is reporting a production outage or critical bug",
+            then: {
+                goTo: "escalation_flow",
+                dataUpdate: { intent: "escalation" },
+                reply: "Routing you to our on-call engineering team now.",
+            } satisfies Directive<Context, Data>,
+        },
+        {
+            label: "standard-priority",
+            then: "tech_support",
+        },
+    ] satisfies BranchMap<Context, Data>,
+};
+
+// 4. Terminal step — no branches, linear end
+const techSupportStep: StepOptions<Context, Data> = {
+    id: "tech_support",
+    prompt: "I'll find the answer to your technical question.",
+    collect: ["answer"],
+};
+
+// ─── Flows ───────────────────────────────────────────────────────────────────
+
+const supportFlow: FlowOptions<Context, Data> = {
+    id: "support_flow",
+    title: "Support",
+    description: "Routes users through support triage",
+    when: "The user needs help or support",
+    steps: [triageStep, classifyStep, priorityStep, techSupportStep],
+    requiredFields: ["answer"],
+};
+
+const billingFlow: FlowOptions<Context, Data> = {
+    id: "billing_flow",
+    title: "Billing",
+    description: "Handles billing inquiries",
+    when: "The user asks about billing",
+    steps: [{ id: "billing_help", prompt: "Let me pull up your billing info." }],
+};
+
+const escalationFlow: FlowOptions<Context, Data> = {
+    id: "escalation_flow",
+    title: "Escalation",
+    description: "Critical issue escalation for enterprise customers",
+    steps: [{ id: "escalate", prompt: "Connecting you to on-call engineering." }],
+};
+
+// ─── Agent ───────────────────────────────────────────────────────────────────
+
+const agent = createAgent<Context, Data>({
+    name: "Support Bot",
+    provider,
+    context: { tier: "pro" },
+    schema: {
+        type: "object",
+        properties: {
+            intent: { type: "string" },
+            query: { type: "string" },
+            answer: { type: "string" },
+        },
+    },
+    flows: [supportFlow, billingFlow, escalationFlow],
+});
+
+// ─── Run ─────────────────────────────────────────────────────────────────────
+
+const response = await agent.respond({
+    history: [{ role: "user", content: "I need help with my API integration" }],
+});
+console.log(response.message);

package/examples/06-flow-control.ts

@@ -0,0 +1,103 @@
+/**
+ * Programmatic flow control via Agent.dispatch and Directive shapes.
+ * Teaches: dispatch from outside a turn, complete with next, abort, reply.
+ * Read after: docs/guides/flow-control.md
+ */
+
+import { createAgent, GeminiProvider, type Directive, type History } from "@falai/agent";
+
+// ─── Schema ──────────────────────────────────────────────────────────────────
+
+interface AppData {
+    item: string;
+    confirmed: boolean;
+}
+
+// ─── Agent setup ─────────────────────────────────────────────────────────────
+
+const agent = createAgent<{}, AppData>({
+    name: "FlowControlDemo",
+    provider: new GeminiProvider({
+        apiKey: process.env.GEMINI_API_KEY!,
+        model: "models/gemini-2.5-flash",
+    }),
+    schema: {
+        type: "object",
+        properties: {
+            item: { type: "string" },
+            confirmed: { type: "boolean" },
+        },
+    },
+    flows: [
+        {
+            title: "Select Item",
+            steps: [
+                {
+                    id: "ask_item",
+                    prompt: "What item would you like?",
+                    collect: ["item"],
+                },
+                {
+                    id: "confirm",
+                    prompt: "You chose {{data.item}}. Confirm?",
+                    collect: ["confirmed"],
+                    requires: ["item"],
+                    // When the user confirms, complete with a chained directive
+                    // that moves to the "Checkout" flow.
+                    hooks: {
+                        finalize: ({ data }) => {
+                            if (data.confirmed) {
+                                const d: Directive<{}, AppData> = {
+                                    complete: { next: { goTo: "Checkout" }, reason: "User confirmed" },
+                                };
+                                return d;
+                            }
+                            // Not confirmed — abort with a reason
+                            return { abort: "User declined the item" };
+                        },
+                    },
+                },
+            ],
+        },
+        {
+            title: "Checkout",
+            steps: [
+                {
+                    id: "receipt",
+                    // reply renders a verbatim message without an LLM call
+                    reply: "Your order for {{data.item}} is confirmed. Thank you!",
+                },
+            ],
+        },
+    ],
+});
+
+// ─── External dispatch ───────────────────────────────────────────────────────
+// Agent.dispatch queues a directive on a session OUTSIDE a respond() turn.
+// The directive takes effect on the next respond() call.
+
+async function externalRedirect() {
+    const history: History = [{ role: "user", content: "hello" }];
+
+    // First turn — enters "Select Item" normally
+    const res = await agent.respond({ history });
+    const session = res.session!;
+
+    // An external system decides to force-redirect to Checkout
+    const updated = await agent.dispatch({ goTo: "Checkout" }, session);
+
+    // Next turn picks up the pending directive
+    const next = await agent.respond({
+        history: [
+            ...history,
+            { role: "assistant", content: res.message },
+            { role: "user", content: "actually, rush my order" },
+        ],
+        session: updated,
+    });
+
+    console.log(next.message);
+    // → "Your order for ... is confirmed. Thank you!"
+}
+
+externalRedirect().catch(console.error);

package/examples/07-streaming.ts

@@ -0,0 +1,69 @@
+/**
+ * Real-time streaming with respondStream and final-chunk metadata.
+ * Teaches: respondStream, chunk consumption, appliedInstructions, triggeredSignals.
+ * Read after: docs/guides/streaming.md
+ */
+
+import { createAgent, GeminiProvider, createSession, type AgentResponseStreamChunk } from "@falai/agent";
+
+// ─── Schema ──────────────────────────────────────────────────────────────────
+
+interface AppData {
+    topic: string;
+}
+
+// ─── Agent setup ─────────────────────────────────────────────────────────────
+
+const agent = createAgent<{}, AppData>({
+    name: "StreamingDemo",
+    provider: new GeminiProvider({
+        apiKey: process.env.GEMINI_API_KEY!,
+        model: "models/gemini-2.5-flash",
+    }),
+    schema: {
+        type: "object",
+        properties: {
+            topic: { type: "string" },
+        },
+    },
+    instructions: [
+        { id: "concise", kind: "should", prompt: "Keep answers under 100 words" },
+    ],
+    flows: [
+        {
+            title: "Chat",
+            steps: [{ id: "talk", prompt: "Discuss the user's topic.", collect: ["topic"] }],
+        },
+    ],
+});
+
+// ─── Stream consumption ──────────────────────────────────────────────────────
+
+async function streamResponse() {
+    const session = createSession<AppData>("stream-demo");
+    const history = [{ role: "user" as const, content: "Explain how tides work" }];
+
+    const stream = agent.respondStream({ history, session });
+
+    let finalChunk: AgentResponseStreamChunk<AppData> | undefined;
+
+    for await (const chunk of stream) {
+        // Print each delta as it arrives (real-time UX)
+        process.stdout.write(chunk.delta);
+
+        if (chunk.done) {
+            finalChunk = chunk;
+        }
+    }
+
+    console.log("\n");
+
+    // ─── Final-chunk metadata ────────────────────────────────────────────────
+    if (finalChunk) {
+        console.log("Accumulated:", finalChunk.accumulated.length, "chars");
+        console.log("Applied instructions:", finalChunk.appliedInstructions ?? []);
+        console.log("Triggered signals:", finalChunk.triggeredSignals ?? []);
+    }
+}
+
+streamResponse().catch(console.error);

package/examples/08-persistence.ts

@@ -0,0 +1,98 @@
+/** @intent Session persistence with MemoryAdapter: implicit default, explicit wiring, and sessionId for cross-turn continuity.
+ *  @teaches MemoryAdapter, PersistenceConfig, sessionId, session resumption
+ *  @readAfter docs/guides/persistence.md */
+import { createAgent, GeminiProvider, MemoryAdapter } from "../src";
+
+if (!process.env.GEMINI_API_KEY) throw new Error("Set GEMINI_API_KEY");
+
+const provider = new GeminiProvider({
+    apiKey: process.env.GEMINI_API_KEY,
+    model: "models/gemini-2.5-flash",
+});
+
+const schema = {
+    type: "object" as const,
+    properties: {
+        city: { type: "string" },
+        checkIn: { type: "string" },
+        checkOut: { type: "string" },
+    },
+};
+
+const flows = [{
+    title: "Book Hotel",
+    requiredFields: ["city", "checkIn", "checkOut"],
+    steps: [
+        { id: "ask_city", prompt: "Which city are you visiting?", collect: ["city"] },
+        { id: "ask_dates", prompt: "What are your check-in and check-out dates?", collect: ["checkIn", "checkOut"] },
+    ],
+}];
+
+// --- 1. Implicit MemoryAdapter (default when no persistence is specified) ---
+// When you omit `persistence`, the agent uses an internal MemoryAdapter automatically.
+// Great for prototyping — zero config, but data is lost when the process exits.
+
+const simpleAgent = createAgent({
+    name: "BookingBot",
+    provider,
+    schema,
+    flows,
+});
+
+const res1 = await simpleAgent.respond({
+    history: [{ role: "user", content: "I'd like to book a hotel in Tokyo" }],
+});
+console.log("[Implicit adapter]", res1.message);
+
+// --- 2. Explicit MemoryAdapter with userId ---
+// Wire a MemoryAdapter explicitly to inspect stored sessions during development.
+
+const adapter = new MemoryAdapter();
+
+const agent = createAgent({
+    name: "BookingBot",
+    provider,
+    schema,
+    flows,
+    persistence: {
+        adapter,
+        userId: "user_42",
+    },
+});
+
+// --- 3. sessionId for cross-turn continuity ---
+// Pass `sessionId` at construct time so the same conversation resumes across calls.
+// In production, swap MemoryAdapter for PrismaAdapter (or Redis, Postgres, etc.)
+// and the session survives process restarts.
+
+const persistentAgent = createAgent({
+    name: "BookingBot",
+    provider,
+    schema,
+    flows,
+    persistence: {
+        adapter,        // swap to: new PrismaAdapter({ prisma }) for production
+        userId: "user_42",
+    },
+    sessionId: "user_42:thread_001",
+});
+
+// Turn 1 — agent collects city
+const turn1 = await persistentAgent.respond({
+    history: [{ role: "user", content: "I want to stay in Paris" }],
+});
+console.log("[Turn 1]", turn1.message);
+
+// Turn 2 — same sessionId, conversation continues where it left off
+const turn2 = await persistentAgent.respond({
+    history: [
+        { role: "user", content: "I want to stay in Paris" },
+        { role: "assistant", content: turn1.message },
+        { role: "user", content: "March 10 to March 14" },
+    ],
+});
+console.log("[Turn 2]", turn2.message);
+
+// Inspect stored data (MemoryAdapter-only convenience method)
+const snapshot = adapter.getSnapshot();
+console.log("[Sessions]", snapshot.sessions.length);