@falai/agent 0.8.1 → 0.9.0-alpha-1

package/examples/{declarative-agent.ts → core-concepts/basic-agent.ts}

@@ -1,28 +1,24 @@
 /**
- * Example: Declarative Agent Configuration with Session Step
+ * Example: Declarative Agent Configuration with Sequential Steps
  *
  * This example demonstrates how to configure an entire agent
  * using declarative syntax in the constructor, including:
- * - Terms (glossary)
+ * - Terms (domain glossary)
  * - Guidelines (behavior rules)
- * - Capabilities
- * - Routes with data extraction schemas and custom IDs
- * - Session step management for multi-turn conversations
+ * - Tools (capabilities)
+ * - Routes with data extraction schemas and sequential steps
+ * - Session management for multi-turn conversations
  */
 
 import {
   Agent,
-  defineTool,
-  createMessageEvent,
-  EventSource,
   GeminiProvider,
-  createSession,
   type Term,
   type Guideline,
-  type Capability,
+  type Tool,
   type RouteOptions,
-  END_ROUTE,
-} from "../src/index";
+  History,
+} from "../../src/index";
 
 // Context type
 interface HealthcareContext {
@@ -45,23 +41,33 @@ interface LabData {
   resultsNeeded: boolean;
 }
 
-// Define tools with custom IDs (optional - IDs are deterministic by default)
-const getInsuranceProviders = defineTool<HealthcareContext, [], string[]>({
-  name: "get_insurance_providers",
-  handler: async () => {
-    return { data: ["MegaCare Insurance", "HealthFirst", "WellnessPlus"] };
-  },
-  id: "healthcare_insurance_providers", // Custom ID for persistence
+// Define tools using the new Tool interface
+const getInsuranceProviders: Tool<HealthcareContext, [], string[]> = {
+  id: "healthcare_insurance_providers",
   description: "Retrieves list of accepted insurance providers",
-});
+  parameters: {
+    type: "object",
+    properties: {},
+  },
+  handler: () => {
+    return {
+      data: ["MegaCare Insurance", "HealthFirst", "WellnessPlus"],
+    };
+  },
+};
 
-const getAvailableSlots = defineTool<
+const getAvailableSlots: Tool<
   HealthcareContext,
   [],
   { date: string; time: string }[]
->({
-  name: "get_available_slots",
-  handler: async () => {
+> = {
+  id: "healthcare_available_slots",
+  description: "Gets available appointment slots",
+  parameters: {
+    type: "object",
+    properties: {},
+  },
+  handler: () => {
     return {
       data: [
         { date: "2025-10-20", time: "10:00 AM" },
@@ -70,18 +76,27 @@ const getAvailableSlots = defineTool<
       ],
     };
   },
-  id: "healthcare_available_slots", // Custom ID
-  description: "Gets available appointment slots",
-});
+};
 
-const getLabResults = defineTool<
+const getLabResults: Tool<
   HealthcareContext,
   [],
   { report: string; status: string }
->({
-  name: "get_lab_results",
-  handler: async ({ context, data }) => {
-    // Tools can now access collected data
+> = {
+  id: "healthcare_lab_results",
+  description: "Retrieves patient lab results",
+  parameters: {
+    type: "object",
+    properties: {},
+  },
+  handler: ({
+    context,
+    data,
+  }: {
+    context: HealthcareContext;
+    data?: Partial<LabData>;
+  }) => {
+    // Tools can access collected data and context
     const labData = data as Partial<LabData>;
     if (labData?.testType) {
       return {
@@ -99,14 +114,26 @@ const getLabResults = defineTool<
       },
     };
   },
-  id: "healthcare_lab_results", // Custom ID
-  description: "Retrieves patient lab results",
-});
+};
 
-const scheduleAppointment = defineTool<HealthcareContext>({
-  name: "schedule_appointment",
-  handler: async ({ context, data }) => {
-    // Tools can access data appointment data
+const scheduleAppointment: Tool<
+  HealthcareContext,
+  [],
+  { confirmation: string }
+> = {
+  id: "healthcare_schedule_appointment",
+  description: "Schedules patient appointments",
+  parameters: {
+    type: "object",
+    properties: {},
+  },
+  handler: ({
+    data,
+  }: {
+    context: HealthcareContext;
+    data?: Partial<AppointmentData>;
+  }) => {
+    // Tools access collected appointment data
     const appointment = data as Partial<AppointmentData>;
     if (!appointment?.preferredDate || !appointment?.preferredTime) {
       return { data: { confirmation: "Please provide appointment details" } };
@@ -118,12 +145,10 @@ const scheduleAppointment = defineTool<HealthcareContext>({
       },
     };
   },
-  id: "healthcare_schedule_appointment",
-  description: "Schedules patient appointments",
-});
+};
 
 // Declarative configuration
-const terms: Term[] = [
+const terms: Term<HealthcareContext>[] = [
   {
     name: "Office Phone Number",
     description: "The phone number of our office, at +1-234-567-8900",
@@ -134,22 +159,23 @@ const terms: Term[] = [
   },
   {
     name: "Dr. Charles Xavier",
-    description: "Neurologist specializing in brain disorders",
+    description: ({ context }) =>
+      `Neurologist specializing in brain disorders for patient ${context?.patientName}`,
     synonyms: ["Professor X", "Dr. Xavier"],
   },
 ];
 
-const guidelines: Guideline[] = [
+const guidelines: Guideline<HealthcareContext>[] = [
   {
     condition: "The patient asks about insurance",
     action:
       "List the insurance providers we accept and tell them to call the office for more details",
-    tools: [getInsuranceProviders],
     tags: ["insurance", "billing"],
   },
   {
     condition: "The patient asks to talk to a human agent",
-    action: "Provide the office phone number and office hours",
+    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"],
   },
   {
@@ -160,22 +186,9 @@ const guidelines: Guideline[] = [
   },
 ];
 
-const capabilities: Capability[] = [
-  {
-    title: "Appointment Scheduling",
-    description: "Schedule, reschedule, or cancel patient appointments",
-    tools: [getAvailableSlots],
-  },
-  {
-    title: "Lab Results Access",
-    description: "Retrieve and explain patient lab results",
-    tools: [getLabResults],
-  },
-];
-
-const routes: RouteOptions[] = [
+const routes: RouteOptions<HealthcareContext>[] = [
   {
-    id: "route_schedule_appointment", // Custom ID ensures consistency across restarts
+    id: "route_schedule_appointment",
     title: "Schedule Appointment",
     description: "Helps the patient schedule an appointment",
     conditions: ["The patient wants to schedule an appointment"],
@@ -215,39 +228,58 @@ const routes: RouteOptions[] = [
         enabled: true,
       },
     ],
-    // NEW: Use sequential steps for a linear booking flow
+    // Sequential steps for a linear booking flow
     steps: [
       {
         id: "ask_appointment_type",
-        instructions:
+        description: "Ask for appointment type",
+        prompt:
           "What type of appointment do you need? (checkup, consultation, or followup)",
         collect: ["appointmentType"],
       },
       {
         id: "ask_date_time",
-        instructions: "When would you like to come in?",
+        description: "Ask for preferred date and time",
+        prompt: "When would you like to come in?",
         collect: ["preferredDate", "preferredTime"],
-        requires: ["appointmentType"],
+        requires: ["appointmentType"], // Must have appointment type first
       },
       {
         id: "ask_symptoms",
-        instructions: "Are you experiencing any symptoms?",
+        description: "Ask about symptoms",
+        prompt: "Are you experiencing any symptoms?",
         collect: ["symptoms"],
+        skipIf: (data: Partial<AppointmentData>) =>
+          data.appointmentType === "checkup", // Skip for checkups
       },
       {
-        id: "confirm_appointment",
-        tool: scheduleAppointment,
+        id: "schedule_appointment",
+        description: "Schedule the appointment",
+        prompt: "I'll schedule your appointment now.",
+        tools: [scheduleAppointment], // Use the scheduling tool
         requires: ["preferredDate", "preferredTime"],
-      },
-      {
-        id: "final_confirmation",
-        instructions:
-          "Your appointment is confirmed. You will receive a notification shortly.",
+        prepare: getInsuranceProviders, // Use existing tool to prepare insurance info
+        finalize: {
+          // Inline tool to handle appointment finalization
+          id: "finalize_appointment",
+          description: "Complete the appointment booking process",
+          parameters: { type: "object", properties: {} },
+          handler: ({ context, data }) => {
+            console.log(`✅ Appointment finalized for ${context.patientName}`);
+            console.log(`📅 Details: ${JSON.stringify(data, null, 2)}`);
+
+            // Could send confirmation email, update calendar, etc.
+            return {
+              data: `Appointment confirmed for ${context.patientName}`,
+            };
+          },
+        },
       },
     ],
+    tools: [getAvailableSlots], // Route-level tools available to all steps
   },
   {
-    id: "route_check_lab_results", // Custom ID
+    id: "route_check_lab_results",
     title: "Check Lab Results",
     description: "Retrieves and explains patient lab results",
     conditions: ["The patient wants to see their lab results"],
@@ -278,14 +310,15 @@ const routes: RouteOptions[] = [
         tags: ["escalation"],
       },
     ],
+    tools: [getLabResults], // Route-level tools
   },
   {
     title: "General Healthcare Questions",
     description: "Answer general healthcare questions",
     conditions: ["Patient asks general healthcare questions"],
-    // No schema - stepless Q&A
+    // No schema - conversational Q&A
   },
-] as RouteOptions[];
+];
 
 // Create the fully configured agent
 const agent = new Agent<HealthcareContext>({
@@ -303,7 +336,7 @@ const agent = new Agent<HealthcareContext>({
   // Declarative initialization
   terms,
   guidelines,
-  capabilities,
+  tools: [getInsuranceProviders], // Agent-level tools
   routes,
 });
 
@@ -320,63 +353,73 @@ agent
     synonyms: ["virtual visit", "video appointment"],
   });
 
-// Example usage with session step
+// Example usage with session management
+
 async function main() {
-  // Initialize session step
-  let session = createSession<AppointmentData | LabData>();
+  // Session is automatically managed by the agent
+  console.log("✨ Session ready:", agent.session.id);
 
-  // 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"
-    ),
-  ];
+  // Turn 1 - Agent responds and routes to appropriate flow
+  console.log("🔄 Turn 1: Initial inquiry");
+  await agent.session.addMessage("user", "Hi, I need to follow up on my recent visit", "Alice");
+  
+  const response1 = await agent.respond({ 
+    history: agent.session.getHistory() 
+  });
+  
+  console.log("🤖 Agent:", response1.message);
+  console.log("🛤️  Route chosen:", response1.session?.currentRoute?.title);
 
-  // Turn 1 - Agent responds and extracts intent
-  const response = await agent.respond({ history, session });
-  console.log("Agent:", response.message);
-  console.log("Route chosen:", response.session?.currentRoute?.title);
-  console.log("Collected data:", response.session?.data);
+  await agent.session.addMessage("assistant", response1.message);
 
-  // Session step is updated with progress
-  session = response.session!;
+  // Turn 2 - User provides more details
+  console.log("\n🔄 Turn 2: Providing appointment details");
+  await agent.session.addMessage("user", "I need a checkup next Tuesday at 2 PM", "Alice");
 
-  // Turn 2 - Continue conversation with session step
-  if (response.session?.currentRoute?.title === "Schedule Appointment") {
-    const history2 = [
-      ...history,
-      createMessageEvent(EventSource.AI_AGENT, "Bot", response.message),
-      createMessageEvent(
-        EventSource.CUSTOMER,
-        "Alice",
-        "I need a checkup next week"
-      ),
-    ];
+  const response2 = await agent.respond({ 
+    history: agent.session.getHistory() 
+  });
+  
+  console.log("🤖 Agent:", response2.message);
+  console.log("📊 Collected data:", agent.session.getData<AppointmentData | LabData>());
+  console.log("📍 Current step:", response2.session?.currentStep?.id);
 
-    const response2 = await agent.respond({ history: history2, session });
-    console.log("Agent:", response2.message);
-    console.log("Updated data:", response2.session?.data);
+  await agent.session.addMessage("assistant", response2.message);
 
-    // Session tracks the appointment booking progress
-    console.log("Current step:", response2.session?.currentStep?.id);
+  // Turn 3 - Continue the conversation flow
+  console.log("\n🔄 Turn 3: Continuing appointment booking");
+  
+  await agent.session.addMessage("user", "I'm feeling a bit anxious about the visit", "Alice");
 
-    // Check for route completion
-    if (response2.isRouteComplete && response2.session) {
-      console.log("\n✅ Appointment scheduling complete!");
-      await sendAppointmentConfirmation(
-        agent.getData(response2.session.id) as AppointmentData
-      );
-    }
+  const response3 = await agent.respond({ 
+    history: agent.session.getHistory() 
+  });
+  
+  console.log("🤖 Agent:", response3.message);
+  console.log("📊 Updated data:", agent.session.getData<AppointmentData | LabData>());
+  console.log("📍 Current step:", response3.session?.currentStep?.id);
+  
+  await agent.session.addMessage("assistant", response3.message);
+
+  // Check for route completion
+  if (response3.isRouteComplete && response3.session) {
+    console.log("\n✅ Appointment scheduling complete!");
+    await sendAppointmentConfirmation(
+      agent.getData<AppointmentData>(response3.session.id) as AppointmentData
+    );
   }
 
-  // Note: Custom IDs ensure consistency across server restarts
-  // Session step enables:
-  // - Tracking conversation progress across turns
-  // - Extracting structured data throughout conversation
-  // - Always-on routing that respects user intent changes
-  // - Step recovery for resuming conversations
+  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);
 }
 
 /**
@@ -389,13 +432,14 @@ async function sendAppointmentConfirmation(data: AppointmentData) {
   console.log("=".repeat(60));
   console.log("Appointment Details:", JSON.stringify(data, null, 2));
   console.log(
-    `   - Sending confirmation to patient for ${data.preferredDate} at ${data.preferredTime}.`
+    `   - Confirmation sent for ${data.preferredDate} at ${data.preferredTime}`
   );
-  await new Promise((resolve) => setTimeout(resolve, 1000));
-  console.log("✨ Confirmation sent!");
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  console.log("✨ Confirmation delivered!");
 }
 
-// Uncomment to run:
-// main().catch(console.error);
-
 export { agent };
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch(console.error);
+}