@falai/agent 0.5.5 → 0.6.0

package/dist/types/route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/types/route.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,UAAU,GAAG,OAAO;IAChD,qGAAqG;IACrG,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,wCAAwC;IACxC,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,4EAA4E;IAC5E,mBAAmB,CAAC,EAAE,gBAAgB,CAAC;IACvC,6EAA6E;IAC7E,oBAAoB,CAAC,EAAE,gBAAgB,CAAC;IACxC;;;OAGG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,QAAQ,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO;IACtE,2FAA2F;IAC3F,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IAEnC,SAAS,CAAC,EAAE,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,EAAE,GAAG,CAAC,CAAC;IAC1C,mDAAmD;IACnD,KAAK,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC;IACrD;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB,CAAC,QAAQ,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO,CACxE,SAAQ,QAAQ;IAChB,iCAAiC;IACjC,YAAY,EAAE,CACZ,IAAI,EAAE,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC,EAC1C,SAAS,CAAC,EAAE,MAAM,KACf,gBAAgB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;CAC7C"}
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/types/route.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,UAAU,GAAG,OAAO;IAChD,qGAAqG;IACrG,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,wCAAwC;IACxC,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,4EAA4E;IAC5E,mBAAmB,CAAC,EAAE,gBAAgB,CAAC;IACvC,6EAA6E;IAC7E,oBAAoB,CAAC,EAAE,gBAAgB,CAAC;IACxC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAClC;;;;OAIG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC,OAAO,EAAE,UAAU,CAAC,EAAE,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,QAAQ,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO;IACtE,2FAA2F;IAC3F,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IAEnC,SAAS,CAAC,EAAE,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,EAAE,GAAG,CAAC,CAAC;IAC1C,mDAAmD;IACnD,KAAK,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC;IACrD;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB,CAAC,QAAQ,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO,CACxE,SAAQ,QAAQ;IAChB,iCAAiC;IACjC,YAAY,EAAE,CACZ,IAAI,EAAE,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC,KACvC,gBAAgB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;CAC7C"}

package/docs/ADAPTERS.md

