@falai/agent 0.1.0-alpha2

package/examples/core-concepts/basic-agent.ts

@@ -0,0 +1,503 @@
+/**
+ * Example: Declarative Agent Configuration with Sequential Steps
+ *
+ * This example demonstrates how to configure an entire agent
+ * using declarative syntax in the constructor, including:
+ * - Terms (domain glossary)
+ * - Guidelines (behavior rules) with flexible ConditionTemplate patterns
+ * - Tools (capabilities)
+ * - Routes with data extraction schemas and sequential steps
+ * - Session management for multi-turn conversations
+ * - NEW: Flexible routing conditions with ConditionTemplate patterns:
+ *   - String-only conditions: "user wants to book" (AI context only)
+ *   - Function-only conditions: (ctx) => ctx.data?.hasPayment (programmatic only)
+ *   - Mixed arrays: ["user wants to book", (ctx) => !ctx.data?.complete] (hybrid)
+ *   - Route skipIf: Dynamic route exclusion based on conditions
+ *   - Step skipIf: Enhanced conditional step skipping
+ */
+
+import {
+  Agent,
+  GeminiProvider,
+  Tool,
+  ValidationError,
+  type Term,
+  type Guideline,
+} from "../../src/index";
+
+// Context type
+interface HealthcareContext {
+  patientId: string;
+  patientName: string;
+}
+
+// Data extraction types
+interface AppointmentData {
+  appointmentType: "checkup" | "consultation" | "followup";
+  preferredDate: string;
+  preferredTime: string;
+  symptoms?: string;
+  urgency: "low" | "medium" | "high";
+}
+
+interface LabData {
+  testType: string;
+  testDate: string;
+  resultsNeeded: boolean;
+}
+
+// Define tools using unified Tool interface
+const getInsuranceProvidersTool: Tool<HealthcareContext, HealthcareData> = {
+  id: "healthcare_insurance_providers",
+  description: "Retrieves list of accepted insurance providers",
+  parameters: {
+    type: "object",
+    properties: {},
+  },
+  handler: async (context, args) => {
+    return {
+      data: "Available insurance providers: MegaCare Insurance, HealthFirst, WellnessPlus",
+    };
+  },
+};
+
+const getAvailableSlotsTool: Tool<HealthcareContext, HealthcareData> = {
+  id: "healthcare_available_slots",
+  description: "Gets available appointment slots",
+  parameters: {
+    type: "object",
+    properties: {},
+  },
+  handler: async (context, args) => {
+    return {
+      data: "Available slots: Oct 20 at 10:00 AM, Oct 20 at 2:00 PM, Oct 21 at 1:00 PM",
+    };
+  },
+};
+
+const getLabResultsTool: Tool<HealthcareContext, HealthcareData> = {
+  id: "healthcare_lab_results",
+  description: "Retrieves patient lab results",
+  parameters: {
+    type: "object",
+    properties: {},
+  },
+  handler: async (toolContext, args) => {
+    // Tools can access collected data and context
+    if (toolContext.data?.testType) {
+      return {
+        data: `${toolContext.data.testType} results for ${toolContext.context.patientName}: All values within normal range`,
+      };
+    }
+
+    return {
+      data: `Lab results for ${toolContext.context.patientName}: All values within normal range`,
+    };
+  },
+};
+
+const scheduleAppointmentTool: Tool<HealthcareContext, HealthcareData> = {
+  id: "healthcare_schedule_appointment",
+  description: "Schedules patient appointments",
+  parameters: {
+    type: "object",
+    properties: {},
+  },
+  handler: async (context, args) => {
+    // Tools access collected appointment data
+    if (!context.data?.preferredDate || !context.data?.preferredTime) {
+      return { data: "Please provide appointment details" };
+    }
+
+    return {
+      data: `Appointment scheduled for ${context.data.preferredDate} at ${context.data.preferredTime}`,
+    };
+  },
+};
+
+// Declarative configuration
+const terms: Term<HealthcareContext>[] = [
+  {
+    name: "Office Phone Number",
+    description: "The phone number of our office, at +1-234-567-8900",
+  },
+  {
+    name: "Office Hours",
+    description: "Office hours are Monday to Friday, 9 AM to 5 PM",
+  },
+  {
+    name: "Dr. Charles Xavier",
+    description: ({ context }) =>
+      `Neurologist specializing in brain disorders for patient ${context?.patientName}`,
+    synonyms: ["Professor X", "Dr. Xavier"],
+  },
+];
+
+const guidelines: Guideline<HealthcareContext>[] = [
+  {
+    // String-only condition for AI context
+    condition: "The patient asks about insurance",
+    action:
+      "List the insurance providers we accept and tell them to call the office for more details",
+    tags: ["insurance", "billing"],
+  },
+  {
+    // Mixed condition: AI context + programmatic check
+    condition: [
+      "The patient asks to talk to a human agent",
+      (ctx) => ctx.context?.patientName !== undefined // Only if we have patient info
+    ],
+    action: ({ context }: { context?: HealthcareContext }) =>
+      `Of course. You can reach our office at +1-234-567-8900 during office hours (Monday to Friday, 9 AM to 5 PM). I've noted that you'd like to speak with someone, and I can have a representative call you back if you'd like, ${context?.patientName}.`,
+    tags: ["escalation"],
+  },
+  {
+    // Function-only condition for programmatic logic
+    condition: (ctx) => {
+      const event = ctx.history?.[ctx.history.length - 1]
+      if(event && "content" in event){
+        const message = (event.content as string).toLocaleLowerCase() || '';
+        return !message.includes('health') && !message.includes('medical') && !message.includes('appointment');
+      }
+      return false
+    },
+    action:
+      "Kindly tell them you cannot assist with off-topic inquiries - do not engage",
+    tags: ["off-topic"],
+  },
+];
+
+const routes = [
+  {
+    id: "route_schedule_appointment",
+    title: "Schedule Appointment",
+    description: "Helps the patient schedule an appointment",
+    // Mixed condition: AI context + programmatic check
+    when: [
+      "The patient wants to schedule an appointment",
+      (ctx) => !ctx.data?.orderId // Only if no existing order
+    ],
+    // Skip if patient already has urgent medical needs
+    skipIf: [
+      "patient has urgent medical emergency",
+      (ctx) => ctx.data?.urgency === "high"
+    ],
+    // NEW: Required fields for route completion (instead of schema)
+    requiredFields: ["appointmentType", "preferredDate", "preferredTime"],
+    // NEW: Optional fields that enhance the experience
+    optionalFields: ["symptoms", "urgency"],
+    guidelines: [
+      {
+        condition: "The patient says their visit is urgent",
+        action: "Tell them to call the office immediately",
+        tags: ["urgent"],
+        enabled: true,
+      },
+    ],
+    // Sequential steps for a linear booking flow
+    steps: [
+      {
+        id: "ask_appointment_type",
+        description: "Ask for appointment type",
+        prompt:
+          "What type of appointment do you need? (checkup, consultation, or followup)",
+        collect: ["appointmentType"],
+      },
+      {
+        id: "ask_date_time",
+        description: "Ask for preferred date and time",
+        prompt: "When would you like to come in?",
+        collect: ["preferredDate", "preferredTime"],
+        requires: ["appointmentType"], // Must have appointment type first
+      },
+      {
+        id: "ask_symptoms",
+        description: "Ask about symptoms",
+        prompt: "Are you experiencing any symptoms?",
+        collect: ["symptoms"],
+        // Mixed skipIf: AI context + programmatic logic
+        skipIf: [
+          "routine checkup doesn't need symptom details",
+          (data: Partial<HealthcareData>) => data.appointmentType === "checkup"
+        ],
+      },
+      {
+        id: "schedule_appointment",
+        description: "Schedule the appointment",
+        prompt: "I'll schedule your appointment now.",
+        tools: [scheduleAppointmentTool], // Inline tool - only available on this step
+        requires: ["preferredDate", "preferredTime"],
+        prepare: "healthcare_insurance_providers", // Reference by ID
+        finalize: "finalize_appointment", // Reference by ID - will be registered later
+      },
+    ],
+    tools: ["healthcare_available_slots"], // Reference by ID
+  },
+  {
+    id: "route_check_lab_results",
+    title: "Check Lab Results",
+    description: "Retrieves and explains patient lab results",
+    // Function-only condition for programmatic logic
+    when: (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.includes('lab') || message.includes('test') || message.includes('results');
+    },
+    // Skip if no patient ID available
+    skipIf: (ctx) => !ctx.context?.patientId,
+    // NEW: Required fields for route completion
+    requiredFields: ["testType"],
+    // NEW: Optional fields
+    optionalFields: ["testDate", "resultsNeeded"],
+    guidelines: [
+      {
+        condition: "The patient presses for more conclusions about results",
+        action:
+          "Assertively tell them they should call the office to speak with a doctor",
+        tags: ["escalation"],
+      },
+    ],
+    tools: ["healthcare_lab_results"], // Reference by ID
+  },
+  {
+    title: "General Healthcare Questions",
+    description: "Answer general healthcare questions",
+    // String-only condition for AI context
+    when: "Patient asks general healthcare questions",
+    // No required fields - conversational Q&A
+  },
+];
+
+// Define a unified data schema for all healthcare interactions
+interface HealthcareData extends AppointmentData, LabData {}
+
+const healthcareSchema = {
+  type: "object",
+  properties: {
+    // Appointment fields
+    appointmentType: {
+      type: "string",
+      enum: ["checkup", "consultation", "followup"],
+      description: "Type of appointment needed",
+    },
+    preferredDate: {
+      type: "string",
+      description: "Preferred appointment date",
+    },
+    preferredTime: {
+      type: "string",
+      description: "Preferred appointment time",
+    },
+    symptoms: {
+      type: "string",
+      description: "Description of symptoms (if applicable)",
+    },
+    urgency: {
+      type: "string",
+      enum: ["low", "medium", "high"],
+      default: "medium",
+    },
+    // Lab fields
+    testType: {
+      type: "string",
+      description: "Type of lab test",
+    },
+    testDate: {
+      type: "string",
+      description: "Date of the lab test",
+    },
+    resultsNeeded: {
+      type: "boolean",
+      default: true,
+      description: "Whether detailed results are needed",
+    },
+  },
+};
+
+// Create the fully configured agent with agent-level schema
+const agent = new Agent<HealthcareContext, HealthcareData>({
+  name: "HealthBot",
+  description: "A compassionate healthcare assistant",
+  goal: "Provide helpful information and assist with appointments",
+  context: {
+    patientId: "p_12345",
+    patientName: "Alice Johnson",
+  },
+  provider: new GeminiProvider({
+    apiKey: process.env.GEMINI_API_KEY || "demo-key",
+    model: "models/gemini-2.5-flash",
+  }),
+  // NEW: Agent-level schema
+  schema: healthcareSchema,
+  // Declarative initialization
+  terms,
+  guidelines,
+  // Enable debug logging
+  debug: true,
+});
+
+// Demonstrate different tool registration approaches
+
+// Method 1: Register tools for ID-based reference in routes
+// Note: scheduleAppointmentTool is NOT registered globally - it's only available on the specific step
+agent.tool.registerMany([
+  getInsuranceProvidersTool,
+  getAvailableSlotsTool,
+  getLabResultsTool,
+  // scheduleAppointmentTool, // Commented out - will be added to specific step only
+]);
+
+// Method 2: Create and register specialized tools
+const appointmentValidator = agent.tool.createValidation({
+  id: "validate_appointment",
+  fields: ["appointmentType", "preferredDate", "preferredTime"] as const,
+  validator: async (context, data) => {
+    const errors: ValidationError[] = [];
+    if (!data.appointmentType) errors.push({ 
+      field: "appointmentType", 
+      value: data.appointmentType,
+      message: "Appointment type is required",
+      schemaPath: "appointmentType"
+    });
+    if (!data.preferredDate) errors.push({ 
+      field: "preferredDate", 
+      value: data.preferredDate,
+      message: "Preferred date is required",
+      schemaPath: "preferredDate"
+    });
+    if (!data.preferredTime) errors.push({ 
+      field: "preferredTime", 
+      value: data.preferredTime,
+      message: "Preferred time is required",
+      schemaPath: "preferredTime"
+    });
+    
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings: [],
+    };
+  },
+});
+
+// Method 3: Create data enrichment tool
+const patientDataEnricher = agent.tool.createDataEnrichment({
+  id: "enrich_patient_data",
+  fields: ["appointmentType", "symptoms"] as const,
+  enricher: async (context, data) => {
+    // Add urgency classification based on symptoms - return fields that exist in HealthcareData
+    const urgentKeywords = ["chest pain", "difficulty breathing", "severe", "emergency"];
+    const hasUrgentSymptoms = data.symptoms && urgentKeywords.some(keyword => 
+      data.symptoms!.toLowerCase().includes(keyword)
+    );
+    
+    return {
+      urgency: hasUrgentSymptoms ? "high" : "medium", // This matches the urgency field in HealthcareData
+    };
+  },
+});
+
+// Method 4: Create tool using tool.create()
+const finalizeAppointmentTool = agent.tool.create({
+  id: "finalize_appointment",
+  description: "Complete the appointment booking process",
+  parameters: { type: "object", properties: {} },
+  handler: async (context, args) => {
+    console.log(`✅ Appointment finalized for ${context.context.patientName}`);
+    console.log(`📅 Details: ${JSON.stringify(context.data, null, 2)}`);
+
+    // Could send confirmation email, update calendar, etc.
+    return {
+      data: `Appointment confirmed for ${context.context.patientName}`,
+    };
+  },
+});
+
+// Add routes after tools are registered
+routes.forEach((route: any) => {
+  agent.createRoute(route);
+});
+
+// You can still add more dynamically after construction
+agent
+  .createGuideline({
+    condition: "The patient seems confused or distressed",
+    action: "Speak slowly, clearly, and offer to connect them with a human",
+    tags: ["empathy", "support"],
+  })
+  .createTerm({
+    name: "Telemedicine",
+    description: "Remote medical consultation via video call",
+    synonyms: ["virtual visit", "video appointment"],
+  });
+
+// Example usage with session management
+
+async function main() {
+  // Session is automatically managed by the agent
+  console.log("✨ Session ready:", agent.session.id);
+
+  // Turn 1 - Agent responds and routes to appropriate flow
+  console.log("🔄 Turn 1: Initial inquiry");
+  const response1 = await agent.chat("Hi, I need to follow up on my recent visit");
+  
+  console.log("🤖 Agent:", response1.message);
+  console.log("🛤️  Route chosen:", response1.session?.currentRoute?.title);
+
+  // Turn 2 - User provides more details
+  console.log("\n🔄 Turn 2: Providing appointment details");
+  const response2 = await agent.chat("I need a checkup next Tuesday at 2 PM");
+  
+  console.log("🤖 Agent:", response2.message);
+  console.log("📊 Collected data:", agent.session.getData());
+  console.log("📍 Current step:", response2.session?.currentStep?.id);
+
+  // Turn 3 - Continue the conversation flow
+  console.log("\n🔄 Turn 3: Continuing appointment booking");
+  const response3 = await agent.chat("I'm feeling a bit anxious about the visit");
+  
+  console.log("🤖 Agent:", response3.message);
+  console.log("📊 Updated data:", agent.session.getData());
+  console.log("📍 Current step:", response3.session?.currentStep?.id);
+
+  // Check for route completion
+  if (response3.isRouteComplete && response3.session) {
+    console.log("\n✅ Appointment scheduling complete!");
+    await sendAppointmentConfirmation(
+      agent.getCollectedData() as HealthcareData
+    );
+  }
+
+  console.log("\n📋 Session Summary:");
+  console.log(
+    "- Agent-level tools:",
+    agent.getTools().map((t) => t.id)
+  );
+  console.log(
+    "- Available routes:",
+    agent.getRoutes().map((r) => r.title)
+  );
+  console.log("- Agent guidelines:", agent.getGuidelines().length);
+  console.log("- Agent terms:", agent.getTerms().length);
+}
+
+/**
+ * Mock function to send an appointment confirmation.
+ * @param data - The healthcare data.
+ */
+async function sendAppointmentConfirmation(data: HealthcareData) {
+  console.log("\n" + "=".repeat(60));
+  console.log("🚀 Sending Appointment Confirmation...");
+  console.log("=".repeat(60));
+  console.log("Appointment Details:", JSON.stringify(data, null, 2));
+  console.log(
+    `   - Confirmation sent for ${data.preferredDate} at ${data.preferredTime}`
+  );
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  console.log("✨ Confirmation delivered!");
+}
+
+export { agent };
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch(console.error);
+}