@falai/agent 0.3.10 → 0.3.12

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/prisma-persistence.ts

@@ -0,0 +1,313 @@
+/**
+ * Example: Using Prisma ORM for Persistence
+ *
+ * This example shows how to use @falai/agent with Prisma for automatic
+ * session and message persistence - as easy as using an AI provider!
+ */
+
+import {
+  Agent,
+  GeminiProvider,
+  PrismaAdapter,
+  createMessageEvent,
+  EventSource,
+} from "../src/index";
+
+// @ts-ignore
+import { PrismaClient } from "@prisma/client";
+
+/**
+ * Setup Steps:
+ *
+ * 1. Install dependencies:
+ *    npm install prisma @prisma/client
+ *
+ * 2. Initialize Prisma:
+ *    npx prisma init
+ *
+ * 3. Copy schema from examples/prisma-schema.example.prisma
+ *    to your prisma/schema.prisma file
+ *
+ * 4. Generate Prisma client:
+ *    npx prisma generate
+ *
+ * 5. Run migrations:
+ *    npx prisma migrate dev --name init
+ */
+
+// Example context type
+interface ConversationContext {
+  userId: string;
+  sessionId: string;
+  userName: string;
+  preferences: {
+    language: string;
+    theme: string;
+  };
+}
+
+async function example() {
+  // Initialize Prisma client
+  const prisma = new PrismaClient();
+
+  const userId = "user_123";
+
+  /**
+   * Create Agent with Persistence - Simple Provider Pattern! ✨
+   */
+  const agent = new Agent<ConversationContext>({
+    name: "Shopping Assistant",
+    description: "A helpful shopping assistant",
+    ai: new GeminiProvider({
+      apiKey: process.env.GEMINI_API_KEY!,
+      model: "models/gemini-2.0-flash-exp",
+    }),
+    context: {
+      userId,
+      sessionId: "", // Will be set when we create/load a session
+      userName: "Alice",
+      preferences: {
+        language: "en",
+        theme: "light",
+      },
+    },
+    // ✨ Just pass the adapter - that's it!
+    persistence: {
+      adapter: new PrismaAdapter({ prisma }),
+      autoSave: true,
+      userId,
+    },
+  });
+
+  /**
+   * Get persistence manager from agent
+   */
+  const persistence = agent.getPersistenceManager();
+
+  if (!persistence) {
+    throw new Error("Persistence not configured");
+  }
+
+  /**
+   * Create or find a session
+   */
+  let session = await persistence.findActiveSession(userId);
+
+  if (!session) {
+    session = await persistence.createSession({
+      userId,
+      agentName: "Shopping Assistant",
+      initialData: {
+        language: "en",
+        theme: "light",
+      },
+    });
+    console.log("✨ Created new session:", session.id);
+  } else {
+    console.log("📂 Found active session:", session.id);
+  }
+
+  // Update context with session ID
+  await agent.updateContext({
+    sessionId: session.id,
+  } as Partial<ConversationContext>);
+
+  /**
+   * Load conversation history
+   */
+  const history = await persistence.loadSessionHistory(session.id);
+  console.log(`📜 Loaded ${history.length} messages from history`);
+
+  /**
+   * Send a message
+   */
+  const userMessage = createMessageEvent(
+    EventSource.CUSTOMER,
+    "Alice",
+    "I'm looking for a winter jacket"
+  );
+
+  // Save user message
+  await persistence.saveMessage({
+    sessionId: session.id,
+    userId,
+    role: "user",
+    content: "I'm looking for a winter jacket",
+    event: userMessage,
+  });
+
+  history.push(userMessage);
+
+  // Generate agent response
+  const response = await agent.respond({ history });
+  console.log("🤖 Agent:", response.message);
+
+  // Save agent message
+  await persistence.saveMessage({
+    sessionId: session.id,
+    userId,
+    role: "agent",
+    content: response.message,
+    route: response.route?.id,
+    state: response.state?.id,
+    toolCalls: response.toolCalls,
+  });
+
+  /**
+   * Query sessions and messages
+   */
+  const userSessions = await persistence.getUserSessions(userId);
+  console.log(`👤 User has ${userSessions.length} total sessions`);
+
+  const messages = await persistence.getSessionMessages(session.id);
+  console.log(`💬 Session has ${messages.length} messages`);
+
+  /**
+   * Complete the session
+   */
+  await persistence.completeSession(session.id);
+  console.log("✅ Session completed");
+
+  /**
+   * Cleanup
+   */
+  await prisma.$disconnect();
+}
+
+/**
+ * Advanced Example: Using with Lifecycle Hooks
+ */
+async function advancedExample() {
+  const prisma = new PrismaClient();
+  const userId = "user_123";
+
+  const agent = new Agent<ConversationContext>({
+    name: "Smart Assistant",
+    description: "An intelligent assistant with persistent state",
+    ai: new GeminiProvider({
+      apiKey: process.env.GEMINI_API_KEY!,
+      model: "models/gemini-2.0-flash-exp",
+    }),
+    context: {
+      userId,
+      sessionId: "",
+      userName: "Alice",
+      preferences: {
+        language: "en",
+        theme: "light",
+      },
+    },
+    // Lifecycle hooks for automatic context sync
+    hooks: {
+      // Load fresh context before each response
+      beforeRespond: async (currentContext) => {
+        const persistence = agent.getPersistenceManager();
+        if (!persistence) return currentContext;
+
+        const freshSession = await persistence.getSession(
+          currentContext.sessionId
+        );
+        return {
+          ...currentContext,
+          preferences:
+            (
+              freshSession?.collectedData as {
+                preferences?: typeof currentContext.preferences;
+              }
+            )?.preferences || currentContext.preferences,
+        };
+      },
+      // Automatically persist context updates
+      onContextUpdate: async (newContext) => {
+        const persistence = agent.getPersistenceManager();
+        if (!persistence) return;
+
+        await persistence.updateCollectedData(newContext.sessionId, {
+          preferences: newContext.preferences,
+        });
+      },
+    },
+    // ✨ Same simple adapter pattern!
+    persistence: {
+      adapter: new PrismaAdapter({ prisma }),
+      autoSave: true,
+      userId,
+    },
+  });
+
+  // Create a session
+  const persistence = agent.getPersistenceManager();
+  const session = await persistence!.createSession({
+    userId,
+    agentName: "Smart Assistant",
+  });
+
+  await agent.updateContext({
+    sessionId: session.id,
+  } as Partial<ConversationContext>);
+
+  // Now context updates are automatically persisted!
+  await agent.updateContext({
+    preferences: {
+      language: "es",
+      theme: "dark",
+    },
+  } as Partial<ConversationContext>);
+
+  console.log("🎉 Context updates automatically saved to database!");
+
+  await prisma.$disconnect();
+}
+
+/**
+ * Minimal Example - Quick Start
+ */
+async function quickStart() {
+  const prisma = new PrismaClient();
+
+  // That's it! Just create the adapter and pass it
+  const agent = new Agent({
+    name: "My Agent",
+    description: "A helpful assistant",
+    ai: new GeminiProvider({
+      apiKey: process.env.GEMINI_API_KEY!,
+      model: "models/gemini-2.5-flash",
+    }),
+    persistence: {
+      adapter: new PrismaAdapter({ prisma }), // ✨ Simple!
+      userId: "user_123",
+    },
+  });
+
+  // Get persistence manager
+  const persistence = agent.getPersistenceManager();
+  if (!persistence) return;
+
+  // Create session
+  const session = await persistence.createSession({
+    userId: "user_123",
+    agentName: "My Agent",
+  });
+
+  // Load history and respond
+  const history = await persistence.loadSessionHistory(session.id);
+  const response = await agent.respond({ history });
+
+  // Save message
+  await persistence.saveMessage({
+    sessionId: session.id,
+    role: "agent",
+    content: response.message,
+  });
+
+  console.log("✅ Done! Messages automatically saved to Prisma.");
+
+  await prisma.$disconnect();
+}
+
+// Run the example
+if (require.main === module) {
+  example().catch(console.error);
+}
+
+export { example, advancedExample, quickStart };

