@falai/agent 0.1.4 → 0.2.0

package/examples/declarative-agent.ts

@@ -6,8 +6,9 @@
  * - Terms (glossary)
  * - Guidelines (behavior rules)
  * - Capabilities
- * - Routes with nested guidelines
- * - Observations with route references
+ * - Routes with nested guidelines and custom IDs
+ * - Observations with route references and custom IDs
+ * - Custom timestamps for events
  */
 
 import {
@@ -29,13 +30,16 @@ interface HealthcareContext {
   patientName: string;
 }
 
-// Define tools
+// Define tools with custom IDs (optional - IDs are deterministic by default)
 const getInsuranceProviders = defineTool<HealthcareContext, [], string[]>(
   "get_insurance_providers",
   async () => {
     return { data: ["MegaCare Insurance", "HealthFirst", "WellnessPlus"] };
   },
-  { description: "Retrieves list of accepted insurance providers" }
+  {
+    id: "healthcare_insurance_providers", // Custom ID for persistence
+    description: "Retrieves list of accepted insurance providers",
+  }
 );
 
 const getAvailableSlots = defineTool<
@@ -53,7 +57,10 @@ const getAvailableSlots = defineTool<
       ],
     };
   },
-  { description: "Gets available appointment slots" }
+  {
+    id: "healthcare_available_slots", // Custom ID
+    description: "Gets available appointment slots",
+  }
 );
 
 const getLabResults = defineTool<
@@ -70,7 +77,10 @@ const getLabResults = defineTool<
       },
     };
   },
-  { description: "Retrieves patient lab results" }
+  {
+    id: "healthcare_lab_results", // Custom ID
+    description: "Retrieves patient lab results",
+  }
 );
 
 // Declarative configuration
