@falai/agent 0.3.10 → 0.3.11

package/docs/API_REFERENCE.md

@@ -109,6 +109,107 @@ if (response.route?.title === END_ROUTE) {
 }
 ```
 
+##### `respondStream(input: RespondInput<TContext>): AsyncGenerator<StreamChunk>`
+
+Generates an AI response as a real-time stream for better user experience. Provides the same structured output as `respond()` but delivers it incrementally.
+
+```typescript
+interface StreamChunk {
+  /** The incremental text delta */
+  delta: string;
+  /** Full accumulated text so far */
+  accumulated: string;
+  /** Whether this is the final chunk */
+  done: boolean;
+  /** Route chosen by the agent (only in final chunk) */
+  route?: { id: string; title: string };
+  /** Current state within the route (only in final chunk) */
+  state?: { id: string; description?: string };
+  /** Tool calls requested by the agent (only in final chunk) */
+  toolCalls?: Array<{
+    toolName: string;
+    arguments: Record<string, unknown>;
+  }>;
+}
+```
+
+**Key Features:**
+
+- 🌊 Real-time streaming for better perceived performance
+- 📊 Access to route, state, and tool information in final chunk
+- 🛑 Cancellable with AbortSignal
+- ✅ Supported by all providers (Anthropic, OpenAI, Gemini, OpenRouter)
+
+**Example:**
+
+```typescript
+// Basic streaming
+for await (const chunk of agent.respondStream({ history })) {
+  if (chunk.delta) {
+    // Display incremental text to user
+    process.stdout.write(chunk.delta);
+  }
+
+  if (chunk.done) {
+    console.log("\n✅ Complete!");
+    // Access final metadata
+    if (chunk.route) {
+      console.log("Route:", chunk.route.title);
+    }
+    if (chunk.toolCalls) {
+      console.log("Tool calls:", chunk.toolCalls.length);
+    }
+  }
+}
+```
+
+**With Cancellation:**
+
+```typescript
+const abortController = new AbortController();
+
+// Cancel after 5 seconds
+setTimeout(() => abortController.abort(), 5000);
+
+try {
+  for await (const chunk of agent.respondStream({
+    history,
+    signal: abortController.signal,
+  })) {
+    console.log(chunk.delta);
+  }
+} catch (error) {
+  if (error.name === "AbortError") {
+    console.log("Stream cancelled");
+  }
+}
+```
+
+**Collecting Full Response:**
+
+```typescript
+let fullMessage = "";
+let finalChunk;
+
+for await (const chunk of agent.respondStream({ history })) {
+  fullMessage += chunk.delta;
+  if (chunk.done) {
+    finalChunk = chunk;
+  }
+}
+
+// Save to database
+await db.agentMessages.create({
+  sessionId: session.id,
+  role: "agent",
+  content: fullMessage,
+  route: finalChunk.route?.title,
+  toolCalls: finalChunk.toolCalls || [],
+});
+```
+
+**See Also:** [streaming-agent.ts](../examples/streaming-agent.ts) for comprehensive examples.
+
 #### Properties
 
 ##### `name: string`
@@ -366,11 +467,15 @@ Returns filtered domains by names. If `allowedNames` is `undefined`, returns all
 const registry = new DomainRegistry();
 
 registry.register("payment", {
-  processPayment: async (amount: number) => { /* ... */ },
+  processPayment: async (amount: number) => {
+    /* ... */
+  },
 });
 
 registry.register("shipping", {
-  calculateShipping: (zipCode: string) => { /* ... */ },
+  calculateShipping: (zipCode: string) => {
+    /* ... */
+  },
 });
 
 // Get specific domains
@@ -386,6 +491,61 @@ Returns list of all registered domain names.
 
 ---
 
+### `AnthropicProvider`
+
+AI provider implementation for Anthropic (Claude models).
+
+#### Constructor
+
+```typescript
+new AnthropicProvider(options: AnthropicProviderOptions)
+
+interface AnthropicProviderOptions {
+  apiKey: string;
+  model: string;               // Required: e.g., "claude-sonnet-4-5"
+  backupModels?: string[];     // Fallback models
+  config?: Partial<Omit<MessageCreateParamsNonStreaming, "model" | "messages" | "max_tokens">>;
+  retryConfig?: {
+    timeout?: number;          // Default: 60000ms
+    retries?: number;          // Default: 3
+  };
+}
+```
+
+**Note:** `model` is required for AnthropicProvider. Available models include:
+
+- `claude-sonnet-4-5` - Latest Claude Sonnet 4.5 (most capable)
+- `claude-opus-4-1` - Claude Opus 4.1 (powerful for complex tasks)
+- `claude-sonnet-4-0` - Claude Sonnet 4.0 (stable, production-ready)
+
+#### Methods
+
+##### `generateMessage<TContext>(input: GenerateMessageInput<TContext>): Promise<GenerateMessageOutput>`
+
+Generates a message with retry logic and backup models using Anthropic's API.
+
+**Example:**
+
+```typescript
+import { AnthropicProvider } from "@falai/agent";
+
+const provider = new AnthropicProvider({
+  apiKey: process.env.ANTHROPIC_API_KEY!,
+  model: "claude-sonnet-4-5",
+  backupModels: ["claude-opus-4-1", "claude-sonnet-4-0"],
+  config: {
+    temperature: 0.7,
+    top_p: 0.9,
+  },
+  retryConfig: {
+    timeout: 60000,
+    retries: 3,
+  },
+});
+```
+
+---
+
 ### `GeminiProvider`
 
 AI provider implementation for Google Gemini.
@@ -414,6 +574,104 @@ Generates a message with retry logic and backup models.
 
 ---
 
+### `OpenAIProvider`
+
+AI provider implementation for OpenAI (GPT models).
+
+#### Constructor
+
+```typescript
+new OpenAIProvider(options: OpenAIProviderOptions)
+
+interface OpenAIProviderOptions {
+  apiKey: string;
+  model: string;               // Required: e.g., "gpt-4o", "gpt-5"
+  backupModels?: string[];     // Fallback models
+  retryConfig?: {
+    timeout?: number;          // Default: 60000ms
+    retries?: number;          // Default: 3
+  };
+}
+```
+
+**Note:** Unlike GeminiProvider, `model` is required for OpenAIProvider. Choose from available OpenAI models like "gpt-4o", "gpt-5", "gpt-4-turbo", etc.
+
+#### Methods
+
+##### `generateMessage<TContext>(input: GenerateMessageInput<TContext>): Promise<GenerateMessageOutput>`
+
+Generates a message with retry logic and backup models using OpenAI's API.
+
+**Example:**
+
+```typescript
+import { OpenAIProvider } from "@falai/agent";
+
+const provider = new OpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: "gpt-5",
+  backupModels: ["gpt-4o", "gpt-4-turbo"],
+  retryConfig: {
+    timeout: 60000,
+    retries: 3,
+  },
+});
+```
+
+---
+
+### `OpenRouterProvider`
+
+AI provider implementation for OpenRouter (access to 200+ models).
+
+#### Constructor
+
+```typescript
+new OpenRouterProvider(options: OpenRouterProviderOptions)
+
+interface OpenRouterProviderOptions {
+  apiKey: string;
+  model: string;               // Required: e.g., "openai/gpt-5", "anthropic/claude-sonnet-4-5"
+  backupModels?: string[];     // Fallback models
+  siteUrl?: string;            // Optional: your app URL for OpenRouter rankings
+  siteName?: string;           // Optional: your app name for OpenRouter rankings
+  retryConfig?: {
+    timeout?: number;          // Default: 60000ms
+    retries?: number;          // Default: 3
+  };
+}
+```
+
+**Note:** OpenRouter provides access to models from multiple providers. Model names follow the format `provider/model-name` (e.g., "openai/gpt-5", "anthropic/claude-sonnet-4-5", "google/gemini-pro").
+
+#### Methods
+
+##### `generateMessage<TContext>(input: GenerateMessageInput<TContext>): Promise<GenerateMessageOutput>`
+
+Generates a message with retry logic and backup models using OpenRouter's API.
+
+**Example:**
+
+```typescript
+import { OpenRouterProvider } from "@falai/agent";
+
+const provider = new OpenRouterProvider({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  model: "openai/gpt-5",
+  backupModels: ["anthropic/claude-sonnet-4-5", "google/gemini-pro"],
+  siteUrl: "https://yourapp.com",
+  siteName: "Your App Name",
+  retryConfig: {
+    timeout: 60000,
+    retries: 3,
+  },
+});
+```
+
+**See Also:** [Providers Guide](./PROVIDERS.md) for detailed provider comparison and configuration examples.
+
+---
+
 ### `PromptBuilder`
 
 Constructs prompts for AI generation.

package/docs/PROVIDERS.md

@@ -10,11 +10,111 @@ This guide covers the available AI providers and how to configure them for optim
 - ✅ Configure provider-specific settings
 - ✅ Use backup models for failover
 - ✅ Customize retry logic and timeouts
+- ⚡ **Stream responses in real-time** (all providers)
+
+## Streaming Support
+
+**All providers support real-time streaming** via the `respondStream()` method on the Agent class.
+
+Streaming provides:
+
+- 🌊 Real-time text generation for better UX
+- 📊 Incremental delivery with `delta` and `accumulated` properties
+- 🛑 Cancellable streams using AbortSignal
+- ✅ Full compatibility with routes, states, and tool calls
+
+**Example:**
+
+```typescript
+for await (const chunk of agent.respondStream({ history })) {
+  process.stdout.write(chunk.delta); // Print incremental text
+
+  if (chunk.done) {
+    // Access final metadata
+    console.log("Route:", chunk.route?.title);
+    console.log("Tool calls:", chunk.toolCalls?.length);
+  }
+}
+```
+
+See [streaming-agent.ts](../examples/streaming-agent.ts) for comprehensive examples with all providers.
 
 ---
 
 ## Available Providers
 
+### 🤖 Anthropic (Claude)
+
+**Package:** `@anthropic-ai/sdk`
+
+#### Overview
+
+Anthropic's Claude models are known for their exceptional reasoning, analysis, and long context windows. Claude 3.5 Sonnet offers:
+
+- State-of-the-art reasoning and analysis
+- 200K context window
+- Excellent at following complex instructions
+- Strong coding and writing capabilities
+
+#### Installation
+
+```bash
+bun add @anthropic-ai/sdk
+# or
+npm install @anthropic-ai/sdk
+```
+
+#### Basic Usage
+
+```typescript
+import { AnthropicProvider } from "@falai/agent";
+
+const provider = new AnthropicProvider({
+  apiKey: process.env.ANTHROPIC_API_KEY!,
+  model: "claude-sonnet-4-5", // Latest Claude 4.5 Sonnet
+});
+```
+
+#### Configuration Options
+
+All models are specified by the user - see [Anthropic Models](https://docs.anthropic.com/en/docs/models-overview) for available options.
+
+```typescript
+const provider = new AnthropicProvider({
+  // Required
+  apiKey: string;
+  model: string; // e.g., "claude-sonnet-4-5", "claude-opus-4-1", etc.
+
+  // Optional
+  backupModels?: string[]; // Default: []
+  config?: Partial<Omit<MessageCreateParamsNonStreaming, "model" | "messages" | "max_tokens">>; // Uses @anthropic-ai/sdk types
+  retryConfig?: {
+    timeout?: number; // Default: 60000ms (60s)
+    retries?: number; // Default: 3
+  };
+});
+```
+
+#### Example: Advanced Configuration
+
+```typescript
+const provider = new AnthropicProvider({
+  apiKey: process.env.ANTHROPIC_API_KEY!,
+  model: "claude-sonnet-4-5",
+  backupModels: ["claude-opus-4-1", "claude-sonnet-4-0"],
+  config: {
+    temperature: 0.7,
+    top_p: 0.9,
+  },
+  retryConfig: {
+    timeout: 45000,
+    retries: 2,
+  },
+});
+```
+
+---
+
 ### 🌐 OpenRouter (Multi-Model Access)
 
 **Package:** `openai` (OpenRouter uses OpenAI-compatible API)
@@ -274,7 +374,22 @@ const provider = new OpenAIProvider({
 You can easily switch between providers:
 
 ```typescript
