@falai/agent 0.6.9 → 0.8.0

package/examples/rules-prohibitions.ts

@@ -1,6 +1,6 @@
 /**
  * Rules & Prohibitions Example
- * Updated for v2 architecture with session state management
+ * Updated for v2 architecture with session step management
  *
  * Demonstrates how to use rules and prohibitions to control agent behavior
  * in different conversation routes (e.g., WhatsApp bot with different styles)
@@ -12,14 +12,14 @@ import {
   type MessageEventData,
   EventKind,
   EventSource,
-  END_STATE,
+  END_ROUTE,
 } from "../src";
 import { OpenAIProvider } from "../src/providers/OpenAIProvider";
 
 /**
  * Configuration for the AI provider
  */
-const ai = new OpenAIProvider({
+const provider = new OpenAIProvider({
   apiKey: process.env.OPENAI_API_KEY || "your-api-key-here",
   model: "gpt-5",
 });
@@ -32,7 +32,7 @@ const agent = new Agent({
   description:
     "A versatile customer service agent that adapts its behavior based on the conversation's context.",
   goal: "Provide excellent customer service by following route-specific rules and prohibitions.",
-  ai,
+  provider,
   debug: true,
 });
 
@@ -99,26 +99,26 @@ agent.createRoute({
   ],
 });
 
-// Add a stateful feedback flow to the Technical Support route
+// Add a stepful feedback flow to the Technical Support route
 const techSupportRoute = agent
   .getRoutes()
   .find((r) => r.title === "Technical Support")!;
-techSupportRoute.initialState
-  .transitionTo({
-    chatState: "Provide step-by-step technical assistance.",
+techSupportRoute.initialStep
+  .nextStep({
+    instructions: "Provide step-by-step technical assistance.",
   })
-  .transitionTo({
-    chatState: "Ask for a rating of the support provided (1-5).",
-    gather: ["feedbackRating"],
+  .nextStep({
+    instructions: "Ask for a rating of the support provided (1-5).",
+    collect: ["feedbackRating"],
   })
-  .transitionTo({
-    chatState: "Ask for any additional comments.",
-    gather: ["feedbackComments"],
+  .nextStep({
+    instructions: "Ask for any additional comments.",
+    collect: ["feedbackComments"],
   })
-  .transitionTo({
-    chatState: "Thank the user for their feedback.",
+  .nextStep({
+    instructions: "Thank the user for their feedback.",
   })
-  .transitionTo({ state: END_STATE });
+  .nextStep({ step: END_ROUTE });
 
 agent.createRoute({
   title: "Emergency Support",
@@ -166,7 +166,7 @@ async function demonstrateRulesAndProhibitions() {
     description:
       "A versatile customer service agent that adapts its behavior based on the conversation's context.",
     goal: "Provide excellent customer service by following route-specific rules and prohibitions.",
-    ai,
+    provider,
     debug: true,
   });
 
@@ -231,26 +231,26 @@ async function demonstrateRulesAndProhibitions() {
     ],
   });
 
-  // Add a stateful feedback flow to the Technical Support route
+  // Add a stepful feedback flow to the Technical Support route
   const techSupportRoute = agent
     .getRoutes()
     .find((r) => r.title === "Technical Support")!;
-  techSupportRoute.initialState
-    .transitionTo({
-      chatState: "Provide step-by-step technical assistance.",
+  techSupportRoute.initialStep
+    .nextStep({
+      instructions: "Provide step-by-step technical assistance.",
     })
-    .transitionTo({
-      chatState: "Ask for a rating of the support provided (1-5).",
-      gather: ["feedbackRating"],
+    .nextStep({
+      instructions: "Ask for a rating of the support provided (1-5).",
+      collect: ["feedbackRating"],
     })
-    .transitionTo({
-      chatState: "Ask for any additional comments.",
-      gather: ["feedbackComments"],
+    .nextStep({
+      instructions: "Ask for any additional comments.",
+      collect: ["feedbackComments"],
     })
-    .transitionTo({
-      chatState: "Thank the user for their feedback.",
+    .nextStep({
+      instructions: "Thank the user for their feedback.",
     })
-    .transitionTo({ state: END_STATE });
+    .nextStep({ step: END_ROUTE });
 
   agent.createRoute({
     title: "Emergency Support",

package/examples/streaming-agent.ts

@@ -1,6 +1,6 @@
 /**
  * Example: Streaming Responses
- * Updated for v2 architecture with session state management
+ * Updated for v2 architecture with session step management
  *
  * This example demonstrates how to use the respondStream method
  * to stream AI responses in real-time for better user experience
@@ -14,7 +14,7 @@ import {
   OpenAIProvider,
   GeminiProvider,
   createSession,
-  END_STATE,
+  END_ROUTE,
 } from "../src/index";
 
 // Custom context type
@@ -51,7 +51,7 @@ async function streamingWithAnthropic() {
         streamingEnabled: true,
       },
     },
-    ai: provider,
+    provider: provider,
   });
 
   // Add guidelines
@@ -73,10 +73,10 @@ async function streamingWithAnthropic() {
     console.log("📤 Streaming response from Claude...\n");
     console.log("Response: ");
 
-    // Initialize session state for streaming conversation
+    // Initialize session step for streaming conversation
     let session = createSession();
 
-    // Use respondStream for real-time streaming with session state
+    // Use respondStream for real-time streaming with session step
     let fullMessage = "";
     for await (const chunk of agent.respondStream({ history, session })) {
       // chunk.delta contains the new text
@@ -94,7 +94,7 @@ async function streamingWithAnthropic() {
         console.log(
           `   - Route: ${chunk.session?.currentRoute?.title || "None"}`
         );
-        console.log(`   - Extracted:`, chunk.session?.extracted || "None");
+        console.log(`   - Data:`, chunk.session?.data || "None");
         console.log(`   - Tool Calls: ${chunk.toolCalls?.length || 0}`);
 
         // Update session with progress
@@ -127,7 +127,7 @@ async function streamingWithOpenAI() {
         streamingEnabled: true,
       },
     },
-    ai: provider,
+    provider: provider,
   });
 
   const history = [
@@ -142,7 +142,7 @@ async function streamingWithOpenAI() {
     console.log("📤 Streaming response from OpenAI...\n");
     console.log("Response: ");
 
-    // Initialize session state for streaming conversation
+    // Initialize session step for streaming conversation
     let session = createSession();
 
     for await (const chunk of agent.respondStream({ history, session })) {
@@ -155,7 +155,7 @@ async function streamingWithOpenAI() {
         console.log(
           `   - Route: ${chunk.session?.currentRoute?.title || "None"}`
         );
-        console.log(`   - Extracted:`, chunk.session?.extracted || "None");
+        console.log(`   - Data:`, chunk.session?.data || "None");
 
         // Update session with progress
         session = chunk.session!;
@@ -187,7 +187,7 @@ async function streamingWithGemini() {
         streamingEnabled: true,
       },
     },
-    ai: provider,
+    provider: provider,
   });
 
   const history = [
@@ -202,7 +202,7 @@ async function streamingWithGemini() {
     console.log("📤 Streaming response from Gemini...\n");
     console.log("Response: ");
 
-    // Initialize session state for streaming conversation
+    // Initialize session step for streaming conversation
     let session = createSession();
 
     for await (const chunk of agent.respondStream({ history, session })) {
@@ -215,7 +215,7 @@ async function streamingWithGemini() {
         console.log(
           `   - Route: ${chunk.session?.currentRoute?.title || "None"}`
         );
-        console.log(`   - Extracted:`, chunk.session?.extracted || "None");
+        console.log(`   - Data:`, chunk.session?.data || "None");
 
         // Update session with progress
         session = chunk.session!;
@@ -227,7 +227,7 @@ async function streamingWithGemini() {
 }
 
 async function streamingWithRoutes() {
-  console.log("\n🤖 Example 4: Streaming with Routes and States\n");
+  console.log("\n🤖 Example 4: Streaming with Routes and Steps\n");
 
   const provider = new AnthropicProvider({
     apiKey: process.env.ANTHROPIC_API_KEY || "",
@@ -244,7 +244,7 @@ async function streamingWithRoutes() {
         streamingEnabled: true,
       },
     },
-    ai: provider,
+    provider: provider,
   });
 
   // Create a route
@@ -254,8 +254,8 @@ async function streamingWithRoutes() {
     conditions: ["User asks about product features or issues"],
   });
 
-  supportRoute.initialState.transitionTo({
-    chatState: "Understand the user's product question",
+  supportRoute.initialStep.nextStep({
+    instructions: "Understand the user's product question",
   });
 
   // Create a feedback route
@@ -266,7 +266,7 @@ async function streamingWithRoutes() {
     title: "Collect Feedback",
     description: "Collect user feedback on their support experience",
     conditions: ["User wants to provide feedback"],
-    extractionSchema: {
+    schema: {
       type: "object",
       properties: {
         rating: { type: "number", minimum: 1, maximum: 5 },
@@ -276,15 +276,15 @@ async function streamingWithRoutes() {
     },
     steps: [
       {
-        chatState: "How would you rate your support experience from 1 to 5?",
-        gather: ["rating"],
+        instructions: "How would you rate your support experience from 1 to 5?",
+        collect: ["rating"],
       },
       {
-        chatState: "Thanks for the rating! Any other comments?",
-        gather: ["comments"],
+        instructions: "Thanks for the rating! Any other comments?",
+        collect: ["comments"],
       },
       {
-        chatState: "We appreciate your feedback!",
+        instructions: "We appreciate your feedback!",
       },
     ],
   });
@@ -301,7 +301,7 @@ async function streamingWithRoutes() {
     console.log("📤 Streaming response with route detection...\n");
     console.log("Response: ");
 
-    // Initialize session state for streaming conversation
+    // Initialize session step for streaming conversation
     let session = createSession();
 
     for await (const chunk of agent.respondStream({ history, session })) {
@@ -315,14 +315,14 @@ async function streamingWithRoutes() {
         console.log(
           `   - Route: ${chunk.session?.currentRoute?.title || "None"}`
         );
-        console.log(`   - Extracted:`, chunk.session?.extracted || "None");
+        console.log(`   - Data:`, chunk.session?.data || "None");
 
         // Check for route completion
         if (chunk.isRouteComplete) {
           console.log("\n✅ Route complete!");
           if (chunk.session?.currentRoute?.title === "Collect Feedback") {
             await logFeedback(
-              agent.getExtractedData(chunk.session?.id) as {
+              agent.getData(chunk.session?.id) as {
                 rating: number;
                 comments: string;
               }
@@ -357,7 +357,7 @@ async function streamingWithAbortSignal() {
         streamingEnabled: true,
       },
     },
-    ai: provider,
+    provider: provider,
   });
 
   const history = [
@@ -381,7 +381,7 @@ async function streamingWithAbortSignal() {
     console.log("📤 Streaming response (will abort after 3s)...\n");
     console.log("Response: ");
 
-    // Initialize session state for streaming conversation
+    // Initialize session step for streaming conversation
     let session = createSession();
 
     for await (const chunk of agent.respondStream({
@@ -399,7 +399,7 @@ async function streamingWithAbortSignal() {
         console.log(
           `   - Route: ${chunk.session?.currentRoute?.title || "None"}`
         );
-        console.log(`   - Extracted:`, chunk.session?.extracted || "None");
+        console.log(`   - Data:`, chunk.session?.data || "None");
 
         // Update session with progress
         session = chunk.session!;
@@ -453,7 +453,7 @@ async function main() {
   console.log("   - Set ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY");
   console.log("   - Streaming provides real-time responses for better UX");
   console.log("   - Use AbortSignal to cancel long-running streams");
-  console.log("   - Access chunk.route and chunk.state for flow information");
+  console.log("   - Access chunk.route and chunk.step for flow information");
 
   console.log("\n" + "=".repeat(60));