@falai/agent 0.9.0 → 0.9.2

package/examples/core-concepts/basic-agent.ts

@@ -13,9 +13,10 @@
 import {
   Agent,
   GeminiProvider,
+  Tool,
+  ValidationError,
   type Term,
   type Guideline,
-  type Tool,
   type RouteOptions,
 } from "../../src/index";
 
@@ -40,98 +41,71 @@ interface LabData {
   resultsNeeded: boolean;
 }
 
-// Define tools using the new Tool interface
-const getInsuranceProviders: Tool<HealthcareContext, HealthcareData, [], string[]> = {
+// Define tools using unified Tool interface
+const getInsuranceProvidersTool: Tool<HealthcareContext, HealthcareData> = {
   id: "healthcare_insurance_providers",
   description: "Retrieves list of accepted insurance providers",
   parameters: {
     type: "object",
     properties: {},
   },
-  handler: () => {
+  handler: async (context, args) => {
     return {
-      data: ["MegaCare Insurance", "HealthFirst", "WellnessPlus"],
+      data: "Available insurance providers: MegaCare Insurance, HealthFirst, WellnessPlus",
     };
   },
 };
 
-const getAvailableSlots: Tool<
-  HealthcareContext,
-  HealthcareData,
-  [],
-  { date: string; time: string }[]
-> = {
+const getAvailableSlotsTool: Tool<HealthcareContext, HealthcareData> = {
   id: "healthcare_available_slots",
   description: "Gets available appointment slots",
   parameters: {
     type: "object",
     properties: {},
   },
-  handler: () => {
+  handler: async (context, args) => {
     return {
-      data: [
-        { date: "2025-10-20", time: "10:00 AM" },
-        { date: "2025-10-20", time: "2:00 PM" },
-        { date: "2025-10-21", time: "1:00 PM" },
-      ],
+      data: "Available slots: Oct 20 at 10:00 AM, Oct 20 at 2:00 PM, Oct 21 at 1:00 PM",
     };
   },
 };
 
-const getLabResults: Tool<
-  HealthcareContext,
-  HealthcareData,
-  [],
-  { report: string; status: string }
-> = {
+const getLabResultsTool: Tool<HealthcareContext, HealthcareData> = {
   id: "healthcare_lab_results",
   description: "Retrieves patient lab results",
   parameters: {
     type: "object",
     properties: {},
   },
-  handler: ({ context, data }) => {
+  handler: async (toolContext, args) => {
     // Tools can access collected data and context
-    if (data?.testType) {
+    if (toolContext.data?.testType) {
       return {
-        data: {
-          report: `${data.testType} results for ${context.patientName}`,
-          status: "All values within normal range",
-        },
+        data: `${toolContext.data.testType} results for ${toolContext.context.patientName}: All values within normal range`,
       };
     }
 
     return {
-      data: {
-        report: `Lab results for ${context.patientName}`,
-        status: "All values within normal range",
-      },
+      data: `Lab results for ${toolContext.context.patientName}: All values within normal range`,
     };
   },
 };
 
-const scheduleAppointment: Tool<
-  HealthcareContext,
-  HealthcareData,
-  [],
-  { confirmation: string }
-> = {
+const scheduleAppointmentTool: Tool<HealthcareContext, HealthcareData> = {
   id: "healthcare_schedule_appointment",
   description: "Schedules patient appointments",
   parameters: {
     type: "object",
     properties: {},
   },
-  handler: ({ data }) => {
+  handler: async (context, args) => {
     // Tools access collected appointment data
-    if (!data?.preferredDate || !data?.preferredTime) {
-      return { data: { confirmation: "Please provide appointment details" } };
+    if (!context.data?.preferredDate || !context.data?.preferredTime) {
+      return { data: "Please provide appointment details" };
     }
 
     return {
-      data: {
-        confirmation: `Appointment scheduled for ${data.preferredDate} at ${data.preferredTime}`,
-      },
+      data: `Appointment scheduled for ${context.data.preferredDate} at ${context.data.preferredTime}`,
     };
   },
 };
@@ -175,7 +149,7 @@ const guidelines: Guideline<HealthcareContext>[] = [
   },
 ];
 
-const routes: RouteOptions<HealthcareContext, HealthcareData>[] = [
+const routes = [
   {
     id: "route_schedule_appointment",
     title: "Schedule Appointment",
@@ -221,27 +195,13 @@ const routes: RouteOptions<HealthcareContext, HealthcareData>[] = [
         id: "schedule_appointment",
         description: "Schedule the appointment",
         prompt: "I'll schedule your appointment now.",
-        tools: [scheduleAppointment], // Use the scheduling tool
+        tools: ["healthcare_schedule_appointment"], // Reference by ID
         requires: ["preferredDate", "preferredTime"],
-        prepare: getInsuranceProviders, // Use existing tool to prepare insurance info
-        finalize: {
-          // Inline tool to handle appointment finalization
-          id: "finalize_appointment",
-          description: "Complete the appointment booking process",
-          parameters: { type: "object", properties: {} },
-          handler: ({ context, data }) => {
-            console.log(`✅ Appointment finalized for ${context.patientName}`);
-            console.log(`📅 Details: ${JSON.stringify(data, null, 2)}`);
-
-            // Could send confirmation email, update calendar, etc.
-            return {
-              data: `Appointment confirmed for ${context.patientName}`,
-            };
-          },
-        },
+        prepare: "healthcare_insurance_providers", // Reference by ID
+        finalize: "finalize_appointment", // Reference by ID - will be registered later
       },
     ],
-    tools: [getAvailableSlots], // Route-level tools available to all steps
+    tools: ["healthcare_available_slots"], // Reference by ID
   },
   {
     id: "route_check_lab_results",
@@ -260,7 +220,7 @@ const routes: RouteOptions<HealthcareContext, HealthcareData>[] = [
         tags: ["escalation"],
       },
     ],
-    tools: [getLabResults], // Route-level tools
+    tools: ["healthcare_lab_results"], // Reference by ID
   },
   {
     title: "General Healthcare Questions",
@@ -334,8 +294,87 @@ const agent = new Agent<HealthcareContext, HealthcareData>({
   // Declarative initialization
   terms,
   guidelines,
-  tools: [getInsuranceProviders], // Agent-level tools
-  routes,
+});
+
+// Demonstrate different tool registration approaches
+
+// Method 1: Register tools for ID-based reference in routes
+agent.tool.registerMany([
+  getInsuranceProvidersTool,
+  getAvailableSlotsTool,
+  getLabResultsTool,
+  scheduleAppointmentTool,
+]);
+
+// Method 2: Create and register specialized tools
+const appointmentValidator = agent.tool.createValidation({
+  id: "validate_appointment",
+  fields: ["appointmentType", "preferredDate", "preferredTime"] as const,
+  validator: async (context, data) => {
+    const errors: ValidationError[] = [];
+    if (!data.appointmentType) errors.push({ 
+      field: "appointmentType", 
+      value: data.appointmentType,
+      message: "Appointment type is required",
+      schemaPath: "appointmentType"
+    });
+    if (!data.preferredDate) errors.push({ 
+      field: "preferredDate", 
+      value: data.preferredDate,
+      message: "Preferred date is required",
+      schemaPath: "preferredDate"
+    });
+    if (!data.preferredTime) errors.push({ 
+      field: "preferredTime", 
+      value: data.preferredTime,
+      message: "Preferred time is required",
+      schemaPath: "preferredTime"
+    });
+    
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings: [],
+    };
+  },
+});
+
+// Method 3: Create data enrichment tool
+const patientDataEnricher = agent.tool.createDataEnrichment({
+  id: "enrich_patient_data",
+  fields: ["appointmentType", "symptoms"] as const,
+  enricher: async (context, data) => {
+    // Add urgency classification based on symptoms - return fields that exist in HealthcareData
+    const urgentKeywords = ["chest pain", "difficulty breathing", "severe", "emergency"];
+    const hasUrgentSymptoms = data.symptoms && urgentKeywords.some(keyword => 
+      data.symptoms!.toLowerCase().includes(keyword)
+    );
+    
+    return {
+      urgency: hasUrgentSymptoms ? "high" : "medium", // This matches the urgency field in HealthcareData
+    };
+  },
+});
+
+// Method 4: Create tool using tool.create()
+const finalizeAppointmentTool = agent.tool.create({
+  id: "finalize_appointment",
+  description: "Complete the appointment booking process",
+  parameters: { type: "object", properties: {} },
+  handler: async (context, args) => {
+    console.log(`✅ Appointment finalized for ${context.context.patientName}`);
+    console.log(`📅 Details: ${JSON.stringify(context.data, null, 2)}`);
+
+    // Could send confirmation email, update calendar, etc.
+    return {
+      data: `Appointment confirmed for ${context.context.patientName}`,
+    };
+  },
+});
+
+// Add routes after tools are registered
+routes.forEach((route: any) => {
+  agent.createRoute(route);
 });
 
 // You can still add more dynamically after construction

package/examples/core-concepts/schema-driven-extraction.ts

@@ -23,22 +23,22 @@ interface UserProfileData {
   newsletterOptIn: boolean;
 }
 
-// Define a tool that uses the collected data
-const saveUserProfile: Tool<unknown, UserProfileData, [], string> = {
+// Define a tool that uses the collected data - using unified Tool interface
+const saveUserProfileTool: Tool<unknown, UserProfileData> = {
   id: "save_user_profile",
   description: "Save the collected user profile information",
   parameters: {
     type: "object",
     properties: {},
   },
-  handler: ({ data }) => {
-    console.log("Saving user profile:", data);
+  handler: async (context, args) => {
+    console.log("Saving user profile:", context.data);
 
     // Simulate saving to database
-    console.log("Profile data:", data);
+    console.log("Profile data:", context.data);
 
     return {
-      data: `Profile saved successfully! Welcome ${data?.name}!`,
+      data: `Profile saved successfully! Welcome ${context.data?.name}!`,
     };
   },
 };
@@ -99,6 +99,9 @@ const agent = new Agent<unknown, UserProfileData>({
   schema: userProfileSchema,
 });
 
+// Add tool using unified interface
+agent.addTool(saveUserProfileTool);
+
 // Create a route that collects profile information step by step
 agent.createRoute({
   title: "User Profile Collection",
@@ -163,7 +166,7 @@ agent.createRoute({
       description: "Save the collected profile",
       prompt:
         "Thanks for providing your information! Let me save your profile.",
-      tools: [saveUserProfile],
+      tools: ["save_user_profile"], // Reference by ID
       requires: ["name", "email"],
     },
   ],

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`