@falai/agent 0.6.7 → 0.6.8

package/docs/ROUTES.md

@@ -9,6 +9,7 @@ A complete guide to creating and managing conversational routes in `@falai/agent
 - [What is a Route?](#what-is-a-route)
 - [Creating Routes](#creating-routes)
 - [Initial State Configuration](#initial-state-configuration)
+- [End State Configuration](#end-state-configuration)
 - [Data Extraction](#data-extraction)
 - [Sequential Steps](#sequential-steps)
 - [Route Properties](#route-properties)
@@ -173,13 +174,140 @@ initialState: {
   // Skip this state if condition is met
   skipIf?: (extracted: Partial<TExtracted>) => boolean;
 
-  // Prerequisites that must be met
+  // Prerequisites that must be metw
   requiredData?: string[];
 }
 ```
 
 ---
 
+## End State Configuration
+
+Every route ends when it reaches `END_STATE`. You can configure what happens at route completion:
+
+### Configure End State at Route Creation
+
+```typescript
+import { END_STATE } from "@falai/agent";
+
+const bookingRoute = agent.createRoute<FlightData>({
+  title: "Book Flight",
+
+  // Configure what happens when route completes
+  endState: {
+    // Custom completion message
+    chatState: "Confirm the booking details and thank the user warmly!",
+
+    // Optional: Execute final actions (like sending confirmation emails)
+    toolState: sendConfirmationEmail,
+
+    // Optional: Gather final data before completing
+    gather: ["finalConfirmation"],
+
+    // Optional: Require certain data to be present
+    requiredData: ["destination", "departureDate"],
+
+    // Optional: Custom state ID
+    id: "booking_complete",
+  },
+
+  extractionSchema: {
+    // ... schema definition
+  },
+});
+
+// Then just transition to END_STATE
+lastState.transitionTo({
+  state: END_STATE,
+});
+```
+
+### Per-Transition Override
+
+You can also override the endState configuration for specific transitions:
+
+```typescript
+// Use route-level endState
+lastState.transitionTo({
+  state: END_STATE,
+});
+
+// OR override with custom chatState for this specific transition
+lastState.transitionTo({
+  chatState: "Special completion message for this path!",
+  state: END_STATE,
+});
+```
+
+### End State Options
+
+```typescript
+endState: {
+  // Completion message instruction (RECOMMENDED)
+  chatState?: string;
+
+  // Execute final tools/actions before completion
+  toolState?: ToolRef;
+
+  // Gather final data at completion
+  gather?: string[];
+
+  // Require specific data to be present
+  requiredData?: string[];
+
+  // Custom state ID for debugging
+  id?: string;
+}
+```
+
+### Default Behavior
+
+If you don't configure `endState`, a smart default is used:
+
+```typescript
+// Default endState behavior:
+{
+  chatState: "Summarize what was accomplished and confirm completion based on the conversation history and collected data"
+}
+```
+
+### End State with Tools
+
+Execute final actions when route completes:
+
+```typescript
+import { defineTool, END_STATE } from "@falai/agent";
+
+const sendConfirmation = defineTool(
+  "send_confirmation",
+  async ({ extracted }) => {
+    await emailService.send({
+      to: extracted.email,
+      subject: "Booking Confirmed",
+      body: `Your flight to ${extracted.destination} is confirmed!`,
+    });
+    return { data: "Confirmation sent" };
+  }
+);
+
+const bookingRoute = agent.createRoute({
+  title: "Book Flight",
+
+  endState: {
+    toolState: sendConfirmation,  // Executes when route completes
+    chatState: "Your booking is complete! Confirmation email sent.",
+  },
+});
+```
+
+**Key Points:**
+- ✅ `endState` is configured once at the route level (DRY principle)
+- ✅ Can be overridden per-transition if needed
+- ✅ Supports full state capabilities: `chatState`, `toolState`, `gather`, `requiredData`
+- ✅ Falls back to smart default if not configured
+
+---
+
 ## Data Extraction
 
 ### Defining Extraction Schema
@@ -637,6 +765,222 @@ return response.message;
 - ✅ **Use `isRouteComplete`** for simplicity and clarity
 - ✅ **Use `END_STATE_ID`** if you want consistency with how you build routes (`END_STATE` symbol)
 
