@falai/agent 0.4.1 → 0.5.1

package/examples/declarative-agent.ts

@@ -1,14 +1,13 @@
 /**
- * Example: Declarative Agent Configuration
+ * Example: Declarative Agent Configuration with Session State
  *
  * This example demonstrates how to configure an entire agent
  * using declarative syntax in the constructor, including:
  * - Terms (glossary)
  * - Guidelines (behavior rules)
  * - Capabilities
- * - Routes with nested guidelines and custom IDs
- * - Observations with route references and custom IDs
- * - Custom timestamps for events
+ * - Routes with data extraction schemas and custom IDs
+ * - Session state management for multi-turn conversations
  */
 
 import {
@@ -17,11 +16,11 @@ import {
   createMessageEvent,
   EventSource,
   GeminiProvider,
+  createSession,
   type Term,
   type Guideline,
   type Capability,
   type RouteOptions,
-  type ObservationOptions,
 } from "../src/index";
 
 // Context type
@@ -30,6 +29,21 @@ interface HealthcareContext {
   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 with custom IDs (optional - IDs are deterministic by default)
 const getInsuranceProviders = defineTool<HealthcareContext, [], string[]>(
   "get_insurance_providers",
@@ -69,7 +83,18 @@ const getLabResults = defineTool<
   { report: string; status: string }
 >(
   "get_lab_results",
-  async ({ context }) => {
+  async ({ context, extracted }) => {
+    // Tools can now access extracted data
+    const labData = extracted as Partial<LabData>;
+    if (labData?.testType) {
+      return {
+        data: {
+          report: `${labData.testType} results for ${context.patientName}`,
+          status: "All values within normal range",
+        },
+      };
+    }
+
     return {
       data: {
         report: `Lab results for ${context.patientName}`,
@@ -83,6 +108,31 @@ const getLabResults = defineTool<
   }
 );
 
+const scheduleAppointment = defineTool<
+  HealthcareContext,
+  [],
+  { confirmation: string }
+>(
+  "schedule_appointment",
+  async ({ context, extracted }) => {
+    // Tools can access extracted appointment data
+    const appointment = extracted as Partial<AppointmentData>;
+    if (!appointment?.preferredDate || !appointment?.preferredTime) {
+      return { data: { confirmation: "Please provide appointment details" } };
+    }
+
+    return {
+      data: {
+        confirmation: `Appointment scheduled for ${appointment.preferredDate} at ${appointment.preferredTime}`,
+      },
+    };
+  },
+  {
+    id: "healthcare_schedule_appointment",
+    description: "Schedules patient appointments",
+  }
+);
+
 // Declarative configuration
 const terms: Term[] = [
   {
@@ -140,6 +190,34 @@ const routes: RouteOptions[] = [
     title: "Schedule Appointment",
     description: "Helps the patient schedule an appointment",
     conditions: ["The patient wants to schedule an appointment"],
+    gatherSchema: {
+      type: "object",
+      properties: {
+        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",
+        },
+      },
+      required: ["appointmentType", "preferredDate", "preferredTime"],
+    },
     guidelines: [
       {
         condition: "The patient says their visit is urgent",
@@ -154,6 +232,25 @@ const routes: RouteOptions[] = [
     title: "Check Lab Results",
     description: "Retrieves and explains patient lab results",
     conditions: ["The patient wants to see their lab results"],
+    gatherSchema: {
+      type: "object",
+      properties: {
+        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",
+        },
+      },
+      required: ["testType"],
+    },
     guidelines: [
       {
         condition: "The patient presses for more conclusions about results",
@@ -163,14 +260,11 @@ 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
+    title: "General Healthcare Questions",
+    description: "Answer general healthcare questions",
+    conditions: ["Patient asks general healthcare questions"],
+    // No gatherSchema - stateless Q&A
   },
 ];
 
@@ -192,7 +286,6 @@ const agent = new Agent<HealthcareContext>({
   guidelines,
   capabilities,
   routes,
-  observations,
 });
 
 // You can still add more dynamically after construction
@@ -208,31 +301,55 @@ agent
     synonyms: ["virtual visit", "video appointment"],
   });
 
-// Example usage
+// Example usage with session state
 async function main() {
+  // Initialize session state
+  let session = createSession<AppointmentData | LabData>();
+
   // 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",
-      "2025-10-13T14:30:00Z" // Optional custom timestamp
+      "Hi, I need to follow up on my recent visit"
     ),
   ];
 
-  const response = await agent.respond({ history });
+  // Turn 1 - Agent responds and extracts intent
+  const response = await agent.respond({ history, session });
   console.log("Agent:", response.message);
-  console.log("Route chosen:", response.route?.title);
-  console.log("Route ID:", response.route?.id); // Custom ID is preserved
+  console.log("Route chosen:", response.session?.currentRoute?.title);
+  console.log("Extracted data:", response.session?.extracted);
+
+  // Session state is updated with progress
+  session = response.session!;
 
-  // The agent will use the observation to disambiguate
-  // and ask which type of follow-up the patient needs
+  // Turn 2 - Continue conversation with session state
+  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: history2, session });
+    console.log("Agent:", response2.message);
+    console.log("Updated extracted:", response2.session?.extracted);
+
+    // Session tracks the appointment booking progress
+    console.log("Current state:", response2.session?.currentState?.id);
+  }
 
   // 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
+  // Session state enables:
+  // - Tracking conversation progress across turns
+  // - Extracting structured data throughout conversation
+  // - Always-on routing that respects user intent changes
+  // - State recovery for resuming conversations
 }
 
 // Uncomment to run:

package/examples/domain-scoping.ts

@@ -1,5 +1,6 @@
 /**
  * Domain Scoping Example
+ * Updated for v2 architecture with session state management
  *
  * This example demonstrates how to use domain scoping to restrict which tools
  * can EXECUTE in different conversation routes for security and isolation.
@@ -11,7 +12,12 @@
  * execute automatically when triggered by the state machine or guidelines.
  */
 
-import { Agent, createMessageEvent, EventSource } from "../src/index";
+import {
+  Agent,
+  createMessageEvent,
+  EventSource,
+  createSession,
+} from "../src/index";
 import { OpenRouterProvider } from "../src/providers";
 
 // Initialize AI provider
@@ -138,11 +144,17 @@ async function demonstrateScoping() {
     ),
   ];
 
-  const response1 = await agent.respond({ history: history1 });
-  console.log(`Route chosen: ${response1.route?.title}`);
+  // Initialize session state for multi-turn conversation
+  let session = createSession();
+
+  const response1 = await agent.respond({ history: history1, session });
+  console.log(`Route chosen: ${response1.session?.currentRoute?.title}`);
   console.log(`Available tools in this route: scraping only`);
   console.log(`Response: ${response1.message}\n`);
 
+  // Update session with progress
+  session = response1.session!;
+
   // Example 2: Schedule Meeting route - only calendar tools available
   console.log("2️⃣  Example: User wants to schedule a meeting");
   const history2 = [
@@ -153,11 +165,14 @@ async function demonstrateScoping() {
     ),
   ];
 
-  const response2 = await agent.respond({ history: history2 });
-  console.log(`Route chosen: ${response2.route?.title}`);
+  const response2 = await agent.respond({ history: history2, session });
+  console.log(`Route chosen: ${response2.session?.currentRoute?.title}`);
   console.log(`Available tools in this route: calendar only`);
   console.log(`Response: ${response2.message}\n`);
 
+  // Update session again
+  session = response2.session!;
+
   // Example 3: Customer Support route - NO tools available
   console.log("3️⃣  Example: User has a general question");
   const history3 = [
@@ -168,11 +183,14 @@ async function demonstrateScoping() {
     ),
   ];
 
-  const response3 = await agent.respond({ history: history3 });
-  console.log(`Route chosen: ${response3.route?.title}`);
+  const response3 = await agent.respond({ history: history3, session });
+  console.log(`Route chosen: ${response3.session?.currentRoute?.title}`);
   console.log(`Available tools in this route: none (conversation only)`);
   console.log(`Response: ${response3.message}\n`);
 
+  // Update session again
+  session = response3.session!;
+
   // Example 4: Admin Support route - ALL tools available (for demo purposes)
   console.log("4️⃣  Example: Admin needs full access");
   const history4 = [
@@ -183,30 +201,33 @@ async function demonstrateScoping() {
     ),
   ];
 
-  const response4 = await agent.respond({ history: history4 });
-  console.log(`Route chosen: ${response4.route?.title}`);
+  const response4 = await agent.respond({ history: history4, session });
+  console.log(`Route chosen: ${response4.session?.currentRoute?.title}`);
   console.log(`Available tools in this route: all domains`);
   console.log(`Response: ${response4.message}\n`);
 }
 
 // Benefits demonstration
 console.log(`
-🔒 Security Benefits:
+🔒 Security Benefits (V2 Architecture):
 - Customer Support route cannot execute payment.processPayment()
 - Data Collection route cannot execute calendar.scheduleEvent()
 - Each route has minimum necessary tool permissions
 - Prevents prompt injection attacks from calling sensitive tools
+- Session state ensures domain scoping persists across turns
 
 🎯 Isolation Benefits:
 - Route execution is isolated - tools can't cross boundaries
 - Checkout can't accidentally trigger admin operations
 - Clear separation of concerns by capability
+- Always-on routing maintains domain restrictions
 
 📋 Clarity Benefits:
 - Routes clearly document their capabilities
 - Easy to audit what each route can execute
 - Better debugging when tools are called
 - Self-documenting security model
+- Session state tracks domain-scoped conversations
 `);
 
 // Inspect route configurations