@falai/agent 0.5.4 → 0.5.5

package/examples/business-onboarding.ts

@@ -586,15 +586,19 @@ async function createBusinessOnboardingAgent(
   // Beautiful fluent chaining for linear flows
   feedbackRoute.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 +607,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/healthcare-agent.ts

@@ -161,19 +161,25 @@ 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,
-  });
+  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"
+  );
 
   // 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"],
-  });
+  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 showSlots = checkUrgency.transitionTo({
     toolState: getUpcomingSlots,
@@ -200,16 +206,22 @@ async function createHealthcareAgent() {
     requiredData: ["appointmentReason", "preferredTime", "preferredDate"],
   });
 
-  const schedule = confirmDetails.transitionTo({
-    toolState: scheduleAppointment,
-    requiredData: ["appointmentReason", "preferredTime", "preferredDate"],
-  });
+  const schedule = confirmDetails.transitionTo(
+    {
+      toolState: scheduleAppointment,
+      requiredData: ["appointmentReason", "preferredTime", "preferredDate"],
+    },
+    "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 },
+    "Appointment booked successfully"
+  );
 
   // Alternative path: no times work - show later slots
   const laterSlots = presentTimes.transitionTo({

package/examples/persistent-onboarding.ts

@@ -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({

package/examples/travel-agent.ts

@@ -270,55 +270,85 @@ async function createTravelAgent() {
   });
 
   // Build the route flow with data extraction and smart state progression
-  const askDestination = flightBookingRoute.initialState.transitionTo({
-    chatState: "Ask about the destination",
-    gather: ["destination"],
-    skipIf: (extracted) => !!extracted.destination,
-  });
+  const askDestination = flightBookingRoute.initialState.transitionTo(
+    {
+      chatState: "Ask about the destination",
+      gather: ["destination"],
+      skipIf: (extracted) => !!extracted.destination,
+    },
+    "Customer needs to specify their travel destination"
+  );
 
-  const enrichDestination = askDestination.transitionTo({
-    toolState: lookupDestinationCode,
-    requiredData: ["destination"],
-  });
+  const enrichDestination = askDestination.transitionTo(
+    {
+      toolState: lookupDestinationCode,
+      requiredData: ["destination"],
+    },
+    "Destination provided, lookup airport code"
+  );
 
-  const askDates = enrichDestination.transitionTo({
-    chatState: "Ask about preferred travel dates",
-    gather: ["departureDate"],
-    skipIf: (extracted) => !!extracted.departureDate,
-    requiredData: ["destination"],
-  });
+  const askDates = enrichDestination.transitionTo(
+    {
+      chatState: "Ask about preferred travel dates",
+      gather: ["departureDate"],
+      skipIf: (extracted) => !!extracted.departureDate,
+      requiredData: ["destination"],
+    },
+    "Destination confirmed, need travel dates"
+  );
 
-  const askPassengers = askDates.transitionTo({
-    chatState: "Ask for number of passengers",
-    gather: ["passengers"],
-    skipIf: (extracted) => !!extracted.passengers,
-    requiredData: ["destination", "departureDate"],
-  });
+  const askPassengers = askDates.transitionTo(
+    {
+      chatState: "Ask for number of passengers",
+      gather: ["passengers"],
+      skipIf: (extracted) => !!extracted.passengers,
+      requiredData: ["destination", "departureDate"],
+    },
+    "Dates confirmed, need passenger count"
+  );
 
-  const searchFlightsState = askPassengers.transitionTo({
-    toolState: searchFlights,
-    // Triggered when shouldSearchFlights flag is set by hook
-  });
+  const searchFlightsState = askPassengers.transitionTo(
+    {
+      toolState: searchFlights,
+      // Triggered when shouldSearchFlights flag is set by hook
+    },
+    "All basic info gathered, search for available flights"
+  );
 
-  const presentFlights = searchFlightsState.transitionTo({
-    chatState: "Present available flights and ask which one works for them",
-  });
+  const presentFlights = searchFlightsState.transitionTo(
+    {
+      chatState: "Present available flights and ask which one works for them",
+    },
+    "Flight search complete, present options to customer"
+  );
 
   // Happy path: customer selects a flight
-  const confirmBooking = presentFlights.transitionTo({
-    chatState: "Confirm booking details before proceeding",
-    gather: ["cabinClass", "urgency"], // Additional optional data
-  });
+  const confirmBooking = presentFlights.transitionTo(
+    {
+      chatState: "Confirm booking details before proceeding",
+      gather: ["cabinClass", "urgency"], // Additional optional data
+    },
+    "Customer interested in a flight, confirm booking details"
+  );
 
-  const bookFlightState = confirmBooking.transitionTo({
-    toolState: bookFlight,
-  });
+  const bookFlightState = confirmBooking.transitionTo(
+    {
+      toolState: bookFlight,
+    },
+    "Customer confirmed, proceed with booking"
+  );
 
-  const provideConfirmation = bookFlightState.transitionTo({
-    chatState: "Provide confirmation number and booking summary",
-  });
+  const provideConfirmation = bookFlightState.transitionTo(
+    {
+      chatState: "Provide confirmation number and booking summary",
+    },
+    "Booking completed successfully"
+  );
 
-  provideConfirmation.transitionTo({ state: END_ROUTE });
+  provideConfirmation.transitionTo(
+    { state: END_ROUTE },
+    "Customer has confirmation, booking flow complete"
+  );
 
   // Add route-specific guidelines
   flightBookingRoute.createGuideline({
@@ -356,22 +386,34 @@ async function createTravelAgent() {
     },
   });
 
-  const askConfirmation = bookingStatusRoute.initialState.transitionTo({
-    chatState: "Ask for the confirmation number or booking reference",
-    gather: ["confirmationNumber"],
-    skipIf: (extracted) => !!extracted.confirmationNumber,
-  });
+  const askConfirmation = bookingStatusRoute.initialState.transitionTo(
+    {
+      chatState: "Ask for the confirmation number or booking reference",
+      gather: ["confirmationNumber"],
+      skipIf: (extracted) => !!extracted.confirmationNumber,
+    },
+    "Customer wants to check booking status but hasn't provided confirmation number"
+  );
 
-  const checkStatus = askConfirmation.transitionTo({
-    toolState: getBookingStatus,
-    requiredData: ["confirmationNumber"],
-  });
+  const checkStatus = askConfirmation.transitionTo(
+    {
+      toolState: getBookingStatus,
+      requiredData: ["confirmationNumber"],
+    },
+    "Confirmation number provided, look up booking details"
+  );
 
-  const provideStatus = checkStatus.transitionTo({
-    chatState: "Provide booking status and relevant information",
-  });
+  const provideStatus = checkStatus.transitionTo(
+    {
+      chatState: "Provide booking status and relevant information",
+    },
+    "Booking status retrieved successfully"
+  );
 
-  provideStatus.transitionTo({ state: END_ROUTE });
+  provideStatus.transitionTo(
+    { state: END_ROUTE },
+    "Booking information provided to customer"
+  );
 
   // Global guidelines
   agent.createGuideline({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
   "type": "module",
   "main": "./dist/cjs/index.js",