@falai/agent 0.9.0-alpha-1 → 0.9.0-alpha-2

package/examples/advanced-patterns/persistent-onboarding.ts

@@ -120,11 +120,37 @@ function createPersistentOnboardingAgent(sessionId: string) {
     model: "models/gemini-2.5-flash",
   });
 
-  const agent = new Agent<OnboardingContext>({
+  // Define the onboarding schema
+  const onboardingSchema = {
+    type: "object",
+    properties: {
+      businessName: {
+        type: "string",
+        description: "Name of the business",
+      },
+      businessDescription: {
+        type: "string",
+        description: "Brief description of what the business does",
+      },
+      industry: {
+        type: "string",
+        description: "Industry the business operates in",
+      },
+      contactEmail: {
+        type: "string",
+        description: "Contact email for the business",
+      },
+    },
+    required: ["businessName", "businessDescription"],
+  };
+
+  const agent = new Agent<OnboardingContext, OnboardingData>({
     name: "OnboardingBot",
     description: "A friendly assistant that helps businesses get started",
     goal: "Collect business information efficiently while being conversational",
     provider: provider,
+    // NEW: Agent-level schema
+    schema: onboardingSchema,
 
     // Knowledge base with onboarding best practices
     knowledgeBase: {
@@ -204,9 +230,9 @@ function createPersistentOnboardingAgent(sessionId: string) {
   // OPTION 1: Using contextUpdate in return value
   const saveBusinessInfo: Tool<
     OnboardingContext,
+    OnboardingData,
     unknown[],
-    unknown,
-    OnboardingData
+    unknown
   > = {
     id: "save_business_info",
     name: "Business Info Saver",
@@ -244,9 +270,9 @@ function createPersistentOnboardingAgent(sessionId: string) {
   // OPTION 2: Using updateContext method directly
   const saveIndustry: Tool<
     OnboardingContext,
+    OnboardingData,
     unknown[],
-    unknown,
-    OnboardingData
+    unknown
   > = {
     id: "save_industry",
     name: "Industry Classifier",
@@ -277,9 +303,9 @@ function createPersistentOnboardingAgent(sessionId: string) {
 
   const saveContactEmail: Tool<
     OnboardingContext,
+    OnboardingData,
     unknown[],
-    unknown,
-    OnboardingData
+    unknown
   > = {
     id: "save_contact_email",
     name: "Contact Email Saver",
@@ -311,32 +337,14 @@ function createPersistentOnboardingAgent(sessionId: string) {
   // ONBOARDING ROUTE WITH DATA EXTRACTION
   // ============================================================================
 
-  const onboardingRoute = agent.createRoute<OnboardingData>({
+  const onboardingRoute = agent.createRoute({
     title: "Business Onboarding",
     description: "Guide user through business information collection",
     conditions: ["User is onboarding their business"],
-    schema: {
-      type: "object",
-      properties: {
-        businessName: {
-          type: "string",
-          description: "Name of the business",
-        },
-        businessDescription: {
-          type: "string",
-          description: "Brief description of what the business does",
-        },
-        industry: {
-          type: "string",
-          description: "Industry the business operates in",
-        },
-        contactEmail: {
-          type: "string",
-          description: "Contact email for the business",
-        },
-      },
-      required: ["businessName", "businessDescription"],
-    },
+    // NEW: Required fields for route completion
+    requiredFields: ["businessName", "businessDescription"],
+    // NEW: Optional fields that enhance the experience
+    optionalFields: ["industry", "contactEmail"],
     endStep: {
       prompt:
         "Summarize all collected information warmly and confirm onboarding is complete",
@@ -428,10 +436,36 @@ function createOnboardingAgentWithProvider(sessionId: string) {
     model: "models/gemini-2.5-flash",
   });
 
-  const agent = new Agent<OnboardingContext>({
+  // Define the onboarding schema
+  const onboardingSchema = {
+    type: "object",
+    properties: {
+      businessName: {
+        type: "string",
+        description: "Name of the business",
+      },
+      businessDescription: {
+        type: "string",
+        description: "Brief description of what the business does",
+      },
+      industry: {
+        type: "string",
+        description: "Industry the business operates in",
+      },
+      contactEmail: {
+        type: "string",
+        description: "Contact email for the business",
+      },
+    },
+    required: ["businessName", "businessDescription"],
+  };
+
+  const agent = new Agent<OnboardingContext, OnboardingData>({
     name: "OnboardingBot",
     description: "A friendly assistant that helps businesses get started",
     provider: provider,
+    // NEW: Agent-level schema
+    schema: onboardingSchema,
 
     // Context is always fetched fresh from database
     contextProvider: () => {
@@ -499,7 +533,7 @@ async function main() {
   });
   
   console.log("🤖 Bot:", response1.message);
-  console.log("📊 Data after turn 1:", agent.session.getData<OnboardingData>());
+  console.log("📊 Data after turn 1:", agent.session.getData());
   console.log("📊 Route:", response1.session?.currentRoute?.title);
 
   // Check route completion after turn 1
@@ -533,7 +567,7 @@ async function main() {
       name: "Alice",
     },
   ];
-  const response2 = await agent.respond({ history: history2, session });
+  const response2 = await agent.respond({ history: history2 });
   console.log("🤖 Bot:", response2.message);
   console.log("📊 Data after turn 2:", response2.session?.data);
 
@@ -547,8 +581,6 @@ async function main() {
 
   console.log();
 
-  // Update session again
-  session = response2.session!;
 
   // Turn 3: User provides industry
   console.log("📱 Turn 3: User provides industry");
@@ -564,7 +596,7 @@ async function main() {
       name: "Alice",
     },
   ];
-  const response3 = await agent.respond({ history: history3, session });
+  const response3 = await agent.respond({ history: history3 });
   console.log("🤖 Bot:", response3.message);
   console.log("📊 Data after turn 3:", response3.session?.data);
 
@@ -578,9 +610,6 @@ async function main() {
 
   console.log();
 
-  // Update session again
-  session = response3.session!;
-
   // Turn 4: User provides contact email, completing the flow
   console.log("📱 Turn 4: User provides contact email");
   const history4 = [
@@ -595,7 +624,7 @@ async function main() {
       name: "Alice",
     },
   ];
-  const response4 = await agent.respond({ history: history4, session });
+  const response4 = await agent.respond({ history: history4 });
   console.log("🤖 Bot:", response4.message);
   console.log("📊 Data after turn 4:", response4.session?.data);
 
@@ -603,7 +632,7 @@ async function main() {
   if (response4.isRouteComplete) {
     console.log("\n✅ Onboarding complete!");
     await finalizeOnboarding(
-      agent.getData(response4.session?.id) as unknown as OnboardingData
+      agent.getData() as unknown as OnboardingData
     );
   }
 

package/examples/advanced-patterns/route-lifecycle-hooks.ts

@@ -16,15 +16,39 @@ const provider = new OpenAIProvider({
   model: "gpt-5",
 });
 
+// Define data schema for feedback collection
+interface ServiceData {
+  feedbackRating?: number;
+  feedbackComments?: string;
+}
+
+const serviceSchema = {
+  type: "object",
+  properties: {
+    feedbackRating: {
+      type: "number",
+      description: "Rating from 1-5",
+      minimum: 1,
+      maximum: 5,
+    },
+    feedbackComments: {
+      type: "string",
+      description: "Additional feedback comments",
+    },
+  },
+};
+
 /**
  * Create a new agent instance with predefined routes and rules/prohibitions.
  */
-const agent = new Agent({
+const agent = new Agent<unknown, ServiceData>({
   name: "CustomerServiceAgent",
   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.",
   provider,
+  // NEW: Agent-level schema
+  schema: serviceSchema,
   debug: true,
 
   // Knowledge base with customer service best practices
@@ -223,12 +247,14 @@ agent.createRoute({
  * Demonstration function to show how the agent responds to different scenarios.
  */
 async function demonstrateRulesAndProhibitions() {
-  const agent = new Agent({
+  const agent = new Agent<unknown, ServiceData>({
     name: "CustomerServiceAgent",
     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.",
     provider,
+    // NEW: Agent-level schema
+    schema: serviceSchema,
     debug: true,
   });
 

package/examples/advanced-patterns/streaming-responses.ts

@@ -36,7 +36,7 @@ async function streamingWithAnthropic() {
   });
 
   // Create agent
-  const agent = new Agent<ConversationContext>({
+  const agent = new Agent<ConversationContext, unknown>({
     name: "StreamingAssistant",
     description: "An AI assistant that streams responses in real-time",
     goal: "Provide helpful information with streaming responses",
@@ -120,7 +120,7 @@ async function streamingWithOpenAI() {
     },
   });
 
-  const agent = new Agent<ConversationContext>({
+  const agent = new Agent<ConversationContext, unknown>({
     name: "CreativeAssistant",
     description: "A creative AI assistant",
     context: {
@@ -185,7 +185,7 @@ async function streamingWithGemini() {
     },
   });
 
-  const agent = new Agent<ConversationContext>({
+  const agent = new Agent<ConversationContext, unknown>({
     name: "AnalyticalAssistant",
     description: "An analytical AI assistant",
     context: {
@@ -247,7 +247,22 @@ async function streamingWithRoutes() {
     model: "claude-sonnet-4-5",
   });
 
-  const agent = new Agent<ConversationContext>({
+  // Define feedback data schema
+  interface FeedbackData {
+    rating: number;
+    comments: string;
+  }
+
+  const feedbackSchema = {
+    type: "object",
+    properties: {
+      rating: { type: "number", minimum: 1, maximum: 5 },
+      comments: { type: "string" },
+    },
+    required: ["rating"],
+  };
+
+  const agent = new Agent<ConversationContext, FeedbackData>({
     name: "SupportAgent",
     description: "A customer support agent with conversation routes",
     context: {
@@ -258,6 +273,8 @@ async function streamingWithRoutes() {
       },
     },
     provider: provider,
+    // NEW: Agent-level schema
+    schema: feedbackSchema,
   });
 
   // Create a route
@@ -272,21 +289,14 @@ async function streamingWithRoutes() {
   });
 
   // Create a feedback route
-  agent.createRoute<{
-    rating: number;
-    comments: string;
-  }>({
+  agent.createRoute({
     title: "Collect Feedback",
     description: "Collect user feedback on their support experience",
     conditions: ["User wants to provide feedback"],
-    schema: {
-      type: "object",
-      properties: {
-        rating: { type: "number", minimum: 1, maximum: 5 },
-        comments: { type: "string" },
-      },
-      required: ["rating"],
-    },
+    // NEW: Required fields for route completion
+    requiredFields: ["rating"],
+    // NEW: Optional fields
+    optionalFields: ["comments"],
     steps: [
       {
         prompt: "How would you rate your support experience from 1 to 5?",
@@ -339,12 +349,7 @@ async function streamingWithRoutes() {
         if (chunk.isRouteComplete) {
           console.log("\n✅ Route complete!");
           if (chunk.session?.currentRoute?.title === "Collect Feedback") {
-            await logFeedback(
-              agent.session.getData() as {
-                rating: number;
-                comments: string;
-              }
-            );
+            await logFeedback(agent.session.getData() as FeedbackData);
           }
         }
 
@@ -364,7 +369,7 @@ async function streamingWithAbortSignal() {
     model: "claude-sonnet-4-5",
   });
 
-  const agent = new Agent<ConversationContext>({
+  const agent = new Agent<ConversationContext, unknown>({
     name: "Assistant",
     description: "An assistant that can be interrupted",
     context: {

package/examples/ai-providers/anthropic-integration.ts

@@ -25,7 +25,7 @@ interface ResearchData {
 }
 
 // Research tool that Claude can use
-const conductResearch: Tool<unknown, unknown[], unknown, ResearchData> = {
+const conductResearch: Tool<unknown, ResearchData, unknown[], unknown> = {
   id: "conduct_research",
   description: "Conduct comprehensive research on a given topic",
   parameters: {
@@ -33,17 +33,16 @@ const conductResearch: Tool<unknown, unknown[], unknown, ResearchData> = {
     properties: {},
   },
   handler: async ({ data }) => {
-    const researchData = data as Partial<ResearchData>;
     console.log(
-      `Conducting ${researchData?.depth} research on: ${researchData?.topic}`
+      `Conducting ${data?.depth} research on: ${data?.topic}`
     );
 
     const researchId = `RES-${Date.now()}`;
 
     // Simulate research process
     const findings = {
-      overview: `Found ${researchData?.sources || 3} sources about ${
-        researchData?.topic
+      overview: `Found ${data?.sources || 3} sources about ${
+        data?.topic
       }`,
       key_points: [
         "Latest developments in the field",
@@ -62,8 +61,36 @@ const conductResearch: Tool<unknown, unknown[], unknown, ResearchData> = {
   },
 };
 
+// Define research schema
+const researchSchema = {
+  type: "object",
+  properties: {
+    topic: { type: "string", description: "The research topic" },
+    depth: {
+      type: "string",
+      enum: ["overview", "detailed", "comprehensive"],
+      default: "detailed",
+    },
+    sources: {
+      type: "number",
+      minimum: 1,
+      maximum: 20,
+      default: 5,
+      description: "Number of sources to analyze",
+    },
+    format: {
+      type: "string",
+      enum: ["summary", "bullet_points", "structured"],
+      default: "structured",
+      description: "Output format preference",
+    },
+    researchId: { type: "string" },
+  },
+  required: ["topic"],
+};
+
 // Create agent with Anthropic provider
-const agent = new Agent({
+const agent = new Agent<unknown, ResearchData>({
   name: "ClaudeResearcher",
   description: "A research assistant powered by Claude",
   provider: new AnthropicProvider({
@@ -75,38 +102,18 @@ const agent = new Agent({
       top_p: 0.9,
     },
   }),
+  // NEW: Agent-level schema
+  schema: researchSchema,
 });
 
 // Create research route
-const researchRoute = agent.createRoute<ResearchData>({
+const researchRoute = agent.createRoute({
   title: "Research Assistant",
   description: "Conduct research using Claude's analytical capabilities",
-  schema: {
-    type: "object",
-    properties: {
-      topic: { type: "string", description: "The research topic" },
-      depth: {
-        type: "string",
-        enum: ["overview", "detailed", "comprehensive"],
-        default: "detailed",
-      },
-      sources: {
-        type: "number",
-        minimum: 1,
-        maximum: 20,
-        default: 5,
-        description: "Number of sources to analyze",
-      },
-      format: {
-        type: "string",
-        enum: ["summary", "bullet_points", "structured"],
-        default: "structured",
-        description: "Output format preference",
-      },
-      researchId: { type: "string" },
-    },
-    required: ["topic"],
-  },
+  // NEW: Required fields for route completion
+  requiredFields: ["topic"],
+  // NEW: Optional fields that enhance the experience
+  optionalFields: ["depth", "sources", "format", "researchId"],
   identity: `You are Claude, an AI research assistant created by Anthropic.
                You have access to extensive knowledge and can conduct thorough research.
                Always be helpful, truthful, and provide well-reasoned analysis.`,

package/examples/ai-providers/openai-integration.ts

@@ -26,7 +26,7 @@ interface WeatherData {
 }
 
 // Define a tool that can access collected data
-const getWeather: Tool<CustomerContext, unknown[], unknown, WeatherData> = {
+const getWeather: Tool<CustomerContext, WeatherData, unknown[], unknown> = {
   id: "get_weather",
   description: "Get current weather for a location",
   parameters: {
@@ -38,8 +38,7 @@ const getWeather: Tool<CustomerContext, unknown[], unknown, WeatherData> = {
   },
   handler: ({ data }, location) => {
     // Use data location if available, otherwise use args
-    const weatherData = data as Partial<WeatherData>;
-    const finalLocation = weatherData?.location || location;
+    const finalLocation = data?.location || location;
 
     // Simulate API call
     return {
@@ -71,7 +70,7 @@ async function main() {
   });
 
   // Create agent with OpenAI
-  const agent = new Agent<CustomerContext>({
+  const agent = new Agent<CustomerContext, WeatherData>({
     name: "Assistant",
     description:
       "A helpful AI assistant that can check weather and answer questions",
@@ -84,6 +83,25 @@ async function main() {
       preferences: ["concise answers", "weather updates"],
     },
     provider: openaiProvider,
+
+    schema: {
+      type: "object",
+      properties: {
+        location: {
+          type: "string",
+          description: "City or location for weather check",
+        },
+        temperature: {
+          type: "number",
+          description: "Temperature in Fahrenheit",
+        },
+        condition: {
+          type: "string",
+          description: "Weather condition (sunny, cloudy, rainy, etc.)",
+        },
+      },
+      required: ["location"],
+    },
   });
 
   // Add domain knowledge
@@ -106,28 +124,10 @@ async function main() {
     });
 
   // Create weather route with data extraction schema
-  const weatherRoute = agent.createRoute<WeatherData>({
+  const weatherRoute = agent.createRoute({
     title: "Check Weather",
     description: "Help user check weather for a location",
     conditions: ["User wants to know the weather"],
-    schema: {
-      type: "object",
-      properties: {
-        location: {
-          type: "string",
-          description: "City or location for weather check",
-        },
-        temperature: {
-          type: "number",
-          description: "Temperature in Fahrenheit",
-        },
-        condition: {
-          type: "string",
-          description: "Weather condition (sunny, cloudy, rainy, etc.)",
-        },
-      },
-      required: ["location"],
-    },
   });
 
   // Step 1: Collect location
@@ -180,14 +180,14 @@ async function main() {
     console.log(`   Customer: What's the weather like in San Francisco?`);
     console.log(`   Agent: ${response.message}`);
     console.log(`   Route: ${response.session?.currentRoute?.title}`);
-    console.log(`   Data:`, agent.session.getData<WeatherData>());
+    console.log(`   Data:`, agent.session.getData());
 
     await agent.session.addMessage("assistant", response.message);
 
     // Check for route completion
     if (response.isRouteComplete) {
       console.log("\n✅ Weather route complete!");
-      await logWeatherRequest(agent.session.getData<WeatherData>());
+      await logWeatherRequest(agent.session.getData());
     }
 
     console.log("\n✨ Session step benefits:");