@falai/agent 0.5.4 → 0.6.0

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,55 +542,79 @@ 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)",
     })
     .transitionTo({
+      id: "ask_liked_most",
       chatState: "What did you like most about the process?",
     })
     .transitionTo({
+      id: "ask_improve",
       chatState: "Is there anything we could improve?",
     })
     .transitionTo({
+      id: "thank_you",
       chatState: "Thank you for your feedback! It helps us improve. 🙏",
     })
     .transitionTo({ state: END_ROUTE });
@@ -603,38 +623,45 @@ async function createBusinessOnboardingAgent(
 
   agent
     .createGuideline({
+      id: "guideline_confused",
       condition: "User seems confused or doesn't understand something",
       action:
         "Be patient and provide practical examples of what you need. E.g., 'José Silva Street, 123, São Paulo - SP' for address",
     })
     .createGuideline({
+      id: "guideline_incomplete",
       condition: "User provides incomplete or very vague information",
       action:
         "Politely ask for the missing specific details. E.g., 'You mentioned the address, but what's the city and state?'",
     })
     .createGuideline({
+      id: "guideline_skip",
       condition:
         "User wants to skip information saying they don't have it or it doesn't apply",
       action:
         "Be smart: if the information is critical for their business type (e.g., address for physical store, website for e-commerce), explain the importance. If not critical, accept it and move forward saying 'no problem, that's fine'",
     })
     .createGuideline({
+      id: "guideline_physical_online",
       condition: "User has physical store but said online-only or vice versa",
       action:
         "Adjust the flow dynamically: if they have a physical store, prioritize address and hours. If online-only, prioritize website/social media and digital support hours. Don't ask for irrelevant information",
     })
     .createGuideline({
+      id: "guideline_why",
       condition: "User asks why they need to provide certain information",
       action:
         "Explain practically: 'This information will help your assistant automatically answer customers when they ask about this. E.g., when they ask about payment methods, the assistant will inform automatically'",
     })
     .createGuideline({
+      id: "guideline_edit",
       condition:
         "User wants to edit or correct something they already provided",
       action:
         "Accept promptly and update the information: 'Of course! I'll update to...'. Use the appropriate tool to save the correction",
     })
     .createGuideline({
+      id: "guideline_unrelated",
       condition: "User asks a question unrelated to onboarding",
       action:
         "Answer briefly and redirect: 'I understand, but let's finish the setup first? We're almost there!'",

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: {
@@ -165,6 +165,7 @@ async function createHealthcareAgent() {
     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
@@ -173,6 +174,7 @@ async function createHealthcareAgent() {
     gather: ["urgency"],
     skipIf: (extracted) => !!extracted.urgency,
     requiredData: ["appointmentReason"],
+    condition: "Reason provided, now assess urgency level",
   });
 
   const showSlots = checkUrgency.transitionTo({
@@ -203,13 +205,17 @@ async function createHealthcareAgent() {
   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 });
+  confirmation.transitionTo({
+    state: END_ROUTE,
+    condition: "Appointment booked successfully",
+  });
 
   // Alternative path: no times work - show later slots
   const laterSlots = presentTimes.transitionTo({
@@ -238,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: {
@@ -269,18 +269,24 @@ async function createPersistentOnboardingAgent(sessionId: string) {
   });
 
   // State 1: Gather business name and description
-  const gatherBusinessInfo = onboardingRoute.initialState.transitionTo({
-    chatState: "Ask for business name and a brief description",
-    gather: ["businessName", "businessDescription"],
-    skipIf: (extracted) =>
-      !!extracted.businessName && !!extracted.businessDescription,
-  });
+  const gatherBusinessInfo = onboardingRoute.initialState.transitionTo(
+    {
+      chatState: "Ask for business name and a brief description",
+      gather: ["businessName", "businessDescription"],
+      skipIf: (extracted) =>
+        !!extracted.businessName && !!extracted.businessDescription,
+    },
+    "Need to collect basic business information first"
+  );
 
   // State 2: Save business info (tool execution)
-  const saveBusiness = gatherBusinessInfo.transitionTo({
-    toolState: saveBusinessInfo,
-    requiredData: ["businessName", "businessDescription"],
-  });
+  const saveBusiness = gatherBusinessInfo.transitionTo(
+    {
+      toolState: saveBusinessInfo,
+      requiredData: ["businessName", "businessDescription"],
+    },
+    "Business name and description provided, save to database"
+  );
 
   // State 3: Gather industry
   const gatherIndustry = saveBusiness.transitionTo({
@@ -497,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" },