@falai/agent 0.8.1 → 0.9.0-alpha-2

package/examples/{persistent-onboarding.ts → advanced-patterns/persistent-onboarding.ts}

@@ -5,13 +5,10 @@
 
 import {
   Agent,
-  defineTool,
+  type Tool,
   GeminiProvider,
   END_ROUTE,
-  EventSource,
-  createMessageEvent,
-  createSession,
-} from "../src/index";
+} from "../../src";
 
 // ============================================================================
 // DATABASE SIMULATION
@@ -35,14 +32,11 @@ const database = new Map<string, SessionData>();
 
 const db = {
   sessions: {
-    async findById(sessionId: string): Promise<SessionData | undefined> {
+    findById(sessionId: string): SessionData | undefined {
       return database.get(sessionId);
     },
 
-    async update(
-      sessionId: string,
-      updates: Partial<SessionData>
-    ): Promise<void> {
+    update(sessionId: string, updates: Partial<SessionData>): void {
       const existing = database.get(sessionId);
       if (existing) {
         database.set(sessionId, {
@@ -53,7 +47,7 @@ const db = {
       }
     },
 
-    async create(sessionData: SessionData): Promise<void> {
+    create(sessionData: SessionData): void {
       database.set(sessionData.sessionId, sessionData);
     },
   },
@@ -90,9 +84,9 @@ interface OnboardingContext {
  * - Load fresh context from database before each response
  * - Persist context updates automatically after changes
  */
-async function createPersistentOnboardingAgent(sessionId: string) {
+function createPersistentOnboardingAgent(sessionId: string) {
   // Load session from database
-  const session = await db.sessions.findById(sessionId);
+  const session = db.sessions.findById(sessionId);
 
   if (!session) {
     throw new Error(`Session ${sessionId} not found`);
@@ -101,7 +95,7 @@ async function createPersistentOnboardingAgent(sessionId: string) {
   // Define lifecycle hooks for automatic persistence
   const hooks = {
     // Called after data extraction - validate and enrich collected data
-    onDataUpdate: async (data: Partial<OnboardingData>) => {
+    onDataUpdate: (data: Partial<OnboardingData>) => {
       console.log("🔄 Processing collected data...");
 
       // Update completed steps based on what's been data
@@ -112,7 +106,7 @@ async function createPersistentOnboardingAgent(sessionId: string) {
       if (data.contactEmail) completedSteps.push("contact");
 
       // Persist to database
-      await db.sessions.update(sessionId, {
+      db.sessions.update(sessionId, {
         collectedData: data,
         completedSteps,
       });
@@ -126,15 +120,94 @@ async function createPersistentOnboardingAgent(sessionId: string) {
     model: "models/gemini-2.5-flash",
   });
 
-  const agent = new Agent<OnboardingContext>({
+  // Define the onboarding schema
+  const onboardingSchema = {
+    type: "object",
+    properties: {
+      businessName: {
+        type: "string",
+        description: "Name of the business",
+      },
+      businessDescription: {
+        type: "string",
+        description: "Brief description of what the business does",
+      },
+      industry: {
+        type: "string",
+        description: "Industry the business operates in",
+      },
+      contactEmail: {
+        type: "string",
+        description: "Contact email for the business",
+      },
+    },
+    required: ["businessName", "businessDescription"],
+  };
+
+  const agent = new Agent<OnboardingContext, OnboardingData>({
     name: "OnboardingBot",
     description: "A friendly assistant that helps businesses get started",
     goal: "Collect business information efficiently while being conversational",
     provider: provider,
+    // NEW: Agent-level schema
+    schema: onboardingSchema,
+
+    // Knowledge base with onboarding best practices
+    knowledgeBase: {
+      onboardingFlow: {
+        stages: [
+          "Business identification",
+          "Industry classification",
+          "Contact information collection",
+          "Verification and confirmation",
+        ],
+        averageCompletion: "3-5 minutes",
+        dropOffPoints: ["Contact email collection", "Industry classification"],
+      },
+      businessTypes: {
+        retail: {
+          commonIndustries: [
+            "Fashion",
+            "Electronics",
+            "Home goods",
+            "Food service",
+          ],
+          keyQuestions: ["Store location", "Target customers", "Peak hours"],
+        },
+        professional: {
+          commonIndustries: ["Consulting", "Legal", "Accounting", "Healthcare"],
+          keyQuestions: ["Service areas", "Certifications", "Client types"],
+        },
+        manufacturing: {
+          commonIndustries: [
+            "Electronics",
+            "Automotive",
+            "Food processing",
+            "Textiles",
+          ],
+          keyQuestions: [
+            "Production capacity",
+            "Supply chain",
+            "Quality standards",
+          ],
+        },
+      },
+      dataValidation: {
+        email: "Must contain @ symbol and valid domain",
+        businessName: "2-100 characters, no special characters",
+        description: "10-500 characters, describes what the business does",
+      },
+      completionCriteria: [
+        "Business name provided",
+        "Business description provided",
+        "Industry category selected",
+        "Valid contact email provided",
+      ],
+    },
     // Context is loaded fresh from database on each respond() call
-    contextProvider: async () => {
+    contextProvider: () => {
       console.log("🔄 Loading fresh context from database...");
-      const freshSession = await db.sessions.findById(sessionId);
+      const freshSession = db.sessions.findById(sessionId);
 
       if (!freshSession) {
         throw new Error(`Session ${sessionId} not found`);
@@ -155,13 +228,25 @@ async function createPersistentOnboardingAgent(sessionId: string) {
   // ============================================================================
 
   // OPTION 1: Using contextUpdate in return value
-  const saveBusinessInfo = defineTool<
+  const saveBusinessInfo: Tool<
     OnboardingContext,
-    [name: string, description: string],
-    boolean
-  >(
-    "save_business_info",
-    async (toolContext, name, description) => {
+    OnboardingData,
+    unknown[],
+    unknown
+  > = {
+    id: "save_business_info",
+    name: "Business Info Saver",
+    description: "Save business name and description",
+    parameters: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Business name" },
+        description: { type: "string", description: "Business description" },
+      },
+      required: ["name", "description"],
+    },
+    handler: (toolContext, ...args) => {
+      const [name, description] = args as [string, string];
       console.log(`📝 Saving business info: ${name}`);
 
       return {
@@ -180,19 +265,27 @@ async function createPersistentOnboardingAgent(sessionId: string) {
         },
       };
     },
-    {
-      description: "Save business name and description",
-    }
-  );
+  };
 
   // OPTION 2: Using updateContext method directly
-  const saveIndustry = defineTool<
+  const saveIndustry: Tool<
     OnboardingContext,
-    [industry: string],
-    boolean
-  >(
-    "save_industry",
-    async (toolContext, industry) => {
+    OnboardingData,
+    unknown[],
+    unknown
+  > = {
+    id: "save_industry",
+    name: "Industry Classifier",
+    description: "Save business industry",
+    parameters: {
+      type: "object",
+      properties: {
+        industry: { type: "string", description: "Business industry" },
+      },
+      required: ["industry"],
+    },
+    handler: async (toolContext, ...args) => {
+      const [industry] = args as [string];
       console.log(`🏭 Saving industry: ${industry}`);
 
       // Direct context update (triggers onContextUpdate hook)
@@ -206,18 +299,26 @@ async function createPersistentOnboardingAgent(sessionId: string) {
 
       return { data: true };
     },
-    {
-      description: "Save business industry",
-    }
-  );
+  };
 
-  const saveContactEmail = defineTool<
+  const saveContactEmail: Tool<
     OnboardingContext,
-    [email: string],
-    boolean
-  >(
-    "save_contact_email",
-    async (toolContext, email) => {
+    OnboardingData,
+    unknown[],
+    unknown
+  > = {
+    id: "save_contact_email",
+    name: "Contact Email Saver",
+    description: "Save contact email",
+    parameters: {
+      type: "object",
+      properties: {
+        email: { type: "string", description: "Contact email address" },
+      },
+      required: ["email"],
+    },
+    handler: async (toolContext, ...args) => {
+      const [email] = args as [string];
       console.log(`📧 Saving contact email: ${email}`);
 
       await toolContext.updateContext({
@@ -230,85 +331,64 @@ async function createPersistentOnboardingAgent(sessionId: string) {
 
       return { data: true };
     },
-    {
-      description: "Save contact email",
-    }
-  );
+  };
 
   // ============================================================================
   // ONBOARDING ROUTE WITH DATA EXTRACTION
   // ============================================================================
 
-  const onboardingRoute = agent.createRoute<OnboardingData>({
+  const onboardingRoute = agent.createRoute({
     title: "Business Onboarding",
     description: "Guide user through business information collection",
     conditions: ["User is onboarding their business"],
-    schema: {
-      type: "object",
-      properties: {
-        businessName: {
-          type: "string",
-          description: "Name of the business",
-        },
-        businessDescription: {
-          type: "string",
-          description: "Brief description of what the business does",
-        },
-        industry: {
-          type: "string",
-          description: "Industry the business operates in",
-        },
-        contactEmail: {
-          type: "string",
-          description: "Contact email for the business",
-        },
-      },
-      required: ["businessName", "businessDescription"],
-    },
+    // NEW: Required fields for route completion
+    requiredFields: ["businessName", "businessDescription"],
+    // NEW: Optional fields that enhance the experience
+    optionalFields: ["industry", "contactEmail"],
     endStep: {
-      instructions:
+      prompt:
         "Summarize all collected information warmly and confirm onboarding is complete",
     },
   });
 
   // Step 1: Collect business name and description
   const collectBusinessInfo = onboardingRoute.initialStep.nextStep({
-    instructions: "Ask for business name and a brief description",
+    prompt: "Ask for business name and a brief description",
     collect: ["businessName", "businessDescription"],
     skipIf: (data) => !!data.businessName && !!data.businessDescription,
-    condition: "Need to collect basic business information first",
+    when: "Need to collect basic business information first",
   });
 
   // Step 2: Save business info (tool execution)
   const saveBusiness = collectBusinessInfo.nextStep({
-    tool: saveBusinessInfo,
+    tools: [saveBusinessInfo],
     requires: ["businessName", "businessDescription"],
-    condition: "Business name and description provided, save to database",
+    when: "Business name and description provided, save to database",
   });
 
   // Step 3: Collect industry
   const collectIndustry = saveBusiness.nextStep({
-    instructions: "Ask what industry the business operates in",
+    prompt: "Ask what industry the business operates in",
     collect: ["industry"],
     skipIf: (data) => !!data.industry,
   });
 
   // Step 4: Save industry (tool execution)
   const saveIndustryStep = collectIndustry.nextStep({
-    tool: saveIndustry,
+    tools: [saveIndustry],
     requires: ["industry"],
   });
 
   // Step 5: Collect contact email
   const collectContact = saveIndustryStep.nextStep({
-    instructions: "Ask for their contact email",
+    prompt: "Ask for their contact email",
     collect: ["contactEmail"],
     skipIf: (data) => !!data.contactEmail,
   });
 
   // Step 6: Save contact (tool execution)
   const saveContact = collectContact.nextStep({
-    tool: saveContactEmail,
+    tools: [saveContactEmail],
     requires: ["contactEmail"],
   });
 
@@ -350,20 +430,46 @@ async function createPersistentOnboardingAgent(sessionId: string) {
  * - No need for beforeRespond hook
  * - Still use onContextUpdate for persistence
  */
-async function createOnboardingAgentWithProvider(sessionId: string) {
+function createOnboardingAgentWithProvider(sessionId: string) {
   const provider = new GeminiProvider({
     apiKey: process.env.GEMINI_API_KEY || "test-key",
     model: "models/gemini-2.5-flash",
   });
 
-  const agent = new Agent<OnboardingContext>({
+  // Define the onboarding schema
+  const onboardingSchema = {
+    type: "object",
+    properties: {
+      businessName: {
+        type: "string",
+        description: "Name of the business",
+      },
+      businessDescription: {
+        type: "string",
+        description: "Brief description of what the business does",
+      },
+      industry: {
+        type: "string",
+        description: "Industry the business operates in",
+      },
+      contactEmail: {
+        type: "string",
+        description: "Contact email for the business",
+      },
+    },
+    required: ["businessName", "businessDescription"],
+  };
+
+  const agent = new Agent<OnboardingContext, OnboardingData>({
     name: "OnboardingBot",
     description: "A friendly assistant that helps businesses get started",
     provider: provider,
+    // NEW: Agent-level schema
+    schema: onboardingSchema,
 
     // Context is always fetched fresh from database
-    contextProvider: async () => {
-      const session = await db.sessions.findById(sessionId);
+    contextProvider: () => {
+      const session = db.sessions.findById(sessionId);
       if (!session) {
         throw new Error(`Session ${sessionId} not found`);
       }
@@ -378,8 +484,8 @@ async function createOnboardingAgentWithProvider(sessionId: string) {
 
     // Still persist updates
     hooks: {
-      onContextUpdate: async (newContext) => {
-        await db.sessions.update(sessionId, {
+      onContextUpdate: (newContext) => {
+        db.sessions.update(sessionId, {
           collectedData: newContext.collectedData,
           completedSteps: newContext.completedSteps,
         });
@@ -401,7 +507,7 @@ async function main() {
   const userId = "user_456";
 
   // Initialize session in database
-  await db.sessions.create({
+  db.sessions.create({
     sessionId,
     userId,
     collectedData: {},
@@ -410,27 +516,24 @@ async function main() {
   });
 
   // Create agent with fresh context loading
-  const agent = await createPersistentOnboardingAgent(sessionId);
+  const agent = createPersistentOnboardingAgent(sessionId);
 
   console.log("=== MULTI-TURN CONVERSATION SIMULATION ===\n");
 
-  // Initialize session step for multi-turn conversation
-  let session = createSession<OnboardingData>();
+  // Session is automatically managed by the agent
+  console.log("✨ Session ready:", agent.session.id);
 
   // Turn 1: Start onboarding
   console.log("📱 Turn 1: User starts onboarding");
+  
+  await agent.session.addMessage("user", "Hi, I want to onboard my business", "Alice");
+  
   const response1 = await agent.respond({
-    history: [
-      createMessageEvent(
-        EventSource.CUSTOMER,
-        "Alice",
-        "Hi, I want to onboard my business"
-      ),
-    ],
-    session,
+    history: agent.session.getHistory(),
   });
+  
   console.log("🤖 Bot:", response1.message);
-  console.log("📊 Data after turn 1:", response1.session?.data);
+  console.log("📊 Data after turn 1:", agent.session.getData());
   console.log("📊 Route:", response1.session?.currentRoute?.title);
 
   // Check route completion after turn 1
@@ -443,25 +546,28 @@ async function main() {
 
   console.log();
 
-  // Update session with progress
-  session = response1.session!;
+  await agent.session.addMessage("assistant", response1.message);
 
   // Turn 2: User provides business info
   console.log("📱 Turn 2: User provides business info");
   const history2 = [
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "Alice",
-      "Hi, I want to onboard my business"
-    ),
-    createMessageEvent(EventSource.AI_AGENT, "Agent", response1.message),
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "Alice",
-      "My business is called 'TechFlow' and we build AI-powered workflow automation tools"
-    ),
+    {
+      role: "user" as const,
+      content: "Hi, I want to onboard my business",
+      name: "Alice",
+    },
+    {
+      role: "assistant" as const,
+      content: response1.message,
+    },
+    {
+      role: "user" as const,
+      content:
+        "My business is called 'TechFlow' and we build AI-powered workflow automation tools",
+      name: "Alice",
+    },
   ];
-  const response2 = await agent.respond({ history: history2, session });
+  const response2 = await agent.respond({ history: history2 });
   console.log("🤖 Bot:", response2.message);
   console.log("📊 Data after turn 2:", response2.session?.data);
 
@@ -475,21 +581,22 @@ async function main() {
 
   console.log();
 
-  // Update session again
-  session = response2.session!;
 
   // Turn 3: User provides industry
   console.log("📱 Turn 3: User provides industry");
   const history3 = [
     ...history2,
-    createMessageEvent(EventSource.AI_AGENT, "Agent", response2.message),
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "Alice",
-      "We're in the SaaS industry"
-    ),
+    {
+      role: "assistant" as const,
+      content: response2.message,
+    },
+    {
+      role: "user" as const,
+      content: "We're in the SaaS industry",
+      name: "Alice",
+    },
   ];
-  const response3 = await agent.respond({ history: history3, session });
+  const response3 = await agent.respond({ history: history3 });
   console.log("🤖 Bot:", response3.message);
   console.log("📊 Data after turn 3:", response3.session?.data);
 
@@ -503,21 +610,21 @@ async function main() {
 
   console.log();
 
-  // Update session again
-  session = response3.session!;
-
   // Turn 4: User provides contact email, completing the flow
   console.log("📱 Turn 4: User provides contact email");
   const history4 = [
     ...history3,
-    createMessageEvent(EventSource.AI_AGENT, "Agent", response3.message),
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "Alice",
-      "Our contact email is contact@techflow.ai"
-    ),
+    {
+      role: "assistant" as const,
+      content: response3.message,
+    },
+    {
+      role: "user" as const,
+      content: "Our contact email is contact@techflow.ai",
+      name: "Alice",
+    },
   ];
-  const response4 = await agent.respond({ history: history4, session });
+  const response4 = await agent.respond({ history: history4 });
   console.log("🤖 Bot:", response4.message);
   console.log("📊 Data after turn 4:", response4.session?.data);
 
@@ -525,13 +632,13 @@ async function main() {
   if (response4.isRouteComplete) {
     console.log("\n✅ Onboarding complete!");
     await finalizeOnboarding(
-      agent.getData(response4.session?.id) as unknown as OnboardingData
+      agent.getData() as unknown as OnboardingData
     );
   }
 
   // Verify persistence
   console.log("=== PERSISTENCE VERIFICATION ===");
-  const finalSession = await db.sessions.findById(sessionId);
+  const finalSession = db.sessions.findById(sessionId);
   console.log(
     "💾 Final persisted session:",
     JSON.stringify(finalSession, null, 2)
@@ -543,9 +650,9 @@ async function main() {
 // ============================================================================
 
 /*
- * ✅ PATTERN 1: Session Step Management (Core v2 pattern)
- *    - createSession<T>(): Initialize typed session step
- *    - Pass session to respond() calls
+ * ✅ PATTERN 1: Session Management (New SessionManager pattern)
+ *    - agent.session: Automatic session management
+ *    - agent.session.addMessage(): Add messages to history
  *    - Session tracks collected data across turns
  *    - Always-on routing respects intent changes
  *