@falai/agent 0.9.0-alpha-1 → 0.9.0

package/examples/integrations/search-integration.ts

@@ -88,8 +88,38 @@ async function example() {
   // Initialize indices
   await adapter.initialize();
 
+  // Define complaint schema
+  const complaintSchema = {
+    type: "object",
+    properties: {
+      category: {
+        type: "string",
+        description: "Complaint category",
+      },
+      severity: {
+        type: "string",
+        enum: ["low", "medium", "high", "critical"],
+        default: "medium",
+        description: "Severity level",
+      },
+      description: {
+        type: "string",
+        description: "Detailed complaint description",
+      },
+      affectedService: {
+        type: "string",
+        description: "Which service is affected",
+      },
+      requestedResolution: {
+        type: "string",
+        description: "What resolution the customer wants",
+      },
+    },
+    required: ["category", "severity", "description"],
+  };
+
   // Create agent with OpenSearch persistence
-  const agent = new Agent<ConversationContext>({
+  const agent = new Agent<ConversationContext, ComplaintData>({
     name: "Customer Service Agent",
     description: "Handle customer complaints with full-text search",
     goal: "Resolve customer issues efficiently",
@@ -102,6 +132,8 @@ async function example() {
       userName: "Alice",
       department: "customer_service",
     },
+    // NEW: Agent-level schema
+    schema: complaintSchema,
     persistence: {
       adapter,
       autoSave: true, // Auto-save session step with collected data
@@ -110,7 +142,7 @@ async function example() {
   });
 
   // Create complaint handling route
-  const complaintRoute = agent.createRoute<ComplaintData>({
+  const complaintRoute = agent.createRoute({
     title: "Handle Customer Complaint",
     description: "Process and resolve customer complaints",
     conditions: [
@@ -118,34 +150,10 @@ async function example() {
       "User reports an issue or problem",
       "User is dissatisfied",
     ],
-    schema: {
-      type: "object",
-      properties: {
-        category: {
-          type: "string",
-          description: "Complaint category",
-        },
-        severity: {
-          type: "string",
-          enum: ["low", "medium", "high", "critical"],
-          default: "medium",
-          description: "Severity level",
-        },
-        description: {
-          type: "string",
-          description: "Detailed complaint description",
-        },
-        affectedService: {
-          type: "string",
-          description: "Which service is affected",
-        },
-        requestedResolution: {
-          type: "string",
-          description: "What resolution the customer wants",
-        },
-      },
-      required: ["category", "severity", "description"],
-    },
+    // NEW: Required fields for route completion
+    requiredFields: ["category", "severity", "description"],
+    // NEW: Optional fields that enhance the experience
+    optionalFields: ["affectedService", "requestedResolution"],
   });
 
   // Step flow
@@ -177,7 +185,7 @@ async function example() {
   console.log("✨ Session ready:", agent.session.id);
   
   // Set initial data
-  await agent.session.setData<ComplaintData>({ severity: "medium" });
+  await agent.session.setData({ severity: "medium" });
 
   // Turn 1
   console.log("\n--- Turn 1 ---");
@@ -193,7 +201,7 @@ async function example() {
   });
 
   console.log("🤖 Agent:", response1.message);
-  console.log("📊 Data:", agent.session.getData<ComplaintData>());
+  console.log("📊 Data:", agent.session.getData());
   
   await agent.session.addMessage("assistant", response1.message);
 
@@ -211,20 +219,20 @@ async function example() {
   });
 
   console.log("🤖 Agent:", response2.message);
-  console.log("📊 Data:", agent.session.getData<ComplaintData>());
+  console.log("📊 Data:", agent.session.getData());
 
   await agent.session.addMessage("assistant", response2.message);
 
   if (response2.isRouteComplete) {
     console.log("\n✅ Complaint route complete!");
-    await createSupportTicket(agent.session.getData<ComplaintData>() as ComplaintData);
+    await createSupportTicket(agent.session.getData() as ComplaintData);
   }
 
   // Demonstrate session recovery with new agent instance
   console.log("\n--- Session Recovery Example ---");
   const sessionId = agent.session.id;
   
-  const recoveredAgent = new Agent<ConversationContext>({
+  const recoveredAgent = new Agent<ConversationContext, ComplaintData>({
     name: "Customer Service Agent",
     provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
@@ -243,7 +251,7 @@ async function example() {
   });
 
   // Recreate the same route on recovered agent
-  recoveredAgent.createRoute<ComplaintData>({
+  recoveredAgent.createRoute({
     title: "Handle Customer Complaint",
     description: "Process and resolve customer complaints",
     conditions: [
@@ -251,28 +259,16 @@ async function example() {
       "User reports an issue or problem",
       "User is dissatisfied",
     ],
-    schema: {
-      type: "object",
-      properties: {
-        category: { type: "string", description: "Complaint category" },
-        severity: {
-          type: "string",
-          enum: ["low", "medium", "high", "critical"],
-          default: "medium",
-          description: "Severity level",
-        },
-        description: { type: "string", description: "Detailed complaint description" },
-        affectedService: { type: "string", description: "Which service is affected" },
-        requestedResolution: { type: "string", description: "What resolution the customer wants" },
-      },
-      required: ["category", "severity", "description"],
-    },
+    // NEW: Required fields for route completion
+    requiredFields: ["category", "severity", "description"],
+    // NEW: Optional fields
+    optionalFields: ["affectedService", "requestedResolution"],
   });
 
   console.log("📥 Recovered session:", {
     sessionId: recoveredAgent.session.id,
     historyLength: recoveredAgent.session.getHistory().length,
-    data: recoveredAgent.session.getData<ComplaintData>(),
+    data: recoveredAgent.session.getData(),
   });
 
   // Demonstrate full-text search
@@ -344,12 +340,27 @@ async function analyticsExample() {
     tags: string[];
   }
 
-  const agent = new Agent<ConversationContext>({
+  const ticketSchema = {
+    type: "object",
+    properties: {
+      ticketType: { type: "string" },
+      priority: { type: "string" },
+      tags: {
+        type: "array",
+        items: { type: "string" },
+      },
+    },
+    required: ["ticketType", "priority"],
+  };
+
+  const agent = new Agent<ConversationContext, TicketData>({
     name: "Support Analyzer",
     provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
       model: "models/gemini-2.5-flash",
     }),
+    // NEW: Agent-level schema
+    schema: ticketSchema,
     persistence: {
       adapter,
       autoSave: true,
@@ -357,20 +368,12 @@ async function analyticsExample() {
     },
   });
 
-  const ticketRoute = agent.createRoute<TicketData>({
+  const ticketRoute = agent.createRoute({
     title: "Analyze Support Ticket",
-    schema: {
-      type: "object",
-      properties: {
-        ticketType: { type: "string" },
-        priority: { type: "string" },
-        tags: {
-          type: "array",
-          items: { type: "string" },
-        },
-      },
-      required: ["ticketType", "priority"],
-    },
+    // NEW: Required fields for route completion
+    requiredFields: ["ticketType", "priority"],
+    // NEW: Optional fields
+    optionalFields: ["tags"],
   });
 
   ticketRoute.initialStep.nextStep({
@@ -380,7 +383,7 @@ async function analyticsExample() {
 
   // Create multiple sessions with different agents
   for (let i = 0; i < 3; i++) {
-    const sessionAgent = new Agent<AnalyticsContext>({
+    const sessionAgent = new Agent<AnalyticsContext, TicketData>({
       name: "Support Analyzer",
       provider: new GeminiProvider({
         apiKey: process.env.GEMINI_API_KEY!,
@@ -390,6 +393,8 @@ async function analyticsExample() {
         userId: "analyst_001",
         department: "support",
       },
+      // NEW: Agent-level schema
+      schema: ticketSchema,
       persistence: {
         adapter: new OpenSearchAdapter<AnalyticsContext>(client),
         autoSave: true,
@@ -397,20 +402,12 @@ async function analyticsExample() {
     });
 
     // Create the ticket route on each agent
-    sessionAgent.createRoute<TicketData>({
+    sessionAgent.createRoute({
       title: "Analyze Support Ticket",
-      schema: {
-        type: "object",
-        properties: {
-          ticketType: { type: "string" },
-          priority: { type: "string" },
-          tags: {
-            type: "array",
-            items: { type: "string" },
-          },
-        },
-        required: ["ticketType", "priority"],
-      },
+      // NEW: Required fields for route completion
+      requiredFields: ["ticketType", "priority"],
+      // NEW: Optional fields
+      optionalFields: ["tags"],
     });
 
     const ticketContent = `Support ticket ${i + 1}: ${
@@ -474,7 +471,7 @@ async function timeSeriesExample() {
   const adapter = new OpenSearchAdapter<ConversationContext>(client);
   await adapter.initialize();
 
-  new Agent<ConversationContext>({
+  new Agent<ConversationContext, unknown>({
     name: "Metrics Agent",
     provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,

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();