@@ -126,6 +136,7 @@ const capabilities: Capability[] = [
 
 const routes: RouteOptions[] = [
   {
+    id: "route_schedule_appointment", // Custom ID ensures consistency across restarts
     title: "Schedule Appointment",
     description: "Helps the patient schedule an appointment",
     conditions: ["The patient wants to schedule an appointment"],
@@ -139,6 +150,7 @@ const routes: RouteOptions[] = [
     ],
   },
   {
+    id: "route_check_lab_results", // Custom ID
     title: "Check Lab Results",
     description: "Retrieves and explains patient lab results",
     conditions: ["The patient wants to see their lab results"],
@@ -155,6 +167,7 @@ const routes: RouteOptions[] = [
 
 const observations: ObservationOptions[] = [
   {
+    id: "obs_visit_followup", // Custom ID for tracking
     description:
       "The patient asks to follow up on their visit, but it's not clear in which way",
     routeRefs: ["Schedule Appointment", "Check Lab Results"], // Reference by title
@@ -172,6 +185,7 @@ const agent = new Agent<HealthcareContext>({
   },
   ai: new GeminiProvider({
     apiKey: process.env.GEMINI_API_KEY || "demo-key",
+    model: "models/gemini-2.5-flash",
   }),
   // Declarative initialization
   terms,
@@ -196,19 +210,29 @@ agent
 
 // Example usage
 async function main() {
+  // Create events with custom timestamps (useful for historical data)
   const history = [
     createMessageEvent(
       EventSource.CUSTOMER,
       "Alice",
-      "Hi, I need to follow up on my recent visit"
+      "Hi, I need to follow up on my recent visit",
+      "2025-10-13T14:30:00Z" // Optional custom timestamp
     ),
   ];
 
   const response = await agent.respond({ history });
   console.log("Agent:", response.message);
+  console.log("Route chosen:", response.route?.title);
+  console.log("Route ID:", response.route?.id); // Custom ID is preserved
 
   // The agent will use the observation to disambiguate
   // and ask which type of follow-up the patient needs
+
+  // Note: Custom IDs ensure consistency across server restarts
+  // This is crucial for:
+  // - Storing conversation state in databases
+  // - Tracking metrics and analytics
+  // - Referencing routes in external systems
 }
 
 // Uncomment to run:

package/examples/persistent-onboarding.ts

@@ -0,0 +1,464 @@
+/**
+ * Persistent multi-turn onboarding agent example
+ * Demonstrates context lifecycle management for stateful conversations
+ */
+
+import {
+  Agent,
+  defineTool,
+  GeminiProvider,
+  END_ROUTE,
+  EventSource,
+  createMessageEvent,
+  type ContextLifecycleHooks,
+} from "../src/index";
+
+// ============================================================================
+// DATABASE SIMULATION
+// ============================================================================
+
+interface SessionData {
+  sessionId: string;
+  userId: string;
+  collectedData: {
+    businessName?: string;
+    businessDescription?: string;
+    industry?: string;
+    contactEmail?: string;
+  };
+  completedSteps: string[];
+  lastUpdated: Date;
+}
+
+// Simple in-memory database simulation
+const database = new Map<string, SessionData>();
+
+const db = {
+  sessions: {
+    async findById(sessionId: string): Promise<SessionData | undefined> {
+      return database.get(sessionId);
+    },
+
+    async update(
+      sessionId: string,
+      updates: Partial<SessionData>
+    ): Promise<void> {
+      const existing = database.get(sessionId);
+      if (existing) {
+        database.set(sessionId, {
+          ...existing,
+          ...updates,
+          lastUpdated: new Date(),
+        });
+      }
+    },
+
+    async create(sessionData: SessionData): Promise<void> {
+      database.set(sessionData.sessionId, sessionData);
+    },
+  },
+};
+
+// ============================================================================
+// CONTEXT TYPE
+// ============================================================================
+
+interface OnboardingContext {
+  sessionId: string;
+  userId: string;
+  userName?: string;
+  collectedData: {
+    businessName?: string;
+    businessDescription?: string;
+    industry?: string;
+    contactEmail?: string;
+  };
+  completedSteps: string[];
+}
+
+// ============================================================================
+// AGENT FACTORY WITH LIFECYCLE HOOKS
+// ============================================================================
+
+/**
+ * Creates an onboarding agent with persistent context management
+ *
+ * PATTERN 1: Factory + Lifecycle Hooks
+ * - Load fresh context from database before each response
+ * - Persist context updates automatically after changes
+ */
+async function createPersistentOnboardingAgent(sessionId: string) {
+  // Load session from database
+  const session = await db.sessions.findById(sessionId);
+
+  if (!session) {
+    throw new Error(`Session ${sessionId} not found`);
+  }
+
+  // Define lifecycle hooks for automatic persistence
+  const hooks: ContextLifecycleHooks<OnboardingContext> = {
+    // Called before respond() - load fresh context from database
+    beforeRespond: async (currentContext) => {
+      console.log("🔄 Loading fresh context from database...");
+      const freshSession = await db.sessions.findById(sessionId);
+
+      if (!freshSession) {
+        return currentContext; // Fallback to current
+      }
+
+      return {
+        sessionId: freshSession.sessionId,
+        userId: freshSession.userId,
+        collectedData: freshSession.collectedData,
+        completedSteps: freshSession.completedSteps,
+      };
+    },
+
+    // Called after context updates - persist to database
+    onContextUpdate: async (newContext) => {
+      console.log("💾 Persisting context update to database...");
+      await db.sessions.update(sessionId, {
+        collectedData: newContext.collectedData,
+        completedSteps: newContext.completedSteps,
+      });
+    },
+  };
+
+  const provider = new GeminiProvider({
+    apiKey: process.env.GEMINI_API_KEY || "test-key",
+    model: "models/gemini-2.5-flash",
+  });
+
+  const agent = new Agent<OnboardingContext>({
+    name: "OnboardingBot",
+    description: "A friendly assistant that helps businesses get started",
+    goal: "Collect business information efficiently while being conversational",
+    ai: provider,
+    context: {
+      sessionId: session.sessionId,
+      userId: session.userId,
+      collectedData: session.collectedData,
+      completedSteps: session.completedSteps,
+    },
+    hooks, // Enable lifecycle hooks for persistence
+  });
+
+  // ============================================================================
+  // TOOLS (with context updates)
+  // ============================================================================
+
+  // OPTION 1: Using contextUpdate in return value
+  const saveBusinessInfo = defineTool<
+    OnboardingContext,
+    [name: string, description: string],
+    boolean
+  >(
+    "save_business_info",
+    async (toolContext, name, description) => {
+      console.log(`📝 Saving business info: ${name}`);
+
+      return {
+        data: true,
+        // Context update is automatically persisted via onContextUpdate hook
+        contextUpdate: {
+          collectedData: {
+            ...toolContext.context.collectedData,
+            businessName: name,
+            businessDescription: description,
+          },
+          completedSteps: [
+            ...toolContext.context.completedSteps,
+            "business_info",
+          ],
+        },
+      };
+    },
+    {
+      description: "Save business name and description",
+    }
+  );
+
+  // OPTION 2: Using updateContext method directly
+  const saveIndustry = defineTool<
+    OnboardingContext,
+    [industry: string],
+    boolean
+  >(
+    "save_industry",
+    async (toolContext, industry) => {
+      console.log(`🏭 Saving industry: ${industry}`);
+
+      // Direct context update (triggers onContextUpdate hook)
+      await toolContext.updateContext({
+        collectedData: {
+          ...toolContext.context.collectedData,
+          industry,
+        },
+        completedSteps: [...toolContext.context.completedSteps, "industry"],
+      });
+
+      return { data: true };
+    },
+    {
+      description: "Save business industry",
+    }
+  );
+
+  const saveContactEmail = defineTool<
+    OnboardingContext,
+    [email: string],
+    boolean
+  >(
+    "save_contact_email",
+    async (toolContext, email) => {
+      console.log(`📧 Saving contact email: ${email}`);
+
+      await toolContext.updateContext({
+        collectedData: {
+          ...toolContext.context.collectedData,
+          contactEmail: email,
+        },
+        completedSteps: [...toolContext.context.completedSteps, "contact"],
+      });
+
+      return { data: true };
+    },
+    {
+      description: "Save contact email",
+    }
+  );
+
+  // ============================================================================
+  // ONBOARDING ROUTE
+  // ============================================================================
+
+  const onboardingRoute = agent.createRoute({
+    title: "Business Onboarding",
+    description: "Guide user through business information collection",
+    conditions: ["User is onboarding their business"],
+  });
+
+  // Step 1: Collect business info
+  const askBusinessInfo = onboardingRoute.initialState.transitionTo({
+    chatState: "Ask for business name and a brief description",
+  });
+
+  const saveBusinessStep = askBusinessInfo.target.transitionTo({
+    toolState: saveBusinessInfo,
+  });
+
+  // Step 2: Collect industry
+  const askIndustry = saveBusinessStep.target.transitionTo({
+    chatState: "Ask what industry the business operates in",
+  });
+
+  const saveIndustryStep = askIndustry.target.transitionTo({
+    toolState: saveIndustry,
+  });
+
+  // Step 3: Collect contact
+  const askContact = saveIndustryStep.target.transitionTo({
+    chatState: "Ask for their contact email",
+  });
+
+  const saveContactStep = askContact.target.transitionTo({
+    toolState: saveContactEmail,
+  });
+
+  // Step 4: Confirmation
+  const confirm = saveContactStep.target.transitionTo({
+    chatState: "Summarize all collected information and ask for confirmation",
+  });
+
+  confirm.target.transitionTo({ state: END_ROUTE });
+
+  // Guidelines
+  onboardingRoute.createGuideline({
+    condition: "User provides invalid email format",
+    action: "Politely ask for a valid email address",
+    tags: ["validation"],
+  });
+
+  onboardingRoute.createGuideline({
+    condition: "User wants to skip a step",
+    action: "Explain why the information is important but allow them to skip",
+    tags: ["flexibility"],
+  });
+
+  agent.createGuideline({
+    condition: "User asks to start over",
+    action:
+      "Confirm they want to clear their progress, then restart the onboarding",
+    tags: ["reset"],
+  });
+
+  return agent;
+}
+
+// ============================================================================
+// ALTERNATIVE PATTERN: CONTEXT PROVIDER
+// ============================================================================
+
+/**
+ * Creates an onboarding agent using the contextProvider pattern
+ *
+ * PATTERN 2: Context Provider (Always Fresh)
+ * - Context is fetched fresh on every respond() call
+ * - No need for beforeRespond hook
+ * - Still use onContextUpdate for persistence
+ */
+async function createOnboardingAgentWithProvider(sessionId: string) {
+  const provider = new GeminiProvider({
+    apiKey: process.env.GEMINI_API_KEY || "test-key",
+    model: "models/gemini-2.5-flash",
+  });
+
+  const agent = new Agent<OnboardingContext>({
+    name: "OnboardingBot",
+    description: "A friendly assistant that helps businesses get started",
+    ai: provider,
+
+    // Context is always fetched fresh from database
+    contextProvider: async () => {
+      const session = await db.sessions.findById(sessionId);
+      if (!session) {
+        throw new Error(`Session ${sessionId} not found`);
+      }
+
+      return {
+        sessionId: session.sessionId,
+        userId: session.userId,
+        collectedData: session.collectedData,
+        completedSteps: session.completedSteps,
+      };
+    },
+
+    // Still persist updates
+    hooks: {
+      onContextUpdate: async (newContext) => {
+        await db.sessions.update(sessionId, {
+          collectedData: newContext.collectedData,
+          completedSteps: newContext.completedSteps,
+        });
+      },
+    },
+  });
+
+  // ... rest of agent setup (same as above)
+
+  return agent;
+}
+
+// ============================================================================
+// USAGE EXAMPLE
+// ============================================================================
+
+async function main() {
+  const sessionId = "session_123";
+  const userId = "user_456";
+
+  // Initialize session in database
+  await db.sessions.create({
+    sessionId,
+    userId,
+    collectedData: {},
+    completedSteps: [],
+    lastUpdated: new Date(),
+  });
+
+  console.log("=== MULTI-TURN CONVERSATION SIMULATION ===\n");
+
+  // Turn 1: Start onboarding
+  console.log("📱 Turn 1: User starts onboarding");
+  const agent1 = await createPersistentOnboardingAgent(sessionId);
+  const response1 = await agent1.respond({
+    history: [
+      createMessageEvent(
+        EventSource.CUSTOMER,
+        "Alice",
+        "Hi, I want to onboard my business"
+      ),
+    ],
+  });
+  console.log("🤖 Bot:", response1.message);
+  console.log("📊 Context after turn 1:", agent1["context"]);
+  console.log();
+
+  // Turn 2: User provides business info
+  // NOTE: We create a NEW agent instance - context is loaded from database
+  console.log("📱 Turn 2: User provides business info");
+  const agent2 = await createPersistentOnboardingAgent(sessionId);
+  const response2 = await agent2.respond({
+    history: [
+      createMessageEvent(
+        EventSource.CUSTOMER,
+        "Alice",
+        "My business is called 'TechFlow' and we build AI-powered workflow automation tools"
+      ),
+    ],
+  });
+  console.log("🤖 Bot:", response2.message);
+  console.log("📊 Context after turn 2:", agent2["context"]);
+  console.log();
+
+  // Turn 3: User provides industry
+  console.log("📱 Turn 3: User provides industry");
+  const agent3 = await createPersistentOnboardingAgent(sessionId);
+  const response3 = await agent3.respond({
+    history: [
+      createMessageEvent(
+        EventSource.CUSTOMER,
+        "Alice",
+        "We're in the SaaS industry"
+      ),
+    ],
+  });
+  console.log("🤖 Bot:", response3.message);
+  console.log("📊 Context after turn 3:", agent3["context"]);
+  console.log();
+
+  // Verify persistence
+  console.log("=== PERSISTENCE VERIFICATION ===");
+  const finalSession = await db.sessions.findById(sessionId);
+  console.log(
+    "💾 Final persisted session:",
+    JSON.stringify(finalSession, null, 2)
+  );
+}
+
+// ============================================================================
+// KEY PATTERNS DEMONSTRATED
+// ============================================================================
+
+/*
+ * ✅ PATTERN 1: Lifecycle Hooks (Recommended for most cases)
+ *    - beforeRespond: Load fresh context before each response
+ *    - onContextUpdate: Persist context after updates
+ *    - Works with both static context and updates
+ *
+ * ✅ PATTERN 2: Context Provider (For always-fresh context)
+ *    - contextProvider: Function that returns fresh context
+ *    - onContextUpdate: Still needed for persistence
+ *    - Best when context is always loaded from external source
+ *
+ * ✅ PATTERN 3: Tool Context Updates (Two options)
+ *    - Option A: Return { data, contextUpdate } in tool result
+ *    - Option B: Call toolContext.updateContext() directly
+ *    - Both trigger onContextUpdate hook automatically
+ *
+ * ✅ PATTERN 4: Explicit Updates
+ *    - agent.updateContext() for manual updates
+ *    - Triggers onContextUpdate hook
+ *    - Useful outside of tool execution
+ *
+ * ❌ ANTI-PATTERN: Caching Agents
+ *    - DON'T cache agent instances across requests
+ *    - DO recreate agents with fresh context
+ *    - Context gets stale if agent is cached
+ */
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch(console.error);
+}
+
+export { createPersistentOnboardingAgent, createOnboardingAgentWithProvider };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
   "type": "module",
   "main": "./dist/cjs/index.js",

package/src/core/Agent.ts

@@ -27,6 +27,7 @@ export class Agent<TContext = unknown> {
   private routes: Route<TContext>[] = [];
   private observations: Observation[] = [];
   private domainRegistry = new DomainRegistry();
+  private context: TContext | undefined;
 
   /**
    * Dynamic domain property - populated via addDomain
@@ -39,6 +40,16 @@ export class Agent<TContext = unknown> {
       this.options.maxEngineIterations = 1;
     }
 
+    // Validate context configuration
+    if (options.context !== undefined && options.contextProvider) {
+      throw new Error(
+        "Cannot provide both 'context' and 'contextProvider'. Choose one."
+      );
+    }
+
+    // Initialize context if provided
+    this.context = options.context;
+
     // Initialize from options
     if (options.terms) {
       this.terms = [...options.terms];
@@ -167,6 +178,39 @@ export class Agent<TContext = unknown> {
     this.domain[name] = domainObject;
   }
 
+  /**
+   * Update the agent's context
+   * Triggers the onContextUpdate lifecycle hook if configured
+   */
+  async updateContext(updates: Partial<TContext>): Promise<void> {
+    const previousContext = this.context;
+
+    // Merge updates with current context
+    this.context = {
+      ...(this.context as Record<string, unknown>),
+      ...(updates as Record<string, unknown>),
+    } as TContext;
+
+    // Trigger lifecycle hook if configured
+    if (this.options.hooks?.onContextUpdate && previousContext !== undefined) {
+      await this.options.hooks.onContextUpdate(this.context, previousContext);
+    }
+  }
+
+  /**
+   * Get current context (fetches from provider if configured)
+   * @internal
+   */
+  private async getContext(): Promise<TContext | undefined> {
+    // If context provider is configured, use it to fetch fresh context
+    if (this.options.contextProvider) {
+      return await this.options.contextProvider();
+    }
+
+    // Otherwise return the stored context
+    return this.context;
+  }
+
   /**
    * Generate a response based on history and context
    */
@@ -183,9 +227,19 @@ export class Agent<TContext = unknown> {
   }> {
     const { history, contextOverride, signal } = params;
 
-    // Merge context
+    // Get current context (may fetch from provider)
+    let currentContext = await this.getContext();
+
+    // Call beforeRespond hook if configured
+    if (this.options.hooks?.beforeRespond && currentContext !== undefined) {
+      currentContext = await this.options.hooks.beforeRespond(currentContext);
+      // Update stored context with the result from beforeRespond
+      this.context = currentContext;
+    }
+
+    // Merge context with override
     const effectiveContext = {
-      ...(this.options.context as Record<string, unknown>),
+      ...(currentContext as Record<string, unknown>),
       ...(contextOverride as Record<string, unknown>),
     } as TContext;
 

package/src/core/Events.ts

@@ -70,7 +70,8 @@ export function adaptEvent(e: Event | EmittedEvent): string {
 export function createMessageEvent(
   source: EventSource,
   participantName: string,
-  message: string
+  message: string,
+  timestamp?: string
 ): Event<MessageEventData> {
   return {
     kind: EventKind.MESSAGE,
@@ -79,7 +80,7 @@ export function createMessageEvent(
       participant: { display_name: participantName },
       message,
     },
-    timestamp: new Date().toISOString(),
+    timestamp: timestamp || new Date().toISOString(),
   };
 }
 
@@ -88,7 +89,8 @@ export function createMessageEvent(
  */
 export function createToolEvent(
   source: EventSource,
-  toolCalls: ToolCall[]
+  toolCalls: ToolCall[],
+  timestamp?: string
 ): Event<ToolEventData> {
   return {
     kind: EventKind.TOOL,
@@ -96,6 +98,6 @@ export function createToolEvent(
     data: {
       tool_calls: toolCalls,
     },
-    timestamp: new Date().toISOString(),
+    timestamp: timestamp || new Date().toISOString(),
   };
 }