@falai/agent 0.9.2 → 1.0.0

package/docs/guides/getting-started/README.md

@@ -13,6 +13,7 @@ By the end of this guide, you'll have a working AI agent that can:
 - ✅ Maintain context across multiple turns
 - ✅ Use tools to perform actions
 - ✅ Handle complex conversation flows
+- ✅ Execute multiple steps in a single LLM call (multi-step execution)
 
 **Time estimate:** 15-30 minutes
 
@@ -78,11 +79,11 @@ const agent = new Agent({
   provider,
 });
 
-// Create a simple route
+// Create a simple route with basic string condition
 const generalRoute = agent.createRoute({
   title: "General Help",
   description: "Answers general questions",
-  conditions: ["User needs help or asks a question"],
+  when: ["User needs help or asks a question"], // Simple string condition
   initialStep: {
     prompt: "How can I help you today?",
   },
@@ -205,7 +206,7 @@ agent.addTool({
 const bookingRoute = agent.createRoute({
   title: "Travel Booking",
   description: "Help users book travel",
-  conditions: ["User wants to book travel"],
+  when: ["User wants to book travel"],
   requiredFields: ["destination", "travelDate", "travelers"], // Required for completion
   optionalFields: ["budget"], // Nice to have but not required
   
@@ -389,6 +390,286 @@ demonstrateLifecycleHooks();
 - ✅ Understood "Next Friday, 2 people, $2000 budget" as structured data
 - ✅ Skipped asking for already-known information
 - ✅ Used the ToolManager API to create and execute tools with simplified context
+- ✅ Batched multiple steps together when data was available
+
+---
+
+## ⚡ Multi-Step Execution Benefits
+
+@falai/agent automatically batches multiple steps together when their data requirements are satisfied, reducing LLM calls and improving conversation flow.
+
+### How It Works
+
+When a user provides information that satisfies multiple steps, they execute together:
+
+```typescript
+// Traditional approach: 3 separate turns
+// Turn 1: "Which hotel?" → "Grand Hotel"
+// Turn 2: "What date?" → "Friday"
+// Turn 3: "How many guests?" → "2"
+
+// With multi-step execution: 1 turn
+const response = await agent.respond("Book Grand Hotel for 2 on Friday");
+
+// All 3 steps execute in a single LLM call!
+console.log(response.executedSteps);
+// [
+//   { id: "ask-hotel", routeId: "booking" },
+//   { id: "ask-date", routeId: "booking" },
+//   { id: "ask-guests", routeId: "booking" }
+// ]
+
+console.log(response.stoppedReason);
+// "route_complete"
+```
+
+### Benefits
+
+1. **Fewer LLM Calls** - Multiple steps in one call reduces costs
+2. **Better UX** - Users don't repeat information they've already provided
+3. **Faster Responses** - Less back-and-forth means quicker completion
+4. **Automatic** - No code changes needed, works with existing routes
+
+### Seeing It In Action
+
+```typescript
+// Create a booking route with multiple steps
+const bookingRoute = agent.createRoute({
+  title: "Hotel Booking",
+  requiredFields: ["hotel", "date", "guests"],
+  initialStep: {
+    prompt: "Which hotel?",
+    collect: ["hotel"],
+    skipIf: (data) => !!data.hotel,
+  },
+});
+
+const askDate = bookingRoute.initialStep.nextStep({
+  prompt: "What date?",
+  collect: ["date"],
+  skipIf: (data) => !!data.date,
+});
+
+const askGuests = askDate.nextStep({
+  prompt: "How many guests?",
+  collect: ["guests"],
+  skipIf: (data) => data.guests !== undefined,
+});
+
+// User provides all info at once
+const response = await agent.respond(
+  "I want to book the Grand Hotel for 2 people next Friday"
+);
+
+// Pre-extraction captures all data
+// All steps execute in one batch
+// Route completes immediately!
+
+console.log(response.message);
+// "Perfect! I've booked the Grand Hotel for 2 guests on Friday."
+
+console.log(response.isRouteComplete);
+// true
+```
+
+### Understanding the Response
+
+The response includes information about what executed:
+
+```typescript
+const response = await agent.respond("Book for 2 guests");
+
+// Which steps ran
+console.log(response.executedSteps);
+// [{ id: "ask-guests", routeId: "booking" }]
+
+// Why execution stopped
+console.log(response.stoppedReason);
+// "needs_input" - waiting for hotel and date
+
+// Or if complete:
+// "route_complete" - all steps finished
+// "end_route" - reached END_ROUTE marker
+```
+
+---
+
+## 🎯 Flexible Routing Conditions (5 minutes)
+
+Learn how to create sophisticated routing logic with the new `ConditionTemplate` system:
+
+### Simple String Conditions (Beginner)
+
+Perfect for AI-driven routing decisions:
+
+```typescript
+// String conditions provide context to AI for routing
+const supportRoute = agent.createRoute({
+  title: "Customer Support",
+  when: "User needs help or has a problem", // AI understands intent
+  initialStep: {
+    prompt: "I'm here to help! What can I assist you with?",
+  },
+});
+
+const feedbackRoute = agent.createRoute({
+  title: "Feedback Collection", 
+  when: "User wants to leave feedback or a review", // AI context
+  initialStep: {
+    prompt: "I'd love to hear your feedback!",
+  },
+});
+```
+
+### Function Conditions (Advanced)
+
+For programmatic logic and precise control:
+
+```typescript
+interface UserContext {
+  userType: 'free' | 'premium' | 'enterprise';
+  loginCount: number;
+  lastActivity: Date;
+}
+
+const agent = new Agent<UserContext>({
+  name: "SmartAgent",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
+  context: {
+    userType: 'free',
+    loginCount: 1,
+    lastActivity: new Date(),
+  },
+});
+
+// Function-only conditions for precise control
+const premiumRoute = agent.createRoute({
+  title: "Premium Features",
+  when: (ctx) => ctx.context?.userType === 'premium', // Programmatic check
+  initialStep: {
+    prompt: "Welcome to premium features! What would you like to explore?",
+  },
+});
+
+const onboardingRoute = agent.createRoute({
+  title: "User Onboarding",
+  when: (ctx) => ctx.context?.loginCount <= 3, // New user logic
+  initialStep: {
+    prompt: "Welcome! Let me show you around.",
+  },
+});
+```
+
+### Mixed Array Conditions (Expert)
+
+Combine AI understanding with programmatic precision:
+
+```typescript
+interface SupportContext {
+  userTier: 'basic' | 'premium' | 'enterprise';
+  supportTickets: number;
+  accountAge: number; // days
+}
+
+interface SupportData {
+  issueType?: 'technical' | 'billing' | 'general';
+  priority?: 'low' | 'medium' | 'high';
+  previousAttempts?: number;
+}
+
+const agent = new Agent<SupportContext, SupportData>({
+  name: "SupportAgent",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
+});
+
+// Mixed conditions: AI context + programmatic logic
+const escalationRoute = agent.createRoute({
+  title: "Escalated Support",
+  when: [
+    "User is frustrated or needs urgent help", // AI context
+    (ctx) => ctx.data?.previousAttempts > 2, // Programmatic check
+    (ctx) => ctx.context?.userTier === 'enterprise' // Context check
+  ],
+  skipIf: [
+    "Support system is under maintenance", // AI context
+    (ctx) => new Date().getHours() < 9 || new Date().getHours() > 17 // Outside hours
+  ],
+  initialStep: {
+    prompt: "I understand this is urgent. Let me connect you with our senior support team.",
+  },
+});
+
+// Advanced step conditions
+const technicalStep = escalationRoute.initialStep.nextStep({
+  when: [
+    "User has a technical issue that needs expert help", // AI context
+    (ctx) => ctx.data?.issueType === 'technical' // Data check
+  ],
+  skipIf: (ctx) => ctx.data?.priority === 'low', // Skip low priority technical issues
+  prompt: "Let me get our technical expert to help you.",
+  collect: ["issueDescription"]
+});
+```
+
+### Route SkipIf (Dynamic Exclusion)
+
+Exclude routes from consideration based on conditions:
+
+```typescript
+const paymentRoute = agent.createRoute({
+  title: "Payment Processing",
+  when: ["User wants to make a payment or purchase"],
+  skipIf: [
+    "Payment system is temporarily unavailable", // AI context
+    (ctx) => ctx.context?.paymentSystemDown === true, // System check
+    (ctx) => ctx.data?.paymentBlocked === true // User-specific block
+  ],
+  initialStep: {
+    prompt: "I'll help you with your payment.",
+  },
+});
+
+const maintenanceRoute = agent.createRoute({
+  title: "Maintenance Notice",
+  when: "User asks about system issues or downtime",
+  skipIf: (ctx) => ctx.context?.maintenanceMode !== true, // Only show during maintenance
+  initialStep: {
+    prompt: "We're currently performing scheduled maintenance. Service will resume shortly.",
+  },
+});
+```
+
+### Testing Your Conditions
+
+```typescript
+async function testConditions() {
+  // Test with different contexts
+  const basicUser = { userTier: 'basic', supportTickets: 1, accountAge: 30 };
+  const premiumUser = { userTier: 'premium', supportTickets: 5, accountAge: 365 };
+
+  // Basic user - should get standard support
+  const response1 = await agent.respond("I need help", {
+    contextOverride: basicUser
+  });
+  console.log("Basic user route:", response1.session?.currentRoute?.title);
+
+  // Premium user with multiple tickets - should get escalated support
+  const response2 = await agent.respond("I'm having issues again", {
+    contextOverride: premiumUser
+  });
+  console.log("Premium user route:", response2.session?.currentRoute?.title);
+}
+
+testConditions();
+```
+
+**Key Benefits:**
+
+- ✅ **Simple strings** for AI-driven routing decisions
+- ✅ **Functions** for precise programmatic control  
+- ✅ **Arrays** to combine both approaches
+- ✅ **Route skipIf** for dynamic exclusion
+- ✅ **Context access** in all condition types
 
 ---
 

package/docs/guides/migration/README.md

@@ -4,6 +4,29 @@ This directory contains migration guides for major changes and updates to the `@
 
 ## Available Migration Guides
 
+### [Multi-Step Execution Migration Guide](./multi-step-execution.md)
+
+**Latest Update** - Guide for understanding and migrating to multi-step batch execution.
+
+**What's New:**
+- 🚀 **Multi-Step Batching**: Multiple steps execute in a single LLM call
+- ⚡ **Reduced LLM Costs**: Fewer calls for the same outcome
+- 🎯 **Better UX**: Less back-and-forth in conversations
+- 📊 **New Response Fields**: `executedSteps`, `stoppedReason`, `error`
+
+**Key Changes:**
+- Steps batch together when data requirements are satisfied
+- Pre-extraction happens before batch determination
+- Hook execution order: all prepare → LLM → all finalize
+- SkipIf conditions affect batch determination
+
+**Migration Status:**
+- ✅ **API Compatible**: Public API shape unchanged
+- ⚠️ **Behavioral Change**: Execution semantics differ
+- ✅ **Gradual Migration**: Review hooks and tests
+
+---
+
 ### [ResponseModal Refactor Migration Guide](./response-modal-refactor.md)
 
 **Latest Update** - Comprehensive guide for migrating to the new ResponseModal architecture.