@falai/agent 0.9.0 → 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?",
   },
@@ -131,30 +132,19 @@ interface BookingData {
 ### Create an Agent with Centralized Data Schema
 
 ```typescript
-import { Agent, GeminiProvider, type Tool } from "@falai/agent";
-
-// Booking tool
-const checkAvailability: Tool<{}, [], string, BookingData> = {
-  id: "check_availability",
-  description: "Check availability and pricing",
-  parameters: {
-    type: "object",
-    properties: {},
-  },
-  handler: async (toolContext) => {
-    // Simulate availability check
-    const available = Math.random() > 0.2;
-    const price = Math.floor(Math.random() * 1000) + 500;
+import { Agent, GeminiProvider } from "@falai/agent";
 
-    return {
-      data: available
-        ? `✅ Available! Estimated cost: $${price}`
-        : "❌ Not available for those dates",
-    };
-  },
-};
+// Define data interface first
+interface BookingData {
+  destination?: string;
+  travelDate?: string;
+  travelers?: number;
+  budget?: number;
+  estimatedPrice?: number;
+  availabilityChecked?: boolean;
+}
 
-// Create agent with centralized data schema
+// Create agent with centralized data schema first
 const agent = new Agent<{}, BookingData>({
   name: "TravelAgent",
   provider: new GeminiProvider({
@@ -173,9 +163,6 @@ const agent = new Agent<{}, BookingData>({
     required: ["destination", "travelers"],
   },
   
-  // Agent-level tools available to all routes
-  tools: [checkAvailability],
-  
   // Agent-level data validation and enrichment
   hooks: {
     onDataUpdate: async (data, previousData) => {
@@ -188,11 +175,38 @@ const agent = new Agent<{}, BookingData>({
   }
 });
 
+// Create booking tool using unified Tool interface - simple return value
+agent.addTool({
+  id: "check_availability",
+  name: "Availability Checker",
+  description: "Check travel availability and pricing",
+  parameters: {
+    type: "object",
+    properties: {},
+  },
+  handler: async ({ context, data, updateData }) => {
+    // Simulate availability check using collected data
+    const available = Math.random() > 0.2;
+    const price = Math.floor(Math.random() * 1000) + 500;
+    
+    // Update data with pricing information using helper method
+    await updateData({ 
+      estimatedPrice: price,
+      availabilityChecked: true 
+    });
+
+    // Return simple string value - unified interface supports both simple and complex returns
+    return available
+      ? `✅ Available! Estimated cost: $${price} for ${data.travelers} travelers to ${data.destination}`
+      : "❌ Not available for those dates. Please try different dates.";
+  },
+};
+
 // Routes specify required fields instead of schemas
 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
   
@@ -226,7 +240,7 @@ const askBudget = askTravelers.nextStep({
 
 const checkAndBook = askBudget.nextStep({
   prompt: "Let me check availability for your trip.",
-  tool: checkAvailability, // Tool accesses complete agent data
+  tools: ["check_availability"], // Reference tool by ID
   requires: ["destination", "travelers"], // Minimum data needed
 });
 ```
@@ -245,10 +259,26 @@ async function testBookingAgent() {
     
     // Same agent-level schema and configuration
     schema: agent.schema,
-    tools: agent.tools,
     hooks: agent.hooks
   });
 
+  // Add the same tool to the session agent
+  sessionAgent.addTool({
+    id: "check_availability",
+    name: "Availability Checker",
+    description: "Check travel availability and pricing",
+    handler: async ({ context, data, updateData }) => {
+      const available = Math.random() > 0.2;
+      const price = Math.floor(Math.random() * 1000) + 500;
+      await updateData({ estimatedPrice: price, availabilityChecked: true });
+      return {
+        data: available
+          ? `✅ Available! Estimated cost: $${price} for ${data.travelers} travelers to ${data.destination}`
+          : "❌ Not available for those dates. Please try different dates.",
+      };
+    },
+  });
+
   // Copy the route to the session agent
   sessionAgent.createRoute(bookingRoute.options);
 
@@ -270,6 +300,88 @@ async function testBookingAgent() {
 }
 
 testBookingAgent();
+
+// Advanced: Show different tool creation approaches
+function demonstrateToolCreationMethods() {
+  // Method 1: Direct addition (simplest)
+  agent.addTool({
+    id: "simple_search",
+    description: "Basic search functionality",
+    handler: async ({ context, data }, args) => `Found results for: ${args.query}`
+  });
+
+  // Method 2: Registry for reuse
+  agent.tool.register({
+    id: "reusable_validator",
+    description: "Reusable validation tool",
+    handler: async ({ context, data }, args) => ({
+      data: "Validation complete",
+      success: true,
+      contextUpdate: { lastValidated: new Date() }
+    })
+  });
+
+  // Method 3: Pattern helpers
+  const enrichmentTool = agent.tool.createDataEnrichment({
+    id: "enrich_booking",
+    fields: ['destination', 'travelers'],
+    enricher: async (context, data) => ({
+      bookingCode: `${data.destination?.slice(0,3).toUpperCase()}-${data.travelers}`,
+      estimatedDuration: data.destination === 'Paris' ? '8 hours' : '12 hours'
+    })
+  });
+  
+  agent.tool.register(enrichmentTool);
+}
+
+demonstrateToolCreationMethods();
+
+// Advanced: Tools as Step Lifecycle Hooks
+function demonstrateLifecycleHooks() {
+  // Create tools for step lifecycle
+  agent.addTool({
+    id: "prepare_booking",
+    description: "Prepare booking context",
+    handler: async ({ context, data, updateContext }) => {
+      // Enrich context before AI response
+      await updateContext({ 
+        bookingStartTime: new Date().toISOString(),
+        userTier: 'premium' 
+      });
+      return "Booking preparation complete"; // Simple return
+    }
+  });
+
+  agent.addTool({
+    id: "finalize_booking", 
+    description: "Finalize booking process",
+    handler: async ({ context, data }) => {
+      // Process after AI response
+      const confirmationId = await bookingService.reserve(data);
+      return {
+        data: `Booking reserved with ID: ${confirmationId}`,
+        success: true,
+        contextUpdate: { lastBookingId: confirmationId }
+      }; // Complex ToolResult
+    }
+  });
+
+  // Use tools in step lifecycle
+  const bookingStep = agent.createRoute({
+    title: "Hotel Booking with Lifecycle",
+    steps: [{
+      id: "process_booking",
+      prompt: "Let me process your booking...",
+      prepare: "prepare_booking", // Tool executes before AI response
+      finalize: "finalize_booking", // Tool executes after AI response
+      collect: ["hotelName", "checkInDate"]
+    }]
+  });
+
+  console.log("Lifecycle hooks configured with tools");
+}
+
+demonstrateLifecycleHooks();
 ```
 
 **Notice how the agent:**
@@ -277,7 +389,287 @@ testBookingAgent();
 - ✅ Automatically extracted destination from "Paris"
 - ✅ Understood "Next Friday, 2 people, $2000 budget" as structured data
 - ✅ Skipped asking for already-known information
-- ✅ Used the check_availability tool to provide real assistance
+- ✅ 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.