@falai/agent 0.9.0-alpha-2 → 0.9.2

package/examples/core-concepts/session-management.ts

@@ -17,6 +17,7 @@ import {
   GeminiProvider,
   MemoryAdapter,
   type Tool,
+  ValidationError,
 } from "../../src/index";
 
 // Define data types for our multi-step process
@@ -36,23 +37,23 @@ interface OrderContext {
 }
 
 interface PaymentData {
-  orderId: string;
+  orderId?: string; // Make this optional to match OrderData
   paymentMethod: "credit_card" | "paypal" | "bank_transfer";
   amount: number;
   confirmed: boolean;
 }
 
-// Tools for order processing
-const createOrder: Tool<unknown, UnifiedOrderData, [], string> = {
+// Tools for order processing - using unified Tool interface
+const createOrderTool: Tool<unknown, UnifiedOrderData> = {
   id: "create_order",
   description: "Create a new order from the collected order data",
   parameters: {
     type: "object",
     properties: {},
   },
-  handler: ({ data }) => {
+  handler: (context, args) => {
     const orderId = `ORD-${Date.now()}`;
-    console.log(`Creating order ${orderId} for ${data?.customerName}`);
+    console.log(`Creating order ${orderId} for ${context.data?.customerName}`);
 
     return {
       data: `Order ${orderId} created successfully!`,
@@ -63,22 +64,22 @@ const createOrder: Tool<unknown, UnifiedOrderData, [], string> = {
   },
 };
 
-const processPayment: Tool<unknown, UnifiedOrderData, [], string> = {
+const processPaymentTool: Tool<unknown, UnifiedOrderData> = {
   id: "process_payment",
   description: "Process payment for an order",
   parameters: {
     type: "object",
     properties: {},
   },
-  handler: ({ data }) => {
-    console.log(`Processing payment for order ${data?.orderId}`);
+  handler: (context, args) => {
+    console.log(`Processing payment for order ${context.data?.orderId}`);
 
     // Simulate payment processing
     const success = Math.random() > 0.1; // 90% success rate
 
     if (success) {
       return {
-        data: `Payment processed successfully! Order ${data?.orderId} is now confirmed.`,
+        data: `Payment processed successfully! Order ${context.data?.orderId} is now confirmed.`,
         dataUpdate: {
           confirmed: true,
         },
@@ -133,6 +134,58 @@ const agent = new Agent<unknown, UnifiedOrderData>({
   },
 });
 
+// Demonstrate different tool registration patterns
+
+// Method 1: Register tools for ID-based reference in steps
+agent.tool.register(createOrderTool);
+agent.tool.register(processPaymentTool);
+
+// Method 2: Create specialized validation tool
+const orderValidationTool = agent.tool.createValidation({
+  id: "validate_order",
+  fields: ["customerName", "productType", "budget"] as const,
+  validator: async (context, data) => {
+    const errors: ValidationError[] = [];
+    if (!data.customerName || data.customerName.length < 2) {
+      errors.push({ 
+        field: "customerName", 
+        value: data.customerName,
+        message: "Customer name must be at least 2 characters",
+        schemaPath: "customerName"
+      });
+    }
+    if (!data.budget || data.budget < 100) {
+      errors.push({ 
+        field: "budget", 
+        value: data.budget,
+        message: "Budget must be at least $100",
+        schemaPath: "budget"
+      });
+    }
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings: [],
+    };
+  },
+});
+
+// Method 3: Create data enrichment tool
+const orderEnrichmentTool = agent.tool.createDataEnrichment({
+  id: "enrich_order",
+  fields: ["productType", "budget"] as const,
+  enricher: async (context, data) => {
+    // Enrich with fields that exist in UnifiedOrderData
+    const urgentDelivery = data.budget > 1000; // Premium orders get urgent delivery
+    const preferredColor = data.productType === "laptop" ? "silver" : "black";
+    
+    return {
+      urgentDelivery,
+      preferredColor,
+    };
+  },
+});
+
 // Order collection route with sequential steps
 agent.createRoute({
   title: "Product Order",
@@ -186,7 +239,7 @@ agent.createRoute({
       id: "create_order",
       description: "Create the order",
       prompt: "Great! Let me create your order.",
-      tools: [createOrder],
+      tools: ["create_order"], // Reference by ID
       requires: ["customerName", "productType", "budget"],
     },
   ],
@@ -226,7 +279,7 @@ agent.createRoute({
       id: "process_payment",
       description: "Process the payment",
       prompt: "Processing your payment...",
-      tools: [processPayment],
+      tools: ["process_payment"], // Reference by ID
       requires: ["orderId", "paymentMethod", "amount"],
     },
   ],
@@ -266,7 +319,7 @@ async function demonstrateSessionManagement() {
 
   console.log("Bot:", response1.message);
   console.log("Session ID:", sessionAgent.session.id);
-  console.log("Session data:", JSON.stringify(sessionAgent.session.getData<UnifiedOrderData>(), null, 2));
+  console.log("Session data:", JSON.stringify(sessionAgent.session.getData(), null, 2));
   console.log("History length:", sessionAgent.session.getHistory().length);
   console.log();
 
@@ -277,7 +330,7 @@ async function demonstrateSessionManagement() {
   const response2 = await sessionAgent.chat("My budget is $1500");
 
   console.log("Bot:", response2.message);
-  console.log("Session data:", JSON.stringify(sessionAgent.session.getData<UnifiedOrderData>(), null, 2));
+  console.log("Session data:", JSON.stringify(sessionAgent.session.getData(), null, 2));
   console.log("History length:", sessionAgent.session.getHistory().length);
   console.log();
 
@@ -288,7 +341,7 @@ async function demonstrateSessionManagement() {
   const response3 = await sessionAgent.chat("I want black color and urgent delivery please");
 
   console.log("Bot:", response3.message);
-  console.log("Session data:", JSON.stringify(sessionAgent.session.getData<UnifiedOrderData>(), null, 2));
+  console.log("Session data:", JSON.stringify(sessionAgent.session.getData(), null, 2));
   console.log("Route complete:", response3.isRouteComplete);
   console.log("History length:", sessionAgent.session.getHistory().length);
   console.log();
@@ -300,7 +353,7 @@ async function demonstrateSessionManagement() {
   const response4 = await sessionAgent.chat("I'll pay with credit card, amount is $1599");
 
   console.log("Bot:", response4.message);
-  console.log("Session data:", JSON.stringify(sessionAgent.session.getData<UnifiedOrderData>(), null, 2));
+  console.log("Session data:", JSON.stringify(sessionAgent.session.getData(), null, 2));
   console.log("Route complete:", response4.isRouteComplete);
   console.log("Final history length:", sessionAgent.session.getHistory().length);
 }
@@ -344,7 +397,7 @@ async function demonstrateSessionPersistence() {
 
   console.log("After first interaction:");
   console.log("🤖 Agent:", response1.message);
-  console.log("Session data:", JSON.stringify(persistentAgent.session.getData<UnifiedOrderData>(), null, 2));
+  console.log("Session data:", JSON.stringify(persistentAgent.session.getData(), null, 2));
   console.log("History length:", persistentAgent.session.getHistory().length);
   console.log("Session automatically saved to persistence ✓");
 
@@ -379,14 +432,14 @@ async function demonstrateSessionPersistence() {
   console.log("Session automatically restored:");
   console.log("- Session ID:", restoredAgent.session.id);
   console.log("- History length:", restoredAgent.session.getHistory().length);
-  console.log("- Restored data:", JSON.stringify(restoredAgent.session.getData<UnifiedOrderData>(), null, 2));
+  console.log("- Restored data:", JSON.stringify(restoredAgent.session.getData(), null, 2));
 
   // Continue conversation seamlessly
   const response2 = await restoredAgent.chat("Actually, make it urgent delivery");
 
   console.log("\nAfter continuing with restored session:");
   console.log("🤖 Agent:", response2.message);
-  console.log("Session data:", JSON.stringify(restoredAgent.session.getData<UnifiedOrderData>(), null, 2));
+  console.log("Session data:", JSON.stringify(restoredAgent.session.getData(), null, 2));
   console.log("History length:", restoredAgent.session.getHistory().length);
   console.log("Session automatically saved again ✓");
 }

package/examples/integrations/healthcare-integration.ts

@@ -39,7 +39,7 @@ interface SatisfactionData {
 
 // Tools
 
-const getUpcomingSlots: Tool<HealthcareContext, HealthcareData, unknown[], unknown> = {
+const getUpcomingSlots: Tool<HealthcareContext, HealthcareData> = {
   id: "get_upcoming_slots",
   name: "Available Appointment Slots",
   description: "Get upcoming appointment slots",
@@ -47,12 +47,12 @@ const getUpcomingSlots: Tool<HealthcareContext, HealthcareData, unknown[], unkno
     type: "object",
     properties: {},
   },
-  handler: () => {
-    return { data: ["Monday 10 AM", "Tuesday 2 PM", "Wednesday 1 PM"] };
+  handler: (context, args) => {
+    return { data: "Available slots: Monday 10 AM, Tuesday 2 PM, Wednesday 1 PM" };
   },
 };
 
-const getLaterSlots: Tool<HealthcareContext, HealthcareData, unknown[], unknown> = {
+const getLaterSlots: Tool<HealthcareContext, HealthcareData> = {
   id: "get_later_slots",
   name: "Extended Appointment Slots",
   description: "Get later appointment slots",
@@ -60,17 +60,12 @@ const getLaterSlots: Tool<HealthcareContext, HealthcareData, unknown[], unknown>
     type: "object",
     properties: {},
   },
-  handler: () => {
-    return { data: ["November 3, 11:30 AM", "November 12, 3 PM"] };
+  handler: (context, args) => {
+    return { data: "Later slots: November 3, 11:30 AM, November 12, 3 PM" };
   },
 };
 
-const scheduleAppointment: Tool<
-  HealthcareContext,
-  HealthcareData,
-  unknown[],
-  unknown
-> = {
+const scheduleAppointment: Tool<HealthcareContext, HealthcareData> = {
   id: "schedule_appointment",
   name: "Appointment Scheduler",
   description: "Schedule an appointment with a healthcare provider",
@@ -81,26 +76,21 @@ const scheduleAppointment: Tool<
     },
     required: ["datetime"],
   },
-  handler: ({ data }) => {
-    if (!data?.preferredDate || !data?.preferredTime) {
+  handler: (context, args) => {
+    if (!context.data?.preferredDate || !context.data?.preferredTime) {
       return {
         data: "Please specify preferred date and time for the appointment",
       };
     }
     return {
-      data: `Appointment scheduled for ${data.preferredDate} at ${
-        data.preferredTime
-      } for ${data.appointmentReason || "consultation"}`,
+      data: `Appointment scheduled for ${context.data.preferredDate} at ${
+        context.data.preferredTime
+      } for ${context.data.appointmentReason || "consultation"}`,
     };
   },
 };
 
-const getLabResults: Tool<
-  HealthcareContext,
-  HealthcareData,
-  unknown[],
-  unknown
-> = {
+const getLabResults: Tool<HealthcareContext, HealthcareData> = {
   id: "get_lab_results",
   name: "Lab Results Retriever",
   description: "Get lab test results",
@@ -108,13 +98,9 @@ const getLabResults: Tool<
     type: "object",
     properties: {},
   },
-  handler: ({ context, data }) => {
+  handler: (context, args) => {
     return {
-      data: {
-        report: `Lab results for ${data?.testType || "general"} tests`,
-        prognosis: "All tests are within the valid range",
-        patientName: context.patientName,
-      },
+      data: `Lab results for ${context.data?.testType || "general"} tests: All tests are within the valid range for ${context.context.patientName}`,
     };
   },
 };

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

@@ -31,15 +31,15 @@ interface BookingData {
 }
 
 // Booking confirmation tool
-const confirmBooking: Tool<unknown, BookingData, [], string> = {
+const confirmBooking: Tool<unknown, BookingData> = {
     id: "confirm_booking",
     description: "Confirm the hotel booking with all details",
     parameters: {
         type: "object",
         properties: {},
     },
-    handler: ({ data }) => {
-        const bookingData = data as Partial<BookingData>;
+    handler: (context, args) => {
+        const bookingData = context.data;
         const bookingId = `BK-${Date.now()}`;
 
         console.log(`📋 Confirming booking ${bookingId} for ${bookingData.customerName}`);

package/examples/persistence/memory-sessions.ts

@@ -38,15 +38,15 @@ interface SupportContext {
 }
 
 // Support tools
-const createTicket: Tool<unknown, SupportTicketData, [], string> = {
+const createTicket: Tool<unknown, SupportTicketData> = {
   id: "create_support_ticket",
   description: "Create a new support ticket",
   parameters: {
     type: "object",
     properties: {},
   },
-  handler: ({ data }) => {
-    const ticketData = data as Partial<SupportTicketData>;
+  handler: (context, args) => {
+    const ticketData = context.data;
     const ticketId = `TICKET-${Date.now()}`;
     console.log(
       `Creating ticket ${ticketId} for ${ticketData?.category} issue`