@falai/agent 0.9.0-alpha-1 → 0.9.0

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

@@ -1,9 +1,12 @@
 /**
  * Example: Streaming Responses
- * Updated for v2 architecture with session step management
+ * Updated for ResponseModal architecture with modern streaming APIs
  *
- * This example demonstrates how to use the respondStream method
- * to stream AI responses in real-time for better user experience
+ * This example demonstrates both the new modern stream() API and the legacy
+ * respondStream() method for streaming AI responses in real-time.
+ * 
+ * NEW: The modern stream() API provides automatic session management and
+ * a simpler interface similar to chat() but with streaming.
  */
 
 import {
@@ -22,8 +25,8 @@ interface ConversationContext {
   };
 }
 
-async function streamingWithAnthropic() {
-  console.log("\n🤖 Example 1: Streaming with Anthropic (Claude)\n");
+async function modernStreamingWithAnthropic() {
+  console.log("\n🤖 Example 1: Modern Streaming API with Anthropic (Claude)\n");
 
   // Initialize Anthropic provider
   const provider = new AnthropicProvider({
@@ -36,7 +39,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",
@@ -56,34 +59,91 @@ async function streamingWithAnthropic() {
     enabled: true,
   });
 
-  // Create conversation history
-  const history = [
-    {
-      role: "user" as const,
-      content: "Explain quantum computing in simple terms.",
-      name: "User",
+  try {
+    console.log("📤 Modern streaming API - automatic session management...\n");
+    console.log("Response: ");
+
+    // Session is automatically managed by the agent
+    console.log("✨ Session ready:", agent.session.id);
+
+    // NEW: Modern stream() API - automatically manages session history
+    for await (const chunk of agent.stream("Explain quantum computing in simple terms.")) {
+      // chunk.delta contains the new text
+      // chunk.accumulated contains the full text so far
+      // chunk.done indicates if this is the final chunk
+
+      if (chunk.delta) {
+        process.stdout.write(chunk.delta);
+      }
+
+      if (chunk.done) {
+        console.log("\n\n✅ Stream complete!");
+        console.log(`\n📊 Metadata:`);
+        console.log(
+          `   - Route: ${chunk.session?.currentRoute?.title || "None"}`
+        );
+        console.log(`   - Data:`, agent.session.getData() || "None");
+        console.log(`   - Tool Calls: ${chunk.toolCalls?.length || 0}`);
+
+        // Session history is automatically updated - no manual management needed!
+        console.log(`   - Session Messages: ${agent.session.getHistory().length}`);
+      }
+    }
+
+    console.log("\n💡 Benefits of modern stream() API:");
+    console.log("   - Automatic session management");
+    console.log("   - Simple interface: agent.stream('message')");
+    console.log("   - No need to manually manage history");
+    console.log("   - Same performance as respondStream()");
+
+  } catch (error) {
+    console.error("❌ Error:", error);
+  }
+}
+
+async function legacyStreamingWithAnthropic() {
+  console.log("\n🤖 Example 2: Legacy Streaming API (respondStream) - Still Supported\n");
+
+  // Initialize Anthropic provider
+  const provider = new AnthropicProvider({
+    apiKey: process.env.ANTHROPIC_API_KEY || "",
+    model: "claude-sonnet-4-5",
+    config: {
+      temperature: 0.7,
+      max_tokens: 1000,
     },
-  ];
+  });
+
+  // Create agent
+  const agent = new Agent<ConversationContext, unknown>({
+    name: "LegacyStreamingAssistant",
+    description: "An AI assistant using legacy streaming API",
+    goal: "Demonstrate backward compatibility",
+    context: {
+      userId: "user123",
+      sessionId: "session456-legacy",
+      preferences: {
+        streamingEnabled: true,
+      },
+    },
+    provider: provider,
+  });
 
   try {
-    console.log("📤 Streaming response from Claude...\n");
+    console.log("📤 Legacy respondStream API - manual session management...\n");
     console.log("Response: ");
 
     // Session is automatically managed by the agent
     console.log("✨ Session ready:", agent.session.id);
 
-    // Add user message to session history
+    // Add user message to session history manually
     await agent.session.addMessage("user", "What's the weather like today?");
 
-    // Use respondStream for real-time streaming with session history
+    // Legacy respondStream API - requires manual session management
     let fullMessage = "";
     for await (const chunk of agent.respondStream({ 
       history: agent.session.getHistory() 
     })) {
-      // chunk.delta contains the new text
-      // chunk.accumulated contains the full text so far
-      // chunk.done indicates if this is the final chunk
-
       if (chunk.delta) {
         process.stdout.write(chunk.delta);
         fullMessage += chunk.delta;
@@ -97,30 +157,36 @@ async function streamingWithAnthropic() {
         );
         console.log(`   - Data:`, agent.session.getData() || "None");
         console.log(`   - Tool Calls: ${chunk.toolCalls?.length || 0}`);
-
-        console.log(`   - Full Message: ${fullMessage}`);
         
-        // Add assistant response to session history
+        // Manual session history management required
         await agent.session.addMessage("assistant", fullMessage);
+        console.log(`   - Session Messages: ${agent.session.getHistory().length}`);
       }
     }
+
+    console.log("\n💡 Legacy respondStream() API characteristics:");
+    console.log("   - Manual session management required");
+    console.log("   - More complex parameter structure");
+    console.log("   - Full backward compatibility maintained");
+    console.log("   - Still fully supported for existing code");
+
   } catch (error) {
     console.error("❌ Error:", error);
   }
 }
 
-async function streamingWithOpenAI() {
-  console.log("\n🤖 Example 2: Streaming with OpenAI\n");
+async function modernStreamingWithOpenAI() {
+  console.log("\n🤖 Example 3: Modern Streaming with OpenAI\n");
 
   const provider = new OpenAIProvider({
     apiKey: process.env.OPENAI_API_KEY || "",
-    model: "gpt-5",
+    model: "gpt-4",
     config: {
       temperature: 0.8,
     },
   });
 
-  const agent = new Agent<ConversationContext>({
+  const agent = new Agent<ConversationContext, unknown>({
     name: "CreativeAssistant",
     description: "A creative AI assistant",
     context: {
@@ -133,26 +199,16 @@ async function streamingWithOpenAI() {
     provider: provider,
   });
 
-  const history = [
-    {
-      role: "user" as const,
-      content: "Write a short poem about TypeScript",
-      name: "User",
-    },
-  ];
-
   try {
-    console.log("📤 Streaming response from OpenAI...\n");
+    console.log("📤 Modern streaming with OpenAI...\n");
     console.log("Response: ");
 
     // Session is automatically managed by the agent
     console.log("✨ Session ready:", agent.session.id);
 
-    // Add user message to session history
-    await agent.session.addMessage("user", "What's the weather like today?");
-
-    for await (const chunk of agent.respondStream({ 
-      history: agent.session.getHistory() 
+    // NEW: Modern stream() API with context override
+    for await (const chunk of agent.stream("Write a short poem about TypeScript", {
+      contextOverride: { preferences: { streamingEnabled: true } }
     })) {
       if (chunk.delta) {
         process.stdout.write(chunk.delta);
@@ -164,9 +220,9 @@ async function streamingWithOpenAI() {
           `   - Route: ${chunk.session?.currentRoute?.title || "None"}`
         );
         console.log(`   - Data:`, agent.session.getData() || "None");
-
-        // Add assistant response to session history
-        await agent.session.addMessage("assistant", chunk.accumulated || "");
+        
+        // Session automatically updated - no manual work needed!
+        console.log(`   - Session Messages: ${agent.session.getHistory().length}`);
       }
     }
   } catch (error) {
@@ -174,8 +230,8 @@ async function streamingWithOpenAI() {
   }
 }
 
-async function streamingWithGemini() {
-  console.log("\n🤖 Example 3: Streaming with Google Gemini\n");
+async function modernStreamingComparison() {
+  console.log("\n🤖 Example 4: Side-by-Side API Comparison\n");
 
   const provider = new GeminiProvider({
     apiKey: process.env.GEMINI_API_KEY || "",
@@ -185,9 +241,9 @@ async function streamingWithGemini() {
     },
   });
 
-  const agent = new Agent<ConversationContext>({
-    name: "AnalyticalAssistant",
-    description: "An analytical AI assistant",
+  const agent = new Agent<ConversationContext, unknown>({
+    name: "ComparisonAssistant",
+    description: "Demonstrates API differences",
     context: {
       userId: "user123",
       sessionId: "session101",
@@ -198,56 +254,95 @@ async function streamingWithGemini() {
     provider: provider,
   });
 
-  const history = [
-    {
-      role: "user" as const,
-      content: "What are the key differences between REST and GraphQL?",
-      name: "User",
-    },
-  ];
+  const userMessage = "What are the key differences between REST and GraphQL?";
 
   try {
-    console.log("📤 Streaming response from Gemini...\n");
-    console.log("Response: ");
+    console.log("📤 Comparing old vs new streaming APIs...\n");
 
-    // Session is automatically managed by the agent
-    console.log("✨ Session ready:", agent.session.id);
-
-    // Add user message to session history
-    await agent.session.addMessage("user", "What are the key differences between REST and GraphQL?");
+    // ========================================================================
+    // OLD WAY: respondStream() - Manual session management
+    // ========================================================================
+    console.log("🔸 OLD WAY: respondStream() with manual session management");
+    console.log("Response: ");
 
+    // Manual session management
+    await agent.session.addMessage("user", userMessage);
+    
+    let oldWayMessage = "";
     for await (const chunk of agent.respondStream({ 
       history: agent.session.getHistory() 
     })) {
       if (chunk.delta) {
         process.stdout.write(chunk.delta);
+        oldWayMessage += chunk.delta;
       }
 
       if (chunk.done) {
-        console.log("\n\n✅ Stream complete!");
-        console.log(
-          `   - Route: ${chunk.session?.currentRoute?.title || "None"}`
-        );
-        console.log(`   - Data:`, agent.session.getData() || "None");
+        // Manual history update required
+        await agent.session.addMessage("assistant", oldWayMessage);
+        console.log("\n   ✅ Manual session update completed");
+      }
+    }
+
+    console.log("\n" + "=".repeat(60));
 
-        // Add assistant response to session history
-        await agent.session.addMessage("assistant", chunk.accumulated || "");
+    // ========================================================================
+    // NEW WAY: stream() - Automatic session management
+    // ========================================================================
+    console.log("🔸 NEW WAY: stream() with automatic session management");
+    console.log("Response: ");
+
+    // Automatic session management - just pass the message!
+    for await (const chunk of agent.stream("Can you explain that in more detail?")) {
+      if (chunk.delta) {
+        process.stdout.write(chunk.delta);
+      }
+
+      if (chunk.done) {
+        console.log("\n   ✅ Automatic session update - no manual work needed!");
+        console.log(`   📊 Total messages in session: ${agent.session.getHistory().length}`);
       }
     }
+
+    console.log("\n💡 Key Differences:");
+    console.log("   OLD: agent.respondStream({ history: agent.session.getHistory() })");
+    console.log("   NEW: agent.stream('message')");
+    console.log("   ");
+    console.log("   OLD: Manual session.addMessage() calls required");
+    console.log("   NEW: Automatic session management");
+    console.log("   ");
+    console.log("   OLD: Complex parameter structure");
+    console.log("   NEW: Simple message + optional options");
+
   } catch (error) {
     console.error("❌ Error:", error);
   }
 }
 
-async function streamingWithRoutes() {
-  console.log("\n🤖 Example 4: Streaming with Routes and Steps\n");
+async function modernStreamingWithRoutes() {
+  console.log("\n🤖 Example 5: Modern Streaming with Routes and Steps\n");
 
   const provider = new AnthropicProvider({
     apiKey: process.env.ANTHROPIC_API_KEY || "",
     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 +353,8 @@ async function streamingWithRoutes() {
       },
     },
     provider: provider,
+    // NEW: Agent-level schema
+    schema: feedbackSchema,
   });
 
   // Create a route
@@ -272,21 +369,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?",
@@ -317,12 +407,8 @@ async function streamingWithRoutes() {
     // Session is automatically managed by the agent
     console.log("✨ Session ready:", agent.session.id);
 
-    // Add user message to session history
-    await agent.session.addMessage("user", "How do I reset my password?");
-
-    for await (const chunk of agent.respondStream({ 
-      history: agent.session.getHistory() 
-    })) {
+    // NEW: Modern stream() API with routes - automatic session management
+    for await (const chunk of agent.stream("How do I reset my password?")) {
       if (chunk.delta) {
         process.stdout.write(chunk.delta);
       }
@@ -339,16 +425,11 @@ 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);
           }
         }
 
-        // Session is automatically updated by the agent
+        // Session is automatically updated by the modern stream() API
       }
     }
   } catch (error) {
@@ -356,15 +437,15 @@ async function streamingWithRoutes() {
   }
 }
 
-async function streamingWithAbortSignal() {
-  console.log("\n🤖 Example 5: Streaming with Abort Control\n");
+async function modernStreamingWithAbortSignal() {
+  console.log("\n🤖 Example 6: Modern Streaming with Abort Control\n");
 
   const provider = new AnthropicProvider({
     apiKey: process.env.ANTHROPIC_API_KEY || "",
     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: {
@@ -401,11 +482,8 @@ async function streamingWithAbortSignal() {
     // Session is automatically managed by the agent
     console.log("✨ Session ready:", agent.session.id);
 
-    // Add user message to session history
-    await agent.session.addMessage("user", "Tell me a very long story about space exploration.");
-
-    for await (const chunk of agent.respondStream({
-      history: agent.session.getHistory(),
+    // NEW: Modern stream() API with abort signal
+    for await (const chunk of agent.stream("Tell me a very long story about space exploration.", {
       signal: abortController.signal,
     })) {
       if (chunk.delta) {
@@ -420,10 +498,7 @@ async function streamingWithAbortSignal() {
         );
         console.log(`   - Data:`, agent.session.getData() || "None");
 
-        // Add assistant response to session history
-        await agent.session.addMessage("assistant", chunk.accumulated || "");
-
-        // Session is automatically updated by the agent
+        // Session is automatically updated by the modern stream() API - no manual work needed!
 
         clearTimeout(timeout);
       }
@@ -458,11 +533,12 @@ async function main() {
   console.log("=".repeat(60));
 
   const examples = [
-    { name: "Anthropic Streaming", fn: streamingWithAnthropic },
-    { name: "OpenAI Streaming", fn: streamingWithOpenAI },
-    { name: "Gemini Streaming", fn: streamingWithGemini },
-    { name: "Streaming with Routes", fn: streamingWithRoutes },
-    { name: "Streaming with Abort", fn: streamingWithAbortSignal },
+    { name: "Modern Streaming API (Anthropic)", fn: modernStreamingWithAnthropic },
+    { name: "Legacy Streaming API (Anthropic)", fn: legacyStreamingWithAnthropic },
+    { name: "Modern Streaming (OpenAI)", fn: modernStreamingWithOpenAI },
+    { name: "API Comparison (Gemini)", fn: modernStreamingComparison },
+    { name: "Modern Streaming with Routes", fn: modernStreamingWithRoutes },
+    { name: "Modern Streaming with Abort", fn: modernStreamingWithAbortSignal },
   ];
 
   console.log("\nAvailable Examples:");
@@ -472,19 +548,21 @@ async function main() {
 
   console.log("\n💡 Tips:");
   console.log("   - Set ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY");
+  console.log("   - NEW: Use agent.stream('message') for automatic session management");
+  console.log("   - OLD: agent.respondStream() still supported for backward compatibility");
   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.step for flow information");
 
   console.log("\n" + "=".repeat(60));
 
-  // Run first example if API key is available
+  // Run modern streaming example if API key is available
   if (process.env.ANTHROPIC_API_KEY) {
-    await streamingWithAnthropic();
+    await modernStreamingWithAnthropic();
   } else if (process.env.OPENAI_API_KEY) {
-    await streamingWithOpenAI();
+    await modernStreamingWithOpenAI();
   } else if (process.env.GEMINI_API_KEY) {
-    await streamingWithGemini();
+    await modernStreamingComparison();
   } else {
     console.log(
       "\n⚠️  No API keys found. Set one of the environment variables to run examples."

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.`,