@ariaflowagents/cf-agent 0.5.3 → 0.8.1

package/README.md

@@ -1,196 +1,497 @@
 # @ariaflowagents/cf-agent
 
-Cloudflare Durable Object base classes for hosting AriaFlow on the edge.
+AriaFlow integration for Cloudflare Workers using AIChatAgent. Build multi-agent AI systems with automatic persistence, resumable streaming, and real-time sync.
 
-## Two Primitive Classes
+## Features
 
-This package provides **two separate base classes** for different use cases:
+- **All AriaFlow Agent Types**: LLM, Flow, Triage, and Composite agents
+- **Automatic Persistence**: Messages stored in SQLite, survive restarts
+- **Resumable Streaming**: Reconnect without data loss
+- **Multi-Client Sync**: Real-time updates across all connected clients
+- **Full Tool Support**: Server-side, client-side, and approval tools
+- **Zero Config**: Works out of the box with sensible defaults
 
-| Class | Use When | Config Returns |
-|-------|----------|----------------|
-| `AriaFlowChatAgent` | Multi-agent systems with handoffs | `HarnessConfig` or `Runtime` |
-| `AriaFlowFlowAgent` | Structured single-flow conversations | `AriaFlowFlowConfig` or `AgentFlowManager` |
+## Quick Start
 
----
+```bash
+# Create a new project
+mkdir my-agent && cd my-agent
+npm init -y
 
-## AriaFlowChatAgent - Multi-Agent Runtime
+# Install dependencies
+npm install @ariaflowagents/cf-agent ai zod
+npm install -D @cloudflare/vite-plugin vite wrangler
 
-Use for **multi-agent systems** where agents can hand off to each other.
+# Create your agent
+# See examples below...
+
+# Run locally
+npm run dev
+```
+
+Open http://localhost:5173 to see your agent in action.
+
+## Installation
+
+```bash
+npm install @ariaflowagents/cf-agent
+```
+
+## Project Structure
+
+```
+my-agent/
+├── src/
+│   ├── server.ts          # Agent implementation
+│   ├── app.tsx            # React chat UI
+│   └── client.tsx         # React entry point
+├── package.json
+├── tsconfig.json
+├── vite.config.ts
+└── wrangler.jsonc
+```
+
+## Basic Example
+
+### 1. Create Agent (`src/server.ts`)
 
 ```typescript
-import { AriaFlowChatAgent } from '@ariaflowagents/cf-agent';
-import { Runtime, type AgentConfig } from '@ariaflowagents/core';
+import { AriaFlowAIChatAgent } from "@ariaflowagents/cf-agent";
+import { createOpenAI } from "@ai-sdk/openai";
+import { tool } from "ai";
+import { z } from "zod";
 
-export class SupportAgent extends AriaFlowChatAgent {
-  async createRuntimeConfig() {
-    const triage: AgentConfig = {
-      id: 'triage',
-      name: 'Triage',
-      type: 'triage',
-      systemPrompt: 'Route customers to specialists.',
-      routes: [
-        { agentId: 'orders', description: 'Order questions' },
-        { agentId: 'billing', description: 'Billing questions' },
-      ],
-    };
+interface Env {
+  OPENAI_API_KEY: string;
+}
 
-    const orders: AgentConfig = {
-      id: 'orders',
-      name: 'Orders',
-      type: 'llm',
-      systemPrompt: 'Help with order questions.',
-    };
+export class MyAgent extends AriaFlowAIChatAgent<Env> {
+  protected getRuntimeConfig() {
+    const openai = createOpenAI({ apiKey: this.env.OPENAI_API_KEY });
 
     return {
-      agents: [triage, orders],
-      defaultAgentId: 'triage',
+      agents: [{
+        id: "assistant",
+        type: "llm" as const,
+        name: "Assistant",
+        model: openai("gpt-4o"),
+        prompt: "You are a helpful assistant",
+        tools: {
+          getWeather: tool({
+            description: "Get weather for a city",
+            inputSchema: z.object({ city: z.string() }),
+            execute: async ({ city }) => {
+              return { temperature: 72, condition: "sunny" };
+            },
+          }),
+        },
+      }],
+      defaultAgentId: "assistant",
     };
   }
 }
+
+export default MyAgent;
 ```
 
