@falai/agent 0.4.1 → 0.5.1

package/examples/streaming-agent.ts

@@ -1,5 +1,6 @@
 /**
  * Example: Streaming Responses
+ * Updated for v2 architecture with session state management
  *
  * This example demonstrates how to use the respondStream method
  * to stream AI responses in real-time for better user experience
@@ -12,6 +13,7 @@ import {
   AnthropicProvider,
   OpenAIProvider,
   GeminiProvider,
+  createSession,
 } from "../src/index";
 
 // Custom context type
@@ -70,9 +72,12 @@ async function streamingWithAnthropic() {
     console.log("📤 Streaming response from Claude...\n");
     console.log("Response: ");
 
-    // Use respondStream for real-time streaming
+    // Initialize session state for streaming conversation
+    let session = createSession();
+
+    // Use respondStream for real-time streaming with session state
     let fullMessage = "";
-    for await (const chunk of agent.respondStream({ history })) {
+    for await (const chunk of agent.respondStream({ history, session })) {
       // chunk.delta contains the new text
       // chunk.accumulated contains the full text so far
       // chunk.done indicates if this is the final chunk
@@ -85,9 +90,14 @@ async function streamingWithAnthropic() {
       if (chunk.done) {
         console.log("\n\n✅ Stream complete!");
         console.log(`\n📊 Metadata:`);
-        console.log(`   - Route: ${chunk.route?.title || "None"}`);
-        console.log(`   - State: ${chunk.state?.description || "None"}`);
+        console.log(
+          `   - Route: ${chunk.session?.currentRoute?.title || "None"}`
+        );
+        console.log(`   - Extracted:`, chunk.session?.extracted || "None");
         console.log(`   - Tool Calls: ${chunk.toolCalls?.length || 0}`);
+
+        // Update session with progress
+        session = chunk.session!;
       }
     }
   } catch (error) {
@@ -131,13 +141,23 @@ async function streamingWithOpenAI() {
     console.log("📤 Streaming response from OpenAI...\n");
     console.log("Response: ");
 
-    for await (const chunk of agent.respondStream({ history })) {
+    // Initialize session state for streaming conversation
+    let session = createSession();
+
+    for await (const chunk of agent.respondStream({ history, session })) {
       if (chunk.delta) {
         process.stdout.write(chunk.delta);
       }
 
       if (chunk.done) {
         console.log("\n\n✅ Stream complete!");
+        console.log(
+          `   - Route: ${chunk.session?.currentRoute?.title || "None"}`
+        );
+        console.log(`   - Extracted:`, chunk.session?.extracted || "None");
+
+        // Update session with progress
+        session = chunk.session!;
       }
     }
   } catch (error) {
@@ -181,13 +201,23 @@ async function streamingWithGemini() {
     console.log("📤 Streaming response from Gemini...\n");
     console.log("Response: ");
 
-    for await (const chunk of agent.respondStream({ history })) {
+    // Initialize session state for streaming conversation
+    let session = createSession();
+
+    for await (const chunk of agent.respondStream({ history, session })) {
       if (chunk.delta) {
         process.stdout.write(chunk.delta);
       }
 
       if (chunk.done) {
         console.log("\n\n✅ Stream complete!");
+        console.log(
+          `   - Route: ${chunk.session?.currentRoute?.title || "None"}`
+        );
+        console.log(`   - Extracted:`, chunk.session?.extracted || "None");
+
+        // Update session with progress
+        session = chunk.session!;
       }
     }
   } catch (error) {
@@ -239,19 +269,24 @@ async function streamingWithRoutes() {
     console.log("📤 Streaming response with route detection...\n");
     console.log("Response: ");
 
-    for await (const chunk of agent.respondStream({ history })) {
+    // Initialize session state for streaming conversation
+    let session = createSession();
+
+    for await (const chunk of agent.respondStream({ history, session })) {
       if (chunk.delta) {
         process.stdout.write(chunk.delta);
       }
 
       if (chunk.done) {
         console.log("\n\n✅ Stream complete!");
-        if (chunk.route) {
-          console.log(`\n🗺️  Route detected: ${chunk.route.title}`);
-        }
-        if (chunk.state) {
-          console.log(`📍 State: ${chunk.state.description}`);
-        }
+        console.log(`\n📊 Metadata:`);
+        console.log(
+          `   - Route: ${chunk.session?.currentRoute?.title || "None"}`
+        );
+        console.log(`   - Extracted:`, chunk.session?.extracted || "None");
+
+        // Update session with progress
+        session = chunk.session!;
       }
     }
   } catch (error) {
@@ -301,8 +336,12 @@ async function streamingWithAbortSignal() {
     console.log("📤 Streaming response (will abort after 3s)...\n");
     console.log("Response: ");
 
+    // Initialize session state for streaming conversation
+    let session = createSession();
+
     for await (const chunk of agent.respondStream({
       history,
+      session,
       signal: abortController.signal,
     })) {
       if (chunk.delta) {
@@ -311,6 +350,15 @@ async function streamingWithAbortSignal() {
 
       if (chunk.done) {
         console.log("\n\n✅ Stream complete!");
+        console.log(`\n📊 Metadata:`);
+        console.log(
+          `   - Route: ${chunk.session?.currentRoute?.title || "None"}`
+        );
+        console.log(`   - Extracted:`, chunk.session?.extracted || "None");
+
+        // Update session with progress
+        session = chunk.session!;
+
         clearTimeout(timeout);
       }
     }

package/examples/travel-agent.ts

@@ -1,6 +1,6 @@
 /**
- * Travel agent example (abridged from Python version)
- * Demonstrates route DSL, tools, and guidelines
+ * Travel agent example with session state management
+ * Demonstrates data-driven conversations with schema extraction and state progression
  */
 
 import {
@@ -10,6 +10,8 @@ import {
   END_ROUTE,
   EventSource,
   createMessageEvent,
+  createSession,
+  type ToolContext,
 } from "../src/index";
 
 // Context type for travel agent
@@ -18,10 +20,27 @@ interface TravelContext {
   customerName: string;
 }
 
-// Tools
-const getAvailableDestinations = defineTool<TravelContext, [], string[]>(
+// Data extraction types for travel booking
+interface FlightBookingData {
+  destination: string;
+  destinationCode?: string; // Enriched by tools
+  departureDate: string;
+  returnDate?: string;
+  passengers: number;
+  cabinClass: "economy" | "business" | "first";
+  urgency: "low" | "medium" | "high";
+  shouldSearchFlights?: boolean; // Action flag
+}
+
+interface BookingStatusData {
+  confirmationNumber: string;
+  email?: string;
+}
+
+// Tools with data access
+const getAvailableDestinations = defineTool(
   "get_available_destinations",
-  async () => {
+  async ({ context }: ToolContext<TravelContext>) => {
     return {
       data: [
         "Paris, France",
@@ -36,78 +55,124 @@ const getAvailableDestinations = defineTool<TravelContext, [], string[]>(
   }
 );
 
-const getAvailableFlights = defineTool<
-  TravelContext,
-  [destination: string],
-  string[]
->(
-  "get_available_flights",
-  async (_context, destination) => {
+const lookupDestinationCode = defineTool(
+  "lookup_destination_code",
+  async ({
+    context,
+    extracted,
+  }: ToolContext<TravelContext, FlightBookingData>) => {
+    if (!extracted?.destination) {
+      return { data: undefined };
+    }
+
+    // Simulate airport code lookup
+    const codes: Record<string, string> = {
+      "Paris, France": "CDG",
+      "Tokyo, Japan": "NRT",
+      "Bali, Indonesia": "DPS",
+      "New York, USA": "JFK",
+    };
+
     return {
-      data: [
-        "Flight 123 - June 15, 9:00 AM, $850",
-        "Flight 321 - June 16, 2:30 PM, $720",
-        "Flight 987 - June 17, 6:45 PM, $680",
-      ],
+      data: undefined,
+      extractedUpdate: {
+        destinationCode: codes[extracted.destination],
+      },
     };
   },
   {
-    description: "Get available flights for a destination",
+    description: "Convert destination name to airport code",
   }
 );
 
-const getAlternativeFlights = defineTool<
-  TravelContext,
-  [destination: string],
-  string[]
->(
-  "get_alternative_flights",
-  async (_context, destination) => {
+const searchFlights = defineTool(
+  "search_flights",
+  async ({
+    context,
+    extracted,
+  }: ToolContext<TravelContext, FlightBookingData>) => {
+    if (!extracted?.destination || !extracted?.departureDate) {
+      return { data: [] };
+    }
+
+    // Simulate flight search based on extracted data
+    const flights = [
+      `Flight 123 - ${extracted.departureDate}, 9:00 AM, $${
+        800 + Math.floor(Math.random() * 200)
+      }`,
+      `Flight 321 - ${extracted.departureDate}, 2:30 PM, $${
+        700 + Math.floor(Math.random() * 200)
+      }`,
+      `Flight 987 - ${extracted.departureDate}, 6:45 PM, $${
+        600 + Math.floor(Math.random() * 200)
+      }`,
+    ];
+
     return {
-      data: [
-        "Flight 485 - June 25, 11:00 AM, $920",
-        "Flight 516 - July 2, 4:15 PM, $780",
-      ],
+      data: flights,
+      extractedUpdate: {
+        shouldSearchFlights: false, // Clear the flag
+      },
     };
   },
   {
-    description: "Get alternative flight options with different dates",
+    description: "Search for flights based on extracted travel data",
   }
 );
 
-const bookFlight = defineTool<TravelContext, [flightDetails: string], string>(
+const bookFlight = defineTool(
   "book_flight",
-  async ({ context }, flightDetails) => {
+  async ({
+    context,
+    extracted,
+  }: ToolContext<TravelContext, FlightBookingData>) => {
+    if (!extracted) {
+      return { data: "Please provide flight details" };
+    }
+
     const confirmationNumber = `TRV-${new Date()
       .toISOString()
       .slice(0, 10)
       .replace(/-/g, "")}-001`;
+
     return {
-      data: `Flight booked: ${flightDetails} for ${context.customerName}. Confirmation number: ${confirmationNumber}`,
+      data: `Flight booked for ${context.customerName} to ${extracted.destination}. Confirmation: ${confirmationNumber}`,
     };
   },
   {
-    description: "Book a flight with the provided details",
+    description: "Book a flight using extracted travel data",
   }
 );
 
 const getBookingStatus = defineTool<
   TravelContext,
-  [confirmationNumber: string],
-  object
+  [],
+  { status: string; details: string; notes?: string }
 >(
   "get_booking_status",
-  async (_context, confirmationNumber) => {
+  async ({
+    context,
+    extracted,
+  }: ToolContext<TravelContext, BookingStatusData>) => {
+    if (!extracted?.confirmationNumber) {
+      return {
+        data: {
+          status: "Error",
+          details: "Please provide a confirmation number",
+        },
+      };
+    }
+
     return {
       data: {
         status: "Confirmed",
-        details: "Flight to Paris on June 15, 9:00 AM. Seat 12A assigned.",
+        details: `Flight booking ${extracted.confirmationNumber} is confirmed.`,
         notes: "Check-in opens 24 hours before departure.",
       },
     };
   },
   {
-    description: "Get booking status by confirmation number",
+    description: "Get booking status using extracted confirmation number",
   }
 );
 
@@ -152,83 +217,108 @@ async function createTravelAgent() {
     synonyms: ["insurance", "trip protection", "travel protection"],
   });
 
-  // Create flight booking route
-  const flightBookingRoute = agent.createRoute({
+  // Create flight booking route with data extraction
+  const flightBookingRoute = agent.createRoute<FlightBookingData>({
     title: "Book a Flight",
     description:
       "Helps the customer find and book a flight to their desired destination.",
     conditions: ["The customer wants to book a flight"],
+    gatherSchema: {
+      type: "object",
+      properties: {
+        destination: {
+          type: "string",
+          description: "Travel destination",
+        },
+        destinationCode: {
+          type: "string",
+          description: "Airport code (enriched by tool)",
+        },
+        departureDate: {
+          type: "string",
+          description: "Departure date",
+        },
+        returnDate: {
+          type: "string",
+          description: "Return date (optional)",
+        },
+        passengers: {
+          type: "number",
+          minimum: 1,
+          maximum: 9,
+          description: "Number of passengers",
+        },
+        cabinClass: {
+          type: "string",
+          enum: ["economy", "business", "first"],
+          default: "economy",
+          description: "Cabin class preference",
+        },
+        urgency: {
+          type: "string",
+          enum: ["low", "medium", "high"],
+          default: "medium",
+          description: "Travel urgency level",
+        },
+        shouldSearchFlights: {
+          type: "boolean",
+          description: "Flag to trigger flight search",
+        },
+      },
+      required: ["destination", "departureDate", "passengers"],
+    },
   });
 
-  // Build the route flow
-  const t0 = flightBookingRoute.initialState.transitionTo({
+  // Build the route flow with data extraction and smart state progression
+  const askDestination = flightBookingRoute.initialState.transitionTo({
     chatState: "Ask about the destination",
+    gather: ["destination"],
+    skipIf: (extracted) => !!extracted.destination,
+  });
+
+  const enrichDestination = askDestination.transitionTo({
+    toolState: lookupDestinationCode,
+    requiredData: ["destination"],
   });
 
-  const t1 = t0.transitionTo({
+  const askDates = enrichDestination.transitionTo({
     chatState: "Ask about preferred travel dates",
+    gather: ["departureDate"],
+    skipIf: (extracted) => !!extracted.departureDate,
+    requiredData: ["destination"],
   });
 
-  const t2 = t1.transitionTo({
-    toolState: getAvailableFlights,
+  const askPassengers = askDates.transitionTo({
+    chatState: "Ask for number of passengers",
+    gather: ["passengers"],
+    skipIf: (extracted) => !!extracted.passengers,
+    requiredData: ["destination", "departureDate"],
   });
 
-  const t3 = t2.transitionTo({
+  const searchFlightsState = askPassengers.transitionTo({
+    toolState: searchFlights,
+    // Triggered when shouldSearchFlights flag is set by hook
+  });
+
+  const presentFlights = searchFlightsState.transitionTo({
     chatState: "Present available flights and ask which one works for them",
   });
 
   // Happy path: customer selects a flight
-  const t4 = t3.transitionTo(
-    {
-      chatState:
-        "Collect passenger information and confirm booking details before proceeding",
-    },
-    "The customer selects a flight"
-  );
-
-  const t5 = t4.transitionTo(
-    {
-      toolState: bookFlight,
-    },
-    "The customer confirms the booking details"
-  );
-
-  const t6 = t5.transitionTo({
-    chatState: "Provide confirmation number and booking summary",
+  const confirmBooking = presentFlights.transitionTo({
+    chatState: "Confirm booking details before proceeding",
+    gather: ["cabinClass", "urgency"], // Additional optional data
   });
 
-  t6.transitionTo({ state: END_ROUTE });
-
-  // Alternative path: no flights work
-  const t7 = t3.transitionTo(
-    {
-      toolState: getAlternativeFlights,
-    },
-    "None of the flights work for the customer"
-  );
-
-  const t8 = t7.transitionTo({
-    chatState: "Present alternative flights and ask if any work",
+  const bookFlightState = confirmBooking.transitionTo({
+    toolState: bookFlight,
   });
 
-  // Link back to happy path
-  t8.transitionTo(
-    {
-      state: t4,
-    },
-    "The customer selects a flight"
-  );
-
-  // No alternative flights work either
-  const t9 = t8.transitionTo(
-    {
-      chatState:
-        "Suggest calling our office or visiting our website for more options",
-    },
-    "None of the alternative flights work either"
-  );
+  const provideConfirmation = bookFlightState.transitionTo({
+    chatState: "Provide confirmation number and booking summary",
+  });
 
-  t9.transitionTo({ state: END_ROUTE });
+  provideConfirmation.transitionTo({ state: END_ROUTE });
 
   // Add route-specific guidelines
   flightBookingRoute.createGuideline({
@@ -244,45 +334,44 @@ async function createTravelAgent() {
       "Inform them that visa requirements vary by destination and nationality, and suggest they check with the embassy or consulate",
   });
 
-  // Create booking status route
-  const bookingStatusRoute = agent.createRoute({
+  // Create booking status route with data extraction
+  const bookingStatusRoute = agent.createRoute<BookingStatusData>({
     title: "Check Booking Status",
     description:
       "Retrieves the customer's booking status and provides relevant information.",
     conditions: ["The customer wants to check their booking status"],
+    gatherSchema: {
+      type: "object",
+      properties: {
+        confirmationNumber: {
+          type: "string",
+          description: "Booking confirmation number",
+        },
+        email: {
+          type: "string",
+          description: "Email address associated with booking (optional)",
+        },
+      },
+      required: ["confirmationNumber"],
+    },
   });
 
-  const s0 = bookingStatusRoute.initialState.transitionTo({
+  const askConfirmation = bookingStatusRoute.initialState.transitionTo({
     chatState: "Ask for the confirmation number or booking reference",
+    gather: ["confirmationNumber"],
+    skipIf: (extracted) => !!extracted.confirmationNumber,
   });
 
-  const s1 = s0.transitionTo({
+  const checkStatus = askConfirmation.transitionTo({
     toolState: getBookingStatus,
+    requiredData: ["confirmationNumber"],
   });
 
-  s1.transitionTo(
-    {
-      chatState:
-        "Tell the customer that the booking could not be found and ask them to verify the confirmation number or call the office",
-    },
-    "The booking could not be found"
-  );
-
-  s1.transitionTo(
-    {
-      chatState:
-        "Provide the booking details and confirm everything is in order",
-    },
-    "The booking is confirmed and all details are correct"
-  );
+  const provideStatus = checkStatus.transitionTo({
+    chatState: "Provide booking status and relevant information",
+  });
 
-  s1.transitionTo(
-    {
-      chatState:
-        "Present the booking information and mention any issues or pending actions required",
-    },
-    "The booking has issues or requires customer action"
-  );
+  provideStatus.transitionTo({ state: END_ROUTE });
 
   // Global guidelines
   agent.createGuideline({
@@ -307,34 +396,78 @@ async function createTravelAgent() {
   return agent;
 }
 
-// Example usage
+// Example usage with session state
 async function main() {
   const agent = await createTravelAgent();
 
+  // Initialize session state
+  let session = createSession<FlightBookingData | BookingStatusData>();
+
   // Simulate a conversation
   const history = [
     createMessageEvent(
       EventSource.CUSTOMER,
-      "Customer",
-      "Hi, I want to book a flight to Paris"
+      "Alice",
+      "Hi, I want to book a flight to Paris next week with 2 passengers"
     ),
   ];
 
   console.log("Agent:", agent.name);
   console.log("Description:", agent.description);
-  console.log("\nRoutes:", agent.getRoutes().length);
-  console.log("Terms:", agent.getTerms().length);
-  console.log("Guidelines:", agent.getGuidelines().length);
-
-  // Print route structure
-  const routes = agent.getRoutes();
-  for (const route of routes) {
-    console.log("\n" + route.describe());
+
+  // Turn 1 - Agent extracts data and starts booking flow
+  const response1 = await agent.respond({ history, session });
+  console.log("\n=== TURN 1 ===");
+  console.log("Agent:", response1.message);
+  console.log("Route:", response1.session?.currentRoute?.title);
+  console.log("State:", response1.session?.currentState?.id);
+  console.log("Extracted:", response1.session?.extracted);
+
+  // Session state updated with progress
+  session = response1.session!;
+
+  // Turn 2 - Continue with session state
+  if (response1.session?.currentRoute?.title === "Book a Flight") {
+    const history2 = [
+      ...history,
+      createMessageEvent(EventSource.AI_AGENT, "Agent", response1.message),
+      createMessageEvent(EventSource.CUSTOMER, "Alice", "Economy class please"),
+    ];
+
+    const response2 = await agent.respond({ history: history2, session });
+    console.log("\n=== TURN 2 ===");
+    console.log("Agent:", response2.message);
+    console.log("Updated extracted:", response2.session?.extracted);
+    console.log("Current state:", response2.session?.currentState?.id);
   }
 
-  // Generate response (would need valid API key)
-  // const response = await agent.respond({ history });
-  // console.log('\nAgent response:', response.message);
+  // Demonstrate booking status check
+  const statusHistory = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "Bob",
+      "Can you check my booking status? Confirmation number TRV-20251015-001"
+    ),
+  ];
+
+  let statusSession = createSession<BookingStatusData>();
+  const statusResponse = await agent.respond({
+    history: statusHistory,
+    session: statusSession,
+  });
+  console.log("\n=== BOOKING STATUS CHECK ===");
+  console.log("Agent:", statusResponse.message);
+  console.log("Route:", statusResponse.session?.currentRoute?.title);
+  console.log("Extracted:", statusResponse.session?.extracted);
+
+  // Show session state management benefits
+  console.log("\n=== SESSION STATE BENEFITS ===");
+  console.log("✅ Always-on routing - respects user intent changes");
+  console.log("✅ Data persistence - extracted data survives across turns");
+  console.log(
+    "✅ State progression - intelligent flow based on collected data"
+  );
+  console.log("✅ Context awareness - router sees current progress");
 }
 
 // Run if executed directly