@falai/agent 0.3.0 → 0.3.11

package/README.md

@@ -34,7 +34,7 @@
 ### 🚀 **Production Ready**
 
 - **Robust Retry Logic** - Exponential backoff & backup models
-- **AI Provider Strategy** - Pluggable backends (Gemini, OpenAI, OpenRouter)
+- **AI Provider Strategy** - Pluggable backends (Claude, Gemini, OpenAI, OpenRouter)
 - **Prompt Composition** - Sophisticated prompt building system
 
 </td>
@@ -87,8 +87,10 @@ Get up and running in 60 seconds:
 ```typescript
 import {
   Agent,
+  AnthropicProvider,
   GeminiProvider,
-  OpenAIProvider, // or use OpenAI
+  OpenAIProvider,
+  OpenRouterProvider,
   createMessageEvent,
   EventSource,
 } from "@falai/agent";
@@ -101,15 +103,25 @@ interface SupportContext {
 }
 
 // 2️⃣ Create AI provider (choose one)
-const ai = new GeminiProvider({
-  apiKey: process.env.GEMINI_API_KEY!,
-  model: "models/gemini-2.5-flash",
+const ai = new AnthropicProvider({
+  apiKey: process.env.ANTHROPIC_API_KEY!,
+  model: "claude-sonnet-4-5",
 });
 
-// Or use OpenAI:
+// Or use other providers:
+// const ai = new GeminiProvider({
+//   apiKey: process.env.GEMINI_API_KEY!,
+//   model: "models/gemini-2.5-flash",
+// });
+
 // const ai = new OpenAIProvider({
 //   apiKey: process.env.OPENAI_API_KEY!,
-//   model: "gpt-5", // Required - specify your model
+//   model: "gpt-5",
+// });
+
+// const ai = new OpenRouterProvider({
+//   apiKey: process.env.OPENROUTER_API_KEY!,
+//   model: "anthropic/claude-sonnet-4-5", // Access to 200+ models
 // });
 
 // 3️⃣ Initialize your agent - two ways!
@@ -174,6 +186,36 @@ const response = await agent.respond({
 console.log(response.message); // 🎉 AI-powered response ready!
 ```
 
+### ⚡ Streaming Responses (NEW!)
+
+Stream AI responses in real-time for better user experience:
+
+```typescript
+// Use respondStream for real-time streaming
+for await (const chunk of agent.respondStream({ history })) {
+  // chunk.delta contains the new text
+  process.stdout.write(chunk.delta);
+
+  if (chunk.done) {
+    // Stream complete - access final metadata
+    console.log("\n✅ Complete!");
+    console.log("Route:", chunk.route?.title);
+    console.log("Tool calls:", chunk.toolCalls?.length);
+  }
+}
+```
+
+**Benefits:**
+
+- ✨ Real-time response generation
+- 🎯 Better perceived performance
+- 🛑 Cancellable with AbortSignal
+- 📊 Access to route/state/tool information in final chunk
+
+**Supported Providers:** All providers support streaming (Anthropic, OpenAI, Gemini, OpenRouter)
+
+See [streaming-agent.ts](./examples/streaming-agent.ts) for complete examples.
+
 ---
 
 ## 📚 Documentation
@@ -287,20 +329,30 @@ const onboardingRoute = agent.createRoute({
   conditions: ["User is new and needs onboarding"],
 });
 
-// Build the flow
+// Option 1: Step-by-step (clear and explicit)
 const askName = onboardingRoute.initialState.transitionTo({
   chatState: "Ask for user's full name",
 });
 
 const askEmail = askName.transitionTo({
   chatState: "Request email address",
-  condition: "User provided their name",
 });
 
 const confirmDetails = askEmail.transitionTo({
   chatState: "Confirm all details before proceeding",
 });
 
