@projectaria/cf-agents 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,6 @@
 # @projectaria/cf-agents
 
-ARIA integration for Cloudflare Workers with Durable Objects. Build stateful AI agents with persistent memory, session management, and multi-turn conversations.
+ARIA integration for Cloudflare Workers with Durable Objects. Build stateful AI agents with persistent memory, session management, and multi-turn conversations using structured flows.
 
 ## Installation
 
@@ -8,45 +8,228 @@ ARIA integration for Cloudflare Workers with Durable Objects. Build stateful AI
 npm install @projectaria/cf-agents agents @cloudflare/ai-chat ai
 ```
 
-## Quick Start
+## Message Flow Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          MESSAGE FLOW DIAGRAM                                │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│  CLIENT SIDE                              SERVER SIDE                         │
+│  ────────────                             ────────────                        │
+│                                                                              │
+│  User Input                                                              │
+│       │                                                                   │
+│       ▼                                                                   │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                    Cloudflare AIChatAgent                            │   │
+│  │  this.messages (UIMessage[]) ←── WebSocket/HTTP                       │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│       │                                                                   │
+│       │ onChatMessage()                                                  │
+│       ▼                                                                   │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                    AriaCFChatAgent                                    │   │
+│  │                                                                     │   │
+│  │  1. extractLastUserInput() → userText                                │   │
+│  │  2. cloudflareToAriaSession() → AgentSession                         │   │
+│  │       │                                                              │   │
+│  │       ▼                                                              │   │
+│  │  3. ariaAgent.streamText({ input, session })                         │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│       │                                                                   │
+│       │ (AsyncIterable<AriaStreamPart>)                                  │
+│       ▼                                                                   │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                         ARIA Agent                                    │   │
+│  │  createAgent()                                                       │   │
+│  │       │                                                              │   │
+│  │       ▼                                                              │   │
+│  │  streamText()                                                        │   │
+│  │       │                                                              │   │
+│  │       ▼                                                              │   │
+│  │  ┌────────────────────────────────────────────────────────────────┐  │   │
+│  │  │              PromptBuilder + Conversation Context               │  │   │
+│  │  └────────────────────────────────────────────────────────────────┘  │   │
+│  │       │                                                              │   │
+│  │       ▼                                                              │   │
+│  │  ┌────────────────────────────────────────────────────────────────┐  │   │
+│  │  │                    AI SDK LanguageModel                          │  │   │
+│  │  │  streamText(model, messages, tools)                              │  │   │
+│  │  └────────────────────────────────────────────────────────────────┘  │   │
+│  │       │                                                              │   │
+│  │       ▼ (stream of TextStreamPart)                                   │   │
+│  │  ┌────────────────────────────────────────────────────────────────┐  │   │
+│  │  │              ResponseService / Tool Execution                    │  │   │
+│  │  └────────────────────────────────────────────────────────────────┘  │   │
+│  │       │                                                              │   │
+│  │       ▼ (AriaStreamPart: text-delta, tool-call, tool-result, ...)   │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│       │                                                                   │
+│       │ ariaToUIStream()                                                 │
+│       ▼                                                                   │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                 aria-to-ui-stream.ts                                  │   │
+│  │  AriaStreamPart → TextUIPart | ToolCallUIPart | ToolResultUIPart     │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│       │                                                                   │
+│       │ createUIMessageStreamResponse()                                  │
+│       ▼                                                                   │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                    Response (SSE/WebSocket)                           │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│       │                                                                   │
+│       ▼                                                                   │
+│  CLIENT UI ←───────────────────────────────────────────────────────────────
+│                                                                              │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                          SESSION & STATE FLOW                                │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                     VoltRuntime                                       │   │
+│  │                                                                     │   │
+│  │  ┌───────────────────────────────────────────────────────────────┐  │   │
+│  │  │                    FlowSupervisor                              │  │   │
+│  │  │  • Selects active flow based on intent                        │  │   │
+│  │  │  • Handles flow switching mid-conversation                    │  │   │
+│  │  └───────────────────────────────────────────────────────────────┘  │   │
+│  │       │                                                             │   │
+│  │       ▼                                                             │   │
+│  │  ┌───────────────────────────────────────────────────────────────┐  │   │
+│  │  │              StreamingFlowManager                              │  │   │
+│  │  │  • Executes current node                                       │  │   │
+│  │  │  • Validates extracted data                                    │  │   │
+│  │  │  • Evaluates transitions                                       │  │   │
+│  │  └───────────────────────────────────────────────────────────────┘  │   │
+│  │       │                                                             │   │
+│  │       ▼                                                             │   │
+│  │  ┌───────────────────────────────────────────────────────────────┐  │   │
+│  │  │              CombinedAnalysisService                           │  │   │
+│  │  │  • LLM validation of extracted fields                          │  │   │
+│  │  │  • Structured data extraction                                  │  │   │
+│  │  └───────────────────────────────────────────────────────────────┘  │   │
+│  │       │                                                             │   │
+│  │       ▼                                                             │   │
+│  │  ┌───────────────────────────────────────────────────────────────┐  │   │
+│  │  │              ProgressionEngine                                  │  │   │
+│  │  │  • Evaluates condition expressions                             │  │   │
+│  │  │  • Determines next node                                        │  │   │
+│  │  └───────────────────────────────────────────────────────────────┘  │   │
+│  │       │                                                             │   │
+│  │       ▼                                                             │   │
+│  │  ┌───────────────────────────────────────────────────────────────┐  │   │
+│  │  │              SessionStore (SQLite via D1)                      │  │   │
+│  │  │  • Persists session.history                                    │  │   │
+│  │  │  • Persists session.workingMemory                              │  │   │
+│  │  │  • Restores sessions on agent restart                          │  │   │
+│  │  └───────────────────────────────────────────────────────────────┘  │   │
+│  │                                                                     │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
 
-### 1. Create Your Agent
+## Message Handling Sequence
 
 ```typescript
