@falai/agent 0.8.0 → 0.9.0-alpha-1

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, [], 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, [], 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(
@@ -235,7 +235,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 +246,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 +288,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 +317,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 +337,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: [
@@ -359,7 +382,7 @@ const feedbackRoute = agent.createRoute<FeedbackData>({
     required: ["rating", "comments"],
   },
   endStep: {
-    instructions:
+    prompt:
       "Thank the user warmly for their valuable feedback and let them know we appreciate their time",
   },
 });
@@ -367,20 +390,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 +415,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,12 +448,12 @@ 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 });
@@ -442,12 +466,12 @@ 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 });
@@ -460,8 +484,12 @@ 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 });
@@ -477,22 +505,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 });
   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,12 +541,12 @@ 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({
@@ -553,7 +588,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
  *