-import { Agent, GeminiProvider, OpenAIProvider } from "@falai/agent";
+import {
+  Agent,
+  AnthropicProvider,
+  GeminiProvider,
+  OpenAIProvider,
+  OpenRouterProvider,
+} from "@falai/agent";
+
+// Use Anthropic (Claude)
+const claudeAgent = new Agent({
+  name: "Claude Assistant",
+  ai: new AnthropicProvider({
+    apiKey: process.env.ANTHROPIC_API_KEY!,
+    model: "claude-sonnet-4-5",
+  }),
+});
 
 // Use Gemini
 const geminiAgent = new Agent({
@@ -290,10 +405,20 @@ const openaiAgent = new Agent({
   name: "OpenAI Assistant",
   ai: new OpenAIProvider({
     apiKey: process.env.OPENAI_API_KEY!,
+    model: "gpt-5",
   }),
 });
 
-// Both agents have the same interface!
+// Use OpenRouter (access to 200+ models)
+const openrouterAgent = new Agent({
+  name: "OpenRouter Assistant",
+  ai: new OpenRouterProvider({
+    apiKey: process.env.OPENROUTER_API_KEY!,
+    model: "anthropic/claude-sonnet-4-5",
+  }),
+});
+
+// All agents have the same interface!
 ```
 
 ---
@@ -304,8 +429,10 @@ It's recommended to store API keys in environment variables:
 
 ```bash
 # .env
+ANTHROPIC_API_KEY=your-anthropic-api-key-here
 GEMINI_API_KEY=your-gemini-api-key-here
 OPENAI_API_KEY=your-openai-api-key-here
+OPENROUTER_API_KEY=your-openrouter-api-key-here
 ```
 
 Then load them:
@@ -314,6 +441,11 @@ Then load them:
 import { config } from "dotenv";
 config();
 
+const anthropicProvider = new AnthropicProvider({
+  apiKey: process.env.ANTHROPIC_API_KEY!,
+  model: "claude-sonnet-4-5",
+});
+
 const geminiProvider = new GeminiProvider({
   apiKey: process.env.GEMINI_API_KEY!,
   model: "models/gemini-2.5-flash",
@@ -323,6 +455,11 @@ const openaiProvider = new OpenAIProvider({
   apiKey: process.env.OPENAI_API_KEY!,
   model: "gpt-5",
 });
+
+const openrouterProvider = new OpenRouterProvider({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  model: "anthropic/claude-sonnet-4-5",
+});
 ```
 
 ---

package/examples/business-onboarding.ts

@@ -13,10 +13,10 @@
 import {
   Agent,
   defineTool,
-  GeminiProvider,
   END_ROUTE,
   EventSource,
   createMessageEvent,
+  OpenAIProvider,
   type ToolContext,
 } from "../src/index";
 
@@ -362,9 +362,10 @@ async function createBusinessOnboardingAgent(
   sessionId: string,
   initialData: OnboardingData = { routes: [] }
 ): Promise<Agent<OnboardingContext>> {
-  const provider = new GeminiProvider({
-    apiKey: process.env.GEMINI_API_KEY || "test-key",
-    model: "models/gemini-2.0-flash-exp",
+  const provider = new OpenAIProvider({
+    apiKey: process.env.OPENAI_API_KEY || "test-key",
+    model: "gpt-5",
+    backupModels: ["gpt-5-mini"],
     retryConfig: {
       timeout: 60000,
       retries: 3,

package/examples/declarative-agent.ts

@@ -13,10 +13,10 @@
 
 import {
   Agent,
-  GeminiProvider,
   defineTool,
   createMessageEvent,
   EventSource,
+  GeminiProvider,
   type Term,
   type Guideline,
   type Capability,

package/examples/domain-scoping.ts

@@ -6,12 +6,13 @@
  */
 
 import { Agent, createMessageEvent, EventSource } from "../src/index";
-import { GeminiProvider } from "../src/providers/GeminiProvider";
+import { OpenRouterProvider } from "../src/providers";
 
 // Initialize AI provider
-const ai = new GeminiProvider({
-  apiKey: process.env.GEMINI_API_KEY || "your-api-key-here",
-  model: "gemini-2.0-flash-exp",
+const ai = new OpenRouterProvider({
+  apiKey: process.env.OPENROUTER_API_KEY || "your-api-key-here",
+  model: "google/gemini-2.0-flash-exp",
+  backupModels: ["anthropic/claude-sonnet-4-5"],
 });
 
 // Create agent

package/examples/healthcare-agent.ts

@@ -5,7 +5,7 @@
 import {
   Agent,
   defineTool,
-  GeminiProvider,
+  AnthropicProvider,
   END_ROUTE,
   EventSource,
   createMessageEvent,
@@ -63,9 +63,9 @@ const getLabResults = defineTool<HealthcareContext, [], object>(
 );
 
 async function createHealthcareAgent() {
-  const provider = new GeminiProvider({
-    apiKey: process.env.GEMINI_API_KEY || "test-key",
-    model: "models/gemini-2.5-flash",
+  const provider = new AnthropicProvider({
+    apiKey: process.env.ANTHROPIC_API_KEY || "test-key",
+    model: "claude-sonnet-4-5",
   });
 
   const agent = new Agent<HealthcareContext>({

package/examples/openai-agent.ts

@@ -108,10 +108,12 @@ async function main() {
     chatState: "Ask which city they want weather for",
   });
 
-  const fetchWeather = askLocation.transitionTo({
-    toolState: getWeather,
-    condition: "User provides a city name",
-  });
+  const fetchWeather = askLocation.transitionTo(
+    {
+      toolState: getWeather,
+    },
+    "User provides a city name"
+  );
 
   const showWeather = fetchWeather.transitionTo({
     chatState:

package/examples/rules-prohibitions.ts

@@ -6,12 +6,12 @@
  */
 
 import { Agent, createMessageEvent, EventSource } from "../src/index";
-import { GeminiProvider } from "../src/providers/GeminiProvider";
+import { AnthropicProvider } from "../src/providers";
 
 // Initialize AI provider
-const ai = new GeminiProvider({
-  apiKey: process.env.GEMINI_API_KEY || "your-api-key-here",
-  model: "gemini-2.0-flash-exp",
+const ai = new AnthropicProvider({
+  apiKey: process.env.ANTHROPIC_API_KEY || "your-api-key-here",
+  model: "claude-sonnet-4-5",
 });
 
 // Create WhatsApp support bot with different styles per route