@falai/agent 0.9.0 → 1.0.0

package/examples/advanced-patterns/knowledge-based-agent.ts

@@ -8,6 +8,12 @@
  * 3. Session step management even for stepless conversations
  * 4. Always-on routing with context awareness
  * 5. Three-phase pipeline: PREPARATION → ROUTING → RESPONSE
+ * 6. NEW: Complex ConditionTemplate patterns for intelligent routing:
+ *    - Mixed conditions: ["AI context", (ctx) => programmatic_check]
+ *    - Route skipIf: Dynamic route exclusion based on message content
+ *    - Function-only conditions: (ctx) => sophisticated_logic
+ *    - String-only conditions: "simple AI context"
+ *    - Fallback routing with programmatic logic
  */
 
 import {
@@ -65,11 +71,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 +93,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 +102,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
@@ -119,7 +125,7 @@ const searchKnowledgeTool: Tool<CompanyContext,UnifiedData, [], string> = {
     ).message.toLowerCase();
 
     // Simple keyword matching (in real app, use vector search)
-    const relevantFaqs = context.context.faqs.filter(
+    const relevantFaqs = toolContext.context.faqs.filter(
       (faq) =>
         faq.question.toLowerCase().includes(query) ||
         faq.answer.toLowerCase().includes(query)
@@ -262,12 +268,25 @@ const agent = new Agent<CompanyContext, UnifiedData>({
 agent.createRoute({
   title: "Company Information",
   description: "Answer general questions about Acme Corp",
-  conditions: [
+  // Mixed condition: AI context + programmatic validation
+  when: [
     "User asks about the company",
     "Questions about company history, size, location",
     "When was the company founded",
     "How many employees",
     "Where is the headquarters",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.includes('company') || message.includes('acme') || message.includes('founded');
+    }
+  ],
+  // Skip if user is asking about specific products instead
+  skipIf: [
+    "user is asking about specific products or services",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.includes('widget') || message.includes('gadget') || message.includes('product');
+    }
   ],
   // Route-specific knowledge base for company information
   knowledgeBase: {
@@ -299,12 +318,18 @@ agent.createRoute({
 agent.createRoute({
   title: "Product Information",
   description: "Answer questions about products",
-  conditions: [
-    "User asks about products",
-    "Questions about features, pricing, availability",
-    "What products do you offer",
-    "Tell me about your widgets",
-  ],
+  // Function-only condition for programmatic logic
+  when: (ctx) => {
+    const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+    return message.includes('product') || message.includes('widget') || 
+           message.includes('gadget') || message.includes('price') || 
+           message.includes('feature');
+  },
+  // Skip if user is asking about company policies instead
+  skipIf: (ctx) => {
+    const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+    return message.includes('policy') || message.includes('return') || message.includes('warranty');
+  },
   // NO schema - just answering questions
 });
 
@@ -315,11 +340,25 @@ agent.createRoute({
 agent.createRoute({
   title: "Policy Information",
   description: "Answer questions about company policies",
-  conditions: [
+  // Mixed condition: AI context + programmatic check
+  when: [
     "User asks about policies",
     "Return policy",
-    "Shipping information",
+    "Shipping information", 
     "Warranty questions",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.includes('policy') || message.includes('return') || 
+             message.includes('shipping') || message.includes('warranty');
+    }
+  ],
+  // Skip if user is asking about news or updates
+  skipIf: [
+    "user wants latest news or updates",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.includes('news') || message.includes('update') || message.includes('new');
+    }
   ],
   // NO schema
 });
@@ -330,12 +369,13 @@ agent.createRoute({
 const newsRoute = agent.createRoute({
   title: "Company News",
   description: "Share latest company news and updates",
-  conditions: [
-    "User asks about news",
-    "What's new",
-    "Recent updates",
-    "Latest announcements",
-  ],
+  // String-only condition for AI context
+  when: "User asks about news, updates, or recent announcements",
+  // Skip if user is asking about general FAQ topics
+  skipIf: (ctx) => {
+    const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+    return message.includes('how do i') || message.includes('can i') || message.includes('is there');
+  },
 });
 
 // Add tool to initial step to fetch news
@@ -351,11 +391,25 @@ fetchNews.nextStep({
 const faqRoute = agent.createRoute({
   title: "FAQ Search",
   description: "Search FAQs for relevant answers",
-  conditions: [
+  // Mixed condition: AI context + programmatic pattern matching
+  when: [
     "User has a question that might be in FAQs",
     "How do I...",
     "Can I...",
     "Is there...",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.startsWith('how ') || message.startsWith('can ') || 
+             message.startsWith('is ') || message.includes('?');
+    }
+  ],
+  // Skip if user is clearly asking for news or company info
+  skipIf: [
+    "user wants company news or general company information",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.includes('news') || message.includes('company') || message.includes('founded');
+    }
   ],
 });
 
@@ -372,12 +426,15 @@ searchFaqs.nextStep({
 agent.createRoute({
   title: "General Conversation",
   description: "Handle general conversation or unclear questions",
-  conditions: [
-    "User message doesn't match other routes",
-    "Greetings",
-    "Small talk",
-    "Unclear intent",
-  ],
+  // Function-only condition for fallback logic
+  when: (ctx) => {
+    // This route catches everything that doesn't match other routes
+    const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+    return !message.includes('product') && !message.includes('policy') && 
+           !message.includes('news') && !message.includes('company');
+  },
+  // Never skip the fallback route
+  skipIf: ()=>false,
 });
 
 // Initial step is enough for fallback conversations
@@ -386,7 +443,27 @@ agent.createRoute({
 const feedbackRoute = agent.createRoute({
   title: "Collect Feedback",
   description: "Collect user feedback about their experience",
-  conditions: ["User wants to leave feedback", "User seems satisfied or upset"],
+  // Mixed condition: AI context + sentiment analysis
+  when: [
+    "User wants to leave feedback", 
+    "User seems satisfied or upset",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.includes('feedback') || message.includes('review') || 
+             message.includes('satisfied') || message.includes('disappointed');
+    }
+  ],
+  // Skip if user is in the middle of another task
+  skipIf: [
+    "user is actively getting help with something else",
+    (ctx) => {
+      const recentMessages = ctx.history?.filter((m) => "content" in m).slice(-3) || [];
+      return recentMessages.some(msg => 
+        (msg.content as string)?.toLowerCase().includes('help') || 
+        (msg.content as string)?.toLowerCase().includes('problem')
+      );
+    }
+  ],
   // NEW: Required fields for route completion
   requiredFields: ["rating", "comments"],
   // NEW: Optional fields

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

@@ -1,6 +1,13 @@
 /**
  * Persistent multi-turn onboarding agent example
  * Updated for v2 architecture with session step management and schema-first data extraction
+ * 
+ * NEW: Enhanced with flexible ConditionTemplate patterns:
+ * - Mixed route conditions: ["AI context", (ctx) => state_check]
+ * - Route skipIf: Skip if onboarding already complete
+ * - Step skipIf: Enhanced conditional step skipping with AI context
+ * - Programmatic when conditions: (ctx) => data_validation
+ * - Performance patterns for condition evaluation
  */
 
 import {
@@ -228,12 +235,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 +247,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 +270,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 +282,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 +310,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 };
+      };
     },
   };
 
@@ -340,7 +334,24 @@ function createPersistentOnboardingAgent(sessionId: string) {
   const onboardingRoute = agent.createRoute({
     title: "Business Onboarding",
     description: "Guide user through business information collection",
-    conditions: ["User is onboarding their business"],
+    // Mixed condition: AI context + programmatic validation
+    when: [
+      "User is onboarding their business",
+      (ctx) => {
+        const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+        return message.includes('onboard') || message.includes('register') || 
+               message.includes('business') || message.includes('start');
+      }
+    ],
+    // Skip if user already has complete business info
+    skipIf: [
+      "business information already complete",
+      (ctx) => {
+        const data = ctx.data;
+        return !!(data?.businessName && data?.businessDescription && 
+                 data?.industry && data?.contactEmail);
+      }
+    ],
     // NEW: Required fields for route completion
     requiredFields: ["businessName", "businessDescription"],
     // NEW: Optional fields that enhance the experience
@@ -355,7 +366,12 @@ function createPersistentOnboardingAgent(sessionId: string) {
   const collectBusinessInfo = onboardingRoute.initialStep.nextStep({
     prompt: "Ask for business name and a brief description",
     collect: ["businessName", "businessDescription"],
-    skipIf: (data) => !!data.businessName && !!data.businessDescription,
+    // Mixed skipIf: AI context + programmatic check
+    skipIf: [
+      "business name and description already provided",
+      (ctx) => !!ctx.data?.businessName && !!ctx.data.businessDescription
+    ],
+    // String-only when condition for AI context
     when: "Need to collect basic business information first",
   });
 
@@ -363,14 +379,19 @@ function createPersistentOnboardingAgent(sessionId: string) {
   const saveBusiness = collectBusinessInfo.nextStep({
     tools: [saveBusinessInfo],
     requires: ["businessName", "businessDescription"],
-    when: "Business name and description provided, save to database",
+    // Function-only when condition for programmatic logic
+    when: (ctx) => !!ctx.data?.businessName && !!ctx.data?.businessDescription,
   });
 
   // Step 3: Collect industry
   const collectIndustry = saveBusiness.nextStep({
     prompt: "Ask what industry the business operates in",
     collect: ["industry"],
-    skipIf: (data) => !!data.industry,
+    // Mixed skipIf: AI context + programmatic logic
+    skipIf: [
+      "industry already specified",
+      (ctx) => !!ctx.data?.industry
+    ],
   });
 
   // Step 4: Save industry (tool execution)
@@ -383,7 +404,8 @@ function createPersistentOnboardingAgent(sessionId: string) {
   const collectContact = saveIndustryStep.nextStep({
     prompt: "Ask for their contact email",
     collect: ["contactEmail"],
-    skipIf: (data) => !!data.contactEmail,
+    // Function-only skipIf for programmatic check
+    skipIf: (ctx) => !!ctx.data?.contactEmail,
   });
 
   // Step 6: Save contact (tool execution)

package/examples/advanced-patterns/route-lifecycle-hooks.ts

@@ -4,6 +4,14 @@
  *
  * Demonstrates how to use rules and prohibitions to control agent behavior
  * in different conversation routes (e.g., WhatsApp bot with different styles)
+ * 
+ * NEW: Enhanced with complex ConditionTemplate patterns:
+ * - Mixed conditions: ["AI context", (ctx) => keyword_detection]
+ * - Route skipIf: Dynamic route exclusion based on message analysis
+ * - Function-only conditions: (ctx) => sophisticated_routing_logic
+ * - String-only conditions: "simple AI context for general chat"
+ * - Emergency routing with never-skip logic (skipIf: false)
+ * - Performance patterns for real-time condition evaluation
  */
 
 import { Agent, type History, END_ROUTE, OpenAIProvider } from "../../src";
@@ -112,7 +120,23 @@ const agent = new Agent<unknown, ServiceData>({
 agent.createRoute({
   title: "Quick Support",
   description: "Fast answers for common questions",
-  conditions: ["User has a simple question", "User wants quick help"],
+  // Mixed condition: AI context + programmatic validation
+  when: [
+    "User has a simple question", 
+    "User wants quick help",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.includes('quick') || message.includes('simple') || message.length < 50;
+    }
+  ],
+  // Skip if user seems to need detailed help
+  skipIf: [
+    "user needs detailed or complex assistance",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.includes('detailed') || message.includes('complex') || message.length > 100;
+    }
+  ],
   rules: [
     "Keep messages extremely short (1-2 lines maximum)",
     "Use bullet points for lists",
@@ -130,9 +154,21 @@ agent.createRoute({
 agent.createRoute({
   title: "Sales Consultation",
   description: "Help customer discover needs and present solutions",
-  conditions: [
-    "User is interested in buying",
-    "User wants product information",
+  // Function-only condition for programmatic sales detection
+  when: (ctx) => {
+    const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+    return message.includes('buy') || message.includes('purchase') || 
+           message.includes('price') || message.includes('cost') ||
+           message.includes('product') || message.includes('interested');
+  },
+  // Skip if user is having technical issues
+  skipIf: [
+    "user has technical problems that need solving first",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.includes('broken') || message.includes('error') || 
+             message.includes('not working') || message.includes('problem');
+    }
   ],
   rules: [
     "Ask open-ended questions to discover needs",
@@ -169,7 +205,22 @@ agent.createRoute({
 agent.createRoute({
   title: "Technical Support",
   description: "Help with technical issues and troubleshooting",
-  conditions: ["User has technical problem", "User needs step-by-step help"],
+  // Mixed condition: AI context + technical keyword detection
+  when: [
+    "User has technical problem", 
+    "User needs step-by-step help",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.includes('help') || message.includes('problem') || 
+             message.includes('error') || message.includes('not working') ||
+             message.includes('broken') || message.includes('fix');
+    }
+  ],
+  // Skip if user is just browsing or asking about sales
+  skipIf: (ctx) => {
+    const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+    return message.includes('price') || message.includes('buy') || message.includes('cost');
+  },
   rules: [
     "Provide clear, numbered steps",
     "Use simple language for technical concepts",
@@ -209,7 +260,19 @@ techSupportRoute.initialStep
 agent.createRoute({
   title: "Emergency Support",
   description: "Handle urgent customer issues",
-  conditions: ["Customer is frustrated", "Urgent issue", "Service down"],
+  // Mixed condition: AI context + urgency detection
+  when: [
+    "Customer is frustrated", 
+    "Urgent issue", 
+    "Service down",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      const urgentWords = ['urgent', 'emergency', 'critical', 'down', 'broken', 'frustrated', 'angry'];
+      return urgentWords.some(word => message.includes(word)) || message.includes('!!!');
+    }
+  ],
+  // Never skip emergency support
+  skipIf: ()=>false,
   rules: [
     "Acknowledge the urgency immediately",
     "Express empathy and understanding",
@@ -229,7 +292,14 @@ agent.createRoute({
 agent.createRoute({
   title: "General Chat",
   description: "Casual conversation and general questions",
-  conditions: ["User is just chatting", "Greeting", "General question"],
+  // String-only condition for AI context
+  when: "User is just chatting, greeting, or asking general questions",
+  // Skip if user has specific needs that other routes can handle
+  skipIf: (ctx) => {
+    const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+    return message.includes('help') || message.includes('buy') || 
+           message.includes('problem') || message.includes('urgent');
+  },
   rules: [
     "Be friendly and conversational",
     "Use emojis naturally 😊",
@@ -262,7 +332,7 @@ async function demonstrateRulesAndProhibitions() {
   agent.createRoute({
     title: "Quick Support",
     description: "Fast answers for common questions",
-    conditions: ["User has a simple question", "User wants quick help"],
+    when: ["User has a simple question", "User wants quick help"],
     rules: [
       "Keep messages extremely short (1-2 lines maximum)",
       "Use bullet points for lists",
@@ -280,7 +350,7 @@ async function demonstrateRulesAndProhibitions() {
   agent.createRoute({
     title: "Sales Consultation",
     description: "Help customer discover needs and present solutions",
-    conditions: [
+    when: [
       "User is interested in buying",
       "User wants product information",
     ],
@@ -303,7 +373,7 @@ async function demonstrateRulesAndProhibitions() {
   agent.createRoute({
     title: "Technical Support",
     description: "Help with technical issues and troubleshooting",
-    conditions: ["User has technical problem", "User needs step-by-step help"],
+    when: ["User has technical problem", "User needs step-by-step help"],
     rules: [
       "Provide clear, numbered steps",
       "Use simple language for technical concepts",
@@ -343,7 +413,7 @@ async function demonstrateRulesAndProhibitions() {
   agent.createRoute({
     title: "Emergency Support",
     description: "Handle urgent customer issues",
-    conditions: ["Customer is frustrated", "Urgent issue", "Service down"],
+    when: ["Customer is frustrated", "Urgent issue", "Service down"],
     rules: [
       "Acknowledge the urgency immediately",
       "Express empathy and understanding",
@@ -363,7 +433,7 @@ async function demonstrateRulesAndProhibitions() {
   agent.createRoute({
     title: "General Chat",
     description: "Casual conversation and general questions",
-    conditions: ["User is just chatting", "Greeting", "General question"],
+    when: ["User is just chatting", "Greeting", "General question"],
     rules: [
       "Be friendly and conversational",
       "Use emojis naturally 😊",

package/examples/advanced-patterns/streaming-responses.ts

@@ -361,7 +361,7 @@ async function modernStreamingWithRoutes() {
   const supportRoute = agent.createRoute({
     title: "Product Support",
     description: "Help users with product questions",
-    conditions: ["User asks about product features or issues"],
+    when: ["User asks about product features or issues"],
   });
 
   supportRoute.initialStep.nextStep({
@@ -372,7 +372,7 @@ async function modernStreamingWithRoutes() {
   agent.createRoute({
     title: "Collect Feedback",
     description: "Collect user feedback on their support experience",
-    conditions: ["User wants to provide feedback"],
+    when: ["User wants to provide feedback"],
     // NEW: Required fields for route completion
     requiredFields: ["rating"],
     // NEW: Optional fields