-**State (Runtime mode):**
+### 2. Create UI (`src/app.tsx`)
+
+```tsx
+import { useAgent } from "agents/react";
+import { useAgentChat } from "@cloudflare/ai-chat/react";
+
+export function Chat() {
+  const agent = useAgent({ agent: "MyAgent" });
+  const { messages, sendMessage, status } = useAgentChat({ agent });
+
+  return (
+    <div>
+      {messages.map((msg) => (
+        <div key={msg.id}>
+          <strong>{msg.role}:</strong>
+          {msg.parts.map((part, i) =>
+            part.type === "text" ? <span key={i}>{part.text}</span> : null
+          )}
+        </div>
+      ))}
+      <form onSubmit={(e) => {
+        e.preventDefault();
+        const input = e.currentTarget.elements.namedItem("input") as HTMLInputElement;
+        sendMessage({ text: input.value });
+        input.value = "";
+      }}>
+        <input name="input" placeholder="Type a message..." />
+        <button type="submit" disabled={status === "streaming"}>Send</button>
+      </form>
+    </div>
+  );
+}
+```
+
+### 3. Configuration Files
+
+**`vite.config.ts`**:
 ```typescript
-state = {
-  activeAgentId: 'orders',      // Current agent
-  lastHandoffReason: 'Order inquiry',
-  updatedAt: 1234567890,
+import { defineConfig } from "vite";
+import { cloudflare } from "@cloudflare/vite-plugin";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [cloudflare(), react()],
+});
+```
+
+**`wrangler.jsonc`**:
+```json
+{
+  "name": "my-agent",
+  "main": "src/server.ts",
+  "compatibility_date": "2026-01-28",
+  "compatibility_flags": ["nodejs_compat"],
+  "ai": { "binding": "AI" },
+  "durable_objects": {
+    "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }]
+  },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }]
+}
+```
+
+**`package.json`** scripts:
+```json
+{
+  "scripts": {
+    "dev": "vite dev",
+    "deploy": "vite build && wrangler deploy",
+    "types": "wrangler types"
+  }
 }
 ```
 
----
+## Agent Types
 
-## AriaFlowFlowAgent - Structured Flow
+### LLMAgent
 
-Use for **structured, multi-step flows** with guided conversations.
+Standard conversational agent with tools:
 
 ```typescript
-import { AriaFlowFlowAgent } from '@ariaflowagents/cf-agent';
-import { AriaFlowFlowConfig } from '@ariaflowagents/cf-agent';
-import { tool } from 'ai';
-import { z } from 'zod';
-import { createFlowTransition } from '@ariaflowagents/core';
+{
+  id: "sales",
+  type: "llm" as const,
+  name: "Sales Agent",
+  model: openai("gpt-4o"),
+  prompt: "You are a sales specialist...",
+  tools: { /* ... */ },
+  canHandoffTo: ["support", "billing"]
+}
+```
 
