@falai/agent 0.9.0-alpha-2 → 0.9.2

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

@@ -131,30 +131,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 +162,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,6 +174,33 @@ 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",
@@ -226,7 +239,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 +258,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 +299,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 +388,7 @@ 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
 
 ---
 

package/docs/guides/migration/README.md

@@ -0,0 +1,72 @@
+# Migration Guides
+
+This directory contains migration guides for major changes and updates to the `@falai/agent` framework.
+
+## Available Migration Guides
+
+### [ResponseModal Refactor Migration Guide](./response-modal-refactor.md)
+
+**Latest Update** - Comprehensive guide for migrating to the new ResponseModal architecture.
+
+**What's New:**
+- 🚀 **Modern Streaming API**: Simple `agent.stream('message')` interface
+- 🏗️ **Better Architecture**: Separated response logic from Agent class
+- 🔄 **Full Backward Compatibility**: All existing code continues to work
+- ⚡ **Performance Improvements**: Unified response logic and optimizations
+
+**Key Benefits:**
+- Automatic session management with `stream()` API
+- Simplified streaming interface compared to `respondStream()`
+- Better error handling with `ResponseGenerationError`
+- Improved maintainability and testability
+
+**Migration Status:**
+- ✅ **Backward Compatible**: No breaking changes
+- ✅ **Gradual Migration**: Adopt new APIs at your own pace
+- ✅ **Production Ready**: New APIs are fully tested and stable
+
+---
+
+## Migration Philosophy
+
+Our migration approach prioritizes:
+
+1. **🔄 Backward Compatibility**: Existing code continues to work without changes
+2. **📈 Gradual Adoption**: New features can be adopted incrementally
+3. **📚 Clear Documentation**: Comprehensive guides with examples
+4. **🛠️ Developer Experience**: Improved APIs that are easier to use
+5. **⚡ Performance**: Better performance without breaking existing functionality
+
+## Getting Help
+
+- **📖 Documentation**: Each migration guide includes detailed examples and comparisons
+- **💡 Examples**: Check the [examples directory](../../../examples/) for updated code samples
+- **🐛 Issues**: Report migration issues on [GitHub Issues](https://github.com/falai-dev/agent/issues)
+- **💬 Discussions**: Ask questions in [GitHub Discussions](https://github.com/falai-dev/agent/discussions)
+
+## Best Practices
+
+### Before Migrating
+
+1. **Read the migration guide** thoroughly
+2. **Test in development** before applying to production
+3. **Review examples** to understand new patterns
+4. **Check for breaking changes** (though we avoid them when possible)
+
+### During Migration
+
+1. **Migrate gradually** - don't change everything at once
+2. **Keep existing code working** while adopting new APIs
+3. **Test thoroughly** after each migration step
+4. **Monitor performance** to ensure improvements
+
+### After Migration
+
+1. **Update documentation** to reflect new patterns
+2. **Train team members** on new APIs and best practices
+3. **Monitor for issues** and report any problems
+4. **Share feedback** to help improve future migrations
+
+---
+
+**Stay Updated**: Watch the repository for new migration guides and updates.