@falai/agent 0.5.5 → 0.6.1

package/docs/PERSISTENCE.md

@@ -110,7 +110,7 @@ const agent = new Agent({
 // Create a route with data extraction
 const bookingRoute = agent.createRoute<BookingData>({
   title: "Book Flight",
-  gatherSchema: {
+  extractionSchema: {
     type: "object",
     properties: {
       destination: { type: "string" },
@@ -273,7 +273,7 @@ await agent.updateContext({ preferences: { theme: "dark" } });
 The new architecture automatically saves and loads `SessionState<TExtracted>` which includes:
 
 - **Current route and state** - Track conversation progress
-- **Extracted data** - All data gathered via `gatherSchema` and `gather` fields
+- **Extracted data** - All data gathered via `extractionSchema` and `gather` fields
 - **Route history** - History of route transitions
 - **Metadata** - Session timestamps and custom data
 
@@ -533,7 +533,7 @@ await persistence.saveMessage({
 
 1. ✅ **Use `createSessionWithState()`** - Get both database record and session state in one call
 2. ✅ **Enable `autoSave: true`** - Automatically persist session state after each response
-3. ✅ **Define extraction schemas** - Use `gatherSchema` in routes for structured data collection
+3. ✅ **Define extraction schemas** - Use `extractionSchema` in routes for structured data collection
 4. ✅ **Pass session state** - Always pass `session` parameter to `agent.respond()`
 5. ✅ **Load session state** - Use `loadSessionState()` to resume conversations
 6. ✅ **Store extracted data** - Leverage `collectedData.extracted` for user input tracking

package/examples/business-onboarding.ts

@@ -446,10 +446,10 @@ async function createBusinessOnboardingAgent(
   });
 
   // Step 1: Business basics - Save
-  const saveBusiness = askBusiness.transitionTo(
-    { toolState: saveBusinessInfo },
-    "User provided company name, sector, and description"
-  );
+  const saveBusiness = askBusiness.transitionTo({
+    toolState: saveBusinessInfo,
+    condition: "User provided company name, sector, and description",
+  });
 
   // Step 2: Products/Services - Ask
   const askProducts = saveBusiness.transitionTo({
@@ -458,10 +458,10 @@ async function createBusinessOnboardingAgent(
   });
 
   // Step 2: Products/Services - Save
-  const saveProducts = askProducts.transitionTo(
-    { toolState: saveProductsServices },
-    "User listed products/services and target audience"
-  );
+  const saveProducts = askProducts.transitionTo({
+    toolState: saveProductsServices,
+    condition: "User listed products/services and target audience",
+  });
 
   // Step 3: Location - Branch point
   const askLocation = saveProducts.transitionTo({
@@ -470,32 +470,28 @@ async function createBusinessOnboardingAgent(
   });
 
   // Step 3a: Physical store path
-  const askPhysicalLocation = askLocation.transitionTo(
-    {
-      chatState:
-        "I see! Since you have a physical presence, I need the complete address (street, number, city, and state) and business hours. This is important for your assistant to inform customers. (e.g., 'José Silva Street, 123, São Paulo - SP - Mon to Fri: 9am to 6pm')",
-    },
-    "User has a physical store"
-  );
+  const askPhysicalLocation = askLocation.transitionTo({
+    chatState:
+      "I see! Since you have a physical presence, I need the complete address (street, number, city, and state) and business hours. This is important for your assistant to inform customers. (e.g., 'José Silva Street, 123, São Paulo - SP - Mon to Fri: 9am to 6pm')",
+    condition: "User has a physical store",
+  });
 
-  const savePhysicalLocation = askPhysicalLocation.transitionTo(
-    { toolState: saveLocationInfo },
-    "User provided physical address"
-  );
+  const savePhysicalLocation = askPhysicalLocation.transitionTo({
+    toolState: saveLocationInfo,
+    condition: "User provided physical address",
+  });
 
   // Step 3b: Online-only path
-  const askOnlineLocation = askLocation.transitionTo(
-    {
-      chatState:
-        "Perfect! Since it's online only, please share your main website or social media where customers can find you? And what are your support hours? (e.g., 'www.example.com - 24/7 support' or 'Instagram @mycompany - Mon to Fri: 9am-6pm')",
-    },
-    "User does not have a physical store"
-  );
+  const askOnlineLocation = askLocation.transitionTo({
+    chatState:
+      "Perfect! Since it's online only, please share your main website or social media where customers can find you? And what are your support hours? (e.g., 'www.example.com - 24/7 support' or 'Instagram @mycompany - Mon to Fri: 9am-6pm')",
+    condition: "User does not have a physical store",
+  });
 
-  const saveOnlineLocation = askOnlineLocation.transitionTo(
-    { toolState: saveContactInfo },
-    "User provided website/social media and support hours"
-  );
+  const saveOnlineLocation = askOnlineLocation.transitionTo({
+    toolState: saveContactInfo,
+    condition: "User provided website/social media and support hours",
+  });
 
   // Step 4: Contact info (convergence point for physical stores)
   const askContact = savePhysicalLocation.transitionTo({
@@ -503,10 +499,10 @@ async function createBusinessOnboardingAgent(
       "Do you also have a website or social media? If yes, which one? (if not, you can skip by saying 'I don't have one')",
   });
 
-  const saveContact = askContact.transitionTo(
-    { toolState: saveContactInfo },
-    "User provided website/social media"
-  );
+  const saveContact = askContact.transitionTo({
+    toolState: saveContactInfo,
+    condition: "User provided website/social media",
+  });
 
   // Step 5: Payment info (convergence point from both paths)
   const askPayment = saveContact.transitionTo({
@@ -517,10 +513,10 @@ async function createBusinessOnboardingAgent(
   // Also connect online path to payment
   saveOnlineLocation.transitionTo({ state: askPayment });
 
-  const savePayment = askPayment.transitionTo(
-    { toolState: savePaymentInfo },
-    "User provided payment methods or said not applicable"
-  );
+  const savePayment = askPayment.transitionTo({
+    toolState: savePaymentInfo,
+    condition: "User provided payment methods or said not applicable",
+  });
 
   // Step 6: Suggest automatic routes
   const suggestRoutes = savePayment.transitionTo({
@@ -528,16 +524,16 @@ async function createBusinessOnboardingAgent(
       "Perfect! Now I'll create the essential routes. Based on what you told me, I'll automatically create:\n\n1. **Products and Services** - for when they ask what you offer\n2. **Pricing and Quotes** - for questions about prices\n3. **Payment Information** - payment methods and installments\n4. **Location and Contact** - address, website, and hours\n\nThese are the most important routes for any business. I'll create them automatically with the information you provided. Sound good?",
   });
 
-  const createRoutes = suggestRoutes.transitionTo(
-    { toolState: addConversationRoute },
-    "User approved automatic route creation"
-  );
+  const createRoutes = suggestRoutes.transitionTo({
+    toolState: addConversationRoute,
+    condition: "User approved automatic route creation",
+  });
 
   // Step 7: Review collected data
-  const reviewData = createRoutes.transitionTo(
-    { toolState: getCollectedData },
-    "Routes created successfully"
-  );
+  const reviewData = createRoutes.transitionTo({
+    toolState: getCollectedData,
+    condition: "Routes created successfully",
+  });
 
   // Step 8: Summary and options
   const summary = reviewData.transitionTo({
@@ -546,45 +542,65 @@ async function createBusinessOnboardingAgent(
   });
 
   // Step 9a: Add more routes
-  const askCustomRoute = summary.transitionTo(
-    {
-      chatState:
-        "Got it! Tell me about this additional route: what's the title, what kind of questions should it answer, and what keywords do customers use? (e.g., 'Warranty and Exchange - answers about warranty, exchange, and returns - keywords: warranty, exchange, return')",
-    },
-    "User wants to add more routes"
-  );
+  const askCustomRoute = summary.transitionTo({
+    chatState:
+      "Got it! Tell me about this additional route: what's the title, what kind of questions should it answer, and what keywords do customers use? (e.g., 'Warranty and Exchange - answers about warranty, exchange, and returns - keywords: warranty, exchange, return')",
+    condition: "User wants to add more routes",
+  });
 
-  const saveCustomRoute = askCustomRoute.transitionTo(
-    { toolState: addConversationRoute },
-    "User provided custom route information"
-  );
+  const saveCustomRoute = askCustomRoute.transitionTo({
+    toolState: addConversationRoute,
+    condition: "User provided custom route information",
+  });
 
   // Loop back to summary after adding custom route
   saveCustomRoute.transitionTo({ state: summary });
 
   // Step 9b: Final confirmation
-  const completion = summary.transitionTo(
-    {
-      chatState:
-        "🎉 Perfect! Setup complete! Your WhatsApp assistant is ready and will use all this information to automatically serve your customers. If you have any questions or need adjustments, just let me know!",
-    },
-    "User confirmed everything is okay"
-  );
+  const completion = summary.transitionTo({
+    chatState:
+      "🎉 Perfect! Setup complete! Your WhatsApp assistant is ready and will use all this information to automatically serve your customers. If you have any questions or need adjustments, just let me know!",
+    condition: "User confirmed everything is okay",
+  });
 
   completion.transitionTo({ state: END_ROUTE });
 
-  // ==================== Alternative: Chained Approach ====================
-  // For simpler linear flows, you can use chaining for conciseness:
+  // ==================== Alternative: Sequential Steps ====================
+  // For simpler linear flows, you can use the new sequential steps approach:
 
-  // Example of a simple feedback collection route
-  const feedbackRoute = agent.createRoute({
+  // Example 1: Using steps array (NEW!)
+  agent.createRoute({
     title: "Collect Feedback",
     description: "Quick feedback collection from completed onboarding",
     conditions: ["User wants to provide feedback"],
+    steps: [
+      {
+        id: "ask_rating",
+        chatState: "How would you rate your onboarding experience? (1-5 stars)",
+      },
+      {
+        id: "ask_liked_most",
+        chatState: "What did you like most about the process?",
+      },
+      {
+        id: "ask_improve",
+        chatState: "Is there anything we could improve?",
+      },
+      {
+        id: "thank_you",
+        chatState: "Thank you for your feedback! It helps us improve. 🙏",
+      },
+    ],
+  });
+
+  // Example 2: Traditional chaining approach (still supported)
+  const manualFeedbackRoute = agent.createRoute({
+    title: "Manual Feedback Route",
+    description: "Same flow using traditional chaining",
+    conditions: ["User wants manual feedback flow"],
   });
 
-  // Beautiful fluent chaining for linear flows
-  feedbackRoute.initialState
+  manualFeedbackRoute.initialState
     .transitionTo({
       id: "ask_rating",
       chatState: "How would you rate your onboarding experience? (1-5 stars)",
@@ -596,10 +612,12 @@ async function createBusinessOnboardingAgent(
     .transitionTo({
       id: "ask_improve",
       chatState: "Is there anything we could improve?",
+      condition: "User wants to provide feedback",
     })
     .transitionTo({
       id: "thank_you",
       chatState: "Thank you for your feedback! It helps us improve. 🙏",
+      condition: "User provided feedback",
     })
     .transitionTo({ state: END_ROUTE });
 

package/examples/company-qna-agent.ts

@@ -2,7 +2,7 @@
  * Example: Company Q&A Agent (Stateless, Knowledge-Based)
  *
  * This demonstrates:
- * 1. Schema-first architecture for stateless Q&A routes (no gatherSchema)
+ * 1. Schema-first architecture for stateless Q&A routes (no extractionSchema)
  * 2. Tools for context enrichment (not data extraction)
  * 3. Session state management even for stateless conversations
  * 4. Always-on routing with context awareness
@@ -234,7 +234,7 @@ const companyInfoRoute = agent.createRoute({
     "How many employees",
     "Where is the headquarters",
   ],
-  // NO gatherSchema - stateless Q&A route
+  // NO extractionSchema - stateless Q&A route
   // Just use initial state with chatState for response generation
 });
 
@@ -250,7 +250,7 @@ const productInfoRoute = agent.createRoute({
     "What products do you offer",
     "Tell me about your widgets",
   ],
-  // NO gatherSchema - just answering questions
+  // NO extractionSchema - just answering questions
 });
 
 // Initial state is enough - no transitions needed for simple Q&A
@@ -265,7 +265,7 @@ const policyRoute = agent.createRoute({
     "Shipping information",
     "Warranty questions",
   ],
-  // NO gatherSchema
+  // NO extractionSchema
 });
 
 // Initial state is enough - no extra setup needed

package/examples/custom-database-persistence.ts

@@ -146,7 +146,7 @@ async function example() {
       "User is a new customer",
       "User needs to set up their account",
     ],
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         fullName: { type: "string" },
@@ -464,7 +464,7 @@ async function advancedExample() {
 
   const route = agent.createRoute<OnboardingData>({
     title: "Onboarding",
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         fullName: { type: "string" },

package/examples/declarative-agent.ts

@@ -190,7 +190,7 @@ const routes: RouteOptions[] = [
     title: "Schedule Appointment",
     description: "Helps the patient schedule an appointment",
     conditions: ["The patient wants to schedule an appointment"],
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         appointmentType: {
@@ -232,7 +232,7 @@ const routes: RouteOptions[] = [
     title: "Check Lab Results",
     description: "Retrieves and explains patient lab results",
     conditions: ["The patient wants to see their lab results"],
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         testType: {
@@ -264,7 +264,7 @@ const routes: RouteOptions[] = [
     title: "General Healthcare Questions",
     description: "Answer general healthcare questions",
     conditions: ["Patient asks general healthcare questions"],
-    // No gatherSchema - stateless Q&A
+    // No extractionSchema - stateless Q&A
   },
 ];
 

package/examples/extracted-data-modification.ts

@@ -251,7 +251,7 @@ const bookingRoute = agent.createRoute<FlightData>({
     "User wants to book a flight",
     "User mentions flying, traveling, or booking",
   ],
-  gatherSchema: {
+  extractionSchema: {
     type: "object",
     properties: {
       destination: {

package/examples/healthcare-agent.ts

@@ -130,7 +130,7 @@ async function createHealthcareAgent() {
     title: "Schedule an Appointment",
     description: "Helps the patient find a time for their appointment.",
     conditions: ["The patient wants to schedule an appointment"],
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         appointmentReason: {
@@ -161,25 +161,21 @@ async function createHealthcareAgent() {
   });
 
   // State 1: Gather appointment reason
-  const gatherReason = schedulingRoute.initialState.transitionTo(
-    {
-      chatState: "Ask what the patient needs an appointment for",
-      gather: ["appointmentReason"],
-      skipIf: (extracted) => !!extracted.appointmentReason,
-    },
-    "Patient hasn't specified reason for appointment yet"
-  );
+  const gatherReason = schedulingRoute.initialState.transitionTo({
+    chatState: "Ask what the patient needs an appointment for",
+    gather: ["appointmentReason"],
+    skipIf: (extracted) => !!extracted.appointmentReason,
+    condition: "Patient hasn't specified reason for appointment yet",
+  });
 
   // State 2: Check urgency and show available slots
-  const checkUrgency = gatherReason.transitionTo(
-    {
-      chatState: "Check if this is urgent and show available slots",
-      gather: ["urgency"],
-      skipIf: (extracted) => !!extracted.urgency,
-      requiredData: ["appointmentReason"],
-    },
-    "Reason provided, now assess urgency level"
-  );
+  const checkUrgency = gatherReason.transitionTo({
+    chatState: "Check if this is urgent and show available slots",
+    gather: ["urgency"],
+    skipIf: (extracted) => !!extracted.urgency,
+    requiredData: ["appointmentReason"],
+    condition: "Reason provided, now assess urgency level",
+  });
 
   const showSlots = checkUrgency.transitionTo({
     toolState: getUpcomingSlots,
@@ -206,22 +202,20 @@ async function createHealthcareAgent() {
     requiredData: ["appointmentReason", "preferredTime", "preferredDate"],
   });
 
-  const schedule = confirmDetails.transitionTo(
-    {
-      toolState: scheduleAppointment,
-      requiredData: ["appointmentReason", "preferredTime", "preferredDate"],
-    },
-    "All details confirmed, book the appointment"
-  );
+  const schedule = confirmDetails.transitionTo({
+    toolState: scheduleAppointment,
+    requiredData: ["appointmentReason", "preferredTime", "preferredDate"],
+    condition: "All details confirmed, book the appointment",
+  });
 
   const confirmation = schedule.transitionTo({
     chatState: "Confirm the appointment has been scheduled",
   });
 
-  confirmation.transitionTo(
-    { state: END_ROUTE },
-    "Appointment booked successfully"
-  );
+  confirmation.transitionTo({
+    state: END_ROUTE,
+    condition: "Appointment booked successfully",
+  });
 
   // Alternative path: no times work - show later slots
   const laterSlots = presentTimes.transitionTo({
@@ -250,7 +244,7 @@ async function createHealthcareAgent() {
     title: "Lab Results",
     description: "Retrieves the patient's lab results and explains them.",
     conditions: ["The patient wants to see their lab results"],
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         testType: {

package/examples/openai-agent.ts

@@ -112,7 +112,7 @@ async function main() {
     title: "Check Weather",
     description: "Help user check weather for a location",
     conditions: ["User wants to know the weather"],
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         location: {

package/examples/opensearch-persistence.ts

@@ -105,7 +105,7 @@ async function example() {
       "User reports an issue or problem",
       "User is dissatisfied",
     ],
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         category: {
@@ -337,7 +337,7 @@ async function analyticsExample() {
 
   const ticketRoute = agent.createRoute<TicketData>({
     title: "Analyze Support Ticket",
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         ticketType: { type: "string" },

package/examples/persistent-onboarding.ts

@@ -244,7 +244,7 @@ async function createPersistentOnboardingAgent(sessionId: string) {
     title: "Business Onboarding",
     description: "Guide user through business information collection",
     conditions: ["User is onboarding their business"],
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         businessName: {
@@ -503,7 +503,7 @@ async function main() {
  *    - Always-on routing respects intent changes
  *
  * ✅ PATTERN 2: Schema-First Data Extraction
- *    - gatherSchema: Define data contracts upfront
+ *    - extractionSchema: Define data contracts upfront
  *    - Type-safe extraction throughout conversation
  *    - skipIf functions for deterministic state logic
  *    - requiredData arrays for prerequisites

package/examples/prisma-persistence.ts

@@ -96,7 +96,7 @@ async function example() {
       "User wants to book a flight",
       "User mentions travel, flying, or booking tickets",
     ],
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         destination: {
@@ -413,7 +413,7 @@ async function advancedExample() {
   const onboardingRoute = agent.createRoute<OnboardingData>({
     title: "User Onboarding",
     description: "Collect user information for account setup",
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         fullName: { type: "string" },
@@ -514,7 +514,7 @@ async function quickStart() {
   // Create a simple contact form route
   const contactRoute = agent.createRoute<ContactFormData>({
     title: "Contact Form",
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         name: { type: "string" },

package/examples/redis-persistence.ts

@@ -88,7 +88,7 @@ async function example() {
       "User wants to report a problem",
       "User mentions support, help, or issue",
     ],
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         issue: {
@@ -286,7 +286,7 @@ async function highThroughputExample() {
   // Simple chat route that extracts topic and sentiment
   const chatRoute = agent.createRoute<QuickChatData>({
     title: "General Chat",
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         topic: {
@@ -364,7 +364,7 @@ async function sessionRecoveryExample() {
 
   const orderRoute = agent.createRoute<OrderData>({
     title: "Place Order",
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         productId: { type: "string" },