+confirmDetails.transitionTo({ state: END_ROUTE });
+
+// Option 2: Fluent chaining (concise and elegant)
+onboardingRoute.initialState
+  .transitionTo({ chatState: "Ask for user's full name" })
+  .transitionTo({ chatState: "Request email address" })
+  .transitionTo({ chatState: "Confirm all details before proceeding" })
+  .transitionTo({ state: END_ROUTE });
+
+// Both approaches work identically - choose what fits your style!
+
 // Add guidelines dynamically (can also be in route options)
 onboardingRoute.createGuideline({
   condition: "User provides invalid email",
@@ -308,17 +360,127 @@ onboardingRoute.createGuideline({
   enabled: true,
   tags: ["validation"],
 });
+```
+
+### 📜 Rules & Prohibitions Per Route
+
+Control agent behavior and communication style for each route:
 
-// Happy path completion
-confirmDetails.transitionTo({
-  chatState: "Welcome message and next steps",
-  condition: "User confirms details",
+```typescript
+// WhatsApp support bot with different styles per route
+agent.createRoute({
+  title: "Quick Support",
+  description: "Fast answers for common questions",
+  conditions: ["User has a simple question"],
+  rules: [
+    "Keep messages extremely short (1-2 lines maximum)",
+    "Use bullet points for lists",
+    "Maximum 1 emoji per message 👍",
+    "Be direct and to the point",
+  ],
+  prohibitions: [
+    "Never send long paragraphs",
+    "Do not over-explain",
+    "Never use more than 2 emojis",
+  ],
 });
 
-// End the route
-confirmDetails.transitionTo({ state: END_ROUTE });
+agent.createRoute({
+  title: "Sales Consultation",
+  description: "Help customer discover needs",
+  conditions: ["User is interested in buying"],
+  rules: [
+    "Ask open-ended questions to discover needs",
+    "Use storytelling when presenting solutions",
+    "Present value before mentioning price",
+  ],
+  prohibitions: [
+    "Never talk about price before showing value",
+    "Do not pressure or push",
+    "Avoid technical jargon",
+  ],
+});
+
+agent.createRoute({
+  title: "Emergency Support",
+  description: "Handle urgent issues",
+  conditions: ["Customer is frustrated", "Urgent issue"],
+  rules: [
+    "Acknowledge the urgency immediately",
+    "Express empathy and understanding",
+    "Set clear expectations on resolution time",
+  ],
+  prohibitions: [
+    "Never downplay the customer's concern",
+    "Do not use emojis (keep it professional)",
+    'Never say "calm down"',
+  ],
+});
 ```
 
+**Use Cases:**
+
+- 📱 Different message styles per channel (WhatsApp, email, chat)
+- 🎭 Context-specific tone and behavior
+- 🎨 Brand consistency across routes
+- ⚡ Automatic enforcement without manual checking
+
+### 🔐 Domain Scoping for Security
+
+Restrict which tools are available in each route:
+
+```typescript
+// Register different tool domains
+agent.addDomain("payment", {
+  processPayment: async (amount: number) => {
+    /* ... */
+  },
+  refund: async (txId: string) => {
+    /* ... */
+  },
+});
+
+agent.addDomain("calendar", {
+  scheduleEvent: async (date: Date, title: string) => {
+    /* ... */
+  },
+});
+
+agent.addDomain("analytics", {
+  trackEvent: async (name: string) => {
+    /* ... */
+  },
+});
+
+// Route 1: Customer Support - NO access to payment tools
+agent.createRoute({
+  title: "Customer Support",
+  description: "Answer general questions",
+  domains: [], // 🔒 No tools (conversation only)
+});
+
+// Route 2: Checkout - ONLY payment and analytics
+agent.createRoute({
+  title: "Checkout Process",
+  description: "Process purchases",
+  domains: ["payment", "analytics"], // 🔒 Limited access
+});
+
+// Route 3: Admin - ALL tools available
+agent.createRoute({
+  title: "Admin Support",
+  description: "Full system access",
+  // domains not specified = all domains available
+});
+```
+
+**Benefits:**
+
+- 🔒 Prevent unauthorized tool calls
+- ⚡ Improve AI performance (reduced decision space)
+- 📋 Clear documentation of route capabilities
+- 🛡️ Security by design
+
 ### 🔀 Disambiguation with Observations
 
 Handle ambiguous user intent gracefully - declaratively or programmatically:
@@ -496,9 +658,27 @@ const event = createMessageEvent(
 
 ### ⚙️ Advanced Configuration
 
-Fine-tune AI provider behavior - works with both Gemini and OpenAI:
+Fine-tune AI provider behavior - works with all providers:
 
 ```typescript
+// Anthropic (Claude) configuration
+const anthropicProvider = new AnthropicProvider({
+  apiKey: process.env.ANTHROPIC_API_KEY!,
+  model: "claude-sonnet-4-5", // Primary model
+  backupModels: [
+    "claude-opus-4-1", // Backup if primary fails
+    "claude-sonnet-4-0", // Stable fallback
+  ],
+  config: {
+    temperature: 0.7,
+    top_p: 0.9,
+  },
+  retryConfig: {
+    timeout: 60000, // 60s timeout
+    retries: 3, // 3 attempts with exponential backoff
+  },
+});
+
 // Gemini configuration
 const geminiProvider = new GeminiProvider({
   apiKey: process.env.GEMINI_API_KEY!,
@@ -508,8 +688,8 @@ const geminiProvider = new GeminiProvider({
     "models/gemini-2.0-flash",
   ],
   retryConfig: {
-    timeout: 60000, // 60s timeout
-    retries: 3, // 3 attempts with exponential backoff
+    timeout: 60000,
+    retries: 3,
   },
 });
 
@@ -523,6 +703,19 @@ const openaiProvider = new OpenAIProvider({
     retries: 3,
   },
 });
+
+// OpenRouter configuration (access to 200+ models)
+const openrouterProvider = new OpenRouterProvider({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  model: "anthropic/claude-sonnet-4-5",
+  backupModels: ["openai/gpt-5", "google/gemini-2.5-flash"],
+  siteUrl: "https://yourapp.com",
+  siteName: "Your App Name",
+  retryConfig: {
+    timeout: 60000,
+    retries: 3,
+  },
+});
 ```
 
 ---
@@ -538,6 +731,16 @@ const openaiProvider = new OpenAIProvider({
 - 🔗 Route references by title in observations
 - ➕ Dynamic additions after construction
 
+### ⚡ [Streaming Responses](./examples/streaming-agent.ts) **(NEW!)**
+
+**Real-time streaming responses for better UX:**
+
+- 🌊 Stream responses from all providers (Anthropic, OpenAI, Gemini, OpenRouter)
+- 📡 Real-time text generation with `respondStream`
+- 🛑 Cancellable streams with AbortSignal
+- 📊 Access route, state, and tool information
+- 🎯 5 comprehensive examples covering different use cases
+
 ### 💾 [Persistent Onboarding Agent](./examples/persistent-onboarding.ts)
 
 **Multi-turn conversation with state persistence:**
@@ -548,6 +751,17 @@ const openaiProvider = new OpenAIProvider({
 - 🔧 Two approaches: lifecycle hooks vs context provider
 - 📝 Complete onboarding flow across multiple turns
 
+### 🏢 [Business Onboarding](./examples/business-onboarding.ts)
+
+**Production-ready business onboarding with advanced patterns:**
+
+- 🎯 Real-world multi-step business setup flow
+- 🔀 Complex branching logic (physical vs online business)
+- 🔄 Tools with `contextUpdate` for automatic state management
+- 🔗 Both step-by-step and fluent chaining approaches
+- 🎨 Lifecycle hooks for agent caching and persistence
+- 📊 Dynamic route creation based on collected data
+
 ### 🌍 [Travel Booking Agent](./examples/travel-agent.ts)
 
 A complete travel agent implementation featuring:
@@ -568,15 +782,34 @@ Healthcare-focused agent demonstrating:
 - 🔐 Sensitive data handling
 - ⚠️ Urgent case prioritization
 
-### 🌐 [OpenAI Agent](./examples/openai-agent.ts)
+### 🌐 Multiple Provider Examples
 
-Using OpenAI provider instead of Gemini:
+See how different AI providers work:
 
-- 🤖 OpenAI GPT-4o integration
-- 🔄 Backup model configuration
-- ⚙️ Custom retry settings
+- **[OpenAI Agent](./examples/openai-agent.ts)** - GPT-5 integration
+- **[Healthcare Agent](./examples/healthcare-agent.ts)** - Claude 3.5 Sonnet
+- **[Travel Agent](./examples/travel-agent.ts)** - OpenRouter with backup models
+- 🔄 All with backup model configuration and retry settings
 - 🌤️ Weather checking example
 
+### 🔐 [Domain Scoping](./examples/domain-scoping.ts)
+
+Control tool access per route for security and clarity:
+
+- 🔒 Restrict which tools are available in each route
+- 🎯 Prevent unauthorized tool calls
+- ⚡ Improve AI performance by reducing decision space
+- 📋 Clear documentation of route capabilities
+
+### 📜 [Rules & Prohibitions](./examples/rules-prohibitions.ts)
+
+Control agent behavior and communication style per route:
+
+- ✅ Define absolute rules the agent must follow
+- ❌ Set prohibitions for what agent must never do
+- 💬 Different communication styles per route
+- 🎨 Perfect for multi-channel bots (WhatsApp, email, chat)
+
 ---
 
 ## 🏗️ Architecture
@@ -585,7 +818,7 @@ Using OpenAI provider instead of Gemini:
 src/
 ├── types/          # Type definitions (strongly typed contracts)
 ├── core/           # Core framework (Agent, Route, State, Tools, etc.)
-├── providers/      # AI providers (Gemini with retry/backup logic)
+├── providers/      # AI providers (Anthropic, Gemini, OpenAI, OpenRouter)
 ├── utils/          # Utilities (retry, timeout, helpers)
 ├── constants/      # Constants (END_ROUTE, symbols)
 └── index.ts        # Public API exports

package/dist/cjs/core/Agent.d.ts

@@ -70,6 +70,31 @@ export declare class Agent<TContext = unknown> {
      * @internal
      */
     private getContext;
+    /**
+     * Generate a response based on history and context as a stream
+     */
+    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>;
+        }>;
+    }>;
     /**
      * Generate a response based on history and context
      */
@@ -117,5 +142,17 @@ export declare class Agent<TContext = unknown> {
      * Get the domain registry
      */
     getDomainRegistry(): 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>>;
+    /**
+     * 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>>;
 }
 //# sourceMappingURL=Agent.d.ts.map

package/dist/cjs/core/Agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../../src/core/Agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../../src/core/Agent.ts"],"names":[],"mappings":"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"}

package/dist/cjs/core/Agent.js

@@ -171,6 +171,136 @@ class Agent {
         // Otherwise return the stored context
         return this.context;
     }
+    /**
+     * Generate a response based on history and context as a stream
+     */
+    async *respondStream(params) {
+        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,
+            ...contextOverride,
+        };
+        // Build prompt (same as respond method)
+        const promptBuilder = new PromptBuilder_1.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 = 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 = null;
+            let state = null;
+            let toolCalls;
+            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
      */
@@ -231,14 +361,22 @@ class Agent {
                 promptBuilder.addObservations(observationsWithRoutes);
             }
         }
-        // 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();
         // Build final prompt
@@ -327,6 +465,34 @@ class Agent {
     getDomainRegistry() {
         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) {
+        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) {
+        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);
+    }
 }
 exports.Agent = Agent;
 //# sourceMappingURL=Agent.js.map