@@ -102,7 +102,7 @@ const agent = new Agent({
 // Create a route with data extraction
 const route = agent.createRoute<YourDataType>({
   title: "My Route",
-  gatherSchema: {
+  extractionSchema: {
     type: "object",
     properties: {
       field1: { type: "string" },

package/docs/API_REFERENCE.md

@@ -321,7 +321,7 @@ interface RouteOptions<TExtracted = unknown> {
   prohibitions?: string[];  // Absolute prohibitions the agent MUST NEVER do in this route
 
   // NEW: Schema-first data extraction
-  gatherSchema?: {
+  extractionSchema?: {
     type: "object";
     properties: Record<string, any>;
     required?: string[];
@@ -395,7 +395,7 @@ Represents a state within a conversation route.
 
 #### Methods
 
-##### `transitionTo(spec: TransitionSpec, condition?: string): TransitionResult`
+##### `transitionTo(spec: TransitionSpec): TransitionResult`
 
 Creates a transition from this state and returns a chainable result.
 
@@ -413,22 +413,23 @@ interface TransitionSpec<TExtracted = unknown> {
 
   // NEW: Prerequisites that must be met to enter this state
   requiredData?: string[];
+
+  // Optional: AI-evaluated text condition for this transition
+  condition?: string;
 }
 
 interface TransitionResult<TExtracted = unknown> {
   id: string; // State identifier
   routeId: string; // Route identifier
   transitionTo: (
-    spec: TransitionSpec<TExtracted>,
-    condition?: string // Optional: AI-evaluated text condition for this transition
+    spec: TransitionSpec<TExtracted>
   ) => TransitionResult<TExtracted>;
 }
 ```
 
 **Parameters:**
 
-- `spec`: The transition specification (see `TransitionSpec` above)
-- `condition` (optional): Human-readable condition text that the AI evaluates when selecting states. Use this to guide the AI's state selection based on conversation context. Examples: "Customer confirmed payment", "All required data collected", "User wants to modify order"
+- `spec`: The transition specification (see `TransitionSpec` above). Can include an optional `condition` property for AI-evaluated state selection guidance.
 
 **Returns:** A `TransitionResult` that includes the target state's reference (`id`, `routeId`) and a `transitionTo` method for chaining additional transitions.
 
@@ -445,7 +446,7 @@ interface FlightData {
 // Create a data-driven route
 const flightRoute = agent.createRoute<FlightData>({
   title: "Book Flight",
-  gatherSchema: {
+  extractionSchema: {
     type: "object",
     properties: {
       destination: { type: "string" },
@@ -457,24 +458,20 @@ const flightRoute = agent.createRoute<FlightData>({
 });
 
 // Approach 1: Step-by-step with data extraction and text conditions
-const askDestination = flightRoute.initialState.transitionTo(
-  {
-    chatState: "Ask where they want to fly",
-    gather: ["destination"],
-    skipIf: (extracted) => !!extracted.destination, // Skip if already have destination
-  },
-  "Customer hasn't specified destination yet" // AI-evaluated condition
-);
+const askDestination = flightRoute.initialState.transitionTo({
+  chatState: "Ask where they want to fly",
+  gather: ["destination"],
+  skipIf: (extracted) => !!extracted.destination, // Skip if already have destination
+  condition: "Customer hasn't specified destination yet", // AI-evaluated condition
+});
 
-const askDates = askDestination.transitionTo(
-  {
-    chatState: "Ask about travel dates",
-    gather: ["departureDate"],
-    skipIf: (extracted) => !!extracted.departureDate,
-    requiredData: ["destination"], // Must have destination first
-  },
-  "Destination confirmed, need travel dates"
-);
+const askDates = askDestination.transitionTo({
+  chatState: "Ask about travel dates",
+  gather: ["departureDate"],
+  skipIf: (extracted) => !!extracted.departureDate,
+  requiredData: ["destination"], // Must have destination first
+  condition: "Destination confirmed, need travel dates",
+});
 
 const askPassengers = askDates.transitionTo({
   chatState: "How many passengers?",
@@ -1557,7 +1554,7 @@ interface SessionState<TExtracted = Record<string, unknown>> {
 **Key Features:**
 
 - **`id`** - Optional session identifier that persists across database operations
-- **`extracted`** - Type-safe data collected via `gatherSchema`
+- **`extracted`** - Type-safe data collected via `extractionSchema`
 - **`currentRoute`** / **`currentState`** - Track conversation position
 - **`routeHistory`** - Full audit trail of route transitions
 - **`metadata`** - Custom data (timestamps, user info, etc.)

package/docs/ARCHITECTURE.md

@@ -22,7 +22,7 @@ interface FlightData {
 const route = agent.createRoute<FlightData>({
   title: "Book Flight",
   description: "Help user book a flight",
-  gatherSchema: {
+  extractionSchema: {
     type: "object",
     properties: {
       destination: { type: "string" },
@@ -112,26 +112,22 @@ Use TypeScript functions for deterministic flow control AND text conditions for
 
 ```typescript
 // State with smart bypassing based on extracted data
-const askDestination = route.initialState.transitionTo(
-  {
-    id: "ask_destination", // Optional: custom state ID
-    chatState: "Ask where they want to fly",
-    gather: ["destination"],
-    skipIf: (extracted) => !!extracted.destination, // Code-based condition!
-  },
-  "Customer hasn't specified destination yet" // Text condition for AI
-);
+const askDestination = route.initialState.transitionTo({
+  id: "ask_destination", // Optional: custom state ID
+  chatState: "Ask where they want to fly",
+  gather: ["destination"],
+  skipIf: (extracted) => !!extracted.destination, // Code-based condition!
+  condition: "Customer hasn't specified destination yet", // Text condition for AI
+});
 
-const askDate = askDestination.transitionTo(
-  {
-    id: "ask_date", // Optional: custom state ID for easier tracking
-    chatState: "Ask about travel dates",
-    gather: ["departureDate"],
-    skipIf: (extracted) => !!extracted.departureDate,
-    requiredData: ["destination"], // Prerequisites
-  },
-  "Destination confirmed, need travel dates now"
-);
+const askDate = askDestination.transitionTo({
+  id: "ask_date", // Optional: custom state ID for easier tracking
+  chatState: "Ask about travel dates",
+  gather: ["departureDate"],
+  skipIf: (extracted) => !!extracted.departureDate,
+  requiredData: ["destination"], // Prerequisites
+  condition: "Destination confirmed, need travel dates now",
+});
 });
 ```
 
@@ -374,7 +370,7 @@ interface BookingData {
 
 const bookingRoute = agent.createRoute<BookingData>({
   title: "Flight Booking",
-  gatherSchema: {
+  extractionSchema: {
     /* schema for all fields */
   },
 });
@@ -404,7 +400,7 @@ For simple question-answering without state:
 const qnaRoute = agent.createRoute({
   title: "Company Q&A",
   conditions: ["User asks about company"],
-  // NO gatherSchema - stateless!
+  // NO extractionSchema - stateless!
 });
 
 // Just use initial state

package/docs/CONSTRUCTOR_OPTIONS.md

@@ -103,7 +103,7 @@ const agent = new Agent<FlightBookingContext>({
       title: 'Book Flight',
       description: 'Help user book a flight',
       conditions: ['User wants to book a flight'],
-      gatherSchema: {
+      extractionSchema: {
         type: 'object',
         properties: {
           destination: { type: 'string' },
@@ -175,7 +175,7 @@ interface RouteOptions<TExtracted = unknown> {
   prohibitions?: string[];  // Absolute prohibitions the agent MUST NEVER do
 
   // NEW: Schema-first data extraction
-  gatherSchema?: {
+  extractionSchema?: {
     type: "object";
     properties: Record<string, any>;
     required?: string[];

package/docs/CONTEXT_MANAGEMENT.md

@@ -182,7 +182,7 @@ interface FlightData {
 
 const route = agent.createRoute<FlightData>({
   title: "Book Flight",
-  gatherSchema: {
+  extractionSchema: {
     type: "object",
     properties: {
       destination: { type: "string" },

package/docs/GETTING_STARTED.md

@@ -86,7 +86,7 @@ const bookingRoute = agent.createRoute<FlightData>({
   title: "Book Flight",
   description: "Help user book a flight",
   conditions: ["User wants to book a flight"],
-  gatherSchema: {
+  extractionSchema: {
     type: "object",
     properties: {
       destination: { type: "string" },

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)",

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: {