@falai/agent 0.9.0 → 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/examples/advanced-patterns/knowledge-based-agent.ts

@@ -65,11 +65,11 @@ interface FeedbackData {
 // ==============================================================================
 
 // Tool: Fetch latest company news (context enrichment)
-const fetchNewsTool: Tool<CompanyContext, UnifiedData, [], void> = {
+const fetchNewsTool: Tool<CompanyContext, UnifiedData> = {
   id: "fetch_news",
   name: "Company News Fetcher",
   description: "Retrieve latest company news and updates",
-  handler: () => {
+  handler: (context, args) => {
     // Simulate API call to news service
     const news = [
       {
@@ -87,7 +87,7 @@ const fetchNewsTool: Tool<CompanyContext, UnifiedData, [], void> = {
     console.log(`[Tool] Fetched ${news.length} news articles`);
 
     return {
-      data: undefined,
+      data: `Fetched ${news.length} latest news articles`,
       contextUpdate: {
         recentNews: news,
       },
@@ -96,12 +96,12 @@ const fetchNewsTool: Tool<CompanyContext, UnifiedData, [], void> = {
 };
 
 // Tool: Search knowledge base (context enrichment)
-const searchKnowledgeTool: Tool<CompanyContext,UnifiedData, [], string> = {
+const searchKnowledgeTool: Tool<CompanyContext, UnifiedData> = {
   id: "search_knowledge",
   name: "Knowledge Base Search",
   description: "Search FAQs and documentation",
-  handler: (context) => {
-    const { history } = context;
+  handler: (toolContext, args) => {
+    const { history } = toolContext;
 
     // Get last user message
     const lastMessage = history

package/examples/advanced-patterns/persistent-onboarding.ts

@@ -228,12 +228,7 @@ function createPersistentOnboardingAgent(sessionId: string) {
   // ============================================================================
 
   // OPTION 1: Using contextUpdate in return value
-  const saveBusinessInfo: Tool<
-    OnboardingContext,
-    OnboardingData,
-    unknown[],
-    unknown
-  > = {
+  const saveBusinessInfo: Tool<OnboardingContext, OnboardingData> = {
     id: "save_business_info",
     name: "Business Info Saver",
     description: "Save business name and description",
@@ -245,12 +240,13 @@ function createPersistentOnboardingAgent(sessionId: string) {
       },
       required: ["name", "description"],
     },
-    handler: (toolContext, ...args) => {
-      const [name, description] = args as [string, string];
+    handler: (toolContext, args) => {
+      const name = args?.name as string;
+      const description = args?.description as string;
       console.log(`📝 Saving business info: ${name}`);
 
       return {
-        data: true,
+        data: "Business information saved successfully",
         // Context update is automatically persisted via onContextUpdate hook
         contextUpdate: {
           collectedData: {
@@ -267,13 +263,8 @@ function createPersistentOnboardingAgent(sessionId: string) {
     },
   };
 
-  // OPTION 2: Using updateContext method directly
-  const saveIndustry: Tool<
-    OnboardingContext,
-    OnboardingData,
-    unknown[],
-    unknown
-  > = {
+  // OPTION 2: Using contextUpdate in return value
+  const saveIndustry: Tool<OnboardingContext, OnboardingData> = {
     id: "save_industry",
     name: "Industry Classifier",
     description: "Save business industry",
@@ -284,29 +275,24 @@ function createPersistentOnboardingAgent(sessionId: string) {
       },
       required: ["industry"],
     },
-    handler: async (toolContext, ...args) => {
-      const [industry] = args as [string];
+    handler: async (toolContext, args) => {
+      const industry = args?.industry as string;
       console.log(`🏭 Saving industry: ${industry}`);
 
-      // Direct context update (triggers onContextUpdate hook)
-      await toolContext.updateContext({
-        collectedData: {
-          ...toolContext.context.collectedData,
-          industry,
+      return {
+        data: "Industry information saved successfully",
+        contextUpdate: {
+          collectedData: {
+            ...toolContext.context.collectedData,
+            industry,
+          },
+          completedSteps: [...toolContext.context.completedSteps, "industry"],
         },
-        completedSteps: [...toolContext.context.completedSteps, "industry"],
-      });
-
-      return { data: true };
+      };
     },
   };
 
-  const saveContactEmail: Tool<
-    OnboardingContext,
-    OnboardingData,
-    unknown[],
-    unknown
-  > = {
+  const saveContactEmail: Tool<OnboardingContext, OnboardingData> = {
     id: "save_contact_email",
     name: "Contact Email Saver",
     description: "Save contact email",
@@ -317,19 +303,20 @@ function createPersistentOnboardingAgent(sessionId: string) {
       },
       required: ["email"],
     },
-    handler: async (toolContext, ...args) => {
-      const [email] = args as [string];
+    handler: async (toolContext, args) => {
+      const email = args?.email as string;
       console.log(`📧 Saving contact email: ${email}`);
 
-      await toolContext.updateContext({
-        collectedData: {
-          ...toolContext.context.collectedData,
-          contactEmail: email,
+      return {
+        data: "Contact email saved successfully",
+        contextUpdate: {
+          collectedData: {
+            ...toolContext.context.collectedData,
+            contactEmail: email,
+          },
+          completedSteps: [...toolContext.context.completedSteps, "contact"],
         },
-        completedSteps: [...toolContext.context.completedSteps, "contact"],
-      });
-
-      return { data: true };
+      };
     },
   };
 

package/examples/ai-providers/anthropic-integration.ts

@@ -25,14 +25,15 @@ interface ResearchData {
 }
 
 // Research tool that Claude can use
-const conductResearch: Tool<unknown, ResearchData, unknown[], unknown> = {
+const conductResearch: Tool<unknown, ResearchData> = {
   id: "conduct_research",
   description: "Conduct comprehensive research on a given topic",
   parameters: {
     type: "object",
     properties: {},
   },
-  handler: async ({ data }) => {
+  handler: async (context, args) => {
+    const data = context.data;
     console.log(
       `Conducting ${data?.depth} research on: ${data?.topic}`
     );
@@ -52,12 +53,12 @@ const conductResearch: Tool<unknown, ResearchData, unknown[], unknown> = {
       sources: ["academic papers", "industry reports", "expert interviews"],
     };
 
-    return Promise.resolve({
+    return {
       data: `Research completed (ID: ${researchId}). ${findings.overview}`,
       dataUpdate: {
         researchId,
       },
-    });
+    };
   },
 };
 
@@ -167,10 +168,13 @@ askFormat.nextStep({
       data?.topic
     }" using ${data?.sources || 5} sources. This may take a moment...`;
   },
-  tools: [conductResearch],
+  tools: ["conduct_research"],
   requires: ["topic"],
 });
 
+// Add the research tool to the agent
+agent.addTool(conductResearch);
+
 // Demonstrate Claude's research capabilities
 async function demonstrateClaudeResearch() {
   console.log("=== Claude Research Assistant Demo ===\n");

package/examples/ai-providers/openai-integration.ts

@@ -25,8 +25,8 @@ interface WeatherData {
   condition?: string;
 }
 
-// Define a tool that can access collected data
-const getWeather: Tool<CustomerContext, WeatherData, unknown[], unknown> = {
+// Define a tool that can access collected data - using unified Tool interface
+const getWeatherTool: Tool<CustomerContext, WeatherData> = {
   id: "get_weather",
   description: "Get current weather for a location",
   parameters: {
@@ -36,14 +36,15 @@ const getWeather: Tool<CustomerContext, WeatherData, unknown[], unknown> = {
     },
     required: ["location"],
   },
-  handler: ({ data }, location) => {
+  handler: async (context, args) => {
     // Use data location if available, otherwise use args
-    const finalLocation = data?.location || location;
+    const finalLocation = context.data?.location || args?.location;
 
     // Simulate API call
     return {
-      data: {
-        location: finalLocation,
+      data: `Weather in ${finalLocation}: 72°F and Sunny`,
+      dataUpdate: {
+        location: finalLocation as string,
         temperature: 72,
         condition: "Sunny",
       },
@@ -104,6 +105,9 @@ async function main() {
     },
   });
 
+  // Add tool using unified interface
+  agent.addTool(getWeatherTool);
+
   // Add domain knowledge
   agent
     .createTerm({
@@ -139,7 +143,7 @@ async function main() {
 
   // Step 2: Get weather data
   const fetchWeather = askLocation.nextStep({
-    tools: [getWeather],
+    tools: ["get_weather"], // Reference by ID
     requires: ["location"],
   });