@falai/agent 1.2.8 → 2.0.1

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

@@ -1,556 +0,0 @@
-/**
- * Rules & Prohibitions Example
- * Updated for v2 architecture with session step management
- *
- * 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";
-
-/**
- * Configuration for the AI provider
- */
-const provider = new OpenAIProvider({
-  apiKey: process.env.OPENAI_API_KEY || "your-api-key-here",
-  model: "gpt-5",
-});
-
-// Define data schema for feedback collection
-interface ServiceData {
-  feedbackRating?: number;
-  feedbackComments?: string;
-}
-
-const serviceSchema = {
-  type: "object",
-  properties: {
-    feedbackRating: {
-      type: "number",
-      description: "Rating from 1-5",
-      minimum: 1,
-      maximum: 5,
-    },
-    feedbackComments: {
-      type: "string",
-      description: "Additional feedback comments",
-    },
-  },
-};
-
-/**
- * Create a new agent instance with predefined routes and rules/prohibitions.
- */
-const agent = new Agent<unknown, ServiceData>({
-  name: "CustomerServiceAgent",
-  description:
-    "A versatile customer service agent that adapts its behavior based on the conversation's context.",
-  goal: "Provide excellent customer service by following route-specific rules and prohibitions.",
-  provider,
-  // NEW: Agent-level schema
-  schema: serviceSchema,
-  debug: true,
-
-  // Knowledge base with customer service best practices
-  knowledgeBase: {
-    communicationGuidelines: {
-      channels: {
-        whatsapp: {
-          maxMessageLength: "1000 characters",
-          supports: ["text", "images", "documents"],
-          bestFor: [
-            "Quick questions",
-            "Personal communication",
-            "Mobile users",
-          ],
-        },
-        email: {
-          maxMessageLength: "No limit",
-          supports: ["text", "attachments", "formatting"],
-          bestFor: [
-            "Detailed inquiries",
-            "Documentation",
-            "Formal communication",
-          ],
-        },
-        chat: {
-          maxMessageLength: "Real-time",
-          supports: ["text", "quick responses"],
-          bestFor: ["Immediate help", "Simple questions", "Live support"],
-        },
-      },
-      toneGuidelines: {
-        professional: "Formal language, complete sentences, proper grammar",
-        casual: "Friendly language, contractions, emojis allowed",
-        urgent: "Direct, clear, action-oriented language",
-      },
-    },
-    escalationPaths: {
-      technical: "Route to technical support team",
-      billing: "Route to billing department",
-      complaint: "Route to customer success manager",
-      legal: "Route to legal/compliance team",
-    },
-    responseTimeTargets: {
-      whatsapp: "Within 5 minutes during business hours",
-      email: "Within 24 hours",
-      chat: "Immediate response",
-      emergency: "Immediate escalation",
-    },
-    customerSegments: {
-      new: "Welcome warmly, provide overview, offer help",
-      returning: "Personalize greeting, reference history, anticipate needs",
-      vip: "Priority service, direct manager access, special offers",
-      enterprise: "Dedicated account manager, SLA guarantees, custom solutions",
-    },
-  },
-});
-
-/**
- * Add routes to the agent.
- */
-agent.createRoute({
-  title: "Quick Support",
-  description: "Fast answers for common questions",
-  // 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",
-    "Maximum 1 emoji per message 👍",
-    "Be direct and to the point",
-  ],
-  prohibitions: [
-    "Never send long paragraphs",
-    "Do not over-explain",
-    "Never use more than 2 emojis",
-    "Do not ask follow-up questions unless necessary",
-  ],
-});
-
-agent.createRoute({
-  title: "Sales Consultation",
-  description: "Help customer discover needs and present solutions",
-  // 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",
-    "Use storytelling when presenting solutions",
-    "Emoji to reinforce positive emotions 😊✨",
-    "Present value before mentioning price",
-    "Make customer feel special and understood",
-  ],
-  prohibitions: [
-    "Never talk about price before showing value",
-    "Do not pressure or push",
-    "Avoid technical jargon",
-    "Never send more than 2 messages without waiting for response",
-    "Do not make promises you cannot keep",
-  ],
-  // Route-level guidelines for sales behavior
-  guidelines: [
-    {
-      condition: "Customer mentions budget concerns",
-      action: "Focus on ROI and long-term value rather than upfront cost",
-    },
-    {
-      condition: "Customer seems hesitant or unsure",
-      action: "Offer a free trial or consultation to reduce risk",
-    },
-    {
-      condition: "Customer asks for competitors comparison",
-      action:
-        "Highlight unique strengths and differentiators without negative comments",
-    },
-  ],
-});
-
-agent.createRoute({
-  title: "Technical Support",
-  description: "Help with technical issues and troubleshooting",
-  // 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",
-    "Confirm understanding after each major step",
-    "Offer screenshots or visual aids when helpful",
-    "Be patient and thorough",
-  ],
-  prohibitions: [
-    "Never skip steps or assume knowledge",
-    "Do not use excessive technical terms without explanation",
-    "Never blame the user for the issue",
-    "Do not rush through explanations",
-  ],
-});
-
-// Add a stepful feedback flow to the Technical Support route
-const techSupportRoute = agent
-  .getRoutes()
-  .find((r) => r.title === "Technical Support")!;
-techSupportRoute.initialStep
-  .nextStep({
-    prompt: "Provide step-by-step technical assistance.",
-  })
-  .nextStep({
-    prompt: "Ask for a rating of the support provided (1-5).",
-    collect: ["feedbackRating"],
-  })
-  .nextStep({
-    prompt: "Ask for any additional comments.",
-    collect: ["feedbackComments"],
-  })
-  .nextStep({
-    prompt: "Thank the user for their feedback.",
-  })
-  .nextStep({ step: END_ROUTE });
-
-agent.createRoute({
-  title: "Emergency Support",
-  description: "Handle urgent customer issues",
-  // 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",
-    "Provide concrete next steps",
-    "Set clear expectations on resolution time",
-    "Keep customer updated",
-  ],
-  prohibitions: [
-    "Never downplay the customer's concern",
-    "Do not use emojis (keep it professional)",
-    'Never say "calm down" or similar dismissive phrases',
-    "Do not transfer without explaining why",
-    "Never make excuses or blame others",
-  ],
-});
-
-agent.createRoute({
-  title: "General Chat",
-  description: "Casual conversation and general questions",
-  // 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 😊",
-    "Mirror the customer's tone and energy",
-    "Keep it light and positive",
-  ],
-  prohibitions: [
-    "Do not be overly formal",
-    "Never ignore the customer's mood",
-    "Do not push products unless asked",
-  ],
-});
-
-/**
- * Demonstration function to show how the agent responds to different scenarios.
- */
-async function demonstrateRulesAndProhibitions() {
-  const agent = new Agent<unknown, ServiceData>({
-    name: "CustomerServiceAgent",
-    description:
-      "A versatile customer service agent that adapts its behavior based on the conversation's context.",
-    goal: "Provide excellent customer service by following route-specific rules and prohibitions.",
-    provider,
-    // NEW: Agent-level schema
-    schema: serviceSchema,
-    debug: true,
-  });
-
-  // Add domains
-  agent.createRoute({
-    title: "Quick Support",
-    description: "Fast answers for common questions",
-    when: ["User has a simple question", "User wants quick help"],
-    rules: [
-      "Keep messages extremely short (1-2 lines maximum)",
-      "Use bullet points for lists",
-      "Maximum 1 emoji per message 👍",
-      "Be direct and to the point",
-    ],
-    prohibitions: [
-      "Never send long paragraphs",
-      "Do not over-explain",
-      "Never use more than 2 emojis",
-      "Do not ask follow-up questions unless necessary",
-    ],
-  });
-
-  agent.createRoute({
-    title: "Sales Consultation",
-    description: "Help customer discover needs and present solutions",
-    when: [
-      "User is interested in buying",
-      "User wants product information",
-    ],
-    rules: [
-      "Ask open-ended questions to discover needs",
-      "Use storytelling when presenting solutions",
-      "Emoji to reinforce positive emotions 😊✨",
-      "Present value before mentioning price",
-      "Make customer feel special and understood",
-    ],
-    prohibitions: [
-      "Never talk about price before showing value",
-      "Do not pressure or push",
-      "Avoid technical jargon",
-      "Never send more than 2 messages without waiting for response",
-      "Do not make promises you cannot keep",
-    ],
-  });
-
-  agent.createRoute({
-    title: "Technical Support",
-    description: "Help with technical issues and troubleshooting",
-    when: ["User has technical problem", "User needs step-by-step help"],
-    rules: [
-      "Provide clear, numbered steps",
-      "Use simple language for technical concepts",
-      "Confirm understanding after each major step",
-      "Offer screenshots or visual aids when helpful",
-      "Be patient and thorough",
-    ],
-    prohibitions: [
-      "Never skip steps or assume knowledge",
-      "Do not use excessive technical terms without explanation",
-      "Never blame the user for the issue",
-      "Do not rush through explanations",
-    ],
-  });
-
-  // Add a stepful feedback flow to the Technical Support route
-  const techSupportRoute = agent
-    .getRoutes()
-    .find((r) => r.title === "Technical Support")!;
-  techSupportRoute.initialStep
-    .nextStep({
-      prompt: "Provide step-by-step technical assistance.",
-    })
-    .nextStep({
-      prompt: "Ask for a rating of the support provided (1-5).",
-      collect: ["feedbackRating"],
-    })
-    .nextStep({
-      prompt: "Ask for any additional comments.",
-      collect: ["feedbackComments"],
-    })
-    .nextStep({
-      prompt: "Thank the user for their feedback.",
-    })
-    .nextStep({ step: END_ROUTE });
-
-  agent.createRoute({
-    title: "Emergency Support",
-    description: "Handle urgent customer issues",
-    when: ["Customer is frustrated", "Urgent issue", "Service down"],
-    rules: [
-      "Acknowledge the urgency immediately",
-      "Express empathy and understanding",
-      "Provide concrete next steps",
-      "Set clear expectations on resolution time",
-      "Keep customer updated",
-    ],
-    prohibitions: [
-      "Never downplay the customer's concern",
-      "Do not use emojis (keep it professional)",
-      'Never say "calm down" or similar dismissive phrases',
-      "Do not transfer without explaining why",
-      "Never make excuses or blame others",
-    ],
-  });
-
-  agent.createRoute({
-    title: "General Chat",
-    description: "Casual conversation and general questions",
-    when: ["User is just chatting", "Greeting", "General question"],
-    rules: [
-      "Be friendly and conversational",
-      "Use emojis naturally 😊",
-      "Mirror the customer's tone and energy",
-      "Keep it light and positive",
-    ],
-    prohibitions: [
-      "Do not be overly formal",
-      "Never ignore the customer's mood",
-      "Do not push products unless asked",
-    ],
-  });
-
-  console.info("\n=== Rules & Prohibitions Demo ===\n");
-
-  // --- Quick Support ---
-  console.info("1️⃣  Quick Support Route (short, direct)");
-  const quickSupportMessages: History = [
-    {
-      role: "user",
-      content: "How do I reset my password?",
-    },
-  ];
-  const response1 = await agent.respond({ history: quickSupportMessages });
-  console.info(`Route: ${response1.session?.currentRoute?.title}`);
-  console.info(`Response: ${response1.message}`);
-  console.info(`Expected: Short, direct, max 1 emoji\n`);
-
-  // --- Sales Consultation ---
-  console.info("2️⃣  Sales Consultation Route (conversational, value-first)");
-  const salesMessages: History = [
-    {
-      role: "user",
-      content: "How much does your premium plan cost?",
-    },
-  ];
-  const response2 = await agent.respond({ history: salesMessages });
-  console.info(`Route: ${response2.session?.currentRoute?.title}`);
-  console.info(`Response: ${response2.message}`);
-  console.info(`Expected: Ask about needs, show value before price\n`);
-
-  // --- Technical Support ---
-  console.info("3️⃣  Technical Support Route (detailed, step-by-step)");
-  const techSupportMessages: History = [
-    {
-      role: "user",
-      content: "My new headphones won't connect to Bluetooth.",
-    },
-  ];
-  const response3 = await agent.respond({ history: techSupportMessages });
-  console.info(`Route: ${response3.session?.currentRoute?.title}`);
-  console.info(`Response: ${response3.message}`);
-  console.info(`Expected: Clear steps, simple language, patient\n`);
-  if (response3.isRouteComplete) {
-    console.info("\n✅ Technical support feedback collected!");
-  }
-
-  // --- Emergency Support ---
-  console.info("4️⃣  Emergency Support Route (urgent, professional)");
-  const emergencyMessages: History = [
-    {
-      role: "user",
-      content: "My account has been compromised!",
-    },
-  ];
-  const response4 = await agent.respond({ history: emergencyMessages });
-  console.info(`Route: ${response4.session?.currentRoute?.title}`);
-  console.info(`Response: ${response4.message}`);
-  console.info(`Expected: Acknowledge urgency, no emojis, concrete steps\n`);
-
-  // --- General Chat ---
-  console.info("5️⃣  General Chat Route (friendly, casual)");
-  const generalMessages: History = [
-    {
-      role: "user",
-      content: "What's the weather like today?",
-    },
-  ];
-  const response5 = await agent.respond({ history: generalMessages });
-  console.info(`Route: ${response5.session?.currentRoute?.title}`);
-  console.info(`Response: ${response5.message}`);
-  console.info(`Expected: Friendly, emojis, mirrors customer tone\n`);
-}
-
-/**
- * Inspect route configurations.
- */
-console.info("\n📋 Route Configurations:\n");
-agent.getRoutes().forEach((route) => {
-  console.info(`\n🛤️  ${route.title}`);
-  const rules = route.getRules();
-  const prohibitions = route.getProhibitions();
-
-  if (rules.length > 0) {
-    console.info(`  ✅ Rules (${rules.length}):`);
-    rules.forEach((rule, i) => console.info(`     ${i + 1}. ${String(rule)}`));
-  }
-
-  if (prohibitions.length > 0) {
-    console.info(`  ❌ Prohibitions (${prohibitions.length}):`);
-    prohibitions.forEach((prohibition, i) =>
-      console.info(`     ${i + 1}. ${String(prohibition)}`)
-    );
-  }
-});
-
-/**
- * Benefits explanation.
- */
-console.info(`
-💡 This demo shows how rules and prohibitions, combined with routing,
-   allow a single agent to handle diverse scenarios with tailored,
-   context-appropriate behavior.
-`);
-// Run demonstration
-if (import.meta.url === `file://${process.argv[1]}`) {
-  demonstrateRulesAndProhibitions().catch((err) => console.error(err));
-}
-
-export { agent };