-export class ReservationAgent extends AriaFlowFlowAgent {
-  async createFlowConfig(): Promise<AriaFlowFlowConfig> {
-    return {
-      initialNode: 'greeting',
-      model: this.env.AI as any,
-      defaultRolePrompt: 'You are a reservation assistant.',
-      nodes: [
-        {
-          name: 'greeting',
-          taskPrompt: 'Greet warmly and ask for party size.',
-          tools: {
-            collect_party_size: tool({
-              description: 'Record party size',
-              inputSchema: z.object({ 
-                partySize: z.number().min(1).max(20) 
-              }),
-              execute: async ({ partySize }) => 
-                createFlowTransition('collect_date', { partySize }),
-            }),
-          },
-        },
-        {
-          name: 'collect_date',
-          taskPrompt: 'Ask for reservation date.',
-        },
-      ],
-    };
+### FlowAgent
+
+Structured node-based conversation flows:
+
+```typescript
+{
+  id: "order-flow",
+  type: "flow" as const,
+  name: "Order Flow",
+  model: openai("gpt-4o"),
+  flow: {
+    nodes: [
+      { 
+        id: "initial", 
+        task: "Ask what they want",
+        transitions: [{ to: "confirm", on: "product_selected" }]
+      },
+      { 
+        id: "confirm", 
+        task: "Confirm order",
+        transitions: [{ to: "end", on: "confirmed" }]
+      }
+    ],
+    hybrid: true // Allow off-flow questions
   }
 }
 ```
 
-**State (Flow mode):**
+### TriageAgent
+
+Intelligent routing between agents:
+
 ```typescript
-state = {
-  currentNode: 'collect_date',   // Current node
-  nodeHistory: ['greeting', 'collect_party_size', 'collect_date'],
-  updatedAt: 1234567890,
+{
+  id: "router",
+  type: "triage" as const,
+  name: "Router",
+  model: openai("gpt-4o-mini"),
+  routingConfig: {
+    agents: ["sales", "support", "billing"],
+    instructions: "Route based on user intent..."
+  }
 }
 ```
 
----
+### CompositeAgent
 
-## Context Strategies
-
-Control conversation history behavior:
+Multi-agent coordination:
 
 ```typescript
 {
-  name: 'confirmation',
-  taskPrompt: 'Confirm details.',
-  contextStrategy: { 
-    strategy: 'reset_with_summary'  // Summarize instead of full history
-  },
+  id: "supervisor",
+  type: "composite" as const,
+  name: "Supervisor",
+  model: openai("gpt-4o"),
+  agents: ["researcher", "analyst", "writer"],
+  coordinationMode: "sequential"
 }
 ```
 
-| Strategy | Behavior |
-|----------|----------|
-| `append` | Keep all messages (default) |
-| `reset` | Clear messages on node entry |
-| `reset_with_summary` | Summarize and replace messages |
+## Tools
 
----
+### Server-Side Tools
 
-## Endpoints (Both Classes)
+Run automatically on the server:
 
-| Endpoint | Returns |
-|----------|---------|
-| `GET /info` | Agent metadata, mode, readiness |
-| `GET /state` | Full agent state |
-| `WS /` | WebSocket for streaming |
+```typescript
+tools: {
+  getWeather: tool({
+    description: "Get weather for a city",
+    inputSchema: z.object({ city: z.string() }),
+    execute: async ({ city }) => {
+      // Runs on server
+      return await fetchWeather(city);
+    }
+  })
+}
+```
 
-**AriaFlowFlowAgent additional:**
-| `GET /flow-state` | Flow-specific state (currentNode, nodeHistory, collectedData) |
+### Client-Side Tools
 
----
+No `execute` function - browser provides the result:
 
-## Quick Reference
+```typescript
+// Server
+tools: {
+  getLocation: tool({
+    description: "Get user location",
+    inputSchema: z.object({})
+    // No execute - client handles it
+  })
+}
 
-| Question | Answer |
-|----------|--------|
-| Need multiple agents with handoffs? | Use `AriaFlowChatAgent` |
-| Need structured step-by-step flow? | Use `AriaFlowFlowAgent` |
-| State persists? | Yes, via Durable Object storage |
-| WebSocket streaming? | Yes, automatic |
-| Can switch modes? | No - choose the right class for your use case |
+// Client
+useAgentChat({
+  onToolCall: async ({ toolCall, addToolOutput }) => {
+    if (toolCall.toolName === "getLocation") {
+      const pos = await navigator.geolocation.getCurrentPosition();
+      addToolOutput({
+        toolCallId: toolCall.toolCallId,
+        output: { lat: pos.coords.latitude, lng: pos.coords.longitude }
+      });
+    }
+  }
+});
+```
 
----
+### Approval Tools
 
-## Example: Cloudflare Worker
+Human-in-the-loop for sensitive operations:
 
 ```typescript
-// Runtime Mode (Multi-Agent)
-import { AriaFlowChatAgent } from '@ariaflowagents/cf-agent';
+tools: {
+  processRefund: tool({
+    description: "Process a refund",
+    inputSchema: z.object({ orderId: z.string(), amount: z.number() }),
+    needsApproval: ({ amount }) => amount > 100,
+    execute: async ({ orderId, amount }) => {
+      // Only runs after user approval
+      return await processRefund(orderId, amount);
+    }
+  })
+}
+```
 
-export class MyAgent extends AriaFlowChatAgent {
-  async createRuntimeConfig() {
-    return {
-      agents: [{ id: 'assistant', name: 'Assistant', systemPrompt: 'Helpful.' }],
-      defaultAgentId: 'assistant',
-    };
-  }
+## Hooks
+
+React to agent lifecycle events:
+
+```typescript
+protected getHooks() {
+  return {
+    onHandoff: async (context, from, to, reason) => {
+      console.log(`Handoff: ${from} -> ${to} (${reason})`);
+    },
+    
+    onToolCall: async (context, toolCall) => {
+      console.log(`Tool: ${toolCall.toolName}`);
+    },
+    
+    onNodeEnter: async (context, node) => {
+      console.log(`Flow node: ${node.name}`);
+    }
+  };
 }
+```
 
-// OR Flow Mode (Single Flow)
-import { AriaFlowFlowAgent } from '@ariaflowagents/cf-agent';
+## State Persistence
 
-export class MyFlowAgent extends AriaFlowFlowAgent {
-  async createFlowConfig() {
-    return {
-      initialNode: 'greeting',
-      model: this.env.AI as any,
-      nodes: [{ name: 'greeting', taskPrompt: 'Hi!' }],
-    };
-  }
+AriaFlow stores two types of data:
+
+1. **CF Tables** (`cf_ai_chat_*`): Chat messages, stream chunks, resumption data
+2. **AriaFlow Tables** (`ariaflow_sessions`): Session state, working memory, flow state
+
+```
+SQLite Database:
+├── cf_ai_chat_agent_messages  (UIMessages for UI)
+├── cf_ai_chat_stream_chunks   (Stream chunks)
+├── cf_ai_chat_stream_metadata (Stream state)
+└── ariaflow_sessions          (AriaFlow Session state)
+```
+
+## Custom Configuration
+
+### Stream Adapter
+
+Control which events are sent to the client:
+
+```typescript
+protected getStreamAdapterConfig() {
+  return {
+    includeHandoffs: true,    // Show agent handoffs in UI
+    includeFlowEvents: true,  // Show flow node transitions
+    includeTripwires: true,   // Show guardrail triggers
+    includeStepEvents: false, // Hide step lifecycle
+    includeAgentEvents: false // Hide agent lifecycle
+  };
 }
+```
 
-export default {
-  async fetch(request: Request, env: Env): Promise<Response> {
-    return MyAgent.fetch(request, env);  // or MyFlowAgent
-  },
-};
+### Session ID
+
+Override default session ID generation:
+
+```typescript
+protected getSessionId(): string {
+  // Default uses Durable Object ID
+  // Override for custom session management
+  return `user-${this.getUserId()}`;
+}
 ```
+
+## Scripts
+
+```bash
+# Development (with hot reload)
+npm run dev
+
+# Deploy to Cloudflare
+npm run deploy
+
+# Generate types
+npm run types
+
+# Build only
+npm run build
+```
+
+## Using Different AI Providers
+
+### Workers AI (No API key needed)
+
+```typescript
+import { createWorkersAI } from "workers-ai-provider";
+
+const workersai = createWorkersAI({ binding: this.env.AI });
+
+// In agent config:
+model: workersai("@cf/meta/llama-3.3-70b-instruct-fp8-fast")
+```
+
+### OpenAI
+
+```bash
+npm install @ai-sdk/openai
+```
+
+```typescript
+import { createOpenAI } from "@ai-sdk/openai";
+
+const openai = createOpenAI({ apiKey: this.env.OPENAI_API_KEY });
+
+// In agent config:
+model: openai("gpt-4o")
+```
+
+### Anthropic
+
+```bash
+npm install @ai-sdk/anthropic
+```
+
+```typescript
+import { createAnthropic } from "@ai-sdk/anthropic";
+
+const anthropic = createAnthropic({ apiKey: this.env.ANTHROPIC_API_KEY });
+
+// In agent config:
+model: anthropic("claude-sonnet-4-20250514")
+```
+
+## API Reference
+
+### AriaFlowAIChatAgent
+
+Abstract base class extending CF's `AIChatAgent`.
+
+```typescript
+abstract class AriaFlowAIChatAgent<Env, State> {
+  // Required
+  protected abstract getRuntimeConfig(): HarnessConfig;
+  
+  // Optional overrides
+  protected getHooks(): Partial<HarnessHooks>;
+  protected getStreamAdapterConfig(): Partial<StreamAdapterConfig>;
+  protected getSessionId(): string;
+  
+  // Utility methods
+  protected async getSession(): Promise<Session | null>;
+  protected getSessionStats(): SessionStats | null;
+}
+```
+
+### Environment Variables
+
+```bash
+# For OpenAI
+OPENAI_API_KEY=your-key
+
+# For Anthropic
+ANTHROPIC_API_KEY=your-key
+
+# For custom providers
+PROVIDER_API_KEY=your-key
+```
+
+## Architecture
+
+```
+Client (useAgentChat)
+    │
+    ▼ WebSocket
+CF AIChatAgent (Durable Object)
+    ├─► CF SQLite: Chat messages, stream chunks
+    └─► AriaFlow Runtime
+        ├─► CloudflareSessionStore (SQLite)
+        ├─► Multi-agent execution
+        └─► StreamAdapter
+            └─► UIMessageChunk format
+```
+
+## Learn More
+
+- [AriaFlow Documentation](https://github.com/ariaflowagents/ariaflow)
+- [Cloudflare Agents SDK](https://developers.cloudflare.com/agents/)
+- [Vercel AI SDK](https://ai-sdk.dev)
+
+## License
+
+MIT