-// src/agent.ts
-import { AriaAgent } from "@projectaria/cf-agents";
-import { createAgent } from "@projectaria/aria-agents";
-import { openai } from "@ai-sdk/openai";
+// 1. Client sends message via WebSocket or HTTP
+//    → Cloudflare AIChatAgent receives it
+//    → Stores in this.messages
+
+// 2. AriaCFChatAgent.onChatMessage() is called
+async onChatMessage(onFinish, options) {
+  // 2a. Extract user text from last message
+  const userText = extractLastUserInput(this.messages);
+
+  // 2b. Convert Cloudflare messages to ARIA session format
+  const ariaSession = cloudflareToAriaSession(this.messages, this.state);
 
-export class MyAssistant extends AriaAgent {
-  // Create an ARIA agent with your configuration
-  private ariaAgent = createAgent({
-    id: "assistant",
-    name: "My Assistant",
-    instructions: "You are a helpful assistant that remembers user preferences.",
-    model: openai("gpt-4o"),
+  // 2c. Start session in VoltRuntime (loads or creates)
+  await this.voltRuntime.startSession(ariaSession.sessionId);
+
+  // 2d. Stream from ARIA agent
+  const result = await this.ariaAgent.streamText({
+    input: userText,
+    session: ariaSession,
   });
 
-  // Handle incoming chat messages
-  async onChatMessage(onFinish: () => void) {
-    // Get the current session with message history
-    const session = this.getSession();
-    const lastMessage = session.messages[session.messages.length - 1];
+  // 2e. Convert ARIA stream parts to UI format
+  return createARIAStreamResponse(result.fullStream, onFinish);
+}
 
-    if (!lastMessage) {
-      return;
-    }
+// 3. ARIA Agent processes the stream
+streamText({ input, session }) {
+  // 3a. Build prompt from flow + session history
+  const prompt = PromptBuilder.build({
+    flow: currentFlow,
+    session,
+    instructions,
+    guidelines,
+  });
 
-    // Run the ARIA agent with automatic memory persistence
-    const result = await this.runAriaAgent(this.ariaAgent, lastMessage.content);
+  // 3b. Call LLM with prompt + tools
+  return streamText(model, messages, tools);
+}
 
-    // Call onFinish to signal completion
-    onFinish();
+// 4. Stream parts are emitted:
+//    - text-delta → UI text chunk
+//    - tool-call → UI tool call (input-available)
+//    - tool-result → UI tool result (output-available)
+//    - reasoning-delta → UI reasoning part
 
-    // Return response (for HTTP) or it's already sent via WebSocket
-    return new Response(result.text);
-  }
+// 5. Session is updated with working memory changes
+//    → Persisted to SQLite via SessionStore
+```
+
+## Quick Start
+
+### 1. Create Your Agent with a Flow
+
+```typescript
+// src/agent.ts
+import { createAriaCFChatAgent } from "@projectaria/cf-agents";
+import type { FlowDefinition } from "@projectaria/aria-agents";
+import { z } from "zod";
+
+interface Env {
+  AI: Ai;
+  DB: D1Database;
 }
+
+// Define a conversation flow
+const greetingFlow: FlowDefinition = {
+  id: "greeting",
+  name: "Greeting Assistant",
+  startNodeId: "greet",
+  nodes: {
+    greet: {
+      id: "greet",
+      type: "task",
+      instructions: "Welcome the user and ask how you can help.",
+      transitions: [
+        { nextNodeId: "help", condition: "intent == 'help'" },
+      ],
+    },
+    help: {
+      id: "help",
+      type: "task",
+      instructions: "Provide helpful assistance.",
+      transitions: [
+        { nextNodeId: "greet", condition: "always" },
+      ],
+    },
+  },
+};
+
+// Create agent with any AI SDK model
+const MyAgent = createAriaCFChatAgent<Env>({
+  flows: new Map([[greetingFlow.id, greetingFlow]]),
+  model: env.AI("@cf/meta/llama-3.1-8b-instruct"), // Any LanguageModel
+  instructions: "You are a friendly assistant.",
+});
+
+export { MyAgent };
 ```
 
 ### 2. Configure Your Worker
@@ -54,13 +237,12 @@ export class MyAssistant extends AriaAgent {
 ```typescript
 // src/index.ts
 import { routeAgentRequest } from "agents";
-import { MyAssistant } from "./agent";
+import { MyAgent } from "./agent";
 
-export { MyAssistant };
+export { MyAgent };
 
 export default {
   async fetch(request: Request, env: Env): Promise<Response> {
-    // Route requests to your agent
     return (
       (await routeAgentRequest(request, env)) ||
       new Response("Not found", { status: 404 })
@@ -71,28 +253,18 @@ export default {
 
 ### 3. Configure Wrangler
 
-```jsonc
-// wrangler.jsonc
-{
-  "name": "my-assistant",
-  "main": "src/index.ts",
-  "compatibility_date": "2025-02-11",
-  "compatibility_flags": ["nodejs_compat"],
-  "durable_objects": {
-    "bindings": [
-      {
-        "name": "MyAssistant",
-        "class_name": "MyAssistant"
-      }
-    ]
-  },
-  "migrations": [
-    {
-      "tag": "v1",
-      "new_sqlite_classes": ["MyAssistant"]
-    }
-  ]
-}
+```toml
+# wrangler.toml
+name = "my-assistant"
+main = "src/index.ts"
+compatibility_date = "2025-02-11"
+
+[[d1_databases]]
+binding = "DB"
+database_name = "aria-sessions"
+
+[ai]
+binding = "AI"
 ```
 
 ### 4. Deploy
@@ -103,100 +275,160 @@ npx wrangler deploy
 
 ## Features
 
-### Memory Primitives
+### Flow Orchestration
+
+Define structured multi-turn conversations:
 
-AriaAgent provides three levels of memory:
+```typescript
+const orderFlow: FlowDefinition = {
+  id: "order",
+  startNodeId: "collect-items",
+  nodes: {
+    "collect-items": {
+      id: "collect-items",
+      type: "task",
+      instructions: "Ask which items they want to order.",
+      transitions: [
+        { nextNodeId: "confirm", condition: "items selected" },
+      ],
+    },
+    confirm: {
+      id: "confirm",
+      type: "task",
+      instructions: "Show order summary and ask for confirmation.",
+      transitions: [
+        { nextNodeId: "complete", condition: "confirmed" },
+        { nextNodeId: "collect-items", condition: "cancelled" },
+      ],
+    },
+  },
+};
+```
 
-| Memory Type | Scope | Use Case |
-|-------------|-------|----------|
-| **Session** | Current conversation | Message history, flow state |
-| **State** | Working memory | Shopping cart, form data |
-| **Memory** | Cross-session | User preferences, learned facts |
+### Working Memory
 
-### Working Memory (Session-scoped)
+Persist data across conversation turns:
 
 ```typescript
-class MyAgent extends AriaAgent {
+const MyAgent = createAriaCFChatAgent<Env>({
+  flows: myFlows,
+  model: env.AI("@cf/meta/llama-3.1-8b-instruct"),
+});
+
+class ShoppingAssistant extends MyAgent {
   async onChatMessage(onFinish) {
-    // Store data for current session
-    this.setWorkingMemory("cart", { items: ["item1", "item2"] });
-    
-    // Retrieve working memory
-    const memory = this.getWorkingMemory();
-    console.log(memory.cart); // { items: ["item1", "item2"] }
+    // Working memory is automatically managed by ARIA
+    // Access via session.workingMemory in tools or flows
   }
 }
 ```
 
-### Cross-Session Memory
+### Tools
+
+Register custom tools for your agent:
 
 ```typescript
-class MyAgent extends AriaAgent {
-  async onChatMessage(onFinish) {
-    // Store a preference that persists across sessions
-    this.storeMemory({
-      key: "user:theme",
-      value: { theme: "dark", fontSize: "large" },
-      type: "preference",
-    });
-
-    // Search memories
-    const results = this.searchMemories({
-      query: "theme",
-      types: ["preference"],
-      limit: 5,
-    });
-  }
-}
+import { tool } from "ai";
+import { z } from "zod";
+
+const MyAgent = createAriaCFChatAgent<Env>({
+  flows: myFlows,
+  model: env.AI("@cf/meta/llama-3.1-8b-instruct"),
+  tools: {
+    searchProducts: tool({
+      description: "Search for products",
+      parameters: z.object({
+        query: z.string(),
+        category: z.string().optional(),
+      }),
+      execute: async ({ query, category }) => {
+        // Your implementation
+        return [{ id: "1", name: "Product", price: 9.99 }];
+      },
+    }),
+  },
+});
 ```
 
-### Flow Orchestration
+### Multiple Model Providers
+
+Use any AI SDK model:
 
 ```typescript
-import { createFlow } from "@projectaria/aria-agents";
-
-class MyAgent extends AriaAgent {
-  private orderFlow = createFlow({
-    id: "order-flow",
-    nodes: [
-      { id: "collect-items", ... },
-      { id: "confirm-order", ... },
-      { id: "payment", ... },
-    ],
-  });
+import { openai } from "@ai-sdk/openai";
+import { anthropic } from "@ai-sdk/anthropic";
+import { google } from "@ai-sdk/google";
 
-  constructor(ctx, env) {
-    super(ctx, env);
-    this.registerFlow(this.orderFlow);
-  }
-}
+// OpenAI
+const agent1 = createAriaCFChatAgent({
+  model: openai("gpt-4o-mini"),
+  flows: myFlows,
+});
+
+// Anthropic
+const agent2 = createAriaCFChatAgent({
+  model: anthropic("claude-sonnet-4-20250514"),
+  flows: myFlows,
+});
+
+// Google
+const agent3 = createAriaCFChatAgent({
+  model: google("gemini-2.0-flash"),
+  flows: myFlows,
+});
+
+// Workers AI (Cloudflare)
+const agent4 = createAriaCFChatAgent({
+  model: env.AI("@cf/meta/llama-3.1-8b-instruct"),
+  flows: myFlows,
+});
 ```
 
 ## API Reference
 
-### AriaAgent Class
+### createAriaCFChatAgent
+
+```typescript
+function createAriaCFChatAgent<Env>(
+  config: AriaCFChatAgentConfig
+): new (ctx: AgentContext, env: Env) => AriaCFChatAgent<Env>;
+```
+
+### AriaCFChatAgentConfig
+
+```typescript
+interface AriaCFChatAgentConfig {
+  // Required
+  flows: Map<string, FlowDefinition>;
+  model: LanguageModel;  // Any AI SDK model
+
+  // Optional
+  instructions?: string;           // Agent instructions
+  guidelines?: string[];           // System guidelines
+  tools?: ToolRegistry;            // Custom tools
+  historyLimit?: number;           // Max history messages (default: 50)
+  enablePersistence?: boolean;     // Enable session persistence (default: true)
+}
+```
+
+### AriaCFChatAgent
+
+Base class extended by the factory:
 
 ```typescript
-class AriaAgent extends AIChatAgent<AriaEnv, AriaSessionState> {
-  // Session Management
-  getSession(): AriaSession
-  
-  // Working Memory
-  getWorkingMemory(): WorkingMemory
-  setWorkingMemory(key: string, value: unknown): void
-  clearWorkingMemory(): void
-  
-  // Cross-Session Memory
-  storeMemory(memory: Omit<AriaMemory, "id" | ...>): string
-  searchMemories(query: MemorySearchQuery): MemorySearchResult[]
-  
-  // ARIA Integration
-  runAriaAgent(agent, input, options?): Promise<{ text: string; session: AgentSession }>
-  streamAriaAgent(agent, input, options?): AsyncIterable<string>
-  
-  // Flow Orchestration
-  registerFlow(flow: FlowDefinition): void
-  transitionFlow(flowId: string, toNodeId: string): void
+abstract class AriaCFChatAgent<Env = any> extends AIChatAgent<Env, AriaCFState> {
+  // Configuration
+  protected readonly config: AriaCFChatAgentConfigResolved;
+  protected readonly ariaAgent: AriaAgent;
+  protected readonly voltRuntime: VoltRuntime;
+
+  // Override these in your subclass
+  protected abstract getConfig(): AriaCFChatAgentConfig;
+
+  // Optional overrides
+  protected getModel(): LanguageModel;
+  protected getModelId(): string;
+  protected getTools(): ToolRegistry;
 }
 ```
 
@@ -226,58 +458,6 @@ function Chat() {
 }
 ```
 
-### Using React (State Synchronization)
-
-The `useAgent` hook provides real-time state synchronization between your React app and the Agent:
-
-```tsx
-import { useState } from "react";
-import { useAgent } from "agents/react";
-
-function ShoppingCart() {
-  const [state, setState] = useState({ 
-    cart: [], 
-    workingMemory: {} 
-  });
-
-  // Connect to the agent and sync state
-  const agent = useAgent({
-    agent: "shopping-assistant",
-    name: "user-session-123",
-    onStateUpdate: (newState) => setState(newState),
-  });
-
-  const addToCart = (item: string) => {
-    // Update state on both client and server
-    agent.setState({
-      ...state,
-      workingMemory: {
-        ...state.workingMemory,
-        cart: [...(state.workingMemory.cart || []), item],
-      },
-    });
-  };
-
-  return (
-    <div>
-      <h2>Cart ({state.workingMemory.cart?.length || 0} items)</h2>
-      <ul>
-        {state.workingMemory.cart?.map((item, i) => (
-          <li key={i}>{item}</li>
-        ))}
-      </ul>
-      <button onClick={() => addToCart("New Item")}>Add Item</button>
-    </div>
-  );
-}
-```
-
-State synchronization features:
-- Automatically syncs Agent state to all connected clients
-- Handles disconnections and reconnections gracefully
-- Provides immediate local updates
-- Supports multiple simultaneous client connections
-
 ### Using WebSocket
 
 ```typescript
@@ -313,84 +493,9 @@ const response = await fetch("https://your-worker.workers.dev/agents/my-assistan
 });
 ```
 
-## Environment Configuration
-
-```typescript
-// src/types.ts
-interface Env {
-  MyAssistant: DurableObjectNamespace;
-  OPENAI_API_KEY: string;
-}
-```
-
-```toml
-# wrangler.toml (secrets)
-[vars]
-# Set via: npx wrangler secret put OPENAI_API_KEY
-```
-
 ## Complete Example
 
-```typescript
-// src/shopping-assistant.ts
-import { AriaAgent } from "@projectaria/cf-agents";
-import { createAgent } from "@projectaria/aria-agents";
-import { openai } from "@ai-sdk/openai";
-import { tool } from "ai";
-import { z } from "zod";
-
-export class ShoppingAssistant extends AriaAgent {
-  private agent = createAgent({
-    id: "shopping-assistant",
-    name: "Shopping Assistant",
-    instructions: `You are a helpful shopping assistant.
-You remember user preferences and can help them find products.
-Use the cart tools to manage their shopping cart.`,
-    model: openai("gpt-4o"),
-    tools: {
-      addToCart: tool({
-        description: "Add an item to the cart",
-        parameters: z.object({
-          item: z.string(),
-          quantity: z.number().default(1),
-        }),
-        execute: async ({ item, quantity }) => {
-          const cart = this.getWorkingMemory().cart || [];
-          cart.push({ item, quantity });
-          this.setWorkingMemory("cart", cart);
-          return { success: true, cart };
-        },
-      }),
-      viewCart: tool({
-        description: "View the current cart",
-        parameters: z.object({}),
-        execute: async () => {
-          return this.getWorkingMemory().cart || [];
-        },
-      }),
-    },
-  });
-
-  async onChatMessage(onFinish: () => void) {
-    const session = this.getSession();
-    const lastMessage = session.messages[session.messages.length - 1];
-
-    if (!lastMessage) return;
-
-    // Check for returning user preferences
-    const prefs = this.searchMemories({
-      types: ["preference"],
-      limit: 5,
-    });
-
-    // Run agent with context
-    const result = await this.runAriaAgent(this.agent, lastMessage.content);
-
-    onFinish();
-    return new Response(result.text);
-  }
-}
-```
+See [`examples/ShoppingAgent.ts`](examples/ShoppingAgent.ts) for a full shopping assistant example with flows, tools, and persistence.
 
 ## License