@falai/agent 0.8.0 → 0.9.0-alpha-1

package/examples/{healthcare-agent.ts → integrations/healthcare-integration.ts}

@@ -5,13 +5,10 @@
 
 import {
   Agent,
-  defineTool,
+  type Tool,
   AnthropicProvider,
   END_ROUTE,
-  EventSource,
-  createMessageEvent,
-  createSession,
-} from "../src/index";
+} from "../../src";
 
 // Context type
 interface HealthcareContext {
@@ -41,51 +38,78 @@ interface SatisfactionData {
 }
 
 // Tools
-const getInsuranceProviders = defineTool<HealthcareContext, [], string[]>(
-  "get_insurance_providers",
-  async () => {
-    return { data: ["Mega Insurance", "Acme Insurance"] };
-  },
-  { description: "Get list of accepted insurance providers" }
-);
 
-const getUpcomingSlots = defineTool<HealthcareContext, [], string[]>(
-  "get_upcoming_slots",
-  async () => {
+const getUpcomingSlots: Tool<HealthcareContext, unknown[], unknown, unknown> = {
+  id: "get_upcoming_slots",
+  name: "Available Appointment Slots",
+  description: "Get upcoming appointment slots",
+  parameters: {
+    type: "object",
+    properties: {},
+  },
+  handler: () => {
     return { data: ["Monday 10 AM", "Tuesday 2 PM", "Wednesday 1 PM"] };
   },
-  { description: "Get upcoming appointment slots" }
-);
-
-const getLaterSlots = defineTool<HealthcareContext, [], string[]>(
-  "get_later_slots",
-  async () => {
+};
+
+const getLaterSlots: Tool<HealthcareContext, unknown[], unknown, unknown> = {
+  id: "get_later_slots",
+  name: "Extended Appointment Slots",
+  description: "Get later appointment slots",
+  parameters: {
+    type: "object",
+    properties: {},
+  },
+  handler: () => {
     return { data: ["November 3, 11:30 AM", "November 12, 3 PM"] };
   },
-  { description: "Get later appointment slots" }
-);
+};
 
-const scheduleAppointment = defineTool<
+const scheduleAppointment: Tool<
   HealthcareContext,
-  [datetime: string],
-  string
->("schedule_appointment", async ({ context, data }, datetime) => {
-  const appointment = data as Partial<AppointmentData>;
-  if (!appointment?.preferredDate || !appointment?.preferredTime) {
+  unknown[],
+  unknown,
+  AppointmentData
+> = {
+  id: "schedule_appointment",
+  name: "Appointment Scheduler",
+  description: "Schedule an appointment with a healthcare provider",
+  parameters: {
+    type: "object",
+    properties: {
+      datetime: { type: "string", description: "Appointment date and time" },
+    },
+    required: ["datetime"],
+  },
+  handler: ({ data }) => {
+    const appointment = data as Partial<AppointmentData>;
+    if (!appointment?.preferredDate || !appointment?.preferredTime) {
+      return {
+        data: "Please specify preferred date and time for the appointment",
+      };
+    }
     return {
-      data: "Please specify preferred date and time for the appointment",
+      data: `Appointment scheduled for ${appointment.preferredDate} at ${
+        appointment.preferredTime
+      } for ${appointment.appointmentReason || "consultation"}`,
     };
-  }
-  return {
-    data: `Appointment scheduled for ${appointment.preferredDate} at ${
-      appointment.preferredTime
-    } for ${appointment.appointmentReason || "consultation"}`,
-  };
-});
-
-const getLabResults = defineTool<HealthcareContext, [], object>(
-  "get_lab_results",
-  async ({ context, data }) => {
+  },
+};
+
+const getLabResults: Tool<
+  HealthcareContext,
+  unknown[],
+  unknown,
+  LabResultsData
+> = {
+  id: "get_lab_results",
+  name: "Lab Results Retriever",
+  description: "Get lab test results",
+  parameters: {
+    type: "object",
+    properties: {},
+  },
+  handler: ({ context, data }) => {
     const labData = data as Partial<LabResultsData>;
     return {
       data: {
@@ -94,10 +118,10 @@ const getLabResults = defineTool<HealthcareContext, [], object>(
         patientName: context.patientName,
       },
     };
-  }
-);
+  },
+};
 
-async function createHealthcareAgent() {
+function createHealthcareAgent() {
   const provider = new AnthropicProvider({
     apiKey: process.env.ANTHROPIC_API_KEY || "test-key",
     model: "claude-sonnet-4-5",
@@ -106,7 +130,50 @@ async function createHealthcareAgent() {
   const agent = new Agent<HealthcareContext>({
     name: "Healthcare Agent",
     description: "Is empathetic and calming to the patient.",
+    identity:
+      "I am the Healthcare Agent, a compassionate AI assistant dedicated to providing excellent patient care. With deep knowledge of medical procedures and a focus on patient comfort, I'm here to help you navigate your healthcare journey with empathy and expertise.",
     provider: provider,
+
+    // Knowledge base with healthcare-specific information
+    knowledgeBase: {
+      medicalProcedures: {
+        checkup: {
+          duration: "30 minutes",
+          preparation: "No special preparation needed",
+          frequency: "Annual or as recommended by doctor",
+        },
+        consultation: {
+          duration: "45-60 minutes",
+          preparation: "Bring medical history and current medications",
+          frequency: "As needed",
+        },
+        followup: {
+          duration: "15-30 minutes",
+          preparation: "Review previous visit notes",
+          frequency: "2-4 weeks after initial treatment",
+        },
+      },
+      insurancePolicies: {
+        acceptedProviders: ["Mega Insurance", "Acme Insurance", "Blue Cross"],
+        coverageTypes: ["HMO", "PPO", "Medicare"],
+        requirements: {
+          referral: "Required for specialist visits",
+          copay: "$25 per visit",
+          deductible: "$500 annual",
+        },
+      },
+      emergencyGuidelines: [
+        "Call 911 for life-threatening emergencies",
+        "Go to nearest ER for severe symptoms",
+        "Contact office for urgent but non-life-threatening issues",
+        "Use telemedicine for minor concerns during office hours",
+      ],
+      patientResources: {
+        patientPortal: "Available 24/7 for appointments and records",
+        educationalMaterials: "Available in English, Spanish, and Portuguese",
+        supportGroups: "Weekly sessions for chronic conditions",
+      },
+    },
     context: {
       patientId: "patient-123",
       patientName: "Test Patient",
@@ -137,6 +204,26 @@ async function createHealthcareAgent() {
     title: "Schedule an Appointment",
     description: "Helps the patient find a time for their appointment.",
     conditions: ["The patient wants to schedule an appointment"],
+    // Route-level identity for healthcare scheduling
+    identity:
+      "You are a compassionate healthcare scheduling assistant who helps patients book appointments. Be empathetic, prioritize urgent cases, and ensure patients feel supported throughout the process.",
+    // Healthcare-specific terms
+    terms: [
+      {
+        name: "HIPAA",
+        description:
+          "Health Insurance Portability and Accountability Act - protects patient privacy and medical records",
+      },
+      {
+        name: "PHI",
+        description:
+          "Protected Health Information - any medical data that can identify a patient",
+      },
+      {
+        name: "Telemedicine",
+        description: "Remote healthcare consultation via video call or phone",
+      },
+    ],
     schema: {
       type: "object",
       properties: {
@@ -171,74 +258,73 @@ async function createHealthcareAgent() {
 
   // Step 1: Collect appointment reason
   const collectReason = schedulingRoute.initialStep.nextStep({
-    instructions: "Ask what the patient needs an appointment for",
+    prompt: "Ask what the patient needs an appointment for",
     collect: ["appointmentReason"],
     skipIf: (data) => !!data.appointmentReason,
-    condition: "Patient hasn't specified reason for appointment yet",
+    when: "Patient hasn't specified reason for appointment yet",
   });
 
   // Step 2: Check urgency and show available slots
   const checkUrgency = collectReason.nextStep({
-    instructions: "Check if this is urgent and show available slots",
+    prompt: "Check if this is urgent and show available slots",
     collect: ["urgency"],
     skipIf: (data) => !!data.urgency,
     requires: ["appointmentReason"],
-    condition: "Reason provided, now assess urgency level",
+    when: "Reason provided, now assess urgency level",
   });
 
   const showSlots = checkUrgency.nextStep({
-    tool: getUpcomingSlots,
+    tools: [getUpcomingSlots],
   });
 
   // Step 3: Present available times
   const presentTimes = showSlots.nextStep({
-    instructions: "List available times and ask which one works for them",
+    prompt: "List available times and ask which one works for them",
   });
 
   // Step 4: Collect preferred time and date
   const collectPreferences = presentTimes.nextStep({
-    instructions: "Collect preferred time and date",
+    prompt: "Collect preferred time and date",
     collect: ["preferredTime", "preferredDate"],
     skipIf: (data) => !!data.preferredTime && !!data.preferredDate,
   });
 
   // Step 5: Confirm details and schedule
   const confirmDetails = collectPreferences.nextStep({
-    instructions: "Confirm the details with the patient before scheduling",
+    prompt: "Confirm the details with the patient before scheduling",
     collect: ["appointmentType"],
     skipIf: (data) => !!data.appointmentType,
     requires: ["appointmentReason", "preferredTime", "preferredDate"],
   });
 
   const schedule = confirmDetails.nextStep({
-    tool: scheduleAppointment,
+    tools: [scheduleAppointment],
     requires: ["appointmentReason", "preferredTime", "preferredDate"],
-    condition: "All details confirmed, book the appointment",
+    when: "All details confirmed, book the appointment",
   });
 
   const confirmation = schedule.nextStep({
-    instructions: "Confirm the appointment has been scheduled",
+    prompt: "Confirm the appointment has been scheduled",
   });
 
   confirmation.nextStep({
     step: END_ROUTE,
-    condition: "Appointment booked successfully",
+    when: "Appointment booked successfully",
   });
 
   // Alternative path: no times work - show later slots
   const laterSlots = presentTimes.nextStep({
-    tool: getLaterSlots,
+    tools: [getLaterSlots],
   });
 
   laterSlots.nextStep({
-    instructions: "List later times and ask if any of them works",
+    prompt: "List later times and ask if any of them works",
   });
 
   // If no times work at all, end route
   laterSlots
     .nextStep({
-      instructions:
-        "Ask the patient to call the office to schedule an appointment",
+      prompt: "Ask the patient to call the office to schedule an appointment",
     })
     .nextStep({ step: END_ROUTE });
 
@@ -275,14 +361,14 @@ async function createHealthcareAgent() {
 
   // Step 1: Collect test information
   const collectTestInfo = labResultsRoute.initialStep.nextStep({
-    instructions: "Ask what type of test results they want to see",
+    prompt: "Ask what type of test results they want to see",
     collect: ["testType"],
     skipIf: (data) => !!data.testType,
   });
 
   // Step 2: Optional: collect test date
   const collectTestDate = collectTestInfo.nextStep({
-    instructions: "Ask for the test date if they remember it",
+    prompt: "Ask for the test date if they remember it",
     collect: ["testDate"],
     skipIf: (data) => !!data.testDate,
     requires: ["testType"],
@@ -290,13 +376,13 @@ async function createHealthcareAgent() {
 
   // Step 3: Get lab results
   const getResults = collectTestDate.nextStep({
-    tool: getLabResults,
+    tools: [getLabResults],
     requires: ["testType"],
   });
 
   // Step 4: Present results based on status
   const presentResults = getResults.nextStep({
-    instructions: "Present the lab results and explain what they mean",
+    prompt: "Present the lab results and explain what they mean",
   });
 
   presentResults.nextStep({ step: END_ROUTE });
@@ -313,6 +399,33 @@ async function createHealthcareAgent() {
     title: "Satisfaction Survey",
     description: "Quick satisfaction survey after scheduling",
     conditions: ["Collect patient satisfaction feedback"],
+
+    // Route-specific knowledge base for patient feedback
+    knowledgeBase: {
+      surveyBestPractices: [
+        "Keep surveys short (3-5 questions maximum)",
+        "Use clear rating scales (1-5 stars)",
+        "Ask specific questions about what can be improved",
+        "Always thank patients for their feedback",
+        "Follow up on critical feedback within 24 hours",
+      ],
+      commonFeedbackThemes: {
+        positive: ["Friendly staff", "Quick response", "Easy scheduling"],
+        improvement: ["Wait times", "Communication", "Facility cleanliness"],
+        urgent: ["Medical errors", "Billing issues", "Privacy concerns"],
+      },
+      npsCalculation: {
+        promoters: "9-10 rating",
+        passives: "7-8 rating",
+        detractors: "0-6 rating",
+        formula: "(Promoters - Detractors) / Total Responses * 100",
+      },
+      followUpActions: {
+        critical: "Immediate review by practice manager",
+        improvement: "Add to quarterly improvement plan",
+        positive: "Share with staff as recognition",
+      },
+    },
     schema: {
       type: "object",
       properties: {
@@ -334,20 +447,19 @@ async function createHealthcareAgent() {
   });
 
   const askRating = satisfactionRoute.initialStep.nextStep({
-    instructions:
+    prompt:
       "Ask for overall satisfaction rating from 1 to 5 with the scheduling experience",
     collect: ["rating"],
     skipIf: (data) => !!data.rating,
   });
 
   const askComments = askRating.nextStep({
-    instructions:
-      "Ask if they have any additional comments or feedback (optional)",
+    prompt: "Ask if they have any additional comments or feedback (optional)",
     collect: ["comments"],
   });
 
   const thankYou = askComments.nextStep({
-    instructions:
+    prompt:
       "Thank them for their feedback and confirm their appointment details one more time",
   });
 
@@ -358,7 +470,6 @@ async function createHealthcareAgent() {
     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],
   });
 
   agent.createGuideline({
@@ -378,18 +489,10 @@ async function createHealthcareAgent() {
 
 // Example usage with session step management
 async function main() {
-  const agent = await createHealthcareAgent();
+  const agent = createHealthcareAgent();
 
-  // Initialize session step for multi-turn conversation
-  let session = createSession<AppointmentData | LabResultsData>();
-
-  const history = [
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "Patient",
-      "Hi, I need to follow up on my visit"
-    ),
-  ];
+  // Session is automatically managed by the agent
+  console.log("✨ Session ready:", agent.session.id);
 
   console.log("Agent:", agent.name);
   console.log("Description:", agent.description);
@@ -403,29 +506,32 @@ async function main() {
     console.log("\n" + route.describe());
   }
 
-  // Example conversation with session step
+  // Example conversation with session management
   console.log("\n=== EXAMPLE CONVERSATION ===");
 
   // Turn 1: Patient wants to follow up
-  const response1 = await agent.respond({ history, session });
+  await agent.session.addMessage("user", "Hi, I need to follow up on my visit", "Patient");
+  
+  const response1 = await agent.respond({ 
+    history: agent.session.getHistory() 
+  });
+  
   console.log("Patient: Hi, I need to follow up on my visit");
   console.log("Agent:", response1.message);
   console.log("Route:", response1.session?.currentRoute?.title);
-  console.log("Data:", response1.session?.data);
+  console.log("Data:", agent.session.getData<AppointmentData | LabResultsData>());
 
-  // Update session with progress
-  session = response1.session!;
+  await agent.session.addMessage("assistant", response1.message);
 
   // Turn 2: Patient specifies they want to schedule an appointment
   if (response1.session?.currentRoute?.title === "Schedule an Appointment") {
     const history2 = [
       ...history,
-      createMessageEvent(EventSource.AI_AGENT, "Agent", response1.message),
-      createMessageEvent(
-        EventSource.CUSTOMER,
-        "Patient",
-        "I need to schedule a checkup for next week"
-      ),
+      {
+        role: "user" as const,
+        content: "I need to schedule a checkup for next week",
+        name: "Patient",
+      },
     ];
 
     const response2 = await agent.respond({ history: history2, session });
@@ -450,12 +556,11 @@ async function main() {
     // Turn 3: Patient provides final details
     const history3 = [
       ...history2,
-      createMessageEvent(EventSource.AI_AGENT, "Agent", response2.message),
-      createMessageEvent(
-        EventSource.CUSTOMER,
-        "Patient",
-        "Tuesday at 2 PM works for me."
-      ),
+      {
+        role: "user" as const,
+        content: "Tuesday at 2 PM works for me.",
+        name: "Patient",
+      },
     ];
 
     const response3 = await agent.respond({ history: history3, session });
@@ -490,22 +595,10 @@ async function sendAppointmentReminder(data: AppointmentData) {
   console.log("✨ Reminder sent!");
 }
 
-/**
- * Mock function to log a patient inquiry about lab results.
- * @param data - The lab results data.
- */
-async function logPatientInquiry(data: LabResultsData) {
-  console.log("\n" + "=".repeat(60));
-  console.log("📝 Logging Patient Inquiry...");
-  console.log("=".repeat(60));
-  console.log("Inquiry Details:", JSON.stringify(data, null, 2));
-  console.log(`   - Logging inquiry for ${data.testType} results.`);
-  await new Promise((resolve) => setTimeout(resolve, 1000));
-  console.log("✨ Inquiry logged!");
-}
-
 if (import.meta.url === `file://${process.argv[1]}`) {
   main().catch(console.error);
 }
 
 export { createHealthcareAgent };
+
+main().catch(console.error);