@falai/agent 0.8.1 → 0.9.0-alpha-1

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
@@ -34,6 +26,60 @@ const agent = new Agent({
   goal: "Provide excellent customer service by following route-specific rules and prohibitions.",
   provider,
   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 +124,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 +167,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 });
 
@@ -237,18 +299,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 +355,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 +397,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 +433,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 +452,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));

package/examples/{streaming-agent.ts → advanced-patterns/streaming-responses.ts}

@@ -8,14 +8,10 @@
 
 import {
   Agent,
-  createMessageEvent,
-  EventSource,
   AnthropicProvider,
   OpenAIProvider,
   GeminiProvider,
-  createSession,
-  END_ROUTE,
-} from "../src/index";
+} from "../../src/index";
 
 // Custom context type
 interface ConversationContext {
@@ -62,23 +58,28 @@ async function streamingWithAnthropic() {
 
   // Create conversation history
   const history = [
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "User",
-      "Explain quantum computing in simple terms."
-    ),
+    {
+      role: "user" as const,
+      content: "Explain quantum computing in simple terms.",
+      name: "User",
+    },
   ];
 
   try {
     console.log("📤 Streaming response from Claude...\n");
     console.log("Response: ");
 
-    // Initialize session step for streaming conversation
-    let session = createSession();
+    // Session is automatically managed by the agent
+    console.log("✨ Session ready:", agent.session.id);
+
+    // Add user message to session history
+    await agent.session.addMessage("user", "What's the weather like today?");
 
-    // Use respondStream for real-time streaming with session step
+    // Use respondStream for real-time streaming with session history
     let fullMessage = "";
-    for await (const chunk of agent.respondStream({ history, session })) {
+    for await (const chunk of agent.respondStream({ 
+      history: agent.session.getHistory() 
+    })) {
       // chunk.delta contains the new text
       // chunk.accumulated contains the full text so far
       // chunk.done indicates if this is the final chunk
@@ -94,11 +95,13 @@ async function streamingWithAnthropic() {
         console.log(
           `   - Route: ${chunk.session?.currentRoute?.title || "None"}`
         );
-        console.log(`   - Data:`, chunk.session?.data || "None");
+        console.log(`   - Data:`, agent.session.getData() || "None");
         console.log(`   - Tool Calls: ${chunk.toolCalls?.length || 0}`);
 
-        // Update session with progress
-        session = chunk.session!;
+        console.log(`   - Full Message: ${fullMessage}`);
+        
+        // Add assistant response to session history
+        await agent.session.addMessage("assistant", fullMessage);
       }
     }
   } catch (error) {
@@ -131,21 +134,26 @@ async function streamingWithOpenAI() {
   });
 
   const history = [
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "User",
-      "Write a short poem about TypeScript"
-    ),
+    {
+      role: "user" as const,
+      content: "Write a short poem about TypeScript",
+      name: "User",
+    },
   ];
 
   try {
     console.log("📤 Streaming response from OpenAI...\n");
     console.log("Response: ");
 
-    // Initialize session step for streaming conversation
-    let session = createSession();
+    // Session is automatically managed by the agent
+    console.log("✨ Session ready:", agent.session.id);
 
-    for await (const chunk of agent.respondStream({ history, session })) {
+    // Add user message to session history
+    await agent.session.addMessage("user", "What's the weather like today?");
+
+    for await (const chunk of agent.respondStream({ 
+      history: agent.session.getHistory() 
+    })) {
       if (chunk.delta) {
         process.stdout.write(chunk.delta);
       }
@@ -155,10 +163,10 @@ async function streamingWithOpenAI() {
         console.log(
           `   - Route: ${chunk.session?.currentRoute?.title || "None"}`
         );
-        console.log(`   - Data:`, chunk.session?.data || "None");
+        console.log(`   - Data:`, agent.session.getData() || "None");
 
-        // Update session with progress
-        session = chunk.session!;
+        // Add assistant response to session history
+        await agent.session.addMessage("assistant", chunk.accumulated || "");
       }
     }
   } catch (error) {
@@ -171,7 +179,7 @@ async function streamingWithGemini() {
 
   const provider = new GeminiProvider({
     apiKey: process.env.GEMINI_API_KEY || "",
-    model: "models/gemini-2.0-flash-exp",
+    model: "models/gemini-2.5-flash",
     config: {
       temperature: 0.7,
     },
@@ -191,21 +199,26 @@ async function streamingWithGemini() {
   });
 
   const history = [
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "User",
-      "What are the key differences between REST and GraphQL?"
-    ),
+    {
+      role: "user" as const,
+      content: "What are the key differences between REST and GraphQL?",
+      name: "User",
+    },
   ];
 
   try {
     console.log("📤 Streaming response from Gemini...\n");
     console.log("Response: ");
 
-    // Initialize session step for streaming conversation
-    let session = createSession();
+    // Session is automatically managed by the agent
+    console.log("✨ Session ready:", agent.session.id);
+
+    // Add user message to session history
+    await agent.session.addMessage("user", "What are the key differences between REST and GraphQL?");
 
-    for await (const chunk of agent.respondStream({ history, session })) {
+    for await (const chunk of agent.respondStream({ 
+      history: agent.session.getHistory() 
+    })) {
       if (chunk.delta) {
         process.stdout.write(chunk.delta);
       }
@@ -215,10 +228,10 @@ async function streamingWithGemini() {
         console.log(
           `   - Route: ${chunk.session?.currentRoute?.title || "None"}`
         );
-        console.log(`   - Data:`, chunk.session?.data || "None");
+        console.log(`   - Data:`, agent.session.getData() || "None");
 
-        // Update session with progress
-        session = chunk.session!;
+        // Add assistant response to session history
+        await agent.session.addMessage("assistant", chunk.accumulated || "");
       }
     }
   } catch (error) {
@@ -255,11 +268,11 @@ async function streamingWithRoutes() {
   });
 
   supportRoute.initialStep.nextStep({
-    instructions: "Understand the user's product question",
+    prompt: "Understand the user's product question",
   });
 
   // Create a feedback route
-  const feedbackRoute = agent.createRoute<{
+  agent.createRoute<{
     rating: number;
     comments: string;
   }>({
@@ -276,35 +289,40 @@ async function streamingWithRoutes() {
     },
     steps: [
       {
-        instructions: "How would you rate your support experience from 1 to 5?",
+        prompt: "How would you rate your support experience from 1 to 5?",
         collect: ["rating"],
       },
       {
-        instructions: "Thanks for the rating! Any other comments?",
+        prompt: "Thanks for the rating! Any other comments?",
         collect: ["comments"],
       },
       {
-        instructions: "We appreciate your feedback!",
+        prompt: "We appreciate your feedback!",
       },
     ],
   });
 
   const history = [
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "User",
-      "How do I reset my password?"
-    ),
+    {
+      role: "user" as const,
+      content: "How do I reset my password?",
+      name: "User",
+    },
   ];
 
   try {
     console.log("📤 Streaming response with route detection...\n");
     console.log("Response: ");
 
-    // Initialize session step for streaming conversation
-    let session = createSession();
+    // Session is automatically managed by the agent
+    console.log("✨ Session ready:", agent.session.id);
 
-    for await (const chunk of agent.respondStream({ history, session })) {
+    // Add user message to session history
+    await agent.session.addMessage("user", "How do I reset my password?");
+
+    for await (const chunk of agent.respondStream({ 
+      history: agent.session.getHistory() 
+    })) {
       if (chunk.delta) {
         process.stdout.write(chunk.delta);
       }
@@ -315,14 +333,14 @@ async function streamingWithRoutes() {
         console.log(
           `   - Route: ${chunk.session?.currentRoute?.title || "None"}`
         );
-        console.log(`   - Data:`, chunk.session?.data || "None");
+        console.log(`   - Data:`, agent.session.getData() || "None");
 
         // Check for route completion
         if (chunk.isRouteComplete) {
           console.log("\n✅ Route complete!");
           if (chunk.session?.currentRoute?.title === "Collect Feedback") {
             await logFeedback(
-              agent.getData(chunk.session?.id) as {
+              agent.session.getData() as {
                 rating: number;
                 comments: string;
               }
@@ -330,8 +348,7 @@ async function streamingWithRoutes() {
           }
         }
 
-        // Update session with progress
-        session = chunk.session!;
+        // Session is automatically updated by the agent
       }
     }
   } catch (error) {
@@ -361,11 +378,11 @@ async function streamingWithAbortSignal() {
   });
 
   const history = [
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "User",
-      "Tell me a very long story about space exploration."
-    ),
+    {
+      role: "user" as const,
+      content: "Tell me a very long story about space exploration.",
+      name: "User",
+    },
   ];
 
   // Create an AbortController to cancel the stream
@@ -381,12 +398,14 @@ async function streamingWithAbortSignal() {
     console.log("📤 Streaming response (will abort after 3s)...\n");
     console.log("Response: ");
 
-    // Initialize session step for streaming conversation
-    let session = createSession();
+    // Session is automatically managed by the agent
+    console.log("✨ Session ready:", agent.session.id);
+
+    // Add user message to session history
+    await agent.session.addMessage("user", "Tell me a very long story about space exploration.");
 
     for await (const chunk of agent.respondStream({
-      history,
-      session,
+      history: agent.session.getHistory(),
       signal: abortController.signal,
     })) {
       if (chunk.delta) {
@@ -399,10 +418,12 @@ async function streamingWithAbortSignal() {
         console.log(
           `   - Route: ${chunk.session?.currentRoute?.title || "None"}`
         );
-        console.log(`   - Data:`, chunk.session?.data || "None");
+        console.log(`   - Data:`, agent.session.getData() || "None");
+
+        // Add assistant response to session history
+        await agent.session.addMessage("assistant", chunk.accumulated || "");
 
-        // Update session with progress
-        session = chunk.session!;
+        // Session is automatically updated by the agent
 
         clearTimeout(timeout);
       }