@falai/agent 0.5.3 → 0.5.5

package/docs/API_REFERENCE.md

@@ -87,29 +87,99 @@ interface RespondOutput {
 - Enables "I changed my mind" scenarios with context-aware routing
 - Automatically merges new extracted data with existing session data
 
-**Example:**
+**Example with Persistence Adapters:**
 
 ```typescript
+import { createSession } from "@falai/agent";
+
+// Using built-in persistence adapters
+const { sessionData, sessionState } =
+  await persistence.createSessionWithState<FlightData>({
+    userId: "user_123",
+    agentName: "Travel Agent",
+  });
+
 const response = await agent.respond({
-  history: conversationHistory,
+  history,
+  session: sessionState, // Auto-saves if autoSave: true
 });
+```
 
-// Save to database
-await db.agentMessages.create({
-  sessionId: session.id,
+**Example with Custom Database (Manual):**
+
+```typescript
+import { createSession, SessionState } from "@falai/agent";
+
+// Load from your custom database
+const dbSession = await yourDb.sessions.findOne({ id: sessionId });
+
+// Restore or create session state
+let agentSession: SessionState<YourDataType>;
+
+if (dbSession && dbSession.currentRoute && dbSession.collectedData) {
+  // Restore existing session from database
+  agentSession = {
+    currentRoute: {
+      id: dbSession.currentRoute,
+      title:
+        dbSession.collectedData?.currentRouteTitle || dbSession.currentRoute,
+      enteredAt: new Date(),
+    },
+    currentState: dbSession.currentState
+      ? {
+          id: dbSession.currentState,
+          description: dbSession.collectedData?.currentStateDescription,
+          enteredAt: new Date(),
+        }
+      : undefined,
+    extracted: dbSession.collectedData?.extracted || {},
+    routeHistory: dbSession.collectedData?.routeHistory || [],
+    metadata: {
+      sessionId: dbSession.id,
+      createdAt: dbSession.createdAt,
+      lastUpdatedAt: new Date(),
+    },
+  };
+} else {
+  // Create new session
+  agentSession = createSession<YourDataType>({
+    sessionId: dbSession?.id || "new-session-id",
+  });
+}
+
+// Use session in conversation
+const response = await agent.respond({
+  history,
+  session: agentSession,
+});
+
+// Manually save to your database
+await yourDb.sessions.update({
+  id: dbSession.id,
+  currentRoute: response.session?.currentRoute?.id,
+  currentState: response.session?.currentState?.id,
+  collectedData: {
+    extracted: response.session?.extracted,
+    routeHistory: response.session?.routeHistory,
+    currentRouteTitle: response.session?.currentRoute?.title,
+    currentStateDescription: response.session?.currentState?.description,
+    metadata: response.session?.metadata,
+  },
+  lastMessageAt: new Date(),
+});
+
+// Save message
+await yourDb.messages.create({
+  sessionId: dbSession.id,
   role: "agent",
   content: response.message,
-  route: response.route?.title,
-  state: response.state?.description,
-  toolCalls: response.toolCalls || [],
+  route: response.session?.currentRoute?.id,
+  state: response.session?.currentState?.id,
 });
-
-// Check if conversation is complete
-if (response.route?.title === END_ROUTE) {
-  await markSessionComplete(session.id);
-}
 ```
 
+See also: [Custom Database Integration Example](../examples/custom-database-persistence.ts)
+
 ##### `respondStream(input: RespondInput<TContext>): AsyncGenerator<StreamChunk>`
 
 Generates an AI response as a real-time stream for better user experience. Provides the same structured output as `respond()` but delivers it incrementally.
@@ -350,11 +420,16 @@ interface TransitionResult<TExtracted = unknown> {
   routeId: string; // Route identifier
   transitionTo: (
     spec: TransitionSpec<TExtracted>,
-    condition?: string
+    condition?: string // Optional: AI-evaluated text condition for this transition
   ) => TransitionResult<TExtracted>;
 }
 ```
 
+**Parameters:**
+
+- `spec`: The transition specification (see `TransitionSpec` above)
+- `condition` (optional): Human-readable condition text that the AI evaluates when selecting states. Use this to guide the AI's state selection based on conversation context. Examples: "Customer confirmed payment", "All required data collected", "User wants to modify order"
+
 **Returns:** A `TransitionResult` that includes the target state's reference (`id`, `routeId`) and a `transitionTo` method for chaining additional transitions.
 
 **Example:**
@@ -381,19 +456,25 @@ const flightRoute = agent.createRoute<FlightData>({
   },
 });
 
-// Approach 1: Step-by-step with data extraction
-const askDestination = flightRoute.initialState.transitionTo({
-  chatState: "Ask where they want to fly",
-  gather: ["destination"],
-  skipIf: (extracted) => !!extracted.destination, // Skip if already have destination
-});
+// Approach 1: Step-by-step with data extraction and text conditions
+const askDestination = flightRoute.initialState.transitionTo(
+  {
+    chatState: "Ask where they want to fly",
+    gather: ["destination"],
+    skipIf: (extracted) => !!extracted.destination, // Skip if already have destination
+  },
+  "Customer hasn't specified destination yet" // AI-evaluated condition
+);
 
-const askDates = askDestination.transitionTo({
-  chatState: "Ask about travel dates",
-  gather: ["departureDate"],
-  skipIf: (extracted) => !!extracted.departureDate,
-  requiredData: ["destination"], // Must have destination first
-});
+const askDates = askDestination.transitionTo(
+  {
+    chatState: "Ask about travel dates",
+    gather: ["departureDate"],
+    skipIf: (extracted) => !!extracted.departureDate,
+    requiredData: ["destination"], // Must have destination first
+  },
+  "Destination confirmed, need travel dates"
+);
 
 const askPassengers = askDates.transitionTo({
   chatState: "How many passengers?",

package/docs/ARCHITECTURE.md

@@ -58,7 +58,11 @@ import {
   mergeExtracted,
 } from "@falai/agent";
 
-let session = createSession<FlightData>();
+// Create session with optional metadata including session ID
+let session = createSession<FlightData>(sessionId, {
+  userId: "user_456",
+  createdAt: new Date(),
+});
 
 // Turn 1 - Extract data
 const response1 = await agent.respond({ history, session });
@@ -67,6 +71,31 @@ session = response1.session!; // Updated with extracted data
 // Turn 2 - User changes mind (always-on routing)
 const response2 = await agent.respond({ history, session: response1.session });
 session = response2.session!; // Route/state updated if user changed direction
+
+// Access session metadata
+console.log(session.metadata?.sessionId); // "unique-session-123"
+```
+
+**Session with Persistence:**
+
+When using persistence adapters, set the session ID from the database:
+
+```typescript
+// Create database session and in-memory session state
+const { sessionData, sessionState } =
+  await persistence.createSessionWithState<FlightData>({
+    userId: "user_123",
+    agentName: "Travel Agent",
+  });
+
+// sessionState.metadata.sessionId is automatically set to sessionData.id
+console.log(sessionState.metadata?.sessionId); // "cuid_from_database"
+
+// Use it in conversation
+const response = await agent.respond({
+  history,
+  session: sessionState, // Auto-saves to database!
+});
 ```
 
 **Why?** Session state enables:
@@ -75,33 +104,75 @@ session = response2.session!; // Route/state updated if user changed direction
 - **Context Awareness** - Router sees current progress and extracted data
 - **Data Persistence** - Extracted data survives across turns
 - **State Recovery** - Resume conversations from any point
+- **Session Tracking** - Track conversations via session ID in database
 
-### 3. 🔧 Code-Based State Logic
+### 3. 🔧 Code-Based State Logic + AI-Driven Transitions
 
-Use TypeScript functions instead of LLM conditions for deterministic flow:
+Use TypeScript functions for deterministic flow control AND text conditions for AI-driven state selection:
 
 ```typescript
 // State with smart bypassing based on extracted data
-const askDestination = route.initialState.transitionTo({
-  chatState: "Ask where they want to fly",
-  gather: ["destination"],
-  skipIf: (extracted) => !!extracted.destination, // Code-based condition!
+const askDestination = route.initialState.transitionTo(
+  {
+    id: "ask_destination", // Optional: custom state ID
+    chatState: "Ask where they want to fly",
+    gather: ["destination"],
+    skipIf: (extracted) => !!extracted.destination, // Code-based condition!
+  },
+  "Customer hasn't specified destination yet" // Text condition for AI
+);
+
+const askDate = askDestination.transitionTo(
+  {
+    id: "ask_date", // Optional: custom state ID for easier tracking
+    chatState: "Ask about travel dates",
+    gather: ["departureDate"],
+    skipIf: (extracted) => !!extracted.departureDate,
+    requiredData: ["destination"], // Prerequisites
+  },
+  "Destination confirmed, need travel dates now"
+);
 });
+```
 
-const askDate = askDestination.transitionTo({
-  chatState: "Ask about travel dates",
-  gather: ["departureDate"],
-  skipIf: (extracted) => !!extracted.departureDate,
-  requiredData: ["destination"], // Prerequisites
+**Custom State IDs:**
+
+You can optionally provide custom IDs for states to make them easier to track and reference:
+
+```typescript
+const confirmBooking = askDate.transitionTo({
+  id: "confirm_booking", // ✅ Custom ID instead of auto-generated
+  chatState: "Confirm all booking details",
+  requiredData: ["destination", "departureDate", "passengers"],
 });
 ```
 
+If you don't provide an ID, one is automatically generated from the route ID and state description.
+
 **Why?** Code-based logic provides:
 
 - **Predictability** - No fuzzy LLM interpretation of conditions
 - **Performance** - No extra LLM calls for condition checking
 - **Debugging** - Clear logic flow you can trace
 - **Type Safety** - Full TypeScript support for data validation
+- **Custom IDs** - Easier tracking and debugging with meaningful state identifiers
+
+**How State Transitions Work:**
+
+1. **Code filters first**: `skipIf` and `requiredData` filter out invalid states deterministically
+2. **AI selects best state**: From valid candidates, AI evaluates text conditions to choose optimal state
+3. **Combined decision**: Single AI call handles both route selection AND state selection (no extra calls!)
+4. **Completion detection**: When all states are skipped and `END_ROUTE` is reached, route is marked complete
+
+```typescript
+// The AI sees:
+// "Available states: askDate, confirmBooking
+//  - askDate: Destination confirmed, need travel dates now
+//  - confirmBooking: All required info collected, ready to book
+//  Current extracted: {destination: 'Paris', departureDate: '2025-01-15'}
+//
+//  → AI selects 'confirmBooking' based on context"
+```
 
 ### 4. 🛠️ Tools with Data Access
 

package/docs/PERSISTENCE.md

@@ -121,11 +121,18 @@ const bookingRoute = agent.createRoute<BookingData>({
   },
 });
 
-// Define states with smart data gathering
-bookingRoute.initialState.transitionTo({
-  chatState: "Collect booking details",
-  gather: ["destination", "date", "passengers"],
-});
+// Define states with smart data gathering and custom IDs
+bookingRoute.initialState
+  .transitionTo({
+    id: "collect_details", // ✅ Custom state ID for easier tracking
+    chatState: "Collect booking details",
+    gather: ["destination", "date", "passengers"],
+  })
+  .transitionTo({
+    id: "confirm_booking", // ✅ Custom state ID
+    chatState: "Confirm all details",
+    requiredData: ["destination", "date", "passengers"],
+  });
 
 // Access persistence methods
 const persistence = agent.getPersistenceManager();
@@ -137,17 +144,22 @@ const { sessionData, sessionState } =
     agentName: "My Agent",
   });
 
+// Session ID is automatically set in metadata
+console.log("Session ID:", sessionState.metadata?.sessionId);
+// Outputs: sessionData.id (e.g., "cuid_abc123")
+
 // Load history
 const history = await persistence.loadSessionHistory(sessionData.id);
 
 // Generate response with session state
 const response = await agent.respond({
   history,
-  session: sessionState, // Pass session state
+  session: sessionState, // Pass session state with ID
 });
 
 // Session state is auto-saved! ✨
 console.log("Extracted data:", response.session?.extracted);
+console.log("Current state ID:", response.session?.currentState?.id); // Custom or auto-generated ID
 
 // Save message
 await persistence.saveMessage({

package/examples/business-onboarding.ts

@@ -586,15 +586,19 @@ async function createBusinessOnboardingAgent(
   // Beautiful fluent chaining for linear flows
   feedbackRoute.initialState
     .transitionTo({
+      id: "ask_rating",
       chatState: "How would you rate your onboarding experience? (1-5 stars)",
     })
     .transitionTo({
+      id: "ask_liked_most",
       chatState: "What did you like most about the process?",
     })
     .transitionTo({
+      id: "ask_improve",
       chatState: "Is there anything we could improve?",
     })
     .transitionTo({
+      id: "thank_you",
       chatState: "Thank you for your feedback! It helps us improve. 🙏",
     })
     .transitionTo({ state: END_ROUTE });
@@ -603,38 +607,45 @@ async function createBusinessOnboardingAgent(
 
   agent
     .createGuideline({
+      id: "guideline_confused",
       condition: "User seems confused or doesn't understand something",
       action:
         "Be patient and provide practical examples of what you need. E.g., 'José Silva Street, 123, São Paulo - SP' for address",
     })
     .createGuideline({
+      id: "guideline_incomplete",
       condition: "User provides incomplete or very vague information",
       action:
         "Politely ask for the missing specific details. E.g., 'You mentioned the address, but what's the city and state?'",
     })
     .createGuideline({
+      id: "guideline_skip",
       condition:
         "User wants to skip information saying they don't have it or it doesn't apply",
       action:
         "Be smart: if the information is critical for their business type (e.g., address for physical store, website for e-commerce), explain the importance. If not critical, accept it and move forward saying 'no problem, that's fine'",
     })
     .createGuideline({
+      id: "guideline_physical_online",
       condition: "User has physical store but said online-only or vice versa",
       action:
         "Adjust the flow dynamically: if they have a physical store, prioritize address and hours. If online-only, prioritize website/social media and digital support hours. Don't ask for irrelevant information",
     })
     .createGuideline({
+      id: "guideline_why",
       condition: "User asks why they need to provide certain information",
       action:
         "Explain practically: 'This information will help your assistant automatically answer customers when they ask about this. E.g., when they ask about payment methods, the assistant will inform automatically'",
     })
     .createGuideline({
+      id: "guideline_edit",
       condition:
         "User wants to edit or correct something they already provided",
       action:
         "Accept promptly and update the information: 'Of course! I'll update to...'. Use the appropriate tool to save the correction",
     })
     .createGuideline({
+      id: "guideline_unrelated",
       condition: "User asks a question unrelated to onboarding",
       action:
         "Answer briefly and redirect: 'I understand, but let's finish the setup first? We're almost there!'",