@falai/agent 0.9.0-alpha-1 → 0.9.0-alpha-2

package/examples/integrations/server-session-management.ts

@@ -31,7 +31,7 @@ interface BookingData {
 }
 
 // Booking confirmation tool
-const confirmBooking: Tool<unknown, [], string, BookingData> = {
+const confirmBooking: Tool<unknown, BookingData, [], string> = {
     id: "confirm_booking",
     description: "Confirm the hotel booking with all details",
     parameters: {
@@ -56,15 +56,33 @@ const confirmBooking: Tool<unknown, [], string, BookingData> = {
     },
 };
 
+// Define booking schema
+const bookingSchema = {
+    type: "object",
+    properties: {
+        customerName: { type: "string" },
+        hotelName: { type: "string" },
+        checkInDate: { type: "string" },
+        checkOutDate: { type: "string" },
+        guests: { type: "number", minimum: 1, maximum: 10 },
+        roomType: { type: "string", enum: ["standard", "deluxe", "suite"] },
+        specialRequests: { type: "string" },
+        bookingId: { type: "string" },
+    },
+    required: ["customerName", "hotelName", "checkInDate", "checkOutDate", "guests"],
+};
+
 // Function to create agent for each request (server pattern)
 function createBookingAgent(sessionId?: string) {
-    return new Agent({
+    return new Agent<unknown, BookingData>({
         name: "Hotel Booking Assistant",
         description: "Help customers book hotel rooms",
         provider: new OpenAIProvider({
             apiKey: process.env.OPENAI_API_KEY!,
             model: "gpt-4",
         }),
+        // NEW: Agent-level schema
+        schema: bookingSchema,
         persistence: {
             adapter: new MemoryAdapter(), // In production: RedisAdapter, PrismaAdapter, etc.
             autoSave: true,
@@ -75,20 +93,10 @@ function createBookingAgent(sessionId?: string) {
                 title: "Hotel Booking",
                 description: "Collect booking details and confirm reservation",
                 conditions: ["User wants to book a hotel room"],
-                schema: {
-                    type: "object",
-                    properties: {
-                        customerName: { type: "string" },
-                        hotelName: { type: "string" },
-                        checkInDate: { type: "string" },
-                        checkOutDate: { type: "string" },
-                        guests: { type: "number", minimum: 1, maximum: 10 },
-                        roomType: { type: "string", enum: ["standard", "deluxe", "suite"] },
-                        specialRequests: { type: "string" },
-                        bookingId: { type: "string" },
-                    },
-                    required: ["customerName", "hotelName", "checkInDate", "checkOutDate", "guests"],
-                },
+                // NEW: Required fields for route completion
+                requiredFields: ["customerName", "hotelName", "checkInDate", "checkOutDate", "guests"],
+                // NEW: Optional fields that enhance the experience
+                optionalFields: ["roomType", "specialRequests", "bookingId"],
                 steps: [
                     {
                         id: "ask_name",
@@ -179,7 +187,7 @@ async function handleChatRequest(request: ChatRequest): Promise<ChatResponse> {
         message: response.message,
         sessionId: agent.session.id!,
         isComplete: response.isRouteComplete!,
-        data: agent.session.getData<BookingData>(),
+        data: agent.session.getData(),
     };
 }
 

package/examples/persistence/database-persistence.ts

@@ -84,7 +84,7 @@ async function example() {
    */
   const sessionId = "session_user123_booking"; // Could be from request params
 
-  const agent = new Agent<ConversationContext>({
+  const agent = new Agent<ConversationContext, FlightBookingData>({
     name: "Travel Assistant",
     description: "A helpful travel booking assistant",
     goal: "Help users book flights with ease",
@@ -100,19 +100,6 @@ async function example() {
       adapter: new PrismaAdapter<ConversationContext>({ prisma }),
       autoSave: true, // Auto-saves session after each response
     },
-    sessionId, // ✨ Agent will automatically load or create this session
-  });
-
-  /**
-   * Create a route with data extraction schema
-   */
-  const flightRoute = agent.createRoute<FlightBookingData>({
-    title: "Book a Flight",
-    description: "Help user book a flight ticket",
-    conditions: [
-      "User wants to book a flight",
-      "User mentions travel, flying, or booking tickets",
-    ],
     schema: {
       type: "object",
       properties: {
@@ -143,6 +130,19 @@ async function example() {
       },
       required: ["destination", "departureDate", "passengers", "cabinClass"],
     },
+    sessionId, // ✨ Agent will automatically load or create this session
+  });
+
+  /**
+   * Create a route with data extraction schema
+   */
+  const flightRoute = agent.createRoute({
+    title: "Book a Flight",
+    description: "Help user book a flight ticket",
+    conditions: [
+      "User wants to book a flight",
+      "User mentions travel, flying, or booking tickets",
+    ],
   });
 
   // Step flow with smart data collecting and custom IDs
@@ -194,8 +194,8 @@ async function example() {
   console.log("📜 Conversation history:", agent.session.getHistory().length, "messages");
 
   // Set some initial data if this is a new session
-  if (!agent.session.getData<FlightBookingData>()?.cabinClass) {
-    await agent.session.setData<FlightBookingData>({ cabinClass: "economy" });
+  if (!agent.session.getData()?.cabinClass) {
+    await agent.session.setData({ cabinClass: "economy" });
   }
 
   /**
@@ -216,7 +216,7 @@ async function example() {
     sessionId: agent.session.id,
     currentRoute: response1.session?.currentRoute?.title,
     currentStepId: response1.session?.currentStep?.id,
-    data: agent.session.getData<FlightBookingData>(),
+    data: agent.session.getData(),
   });
 
   // Add agent response to session history
@@ -237,14 +237,14 @@ async function example() {
   console.log("📊 Session after turn 2:", {
     currentRoute: response2.session?.currentRoute?.title,
     currentStep: response2.session?.currentStep?.id,
-    data: agent.session.getData<FlightBookingData>(),
+    data: agent.session.getData(),
   });
 
   await agent.session.addMessage("assistant", response2.message);
 
   if (response2.isRouteComplete) {
     console.log("\n✅ Flight booking complete!");
-    await sendFlightConfirmation(agent.session.getData<FlightBookingData>());
+    await sendFlightConfirmation(agent.session.getData());
   }
 
   /**
@@ -252,7 +252,7 @@ async function example() {
    */
   console.log("\n--- Session Recovery (New Agent Instance) ---");
   
-  const newAgent = new Agent<ConversationContext>({
+  const newAgent = new Agent<ConversationContext, FlightBookingData>({
     name: "Travel Assistant",
     provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
@@ -262,6 +262,18 @@ async function example() {
       userId: "user_123",
       userName: "Alice",
     },
+    // NEW: Agent-level schema (same as original agent)
+    schema: {
+      type: "object",
+      properties: {
+        destination: { type: "string" },
+        departureDate: { type: "string" },
+        returnDate: { type: "string" },
+        passengers: { type: "number", minimum: 1, maximum: 9 },
+        cabinClass: { type: "string", enum: ["economy", "premium", "business", "first"] },
+      },
+      required: ["destination", "departureDate", "passengers", "cabinClass"],
+    },
     persistence: {
       adapter: new PrismaAdapter<ConversationContext>({ prisma }),
     },
@@ -271,7 +283,7 @@ async function example() {
   console.log("📥 Recovered session:", {
     sessionId: newAgent.session.id,
     historyLength: newAgent.session.getHistory().length,
-    data: newAgent.session.getData<FlightBookingData>(),
+    data: newAgent.session.getData(),
   });
 
   /**
@@ -308,7 +320,7 @@ async function advancedExample() {
     };
   }
 
-  const agent = new Agent<UserContext>({
+  const agent = new Agent<UserContext, OnboardingData>({
     name: "Onboarding Assistant",
     description: "Help new users get started",
     provider: new GeminiProvider({
@@ -357,12 +369,6 @@ async function advancedExample() {
       autoSave: true,
     },
     sessionId,
-  });
-
-  // Create onboarding route
-  const onboardingRoute = agent.createRoute<OnboardingData>({
-    title: "User Onboarding",
-    description: "Collect user information for account setup",
     schema: {
       type: "object",
       properties: {
@@ -375,6 +381,12 @@ async function advancedExample() {
     },
   });
 
+  // Create onboarding route
+  const onboardingRoute = agent.createRoute({
+    title: "User Onboarding",
+    description: "Collect user information for account setup",
+  });
+
   onboardingRoute.initialStep
     .nextStep({
       prompt: "Welcome and ask for name",
@@ -413,7 +425,7 @@ async function advancedExample() {
   });
 
   console.log("🤖 Agent:", response.message);
-  console.log("📊 Data collected:", agent.session.getData<OnboardingData>());
+  console.log("📊 Data collected:", agent.session.getData());
 
   // Add to session history for future responses
   await agent.session.addMessage("user", "I'd like to create an account");
@@ -427,12 +439,12 @@ async function advancedExample() {
   });
 
   console.log("🤖 Agent:", response2.message);
-  console.log("📊 Normalized data:", agent.session.getData<OnboardingData>());
+  console.log("📊 Normalized data:", agent.session.getData());
   // Shows normalized phone and email
 
   if (response2.isRouteComplete) {
     console.log("\n✅ Onboarding complete!");
-    await sendOnboardingEmail(agent.session.getData<OnboardingData>());
+    await sendOnboardingEmail(agent.session.getData());
   }
 
   await prisma.$disconnect();
@@ -450,32 +462,36 @@ async function serverEndpointExample() {
     message: "I need help, my name is John and my email is john@example.com",
   };
 
+  // Define contact form schema
+  const contactFormSchema = {
+    type: "object",
+    properties: {
+      name: { type: "string" },
+      email: { type: "string" },
+      message: { type: "string" },
+    },
+    required: ["name", "email", "message"],
+  };
+
   // Create agent with sessionId (loads existing or creates new)
-  const agent = new Agent({
+  const agent = new Agent<unknown, ContactFormData>({
     name: "Support Agent",
     provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
       model: "models/gemini-2.5-flash",
     }),
+    // NEW: Agent-level schema
+    schema: contactFormSchema,
     persistence: {
-      adapter: new PrismaAdapter<ContactFormData>({ prisma }),
+      adapter: new PrismaAdapter<unknown>({ prisma }),
       autoSave: true,
     },
     sessionId: requestData.sessionId, // ✨ Automatic session management
   });
 
   // Create a simple contact form route
-  const contactRoute = agent.createRoute<ContactFormData>({
+  const contactRoute = agent.createRoute({
     title: "Contact Form",
-    schema: {
-      type: "object",
-      properties: {
-        name: { type: "string" },
-        email: { type: "string" },
-        message: { type: "string" },
-      },
-      required: ["name", "email", "message"],
-    },
   });
 
   contactRoute.initialStep
@@ -502,14 +518,14 @@ async function serverEndpointExample() {
     message: response.message,
     sessionId: agent.session.id,
     isComplete: response.isRouteComplete,
-    data: agent.session.getData<ContactFormData>(),
+    data: agent.session.getData(),
   };
 
   console.log("✅ API Response:", apiResponse);
 
   if (response.isRouteComplete) {
     console.log("\n✅ Contact form submitted!");
-    await logContactForm(agent.session.getData<ContactFormData>());
+    await logContactForm(agent.session.getData());
   }
 
   await prisma.$disconnect();

package/examples/persistence/memory-sessions.ts

@@ -38,7 +38,7 @@ interface SupportContext {
 }
 
 // Support tools
-const createTicket: Tool<unknown, [], string, SupportTicketData> = {
+const createTicket: Tool<unknown, SupportTicketData, [], string> = {
   id: "create_support_ticket",
   description: "Create a new support ticket",
   parameters: {
@@ -62,38 +62,46 @@ const createTicket: Tool<unknown, [], string, SupportTicketData> = {
   },
 };
 
+// Define support ticket schema
+const supportTicketSchema = {
+  type: "object",
+  properties: {
+    issue: { type: "string" },
+    category: {
+      type: "string",
+      enum: ["technical", "billing", "account", "general"],
+    },
+    priority: { type: "string", enum: ["low", "medium", "high"] },
+    status: { type: "string", enum: ["open", "in_progress", "resolved"] },
+    ticketId: { type: "string" },
+    assignedAgent: { type: "string" },
+  },
+  required: ["issue"],
+};
+
 // Create agent with memory persistence
-const agent = new Agent({
+const agent = new Agent<unknown, SupportTicketData>({
   name: "SupportBot",
   description: "A support agent with memory-based session management",
   provider: new GeminiProvider({
     apiKey: process.env.GEMINI_API_KEY!,
     model: "models/gemini-2.5-flash",
   }),
+  // NEW: Agent-level schema
+  schema: supportTicketSchema,
   persistence: {
     adapter: new MemoryAdapter(),
   },
 });
 
 // Create support route with sequential steps
-const supportRoute = agent.createRoute<SupportTicketData>({
+const supportRoute = agent.createRoute({
   title: "Customer Support",
   description: "Handle customer support requests with session persistence",
-  schema: {
-    type: "object",
-    properties: {
-      issue: { type: "string" },
-      category: {
-        type: "string",
-        enum: ["technical", "billing", "account", "general"],
-      },
-      priority: { type: "string", enum: ["low", "medium", "high"] },
-      status: { type: "string", enum: ["open", "in_progress", "resolved"] },
-      ticketId: { type: "string" },
-      assignedAgent: { type: "string" },
-    },
-    required: ["issue"],
-  },
+  // NEW: Required fields for route completion
+  requiredFields: ["issue"],
+  // NEW: Optional fields that enhance the experience
+  optionalFields: ["category", "priority", "status", "ticketId", "assignedAgent"],
   // Sequential steps for support ticket creation
   steps: [
     {
@@ -138,7 +146,7 @@ async function demonstrateSessionBasics() {
 
   // Create agent with specific sessionId
   const sessionId = "session-user-123";
-  const sessionAgent = new Agent<SupportContext>({
+  const sessionAgent = new Agent<SupportContext, SupportTicketData>({
     name: "Support Assistant",
     description: "Help users with technical issues",
     provider: new GeminiProvider({
@@ -150,6 +158,8 @@ async function demonstrateSessionBasics() {
       userName: "Alice",
       userTier: "premium",
     },
+    // NEW: Agent-level schema
+    schema: supportTicketSchema,
     persistence: {
       adapter: new MemoryAdapter(),
       autoSave: true,
@@ -158,33 +168,22 @@ async function demonstrateSessionBasics() {
   });
 
   // Create the same route on the new agent
-  sessionAgent.createRoute<SupportTicketData>({
+  sessionAgent.createRoute({
     title: "Customer Support",
     description: "Handle customer support requests with session persistence",
-    schema: {
-      type: "object",
-      properties: {
-        issue: { type: "string" },
-        category: {
-          type: "string",
-          enum: ["technical", "billing", "account", "general"],
-        },
-        priority: { type: "string", enum: ["low", "medium", "high"] },
-        status: { type: "string", enum: ["open", "in_progress", "resolved"] },
-        ticketId: { type: "string" },
-        assignedAgent: { type: "string" },
-      },
-      required: ["issue"],
-    },
+    // NEW: Required fields for route completion
+    requiredFields: ["issue"],
+    // NEW: Optional fields that enhance the experience
+    optionalFields: ["category", "priority", "status", "ticketId", "assignedAgent"],
   });
 
   console.log("Session ready:", sessionAgent.session.id);
 
   // Use the session in conversation
   console.log("\nUser: I can't access my account");
-  
+
   await sessionAgent.session.addMessage("user", "I can't access my account", "Alice");
-  
+
   const response1 = await sessionAgent.respond({
     history: sessionAgent.session.getHistory(),
   });
@@ -192,9 +191,9 @@ async function demonstrateSessionBasics() {
   console.log("Bot:", response1.message);
   console.log(
     "Session data:",
-    JSON.stringify(sessionAgent.session.getData<SupportTicketData>(), null, 2)
+    JSON.stringify(sessionAgent.session.getData(), null, 2)
   );
-  
+
   await sessionAgent.session.addMessage("assistant", response1.message);
 
   // Continue the conversation with the returned session
@@ -331,8 +330,7 @@ async function demonstrateMultiUserSessions() {
 
     console.log(`   Session ID: ${response.session?.id}`);
     console.log(
-      `   Issue recorded: ${
-        (response.session?.data as Partial<SupportTicketData>)?.issue
+      `   Issue recorded: ${(response.session?.data as Partial<SupportTicketData>)?.issue
       }`
     );
   }
@@ -362,8 +360,8 @@ async function demonstrateSessionLifecycle() {
   // 1. Create agent with session
   console.log("1. 🆕 Creating new session");
   const sessionId = `lifecycle-demo-${Date.now()}`;
-  
-  const lifecycleAgent = new Agent<SupportContext>({
+
+  const lifecycleAgent = new Agent<SupportContext, SupportTicketData>({
     name: "Support Assistant",
     provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
@@ -374,6 +372,8 @@ async function demonstrateSessionLifecycle() {
       userName: "Demo",
       userTier: "standard",
     },
+    // NEW: Agent-level schema
+    schema: supportTicketSchema,
     persistence: {
       adapter: new MemoryAdapter(),
       autoSave: true,
@@ -382,39 +382,28 @@ async function demonstrateSessionLifecycle() {
   });
 
   // Create the same route on the lifecycle agent
-  lifecycleAgent.createRoute<SupportTicketData>({
+  lifecycleAgent.createRoute({
     title: "Customer Support",
     description: "Handle customer support requests with session persistence",
-    schema: {
-      type: "object",
-      properties: {
-        issue: { type: "string" },
-        category: {
-          type: "string",
-          enum: ["technical", "billing", "account", "general"],
-        },
-        priority: { type: "string", enum: ["low", "medium", "high"] },
-        status: { type: "string", enum: ["open", "in_progress", "resolved"] },
-        ticketId: { type: "string" },
-        assignedAgent: { type: "string" },
-      },
-      required: ["issue"],
-    },
+    // NEW: Required fields for route completion
+    requiredFields: ["issue"],
+    // NEW: Optional fields that enhance the experience
+    optionalFields: ["category", "priority", "status", "ticketId", "assignedAgent"],
   });
 
   console.log(`   Created session: ${lifecycleAgent.session.id}`);
 
   // 2. Use session in conversation
   console.log("\n2. 💬 Using session in conversation");
-  
+
   await lifecycleAgent.session.addMessage("user", "I need help with something", "Demo");
-  
+
   const response1 = await lifecycleAgent.respond({
     history: lifecycleAgent.session.getHistory(),
   });
 
-  console.log(`   Session data: ${JSON.stringify(lifecycleAgent.session.getData<SupportTicketData>())}`);
-  
+  console.log(`   Session data: ${JSON.stringify(lifecycleAgent.session.getData())}`);
+
   await lifecycleAgent.session.addMessage("assistant", response1.message);
 
   // 3. Complete the session