@falai/agent 1.2.8 → 2.0.0

package/examples/core-concepts/session-management.ts

@@ -1,494 +0,0 @@
-/**
- * Session Management Example
- *
- * This example demonstrates how to manage conversation state across multiple turns
- * using session management, persistence, and state restoration.
- *
- * Key concepts:
- * - Session state management
- * - Multi-turn conversations
- * - Data persistence across turns
- * - Session restoration
- * - Route transitions with session state
- * - NEW: Flexible ConditionTemplate patterns for session-aware routing:
- *   - String-only conditions: "user wants to order" (AI context only)
- *   - Function-only conditions: (ctx) => !!ctx.data?.orderId (session state checks)
- *   - Mixed arrays: ["payment needed", (ctx) => !ctx.data?.confirmed] (hybrid)
- *   - Session-aware skipIf conditions for flow control
- */
-
-import {
-  Agent,
-  GeminiProvider,
-  MemoryAdapter,
-  type Tool,
-  ValidationError,
-} from "../../src/index";
-
-// Define data types for our multi-step process
-interface OrderData {
-  customerName: string;
-  productType: "laptop" | "phone" | "tablet";
-  budget: number;
-  preferredColor?: string;
-  urgentDelivery: boolean;
-  orderId?: string;
-}
-
-interface OrderContext {
-  userId: string;
-  userName: string;
-  isVip: boolean;
-}
-
-interface PaymentData {
-  orderId?: string; // Make this optional to match OrderData
-  paymentMethod: "credit_card" | "paypal" | "bank_transfer";
-  amount: number;
-  confirmed: boolean;
-}
-
-// Tools for order processing - using unified Tool interface
-const createOrderTool: Tool<unknown, UnifiedOrderData> = {
-  id: "create_order",
-  description: "Create a new order from the collected order data",
-  parameters: {
-    type: "object",
-    properties: {},
-  },
-  handler: (context, args) => {
-    const orderId = `ORD-${Date.now()}`;
-    console.log(`Creating order ${orderId} for ${context.data?.customerName}`);
-
-    return {
-      data: `Order ${orderId} created successfully!`,
-      dataUpdate: {
-        orderId,
-      },
-    };
-  },
-};
-
-const processPaymentTool: Tool<unknown, UnifiedOrderData> = {
-  id: "process_payment",
-  description: "Process payment for an order",
-  parameters: {
-    type: "object",
-    properties: {},
-  },
-  handler: (context, args) => {
-    console.log(`Processing payment for order ${context.data?.orderId}`);
-
-    // Simulate payment processing
-    const success = Math.random() > 0.1; // 90% success rate
-
-    if (success) {
-      return {
-        data: `Payment processed successfully! Order ${context.data?.orderId} is now confirmed.`,
-        dataUpdate: {
-          confirmed: true,
-        },
-      };
-    } else {
-      return {
-        data: "Payment failed. Please try again or contact support.",
-        dataUpdate: {
-          confirmed: false,
-        },
-      };
-    }
-  },
-};
-
-// Define unified data schema for all order-related interactions
-interface UnifiedOrderData extends OrderData, PaymentData { }
-
-const orderSchema = {
-  type: "object",
-  properties: {
-    // Order fields
-    customerName: { type: "string" },
-    productType: { type: "string", enum: ["laptop", "phone", "tablet"] },
-    budget: { type: "number", minimum: 100 },
-    preferredColor: { type: "string" },
-    urgentDelivery: { type: "boolean" },
-    orderId: { type: "string" },
-    // Payment fields
-    paymentMethod: {
-      type: "string",
-      enum: ["credit_card", "paypal", "bank_transfer"],
-    },
-    amount: { type: "number" },
-    confirmed: { type: "boolean" },
-  },
-};
-
-// Create agent with persistence and agent-level schema
-const agent = new Agent<unknown, UnifiedOrderData>({
-  name: "OrderBot",
-  description:
-    "A bot that handles multi-step order processing with session management",
-  provider: new GeminiProvider({
-    apiKey: process.env.GEMINI_API_KEY!,
-    model: "models/gemini-2.5-flash",
-  }),
-  // NEW: Agent-level schema
-  schema: orderSchema,
-  persistence: {
-    adapter: new MemoryAdapter(), // In production, use RedisAdapter, PrismaAdapter, etc.
-  },
-});
-
-// Demonstrate different tool registration patterns
-
-// Method 1: Register tools for ID-based reference in steps
-agent.tool.register(createOrderTool);
-agent.tool.register(processPaymentTool);
-
-// Method 2: Create specialized validation tool
-const orderValidationTool = agent.tool.createValidation({
-  id: "validate_order",
-  fields: ["customerName", "productType", "budget"] as const,
-  validator: async (context, data) => {
-    const errors: ValidationError[] = [];
-    if (!data.customerName || data.customerName.length < 2) {
-      errors.push({
-        field: "customerName",
-        value: data.customerName,
-        message: "Customer name must be at least 2 characters",
-        schemaPath: "customerName"
-      });
-    }
-    if (!data.budget || data.budget < 100) {
-      errors.push({
-        field: "budget",
-        value: data.budget,
-        message: "Budget must be at least $100",
-        schemaPath: "budget"
-      });
-    }
-    return {
-      valid: errors.length === 0,
-      errors,
-      warnings: [],
-    };
-  },
-});
-
-// Method 3: Create data enrichment tool
-const orderEnrichmentTool = agent.tool.createDataEnrichment({
-  id: "enrich_order",
-  fields: ["productType", "budget"] as const,
-  enricher: async (context, data) => {
-    // Enrich with fields that exist in UnifiedOrderData
-    const urgentDelivery = data.budget > 1000; // Premium orders get urgent delivery
-    const preferredColor = data.productType === "laptop" ? "silver" : "black";
-
-    return {
-      urgentDelivery,
-      preferredColor,
-    };
-  },
-});
-
-// Order collection route with sequential steps
-agent.createRoute({
-  title: "Product Order",
-  description: "Collect order details and create an order",
-  // Mixed condition: AI context + programmatic validation
-  when: [
-    "user wants to place an order or buy something",
-    (ctx) => {
-      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
-      return message.includes('order') || message.includes('buy') || message.includes('purchase');
-    }
-  ],
-  // Skip if user already has a pending order
-  skipIf: [
-    "user already has an active order",
-    (ctx) => !!ctx.data?.orderId && !ctx.data?.confirmed
-  ],
-  // NEW: Required fields for route completion
-  requiredFields: ["customerName", "productType", "budget"],
-  // NEW: Optional fields that enhance the experience
-  optionalFields: ["preferredColor", "urgentDelivery", "orderId"],
-  // Sequential steps for order collection
-  steps: [
-    {
-      id: "ask_name",
-      description: "Ask for customer name",
-      prompt: "Hi! I'd like to help you place an order. What's your name?",
-      collect: ["customerName"],
-      // String-only skipIf for AI context
-      skipIf: "customer name already provided",
-    },
-    {
-      id: "ask_product",
-      description: "Ask for product type",
-      prompt: "What would you like to order? (laptop, phone, or tablet)",
-      collect: ["productType"],
-      requires: ["customerName"],
-      // Function-only skipIf for programmatic check
-      skipIf: (ctx) => !!ctx.data?.productType,
-    },
-    {
-      id: "ask_budget",
-      description: "Ask for budget",
-      prompt: "What's your budget for this purchase?",
-      collect: ["budget"],
-      requires: ["customerName", "productType"],
-      // Mixed skipIf: AI context + programmatic logic
-      skipIf: [
-        "budget already specified",
-        (ctx) => ctx.data?.budget !== undefined
-      ],
-    },
-    {
-      id: "ask_color",
-      description: "Ask for preferred color",
-      prompt: "Do you have a preferred color?",
-      collect: ["preferredColor"],
-      requires: ["customerName", "productType", "budget"],
-      // Function-only skipIf
-      skipIf: (ctx) => !!ctx.data?.preferredColor,
-    },
-    {
-      id: "ask_urgent",
-      description: "Ask about urgent delivery",
-      prompt: "Do you need urgent delivery?",
-      collect: ["urgentDelivery"],
-      requires: ["customerName", "productType", "budget"],
-      // String-only skipIf for simple cases
-      skipIf: "delivery preference already collected",
-    },
-    {
-      id: "create_order",
-      description: "Create the order",
-      prompt: "Great! Let me create your order.",
-      tools: ["create_order"], // Reference by ID
-      requires: ["customerName", "productType", "budget"],
-    },
-  ],
-  onComplete: {
-    nextStep: "Payment Processing",
-    condition: "Order has been created successfully",
-  },
-});
-
-// Payment route with sequential steps
-agent.createRoute({
-  title: "Payment Processing",
-  description: "Process payment for an order",
-  // Function-only condition for programmatic logic
-  when: (ctx) => !!ctx.data?.orderId && !ctx.data?.confirmed,
-  // Skip if payment already processed
-  skipIf: (ctx) => !!ctx.data?.confirmed,
-  // NEW: Required fields for route completion
-  requiredFields: ["orderId", "paymentMethod", "amount"],
-  // NEW: Optional fields
-  optionalFields: ["confirmed"],
-  // Sequential steps for payment processing
-  steps: [
-    {
-      id: "ask_payment_method",
-      description: "Ask for payment method",
-      prompt:
-        "Now let's process payment for your order. What payment method would you prefer?",
-      collect: ["paymentMethod"],
-      // Mixed skipIf: AI context + programmatic check
-      skipIf: [
-        "payment method already selected",
-        (ctx) => !!ctx.data?.paymentMethod
-      ],
-    },
-    {
-      id: "ask_amount",
-      description: "Ask for payment amount",
-      prompt: "What's the payment amount?",
-      collect: ["amount"],
-      requires: ["paymentMethod"],
-      // Function-only skipIf
-      skipIf: (ctx) => ctx.data?.amount !== undefined,
-    },
-    {
-      id: "process_payment",
-      description: "Process the payment",
-      prompt: "Processing your payment...",
-      tools: ["process_payment"], // Reference by ID
-      requires: ["orderId", "paymentMethod", "amount"],
-    },
-  ],
-  onComplete: "Order Complete", // End conversation when payment is complete
-});
-
-// Demonstration of automatic session management
-async function demonstrateSessionManagement() {
-  console.log("=== Automatic Session Management Demo ===\n");
-
-  // Create agent with automatic session management
-  const sessionAgent = new Agent<unknown, UnifiedOrderData>({
-    name: "OrderBot",
-    description: "A bot that handles multi-step order processing",
-    provider: new GeminiProvider({
-      apiKey: process.env.GEMINI_API_KEY!,
-      model: "models/gemini-2.5-flash",
-    }),
-    // NEW: Agent-level schema
-    schema: orderSchema,
-    persistence: {
-      adapter: new MemoryAdapter(),
-    },
-    sessionId: "user-alice-123", // Automatically creates/loads this session
-  });
-
-  // Copy routes to the session agent
-  agent.getRoutes().forEach(route => {
-    sessionAgent.createRoute(route.toOptions());
-  });
-
-  // Turn 1: Start order process - simple message API
-  console.log("Turn 1: Starting order process");
-  console.log("User: Hi, I'm Alice and I want to buy a laptop");
-
-  const response1 = await sessionAgent.chat("Hi, I'm Alice and I want to buy a laptop");
-
-  console.log("Bot:", response1.message);
-  console.log("Session ID:", sessionAgent.session.id);
-  console.log("Session data:", JSON.stringify(sessionAgent.session.getData(), null, 2));
-  console.log("History length:", sessionAgent.session.getHistory().length);
-  console.log();
-
-  // Turn 2: Provide budget - session automatically maintained
-  console.log("Turn 2: Providing budget");
-  console.log("User: My budget is $1500");
-
-  const response2 = await sessionAgent.chat("My budget is $1500");
-
-  console.log("Bot:", response2.message);
-  console.log("Session data:", JSON.stringify(sessionAgent.session.getData(), null, 2));
-  console.log("History length:", sessionAgent.session.getHistory().length);
-  console.log();
-
-  // Turn 3: Complete order details - session automatically updated
-  console.log("Turn 3: Completing order and transitioning to payment");
-  console.log("User: I want black color and urgent delivery please");
-
-  const response3 = await sessionAgent.chat("I want black color and urgent delivery please");
-
-  console.log("Bot:", response3.message);
-  console.log("Session data:", JSON.stringify(sessionAgent.session.getData(), null, 2));
-  console.log("Route complete:", response3.isRouteComplete);
-  console.log("History length:", sessionAgent.session.getHistory().length);
-  console.log();
-
-  // Turn 4: Process payment - automatic route transition
-  console.log("Turn 4: Processing payment in transitioned route");
-  console.log("User: I'll pay with credit card, amount is $1599");
-
-  const response4 = await sessionAgent.chat("I'll pay with credit card, amount is $1599");
-
-  console.log("Bot:", response4.message);
-  console.log("Session data:", JSON.stringify(sessionAgent.session.getData(), null, 2));
-  console.log("Route complete:", response4.isRouteComplete);
-  console.log("Final history length:", sessionAgent.session.getHistory().length);
-}
-
-// Demonstrate automatic session persistence and restoration
-async function demonstrateSessionPersistence() {
-  console.log("\n=== Automatic Session Persistence Demo ===\n");
-
-  // Create agent with specific sessionId for demonstration
-  const sessionId = "demo-session-456";
-  const persistentAgent = new Agent<OrderContext, UnifiedOrderData>({
-    name: "Order Assistant",
-    description: "Help customers place orders with automatic persistence",
-    provider: new GeminiProvider({
-      apiKey: process.env.GEMINI_API_KEY!,
-      model: "models/gemini-2.5-flash",
-    }),
-    context: {
-      userId: "user_alice",
-      userName: "Alice",
-      isVip: false,
-    },
-    // NEW: Agent-level schema
-    schema: orderSchema,
-    persistence: {
-      adapter: new MemoryAdapter(),
-      autoSave: true, // Automatic persistence
-    },
-    sessionId, // Agent automatically loads or creates this session
-  });
-
-  // Copy routes to the persistent agent
-  agent.getRoutes().forEach(route => {
-    persistentAgent.createRoute(route.toOptions());
-  });
-
-  console.log("Session ready:", persistentAgent.session.id);
-
-  // Start conversation - session automatically managed
-  const response1 = await persistentAgent.chat("I want to buy a phone for $800");
-
-  console.log("After first interaction:");
-  console.log("🤖 Agent:", response1.message);
-  console.log("Session data:", JSON.stringify(persistentAgent.session.getData(), null, 2));
-  console.log("History length:", persistentAgent.session.getHistory().length);
-  console.log("Session automatically saved to persistence ✓");
-
-  // Simulate server restart - create new agent instance with same sessionId
-  console.log("\n🔄 Simulating server restart - creating new agent instance...");
-
-  const restoredAgent = new Agent<OrderContext, UnifiedOrderData>({
-    name: "Order Assistant",
-    provider: new GeminiProvider({
-      apiKey: process.env.GEMINI_API_KEY!,
-      model: "models/gemini-2.5-flash",
-    }),
-    context: {
-      userId: "user_alice",
-      userName: "Alice",
-      isVip: false,
-    },
-    // NEW: Agent-level schema
-    schema: orderSchema,
-    persistence: {
-      adapter: new MemoryAdapter(), // Same adapter instance for demo
-      autoSave: true,
-    },
-    sessionId, // Same sessionId - automatically loads existing session
-  });
-
-  // Copy routes to the restored agent
-  agent.getRoutes().forEach(route => {
-    restoredAgent.createRoute(route.toOptions());
-  });
-
-  console.log("Session automatically restored:");
-  console.log("- Session ID:", restoredAgent.session.id);
-  console.log("- History length:", restoredAgent.session.getHistory().length);
-  console.log("- Restored data:", JSON.stringify(restoredAgent.session.getData(), null, 2));
-
-  // Continue conversation seamlessly
-  const response2 = await restoredAgent.chat("Actually, make it urgent delivery");
-
-  console.log("\nAfter continuing with restored session:");
-  console.log("🤖 Agent:", response2.message);
-  console.log("Session data:", JSON.stringify(restoredAgent.session.getData(), null, 2));
-  console.log("History length:", restoredAgent.session.getHistory().length);
-  console.log("Session automatically saved again ✓");
-}
-
-// Run demonstrations
-async function main() {
-  try {
-    await demonstrateSessionManagement();
-    await demonstrateSessionPersistence();
-  } catch (error) {
-    console.error("Error:", error);
-  }
-}
-
-if (import.meta.url === `file://${process.argv[1]}`) {
-  main().catch(console.error);
-}