+---
+
+## Route Transitions with `onComplete`
+
+**NEW:** You can now automatically transition to another route when a route completes using the `onComplete` option. This is perfect for chaining workflows like:
+
+- 📋 Post-booking feedback collection
+- 🎁 Upsell offers after purchase
+- 📊 Satisfaction surveys after support
+- ↩️ Error recovery flows
+
+### Simple String Transition
+
+The simplest form - just specify the target route ID or title:
+
+```typescript
+const bookingRoute = agent.createRoute<BookingData>({
+  title: "Book Hotel",
+  conditions: ["User wants to book a hotel"],
+  extractionSchema: BOOKING_SCHEMA,
+  // Automatically transition to feedback when booking completes
+  onComplete: "Collect Feedback",
+});
+
+const feedbackRoute = agent.createRoute<FeedbackData>({
+  title: "Collect Feedback",
+  conditions: ["Collect user feedback"],
+  extractionSchema: FEEDBACK_SCHEMA,
+});
+```
+
+### With AI-Evaluated Condition
+
+Add an optional condition that the AI evaluates to determine if transition should happen:
+
+```typescript
+const bookingRoute = agent.createRoute<BookingData>({
+  title: "Book Hotel",
+  extractionSchema: BOOKING_SCHEMA,
+  onComplete: {
+    transitionTo: "Collect Feedback",
+    condition: "if booking was successful", // AI evaluates this
+  },
+});
+```
+
+### Dynamic Function-Based Transition
+
+Use a function for complex logic based on extracted data or context:
+
+```typescript
+const bookingRoute = agent.createRoute<BookingData>({
+  title: "Book Hotel",
+  extractionSchema: BOOKING_SCHEMA,
+  // Function receives session and context
+  onComplete: (session, context) => {
+    // Conditional logic based on extracted data
+    if (session.extracted?.guests && session.extracted.guests > 5) {
+      return "VIP Feedback"; // Large groups get VIP treatment
+    }
+    if (session.extracted?.bookingFailed) {
+      return "Error Recovery"; // Handle failures gracefully
+    }
+    return "Collect Feedback"; // Standard feedback flow
+  },
+});
+```
+
+Function can also return a config object:
+
+```typescript
+onComplete: (session) => ({
+  transitionTo: "Collect Feedback",
+  condition: session.extracted?.vip ? "if user is satisfied" : undefined,
+})
+```
+
+### How It Works
+
+1. **Route completes** → reaches `END_STATE`
+2. **Agent evaluates** `onComplete` handler
+3. **Sets pending transition** in session state
+4. **Next `respond()` call** → automatically transitions to target route
+5. **User sees seamless flow** → no interruption in conversation
+
+```typescript
+// User books hotel
+const response1 = await agent.respond({ history, session });
+console.log(response1.isRouteComplete); // true
+console.log(response1.session?.pendingTransition); // { targetRouteId: "...", reason: "route_complete" }
+
+// Next message automatically transitions to feedback route
+history.push(createMessageEvent(EventSource.CUSTOMER, "User", "Yes!"));
+const response2 = await agent.respond({ history, session: response1.session });
+console.log(response2.session?.currentRoute?.title); // "Collect Feedback"
+```
+
+### Manual Transition Control
+
+For more control, use `agent.transitionToRoute()` to manually set the transition:
+
+```typescript
+const response = await agent.respond({ history, session });
+
+if (response.isRouteComplete && shouldCollectFeedback) {
+  // Manually trigger transition instead of onComplete
+  const updatedSession = agent.transitionToRoute(
+    "Collect Feedback",
+    response.session
+  );
+
+  // Next respond() will transition automatically
+  const nextResponse = await agent.respond({
+    history,
+    session: updatedSession,
+  });
+}
+```
+
+### Complete Example
+
+```typescript
+interface BookingData {
+  hotelName: string;
+  date: string;
+  guests: number;
+}
+
+interface FeedbackData {
+  rating: number;
+  comments?: string;
+}
+
+// Booking route with automatic transition to feedback
+const bookingRoute = agent.createRoute<BookingData>({
+  title: "Book Hotel",
+  conditions: ["User wants to book a hotel"],
+  extractionSchema: {
+    type: "object",
+    properties: {
+      hotelName: { type: "string" },
+      date: { type: "string" },
+      guests: { type: "number" },
+    },
+    required: ["hotelName", "date", "guests"],
+  },
+  onComplete: "Collect Feedback",
+});
+
+const askHotel = bookingRoute.initialState.transitionTo({
+  chatState: "Ask which hotel",
+  gather: ["hotelName"],
+  skipIf: (e) => !!e.hotelName,
+});
+
+const askDate = askHotel.transitionTo({
+  chatState: "Ask for date",
+  gather: ["date"],
+  skipIf: (e) => !!e.date,
+});
+
+const askGuests = askDate.transitionTo({
+  chatState: "Ask for guests",
+  gather: ["guests"],
+  skipIf: (e) => !!e.guests,
+});
+
+askGuests.transitionTo({
+  chatState: "Confirm booking",
+  state: END_STATE,
+});
+
+// Feedback route
+const feedbackRoute = agent.createRoute<FeedbackData>({
+  title: "Collect Feedback",
+  conditions: ["Collect user feedback"],
+  extractionSchema: {
+    type: "object",
+    properties: {
+      rating: { type: "number" },
+      comments: { type: "string" },
+    },
+    required: ["rating"],
+  },
+});
+
+const askRating = feedbackRoute.initialState.transitionTo({
+  chatState: "Ask for rating 1-5",
+  gather: ["rating"],
+});
+
+askRating.transitionTo({
+  chatState: "Thank user",
+  state: END_STATE,
+});
+
+// Usage - seamless transition from booking to feedback
+let session;
+const response1 = await agent.respond({ history, session });
+// Booking complete, pending transition set
+
+history.push(createMessageEvent(EventSource.CUSTOMER, "User", "Yes!"));
+const response2 = await agent.respond({ history, session: response1.session });
+// Now in feedback route automatically
+```
+
+### Benefits
+
+✅ **Seamless user experience** - No awkward pauses between flows
+✅ **Predictable behavior** - Transitions defined at design time
+✅ **Flexible** - Simple strings, conditions, or complex functions
+✅ **Type-safe** - Full TypeScript inference for extracted data
+✅ **Non-breaking** - Existing routes without `onComplete` work as before
+
+See [examples/route-transitions.ts](../examples/route-transitions.ts) for a complete working example.
+
 ### Immediate Completion
 
 Routes can complete **immediately** if all states are skipped due to `skipIf` conditions. This is useful when:

package/docs/STATES.md

@@ -503,21 +503,111 @@ route.initialState.configure({
 - Set expectations
 - Pre-populate data
 
-### 4. Terminal State
+### 4. End State (Terminal State)
 
-End of a route:
+Every route ends when it reaches `END_STATE`. You can configure what happens at completion:
+
+#### Option A: Route-Level Configuration (Recommended)
 
 ```typescript
-const end = finalStep.transitionTo({
+import { END_STATE } from "@falai/agent";
+
+const bookingRoute = agent.createRoute({
+  title: "Book Flight",
+
+  // Configure end state behavior
+  endState: {
+    chatState: "Confirm booking and thank the user!",
+    toolState: sendConfirmationEmail,  // Execute final actions
+    gather: ["finalConfirmation"],     // Gather last data
+  },
+});
+
+// Later, just transition to END_STATE
+finalStep.transitionTo({
   state: END_STATE,
 });
 ```
 
-**When to use:**
+#### Option B: Per-Transition Override
+
+```typescript
+// Override endState for this specific path
+finalStep.transitionTo({
+  chatState: "Special completion message for VIP users!",
+  state: END_STATE,
+});
+```
+
+#### Option C: Default Behavior
+
+If you don't configure `endState`, a smart default completion message is generated:
+
+```typescript
+finalStep.transitionTo({
+  state: END_STATE,
+});
+// Uses default: "Summarize what was accomplished and confirm completion..."
+```
+
+**End State Capabilities:**
+
+```typescript
+endState: {
+  // Completion message instruction
+  chatState?: string;
+
+  // Execute final actions (emails, database updates, etc.)
+  toolState?: ToolRef;
+
+  // Gather final data before completion
+  gather?: string[];
+
+  // Require certain data to be present
+  requiredData?: string[];
+
+  // Custom state ID for debugging
+  id?: string;
+}
+```
+
+**When to use END_STATE:**
+
+- ✅ Route completion - all required data collected
+- ✅ Success outcomes - action completed successfully
+- ✅ Failure outcomes - error handling completed
+- ✅ Before transition - handoff to another route via `onComplete`
+
+**End State with Tools:**
+
+Execute final actions when route completes:
+
+```typescript
+import { defineTool, END_STATE } from "@falai/agent";
+
+const notifyTeam = defineTool("notify_team", async ({ extracted }) => {
+  await slack.send({
+    channel: "#bookings",
+    message: `New booking: ${extracted.hotelName} for ${extracted.guests} guests`,
+  });
+  return { data: "Team notified" };
+});
+
+const bookingRoute = agent.createRoute({
+  endState: {
+    toolState: notifyTeam,  // Runs when route completes
+    chatState: "Booking complete! Our team has been notified.",
+  },
+});
+```
+
+**Key Points:**
 
-- Route completion
-- Success/failure outcomes
-- Handoff to another route
+- ✅ Configure once at route level (DRY principle)
+- ✅ Can be overridden per-transition if needed
+- ✅ Supports full state capabilities: `chatState`, `toolState`, `gather`, `requiredData`
+- ✅ Automatically generates message if not configured
+- ✅ Executes before `onComplete` route transitions
 
 ---
 

package/examples/business-onboarding.ts

@@ -417,6 +417,9 @@ async function createBusinessOnboardingAgent(
     title: "Business Onboarding",
     description: "Complete onboarding process to configure personalized routes",
     conditions: ["User is starting the onboarding process"],
+    endState: {
+      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!",
+    },
   });
 
   // ==================== Build the Flow ====================
@@ -556,15 +559,12 @@ async function createBusinessOnboardingAgent(
   // 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!",
+  // Step 9b: Final confirmation - transition to END_STATE (uses route-level endState)
+  summary.transitionTo({
+    state: END_STATE,
     condition: "User confirmed everything is okay",
   });
 
-  completion.transitionTo({ state: END_STATE });
-
   // ==================== Alternative: Sequential Steps ====================
   // For simpler linear flows, you can use the new sequential steps approach:
 
@@ -598,6 +598,9 @@ async function createBusinessOnboardingAgent(
     title: "Manual Feedback Route",
     description: "Same flow using traditional chaining",
     conditions: ["User wants manual feedback flow"],
+    endState: {
+      chatState: "Thank you for your feedback! It helps us improve. 🙏",
+    },
   });
 
   manualFeedbackRoute.initialState
@@ -614,12 +617,7 @@ async function createBusinessOnboardingAgent(
       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_STATE });
