@falai/agent 0.3.0 → 0.3.11

package/examples/streaming-agent.ts

@@ -0,0 +1,371 @@
+/**
+ * Example: Streaming Responses
+ *
+ * This example demonstrates how to use the respondStream method
+ * to stream AI responses in real-time for better user experience
+ */
+
+import {
+  Agent,
+  createMessageEvent,
+  EventSource,
+  AnthropicProvider,
+  OpenAIProvider,
+  GeminiProvider,
+} from "../src/index";
+
+// Custom context type
+interface ConversationContext {
+  userId: string;
+  sessionId: string;
+  preferences: {
+    streamingEnabled: boolean;
+  };
+}
+
+async function streamingWithAnthropic() {
+  console.log("\n🤖 Example 1: Streaming with Anthropic (Claude)\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>({
+    name: "StreamingAssistant",
+    description: "An AI assistant that streams responses in real-time",
+    goal: "Provide helpful information with streaming responses",
+    context: {
+      userId: "user123",
+      sessionId: "session456",
+      preferences: {
+        streamingEnabled: true,
+      },
+    },
+    ai: provider,
+  });
+
+  // Add guidelines
+  agent.createGuideline({
+    action: "Be concise but informative in your responses",
+    enabled: true,
+  });
+
+  // Create conversation history
+  const history = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "User",
+      "Explain quantum computing in simple terms."
+    ),
+  ];
+
+  try {
+    console.log("📤 Streaming response from Claude...\n");
+    console.log("Response: ");
+
+    // Use respondStream for real-time streaming
+    let fullMessage = "";
+    for await (const chunk of agent.respondStream({ history })) {
+      // 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;
+      }
+
+      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(`   - Tool Calls: ${chunk.toolCalls?.length || 0}`);
+      }
+    }
+  } catch (error) {
+    console.error("❌ Error:", error);
+  }
+}
+
+async function streamingWithOpenAI() {
+  console.log("\n🤖 Example 2: Streaming with OpenAI\n");
+
+  const provider = new OpenAIProvider({
+    apiKey: process.env.OPENAI_API_KEY || "",
+    model: "gpt-5",
+    config: {
+      temperature: 0.8,
+    },
+  });
+
+  const agent = new Agent<ConversationContext>({
+    name: "CreativeAssistant",
+    description: "A creative AI assistant",
+    context: {
+      userId: "user123",
+      sessionId: "session789",
+      preferences: {
+        streamingEnabled: true,
+      },
+    },
+    ai: provider,
+  });
+
+  const history = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "User",
+      "Write a short poem about TypeScript"
+    ),
+  ];
+
+  try {
+    console.log("📤 Streaming response from OpenAI...\n");
+    console.log("Response: ");
+
+    for await (const chunk of agent.respondStream({ history })) {
+      if (chunk.delta) {
+        process.stdout.write(chunk.delta);
+      }
+
+      if (chunk.done) {
+        console.log("\n\n✅ Stream complete!");
+      }
+    }
+  } catch (error) {
+    console.error("❌ Error:", error);
+  }
+}
+
+async function streamingWithGemini() {
+  console.log("\n🤖 Example 3: Streaming with Google Gemini\n");
+
+  const provider = new GeminiProvider({
+    apiKey: process.env.GEMINI_API_KEY || "",
+    model: "models/gemini-2.0-flash-exp",
+    config: {
+      temperature: 0.7,
+    },
+  });
+
+  const agent = new Agent<ConversationContext>({
+    name: "AnalyticalAssistant",
+    description: "An analytical AI assistant",
+    context: {
+      userId: "user123",
+      sessionId: "session101",
+      preferences: {
+        streamingEnabled: true,
+      },
+    },
+    ai: provider,
+  });
+
+  const history = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "User",
+      "What are the key differences between REST and GraphQL?"
+    ),
+  ];
+
+  try {
+    console.log("📤 Streaming response from Gemini...\n");
+    console.log("Response: ");
+
+    for await (const chunk of agent.respondStream({ history })) {
+      if (chunk.delta) {
+        process.stdout.write(chunk.delta);
+      }
+
+      if (chunk.done) {
+        console.log("\n\n✅ Stream complete!");
+      }
+    }
+  } catch (error) {
+    console.error("❌ Error:", error);
+  }
+}
+
+async function streamingWithRoutes() {
+  console.log("\n🤖 Example 4: Streaming with Routes and States\n");
+
+  const provider = new AnthropicProvider({
+    apiKey: process.env.ANTHROPIC_API_KEY || "",
+    model: "claude-sonnet-4-5",
+  });
+
+  const agent = new Agent<ConversationContext>({
+    name: "SupportAgent",
+    description: "A customer support agent with conversation routes",
+    context: {
+      userId: "user123",
+      sessionId: "session202",
+      preferences: {
+        streamingEnabled: true,
+      },
+    },
+    ai: provider,
+  });
+
+  // Create a route
+  const supportRoute = agent.createRoute({
+    title: "Product Support",
+    description: "Help users with product questions",
+    conditions: ["User asks about product features or issues"],
+  });
+
+  supportRoute.initialState.transitionTo({
+    chatState: "Understand the user's product question",
+  });
+
+  const history = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "User",
+      "How do I reset my password?"
+    ),
+  ];
+
+  try {
+    console.log("📤 Streaming response with route detection...\n");
+    console.log("Response: ");
+
+    for await (const chunk of agent.respondStream({ history })) {
+      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}`);
+        }
+      }
+    }
+  } catch (error) {
+    console.error("❌ Error:", error);
+  }
+}
+
+async function streamingWithAbortSignal() {
+  console.log("\n🤖 Example 5: 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>({
+    name: "Assistant",
+    description: "An assistant that can be interrupted",
+    context: {
+      userId: "user123",
+      sessionId: "session303",
+      preferences: {
+        streamingEnabled: true,
+      },
+    },
+    ai: provider,
+  });
+
+  const history = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "User",
+      "Tell me a very long story about space exploration."
+    ),
+  ];
+
+  // Create an AbortController to cancel the stream
+  const abortController = new AbortController();
+
+  // Automatically abort after 3 seconds
+  const timeout = setTimeout(() => {
+    console.log("\n\n⚠️  Aborting stream after 3 seconds...");
+    abortController.abort();
+  }, 3000);
+
+  try {
+    console.log("📤 Streaming response (will abort after 3s)...\n");
+    console.log("Response: ");
+
+    for await (const chunk of agent.respondStream({
+      history,
+      signal: abortController.signal,
+    })) {
+      if (chunk.delta) {
+        process.stdout.write(chunk.delta);
+      }
+
+      if (chunk.done) {
+        console.log("\n\n✅ Stream complete!");
+        clearTimeout(timeout);
+      }
+    }
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      console.log("\n\n🛑 Stream was aborted successfully!");
+    } else {
+      console.error("❌ Error:", error);
+    }
+    clearTimeout(timeout);
+  }
+}
+
+async function main() {
+  console.log("🚀 Starting Streaming Examples\n");
+  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 },
+  ];
+
+  console.log("\nAvailable Examples:");
+  examples.forEach((ex, i) => {
+    console.log(`  ${i + 1}. ${ex.name}`);
+  });
+
+  console.log("\n💡 Tips:");
+  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("\n" + "=".repeat(60));
+
+  // Run first example if API key is available
+  if (process.env.ANTHROPIC_API_KEY) {
+    await streamingWithAnthropic();
+  } else if (process.env.OPENAI_API_KEY) {
+    await streamingWithOpenAI();
+  } else if (process.env.GEMINI_API_KEY) {
+    await streamingWithGemini();
+  } else {
+    console.log(
+      "\n⚠️  No API keys found. Set one of the environment variables to run examples."
+    );
+  }
+}
+
+// Run if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch(console.error);
+}
+
+export { main };

package/examples/travel-agent.ts

@@ -6,7 +6,7 @@
 import {
   Agent,
   defineTool,
-  GeminiProvider,
+  OpenRouterProvider,
   END_ROUTE,
   EventSource,
   createMessageEvent,
@@ -113,9 +113,12 @@ const getBookingStatus = defineTool<
 
 // Initialize agent
 async function createTravelAgent() {
-  const provider = new GeminiProvider({
-    apiKey: process.env.GEMINI_API_KEY || "test-key",
-    model: "models/gemini-2.0-flash-exp",
+  const provider = new OpenRouterProvider({
+    apiKey: process.env.OPENROUTER_API_KEY || "test-key",
+    model: "google/gemini-2.0-flash-exp",
+    backupModels: ["anthropic/claude-sonnet-4-5", "openai/gpt-5"],
+    siteUrl: "https://github.com/gusnips/falai",
+    siteName: "Falai Travel Agent Example",
     retryConfig: {
       timeout: 60000,
       retries: 3,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "0.3.0",
+  "version": "0.3.11",
   "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -77,6 +77,7 @@
     "typescript-eslint": "^8.18.2"
   },
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.65.0",
     "@google/genai": "^0.3.0",
     "openai": "^6.3.0"
   }

package/src/core/Agent.ts

@@ -211,6 +211,180 @@ export class Agent<TContext = unknown> {
     return this.context;
   }
 
+  /**
+   * Generate a response based on history and context as a stream
+   */
+  async *respondStream(params: {
+    history: Event[];
+    state?: StateRef;
+    contextOverride?: Partial<TContext>;
+    signal?: AbortSignal;
+  }): AsyncGenerator<{
+    delta: string;
+    accumulated: string;
+    done: boolean;
+    route?: { id: string; title: string } | null;
+    state?: { id: string; description?: string } | null;
+    toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
+  }> {
+    const { history, contextOverride, signal } = params;
+
+    // Get current context (may fetch from provider)
+    let currentContext = await this.getContext();
+
+    // Call beforeRespond hook if configured
+    if (this.options.hooks?.beforeRespond && currentContext !== undefined) {
+      currentContext = await this.options.hooks.beforeRespond(currentContext);
+      // Update stored context with the result from beforeRespond
+      this.context = currentContext;
+    }
+
+    // Merge context with override
+    const effectiveContext = {
+      ...(currentContext as Record<string, unknown>),
+      ...(contextOverride as Record<string, unknown>),
+    } as TContext;
+
+    // Build prompt (same as respond method)
+    const promptBuilder = new PromptBuilder();
+
+    // Add agent identity
+    if (this.options.description) {
+      promptBuilder.addAgentIdentity({
+        name: this.options.name,
+        description: this.options.description,
+      });
+    }
+
+    // Add interaction history
+    promptBuilder.addInteractionHistoryForMessageGeneration(history);
+
+    // Add glossary
+    if (this.terms.length > 0) {
+      promptBuilder.addGlossary(this.terms);
+    }
+
+    // Add guidelines (convert to GuidelineMatch format, filter enabled only)
+    const enabledGuidelines = this.guidelines.filter(
+      (g) => g.enabled !== false
+    );
+    if (enabledGuidelines.length > 0) {
+      const guidelineMatches: GuidelineMatch[] = enabledGuidelines.map((g) => ({
+        guideline: g,
+      }));
+      promptBuilder.addGuidelinesForMessageGeneration(guidelineMatches);
+    }
+
+    // Add capabilities
+    if (this.capabilities.length > 0) {
+      promptBuilder.addCapabilitiesForMessageGeneration(this.capabilities);
+    }
+
+    // Add observations
+    if (this.observations.length > 0) {
+      const observationsWithRoutes = this.observations
+        .map((obs) => ({
+          description: obs.description,
+          routes: obs.getRoutes().map((routeRef) => {
+            const route = this.routes.find((r) => r.id === routeRef.id);
+            return { title: route?.title || routeRef.id };
+          }),
+        }))
+        .filter((obs) => obs.routes.length > 0);
+
+      if (observationsWithRoutes.length > 0) {
+        promptBuilder.addObservations(observationsWithRoutes);
+      }
+    }
+
+    // Add active routes with their rules and prohibitions
+    if (this.routes.length > 0) {
+      promptBuilder.addActiveRoutes(
+        this.routes.map((r) => ({
+          title: r.title,
+          description: r.description,
+          conditions: r.conditions,
+          domains: r.getDomains(),
+          rules: r.getRules(),
+          prohibitions: r.getProhibitions(),
+        }))
+      );
+    }
+
+    // Add domains (tools) information if any domains are registered
+    const allDomains = this.domainRegistry.all();
+    if (Object.keys(allDomains).length > 0) {
+      promptBuilder.addDomains(allDomains);
+    }
+
+    // Add JSON response schema instructions
+    promptBuilder.addJsonResponseSchema();
+
+    // Build final prompt
+    const prompt = promptBuilder.build();
+
+    // Generate message stream using AI provider with JSON mode enabled
+    const stream = this.options.ai.generateMessageStream({
+      prompt,
+      history,
+      context: effectiveContext,
+      signal,
+      parameters: {
+        jsonMode: true,
+      },
+    });
+
+    // Stream chunks to caller
+    for await (const chunk of stream) {
+      // Extract route and state from structured response on final chunk
+      let route: { id: string; title: string } | null = null;
+      let state: { id: string; description?: string } | null = null;
+      let toolCalls:
+        | Array<{ toolName: string; arguments: Record<string, unknown> }>
+        | undefined;
+
+      if (chunk.done && chunk.structured) {
+        // Find route by title
+        if (chunk.structured.route) {
+          const foundRoute = this.routes.find(
+            (r) => r.title === chunk.structured?.route
+          );
+          if (foundRoute) {
+            route = {
+              id: foundRoute.id,
+              title: foundRoute.title,
+            };
+          }
+        }
+
+        // Create state reference if provided
+        if (chunk.structured.state) {
+          state = {
+            id: "dynamic_state",
+            description: chunk.structured.state,
+          };
+        }
+
+        // Extract tool calls
+        if (
+          chunk.structured.toolCalls &&
+          chunk.structured.toolCalls.length > 0
+        ) {
+          toolCalls = chunk.structured.toolCalls;
+        }
+      }
+
+      yield {
+        delta: chunk.delta,
+        accumulated: chunk.accumulated,
+        done: chunk.done,
+        route: route || undefined,
+        state: state || undefined,
+        toolCalls,
+      };
+    }
+  }
+
   /**
    * Generate a response based on history and context
    */
@@ -295,17 +469,26 @@ export class Agent<TContext = unknown> {
       }
     }
 
-    // Add active routes
+    // Add active routes with their rules and prohibitions
     if (this.routes.length > 0) {
       promptBuilder.addActiveRoutes(
         this.routes.map((r) => ({
           title: r.title,
           description: r.description,
           conditions: r.conditions,
+          domains: r.getDomains(),
+          rules: r.getRules(),
+          prohibitions: r.getProhibitions(),
         }))
       );
     }
 
+    // Add domains (tools) information if any domains are registered
+    const allDomains = this.domainRegistry.all();
+    if (Object.keys(allDomains).length > 0) {
+      promptBuilder.addDomains(allDomains);
+    }
+
     // Add JSON response schema instructions
     promptBuilder.addJsonResponseSchema();
 
@@ -414,4 +597,40 @@ export class Agent<TContext = unknown> {
   getDomainRegistry(): DomainRegistry {
     return this.domainRegistry;
   }
+
+  /**
+   * Get allowed domains for a specific route
+   * @param routeId - Route ID to check
+   * @returns Filtered domains object, or all domains if route has no restrictions
+   */
+  getDomainsForRoute(routeId: string): Record<string, Record<string, unknown>> {
+    const route = this.routes.find((r) => r.id === routeId);
+
+    if (!route) {
+      // Route not found, return all domains
+      return this.domainRegistry.all();
+    }
+
+    const allowedDomains = route.getDomains();
+    return this.domainRegistry.getFiltered(allowedDomains);
+  }
+
+  /**
+   * Get allowed domains for a specific route by title
+   * @param routeTitle - Route title to check
+   * @returns Filtered domains object, or all domains if route has no restrictions
+   */
+  getDomainsForRouteByTitle(
+    routeTitle: string
+  ): Record<string, Record<string, unknown>> {
+    const route = this.routes.find((r) => r.title === routeTitle);
+
+    if (!route) {
+      // Route not found, return all domains
+      return this.domainRegistry.all();
+    }
+
+    const allowedDomains = route.getDomains();
+    return this.domainRegistry.getFiltered(allowedDomains);
+  }
 }

package/src/core/DomainRegistry.ts

@@ -47,4 +47,34 @@ export class DomainRegistry {
     }
     return result;
   }
+
+  /**
+   * Get filtered domains by names
+   * @param allowedNames - Array of domain names to include (undefined = all domains)
+   * @returns Object with only the specified domains
+   */
+  getFiltered(
+    allowedNames?: string[]
+  ): Record<string, Record<string, unknown>> {
+    // If no filter specified, return all domains
+    if (!allowedNames) {
+      return this.all();
+    }
+
+    const result: Record<string, Record<string, unknown>> = {};
+    for (const name of allowedNames) {
+      const domain = this.domains.get(name);
+      if (domain) {
+        result[name] = domain;
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Get list of all registered domain names
+   */
+  getDomainNames(): string[] {
+    return Array.from(this.domains.keys());
+  }
 }