@falai/agent 0.8.1 → 0.9.0-alpha-2

package/examples/{rules-prohibitions.ts → advanced-patterns/route-lifecycle-hooks.ts}

@@ -6,15 +6,7 @@
  * in different conversation routes (e.g., WhatsApp bot with different styles)
  */
 
-import {
-  Agent,
-  type Event,
-  type MessageEventData,
-  EventKind,
-  EventSource,
-  END_ROUTE,
-} from "../src";
-import { OpenAIProvider } from "../src/providers/OpenAIProvider";
+import { Agent, type History, END_ROUTE, OpenAIProvider } from "../../src";
 
 /**
  * Configuration for the AI provider
@@ -24,16 +16,94 @@ const provider = new OpenAIProvider({
   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({
+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",
+    },
+  },
 });
 
 /**
@@ -78,6 +148,22 @@ agent.createRoute({
     "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({
@@ -105,18 +191,18 @@ const techSupportRoute = agent
   .find((r) => r.title === "Technical Support")!;
 techSupportRoute.initialStep
   .nextStep({
-    instructions: "Provide step-by-step technical assistance.",
+    prompt: "Provide step-by-step technical assistance.",
   })
   .nextStep({
-    instructions: "Ask for a rating of the support provided (1-5).",
+    prompt: "Ask for a rating of the support provided (1-5).",
     collect: ["feedbackRating"],
   })
   .nextStep({
-    instructions: "Ask for any additional comments.",
+    prompt: "Ask for any additional comments.",
     collect: ["feedbackComments"],
   })
   .nextStep({
-    instructions: "Thank the user for their feedback.",
+    prompt: "Thank the user for their feedback.",
   })
   .nextStep({ step: END_ROUTE });
 
@@ -161,12 +247,14 @@ agent.createRoute({
  * Demonstration function to show how the agent responds to different scenarios.
  */
 async function demonstrateRulesAndProhibitions() {
-  const agent = new Agent({
+  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,
   });
 
@@ -237,18 +325,18 @@ async function demonstrateRulesAndProhibitions() {
     .find((r) => r.title === "Technical Support")!;
   techSupportRoute.initialStep
     .nextStep({
-      instructions: "Provide step-by-step technical assistance.",
+      prompt: "Provide step-by-step technical assistance.",
     })
     .nextStep({
-      instructions: "Ask for a rating of the support provided (1-5).",
+      prompt: "Ask for a rating of the support provided (1-5).",
       collect: ["feedbackRating"],
     })
     .nextStep({
-      instructions: "Ask for any additional comments.",
+      prompt: "Ask for any additional comments.",
       collect: ["feedbackComments"],
     })
     .nextStep({
-      instructions: "Thank the user for their feedback.",
+      prompt: "Thank the user for their feedback.",
     })
     .nextStep({ step: END_ROUTE });
 
@@ -293,51 +381,39 @@ async function demonstrateRulesAndProhibitions() {
 
   // --- Quick Support ---
   console.info("1️⃣  Quick Support Route (short, direct)");
-  const quickSupportHistory: Event[] = [
+  const quickSupportMessages: History = [
     {
-      kind: EventKind.MESSAGE,
-      source: EventSource.CUSTOMER,
-      data: {
-        participant: { display_name: "User" },
-        message: "How do I reset my password?",
-      },
+      role: "user",
+      content: "How do I reset my password?",
     },
   ];
-  const response1 = await agent.respond({ history: quickSupportHistory });
+  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 salesHistory: Event[] = [
+  const salesMessages: History = [
     {
-      kind: EventKind.MESSAGE,
-      source: EventSource.CUSTOMER,
-      data: {
-        message: "How much does your premium plan cost?",
-        participant: { display_name: "User" },
-      },
+      role: "user",
+      content: "How much does your premium plan cost?",
     },
   ];
-  const response2 = await agent.respond({ history: salesHistory });
+  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 techSupportHistory: Event[] = [
+  const techSupportMessages: History = [
     {
-      kind: EventKind.MESSAGE,
-      source: EventSource.CUSTOMER,
-      data: {
-        message: "My new headphones won't connect to Bluetooth.",
-        participant: { display_name: "User" },
-      },
+      role: "user",
+      content: "My new headphones won't connect to Bluetooth.",
     },
   ];
-  const response3 = await agent.respond({ history: techSupportHistory });
+  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`);
@@ -347,34 +423,26 @@ async function demonstrateRulesAndProhibitions() {
 
   // --- Emergency Support ---
   console.info("4️⃣  Emergency Support Route (urgent, professional)");
-  const emergencyHistory: Event[] = [
+  const emergencyMessages: History = [
     {
-      kind: EventKind.MESSAGE,
-      source: EventSource.CUSTOMER,
-      data: {
-        message: "My account has been compromised!",
-        participant: { display_name: "User" },
-      },
+      role: "user",
+      content: "My account has been compromised!",
     },
   ];
-  const response4 = await agent.respond({ history: emergencyHistory });
+  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 generalHistory: Event[] = [
+  const generalMessages: History = [
     {
-      kind: EventKind.MESSAGE,
-      source: EventSource.CUSTOMER,
-      data: {
-        message: "What's the weather like today?",
-        participant: { display_name: "User" },
-      },
-    } as Event<MessageEventData>,
+      role: "user",
+      content: "What's the weather like today?",
+    },
   ];
-  const response5 = await agent.respond({ history: generalHistory });
+  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`);
@@ -391,13 +459,13 @@ agent.getRoutes().forEach((route) => {
 
   if (rules.length > 0) {
     console.info(`  ✅ Rules (${rules.length}):`);
-    rules.forEach((rule, i) => console.info(`     ${i + 1}. ${rule}`));
+    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}. ${prohibition}`)
+      console.info(`     ${i + 1}. ${String(prohibition)}`)
     );
   }
 });
@@ -410,28 +478,6 @@ console.info(`
    allow a single agent to handle diverse scenarios with tailored,
    context-appropriate behavior.
 `);
-
-/**
- * Mock function to log support feedback.
- * @param data - The feedback data.
- */
-async function logSupportFeedback(
-  _context: undefined,
-  _history: Event[],
-  _session: undefined,
-  data: { feedbackRating: number; feedbackComments: string }
-) {
-  console.info("\n" + "=".repeat(60));
-  console.info("📝 Logging Support Feedback...");
-  console.info("=".repeat(60));
-  console.info("Feedback Details:", JSON.stringify(data, null, 2));
-  console.info(`   - Rating: ${data.feedbackRating}`);
-  console.info(`   - Comments: ${data.feedbackComments}`);
-  await new Promise((resolve) => setTimeout(resolve, 500));
-  console.info("✨ Feedback logged successfully!");
-  return { success: true };
-}
-
 // Run demonstration
 if (import.meta.url === `file://${process.argv[1]}`) {
   demonstrateRulesAndProhibitions().catch((err) => console.error(err));