package/examples/prisma-schema.example.prisma

@@ -0,0 +1,74 @@
+// This is an example Prisma schema file for @falai/agent persistence
+// Copy and adapt this to your needs
+
+datasource db {
+  provider = "postgresql" // or "mysql", "sqlite", "sqlserver", "mongodb"
+  url      = env("DATABASE_URL")
+}
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+// Agent Session model
+// Stores conversation session state
+model AgentSession {
+  id              String    @id @default(cuid())
+  userId          String?   @map("user_id")
+  agentName       String?   @map("agent_name")
+  status          String    @default("active") // "active" | "completed" | "abandoned"
+  currentRoute    String?   @map("current_route")
+  currentState    String?   @map("current_state")
+  collectedData   Json?     @map("collected_data")
+  messageCount    Int       @default(0) @map("message_count")
+  lastMessageAt   DateTime? @map("last_message_at")
+  completedAt     DateTime? @map("completed_at")
+  createdAt       DateTime  @default(now()) @map("created_at")
+  updatedAt       DateTime  @updatedAt @map("updated_at")
+
+  // Relations
+  messages AgentMessage[]
+
+  @@index([userId])
+  @@index([status])
+  @@index([userId, status])
+  @@map("agent_sessions")
+}
+
+// Agent Message model
+// Stores individual messages in a conversation
+model AgentMessage {
+  id        String   @id @default(cuid())
+  sessionId String   @map("session_id")
+  userId    String?  @map("user_id")
+  role      String   // "user" | "agent" | "system"
+  content   String   @db.Text
+  route     String?
+  state     String?
+  toolCalls Json?    @map("tool_calls")
+  event     Json?    // Optional: store full event data
+  createdAt DateTime @default(now()) @map("created_at")
+
+  // Relations
+  session AgentSession @relation(fields: [sessionId], references: [id], onDelete: Cascade)
+
+  @@index([sessionId])
+  @@index([userId])
+  @@index([sessionId, createdAt])
+  @@map("agent_messages")
+}
+
+// Alternative: If you want different table names, you can customize:
+// 
+// model ConversationSession {
+//   id              String    @id @default(cuid())
+//   ...
+//   @@map("conversations")
+// }
+//
+// model ChatMessage {
+//   id        String   @id @default(cuid())
+//   ...
+//   @@map("chat_messages")
+// }
+

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