+    .transitionTo({ state: END_STATE }); // Uses route-level endState
 
   // ==================== Global Guidelines ====================
 

package/examples/company-qna-agent.ts

@@ -358,6 +358,9 @@ const feedbackRoute = agent.createRoute<FeedbackData>({
     },
     required: ["rating", "comments"],
   },
+  endState: {
+    chatState: "Thank the user warmly for their valuable feedback and let them know we appreciate their time",
+  },
 });
 
 feedbackRoute.initialState
@@ -381,11 +384,7 @@ feedbackRoute.initialState
     gather: ["contactPermission"],
     requiredData: ["comments"],
   })
-  .transitionTo({
-    id: "thank_you",
-    chatState: "Thank you for your valuable feedback!",
-  })
-  .transitionTo({ state: END_STATE });
+  .transitionTo({ state: END_STATE }); // Uses route-level endState configuration
 
 // ==============================================================================
 // USAGE EXAMPLES: Three-Phase Pipeline Demonstration

package/examples/healthcare-agent.ts

@@ -34,6 +34,12 @@ interface LabResultsData {
   resultsNeeded?: boolean;
 }
 
+interface SatisfactionData {
+  rating?: number;
+  easeOfScheduling?: number;
+  comments?: string;
+}
+
 // Tools
 const getInsuranceProviders = defineTool<HealthcareContext, [], string[]>(
   "get_insurance_providers",
@@ -126,6 +132,7 @@ async function createHealthcareAgent() {
   });
 
   // Create scheduling route with data extraction schema
