@falai/agent 0.8.1 → 0.9.0-alpha-2

package/examples/{company-qna-agent.ts → advanced-patterns/knowledge-based-agent.ts}

@@ -1,3 +1,4 @@
+/* eslint @typescript-eslint/no-unused-vars: "off" */
 /**
  * Example: Company Q&A Agent (Stepless, Knowledge-Based)
  *
@@ -11,15 +12,12 @@
 
 import {
   Agent,
-  createSession,
-  EventSource,
-  createMessageEvent,
-  EventKind,
   END_ROUTE,
+  EventKind,
+  MessageRole,
   OpenAIProvider,
-} from "../src";
-import type { Event } from "../src/types";
-import type { ToolRef } from "../src/types/tool";
+  type Tool,
+} from "../../src/index";
 
 // ==============================================================================
 // CONTEXT: Company Knowledge Base
@@ -67,11 +65,11 @@ interface FeedbackData {
 // ==============================================================================
 
 // Tool: Fetch latest company news (context enrichment)
-const fetchNewsTool: ToolRef<CompanyContext, [], void> = {
+const fetchNewsTool: Tool<CompanyContext, UnifiedData, [], void> = {
   id: "fetch_news",
-  name: "Fetch Company News",
+  name: "Company News Fetcher",
   description: "Retrieve latest company news and updates",
-  handler: async (context) => {
+  handler: () => {
     // Simulate API call to news service
     const news = [
       {
@@ -98,17 +96,17 @@ const fetchNewsTool: ToolRef<CompanyContext, [], void> = {
 };
 
 // Tool: Search knowledge base (context enrichment)
-const searchKnowledgeTool: ToolRef<CompanyContext, [], string> = {
+const searchKnowledgeTool: Tool<CompanyContext,UnifiedData, [], string> = {
   id: "search_knowledge",
-  name: "Search Knowledge Base",
+  name: "Knowledge Base Search",
   description: "Search FAQs and documentation",
-  handler: async (context) => {
+  handler: (context) => {
     const { history } = context;
 
     // Get last user message
     const lastMessage = history
       .filter(
-        (e) => e.kind === EventKind.MESSAGE && e.source === EventSource.CUSTOMER
+        (e) => e.kind === EventKind.MESSAGE && e.source === MessageRole.USER
       )
       .pop();
 
@@ -116,7 +114,9 @@ const searchKnowledgeTool: ToolRef<CompanyContext, [], string> = {
       return { data: "No query found" };
     }
 
-    const query = (lastMessage.data as any).message.toLowerCase();
+    const query = (
+      lastMessage.data as { message: string }
+    ).message.toLowerCase();
 
     // Simple keyword matching (in real app, use vector search)
     const relevantFaqs = context.context.faqs.filter(
@@ -139,7 +139,28 @@ const searchKnowledgeTool: ToolRef<CompanyContext, [], string> = {
 // AGENT SETUP
 // ==============================================================================
 
-const agent = new Agent<CompanyContext>({
+// Define unified data schema for all interactions
+interface UnifiedData extends FeedbackData {}
+
+const unifiedSchema = {
+  type: "object",
+  properties: {
+    // Feedback fields
+    rating: {
+      type: "number",
+      description: "A rating from 1 to 5",
+      minimum: 1,
+      maximum: 5,
+    },
+    comments: { type: "string", description: "Open-ended feedback" },
+    contactPermission: {
+      type: "boolean",
+      description: "Permission to contact the user for more details",
+    },
+  },
+};
+
+const agent = new Agent<CompanyContext, UnifiedData>({
   name: "Acme Support Agent",
   goal: "Answer questions about Acme Corp and our products",
   description:
@@ -150,6 +171,8 @@ const agent = new Agent<CompanyContext>({
     apiKey: process.env.OPENAI_API_KEY || "test-key",
     model: "gpt-5o-mini",
   }),
+  // NEW: Agent-level schema
+  schema: unifiedSchema,
 
   // Initialize with company knowledge
   context: {
@@ -235,7 +258,8 @@ const agent = new Agent<CompanyContext>({
 // ==============================================================================
 
 // Route 1: Company Information (stepless - no data extraction)
-const companyInfoRoute = agent.createRoute({
+
+agent.createRoute({
   title: "Company Information",
   description: "Answer general questions about Acme Corp",
   conditions: [
@@ -245,14 +269,34 @@ const companyInfoRoute = agent.createRoute({
     "How many employees",
     "Where is the headquarters",
   ],
+  // Route-specific knowledge base for company information
+  knowledgeBase: {
+    company: {
+      name: "Acme Corporation",
+      founded: "1985",
+      headquarters: "San Francisco, CA",
+      employees: "2,500+",
+      mission:
+        "To build software that makes businesses more efficient and people more productive",
+    },
+    history: {
+      founding: "Founded in 1985 by tech entrepreneurs",
+      milestones: [
+        "IPO in 1998",
+        "Acquired 3 companies in 2010s",
+        "Expanded to 20 countries by 2020",
+      ],
+    },
+  },
   // NO schema - stepless Q&A route
-  // Just use initial step with instructions for response generation
+  // Just use initial step with prompt for response generation
 });
 
 // Initial step: Answer from knowledge base (no data collecting needed)
 
 // Route 2: Product Information (stepless)
-const productInfoRoute = agent.createRoute({
+
+agent.createRoute({
   title: "Product Information",
   description: "Answer questions about products",
   conditions: [
@@ -267,7 +311,8 @@ const productInfoRoute = agent.createRoute({
 // Initial step is enough - no transitions needed for simple Q&A
 
 // Route 3: Policy Questions (stepless)
-const policyRoute = agent.createRoute({
+
+agent.createRoute({
   title: "Policy Information",
   description: "Answer questions about company policies",
   conditions: [
@@ -295,11 +340,11 @@ const newsRoute = agent.createRoute({
 
 // Add tool to initial step to fetch news
 const fetchNews = newsRoute.initialStep.nextStep({
-  tool: fetchNewsTool,
+  tools: [fetchNewsTool],
 });
 
-const shareNews = fetchNews.nextStep({
-  instructions: "Share the latest company news from context",
+fetchNews.nextStep({
+  prompt: "Share the latest company news from context",
 });
 
 // Route 5: General FAQ Search (uses tool)
@@ -315,15 +360,16 @@ const faqRoute = agent.createRoute({
 });
 
 const searchFaqs = faqRoute.initialStep.nextStep({
-  tool: searchKnowledgeTool,
+  tools: [searchKnowledgeTool],
 });
 
-const provideFaqAnswer = searchFaqs.nextStep({
-  instructions: "Provide answer based on FAQ search results",
+searchFaqs.nextStep({
+  prompt: "Provide answer based on FAQ search results",
 });
 
 // Route 6: Fallback (generic response)
-const fallbackRoute = agent.createRoute({
+
+agent.createRoute({
   title: "General Conversation",
   description: "Handle general conversation or unclear questions",
   conditions: [
@@ -337,29 +383,16 @@ const fallbackRoute = agent.createRoute({
 // Initial step is enough for fallback conversations
 
 // Route 7: Collect Feedback (Stepful Example)
-const feedbackRoute = agent.createRoute<FeedbackData>({
+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"],
-  schema: {
-    type: "object",
-    properties: {
-      rating: {
-        type: "number",
-        description: "A rating from 1 to 5",
-        minimum: 1,
-        maximum: 5,
-      },
-      comments: { type: "string", description: "Open-ended feedback" },
-      contactPermission: {
-        type: "boolean",
-        description: "Permission to contact the user for more details",
-      },
-    },
-    required: ["rating", "comments"],
-  },
+  // NEW: Required fields for route completion
+  requiredFields: ["rating", "comments"],
+  // NEW: Optional fields
+  optionalFields: ["contactPermission"],
   endStep: {
-    instructions:
+    prompt:
       "Thank the user warmly for their valuable feedback and let them know we appreciate their time",
   },
 });
@@ -367,20 +400,20 @@ const feedbackRoute = agent.createRoute<FeedbackData>({
 feedbackRoute.initialStep
   .nextStep({
     id: "ask_rating",
-    instructions:
+    prompt:
       "I'd love to hear your feedback. On a scale of 1 to 5, how would you rate your experience with me today?",
     collect: ["rating"],
   })
   .nextStep({
     id: "ask_comments",
-    instructions:
+    prompt:
       "Thanks for the rating! Do you have any specific comments or suggestions?",
     collect: ["comments"],
     requires: ["rating"],
   })
   .nextStep({
     id: "ask_permission",
-    instructions:
+    prompt:
       "Thank you for the detailed feedback. Would it be okay if our team contacted you for more details?",
     collect: ["contactPermission"],
     requires: ["comments"],
@@ -392,23 +425,24 @@ feedbackRoute.initialStep
 // ==============================================================================
 
 async function exampleConversations() {
-  let session = createSession();
+  // Session is automatically managed by the agent
+  console.log("✨ Session ready:", agent.session.id);
 
   // =========================================================================
   // Example 1: Simple company info question (stepless)
   // =========================================================================
   console.log("\n=== EXAMPLE 1: Company Info (Stepless Q&A) ===");
-  const history1: Event[] = [
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "User",
-      "How many employees does Acme have?"
-    ),
-  ];
+  
+  await agent.session.addMessage("user", "How many employees does Acme have?", "User");
 
-  const response1 = await agent.respond({ history: history1, session });
+  const response1 = await agent.respond({ 
+    history: agent.session.getHistory() 
+  });
+  
   console.log("AI:", response1.message);
   console.log("Route:", response1.session?.currentRoute?.title);
+  
+  await agent.session.addMessage("assistant", response1.message);
 
   /*
    * ARCHITECTURE FLOW:
@@ -424,15 +458,15 @@ async function exampleConversations() {
   // Example 2: Product question (stepless)
   // =========================================================================
   console.log("\n=== EXAMPLE 2: Product Info ===");
-  const history2: Event[] = [
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "User",
-      "What products do you offer?"
-    ),
+  const history2 = [
+    {
+      role: "user" as const,
+      content: "What products do you offer?",
+      name: "User",
+    },
   ];
 
-  const response2 = await agent.respond({ history: history2, session });
+  const response2 = await agent.respond({ history: history2 });
   console.log("AI:", response2.message);
   console.log("Route:", response2.session?.currentRoute?.title);
   // Expected: "We offer two main products: Acme Widget ($99.99)..."
@@ -442,15 +476,15 @@ async function exampleConversations() {
   // Example 3: Policy question (stepless)
   // =========================================================================
   console.log("\n=== EXAMPLE 3: Policy Question ===");
-  const history3: Event[] = [
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "User",
-      "What's your return policy?"
-    ),
+  const history3 = [
+    {
+      role: "user" as const,
+      content: "What's your return policy?",
+      name: "User",
+    },
   ];
 
-  const response3 = await agent.respond({ history: history3, session });
+  const response3 = await agent.respond({ history: history3 });
   console.log("AI:", response3.message);
   console.log("Route:", response3.session?.currentRoute?.title);
   // Expected: "We offer a 30-day money-back guarantee..."
@@ -460,11 +494,15 @@ async function exampleConversations() {
   // Example 4: News request (tool execution, but still stepless)
   // =========================================================================
   console.log("\n=== EXAMPLE 4: Latest News ===");
-  const history4: Event[] = [
-    createMessageEvent(EventSource.CUSTOMER, "User", "What's new at Acme?"),
+  const history4 = [
+    {
+      role: "user" as const,
+      content: "What's new at Acme?",
+      name: "User",
+    },
   ];
 
-  const response4 = await agent.respond({ history: history4, session });
+  const response4 = await agent.respond({ history: history4 });
   console.log("AI:", response4.message);
   console.log("Route:", response4.session?.currentRoute?.title);
   // Tool fetches news → Updates context → AI responds with news
@@ -477,22 +515,29 @@ async function exampleConversations() {
   console.log("\n=== EXAMPLE 5: Multi-turn ===");
 
   // Turn 1
-  const turn1: Event[] = [
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "User",
-      "Tell me about the Acme Widget"
-    ),
+  const turn1 = [
+    {
+      role: "user" as const,
+      content: "Tell me about the Acme Widget",
+      name: "User",
+    },
   ];
-  const resp1 = await agent.respond({ history: turn1, session });
+  const resp1 = await agent.respond({ history: turn1 });
   console.log("User: Tell me about the Acme Widget");
   console.log("AI:", resp1.message);
 
   // Turn 2 - follow-up question
-  const turn2: Event[] = [
+  const turn2 = [
     ...turn1,
-    createMessageEvent(EventSource.AI_AGENT, "Agent", resp1.message),
-    createMessageEvent(EventSource.CUSTOMER, "User", "How much does it cost?"),
+    {
+      role: "assistant" as const,
+      content: resp1.message,
+    },
+    {
+      role: "user" as const,
+      content: "How much does it cost?",
+      name: "User",
+    },
   ];
   const resp2 = await agent.respond({
     history: turn2,
@@ -506,24 +551,23 @@ async function exampleConversations() {
   // Example 6: Stepful feedback collection
   // =========================================================================
   console.log("\n=== EXAMPLE 6: Stepful Feedback Collection ===");
-  const feedbackHistory: Event[] = [
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "User",
-      "This was very helpful, I want to leave some feedback."
-    ),
+  const feedbackHistory = [
+    {
+      role: "user" as const,
+      content: "This was very helpful, I want to leave some feedback.",
+      name: "User",
+    },
   ];
 
   const feedbackResponse = await agent.respond({
     history: feedbackHistory,
-    session,
   });
   console.log("AI:", feedbackResponse.message);
   console.log("Route:", feedbackResponse.session?.currentRoute?.title);
 
   if (feedbackResponse.isRouteComplete) {
     console.log("\n✅ Feedback collection complete!");
-    await processFeedback(agent.getData(feedbackResponse.session?.id));
+    await processFeedback(agent.getCollectedData());
   } else {
     console.log("\n⏳ Feedback collection in progress...");
   }
@@ -533,7 +577,7 @@ async function exampleConversations() {
  * Mock function to process collected feedback.
  * @param data The feedback data collected from the user.
  */
-async function processFeedback(data: Partial<FeedbackData>) {
+async function processFeedback(data: Partial<UnifiedData>) {
   console.log("\n" + "=".repeat(60));
   console.log("Processing user feedback...");
   console.log("=".repeat(60));
@@ -553,7 +597,7 @@ async function processFeedback(data: Partial<FeedbackData>) {
 
 /*
  * 1. NO STEP MACHINES REQUIRED
- *    - Just use the initial step with a instructions description
+ *    - Just use the initial step with a prompt description
  *    - No collect, no skipIf, no step transitions
  *    - Perfect for stepless question-answering
  *