+  // NEW: Added onComplete to automatically transition to satisfaction survey after booking
   const schedulingRoute = agent.createRoute<AppointmentData>({
     title: "Schedule an Appointment",
     description: "Helps the patient find a time for their appointment.",
@@ -158,6 +165,8 @@ async function createHealthcareAgent() {
       },
       required: ["appointmentReason"],
     },
+    // NEW: Automatically collect feedback after successful scheduling
+    onComplete: "Satisfaction Survey",
   });
 
   // State 1: Gather appointment reason
@@ -300,6 +309,50 @@ async function createHealthcareAgent() {
       "Assertively tell them that you cannot help and they should call the office",
   });
 
+  // NEW: Satisfaction Survey route - collects feedback after appointment scheduling
+  const satisfactionRoute = agent.createRoute<SatisfactionData>({
+    title: "Satisfaction Survey",
+    description: "Quick satisfaction survey after scheduling",
+    conditions: ["Collect patient satisfaction feedback"],
+    extractionSchema: {
+      type: "object",
+      properties: {
+        rating: {
+          type: "number",
+          description: "Overall satisfaction rating 1-5",
+        },
+        easeOfScheduling: {
+          type: "number",
+          description: "Ease of scheduling process 1-5",
+        },
+        comments: {
+          type: "string",
+          description: "Optional feedback comments",
+        },
+      },
+      required: ["rating"],
+    },
+  });
+
+  const askRating = satisfactionRoute.initialState.transitionTo({
+    chatState:
+      "Ask for overall satisfaction rating from 1 to 5 with the scheduling experience",
+    gather: ["rating"],
+    skipIf: (extracted) => !!extracted.rating,
+  });
+
+  const askComments = askRating.transitionTo({
+    chatState: "Ask if they have any additional comments or feedback (optional)",
+    gather: ["comments"],
+  });
+
+  const thankYou = askComments.transitionTo({
+    chatState:
+      "Thank them for their feedback and confirm their appointment details one more time",
+  });
+
+  thankYou.transitionTo({ state: END_STATE });
+
   // Global guidelines
   agent.createGuideline({
     condition: "The patient asks about insurance",
@@ -384,6 +437,16 @@ async function main() {
     // Update session again
     session = response2.session!;
 
+    // NEW: Check if route is complete - will auto-transition to satisfaction survey
+    if (response2.isRouteComplete) {
+      console.log("\n✓ Appointment scheduling complete!");
+      console.log("Pending transition:", response2.session?.pendingTransition);
+      console.log(
+        "Next respond() will auto-transition to:",
+        response2.session?.pendingTransition?.targetRouteId
+      );
+    }
+
     // Turn 3: Patient provides final details
     const history3 = [
       ...history2,

package/examples/persistent-onboarding.ts

@@ -8,7 +8,6 @@ import {
   defineTool,
   GeminiProvider,
   END_STATE,
-  END_STATE_ID,
   EventSource,
   createMessageEvent,
   createSession,
@@ -102,7 +101,7 @@ async function createPersistentOnboardingAgent(sessionId: string) {
   // Define lifecycle hooks for automatic persistence
   const hooks = {
     // Called after data extraction - validate and enrich extracted data
-    onExtractedUpdate: async (extracted, previousExtracted) => {
+    onExtractedUpdate: async (extracted: Partial<OnboardingData>) => {
       console.log("🔄 Processing extracted data...");
 
       // Update completed steps based on what's been extracted
@@ -267,6 +266,9 @@ async function createPersistentOnboardingAgent(sessionId: string) {
       },
       required: ["businessName", "businessDescription"],
     },
+    endState: {
+      chatState: "Summarize all collected information warmly and confirm onboarding is complete",
+    },
   });
 
   // State 1: Gather business name and description
@@ -311,12 +313,8 @@ async function createPersistentOnboardingAgent(sessionId: string) {
     requiredData: ["contactEmail"],
   });
 
-  // State 7: Confirmation
-  const confirm = saveContact.transitionTo({
-    chatState: "Summarize all collected information and ask for confirmation",
-  });
-
-  confirm.transitionTo({ state: END_STATE });
+  // State 7: Confirmation - uses route-level endState
+  saveContact.transitionTo({ state: END_STATE });
 
   // Guidelines
   onboardingRoute.createGuideline({