@ariaflowagents/cf-agent

Cloudflare Durable Object base classes for hosting AriaFlow on the edge.

Two Primitive Classes

This package provides two separate base classes for different use cases:

| Class | Use When | Config Returns |
|-------|----------|----------------|
| AriaFlowChatAgent | Multi-agent systems with handoffs | HarnessConfig or Runtime |
| AriaFlowFlowAgent | Structured single-flow conversations | AriaFlowFlowConfig or AgentFlowManager |

---

AriaFlowChatAgent - Multi-Agent Runtime

Use for multi-agent systems where agents can hand off to each other.

``typescript
import { AriaFlowChatAgent } from '@ariaflowagents/cf-agent';
import { Runtime, type AgentConfig } from '@ariaflowagents/core';

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' },
],
};

const orders: AgentConfig = {
id: 'orders',
name: 'Orders',
type: 'llm',
systemPrompt: 'Help with order questions.',
};

return {
agents: [triage, orders],
defaultAgentId: 'triage',
};
}
}
`

State (Runtime mode):
`typescript
state = {
activeAgentId: 'orders', // Current agent
lastHandoffReason: 'Order inquiry',
updatedAt: 1234567890,
}
`

---

AriaFlowFlowAgent - Structured Flow

Use for structured, multi-step flows with guided conversations.

`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';

export class ReservationAgent extends AriaFlowFlowAgent {
async createFlowConfig(): Promise {
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.',
},
],
};
}
}
`

State (Flow mode):
`typescript
state = {
currentNode: 'collect_date', // Current node
nodeHistory: ['greeting', 'collect_party_size', 'collect_date'],
updatedAt: 1234567890,
}
`

---

Context Strategies

Control conversation history behavior:

`typescript
{
name: 'confirmation',
taskPrompt: 'Confirm details.',
contextStrategy: {
strategy: 'reset_with_summary' // Summarize instead of full history
},
}
`

| Strategy | Behavior |
|----------|----------|
| append | Keep all messages (default) |
| reset | Clear messages on node entry |
| reset_with_summary | Summarize and replace messages |

---

Endpoints (Both Classes)

| Endpoint | Returns |
|----------|---------|
| GET /info | Agent metadata, mode, readiness |
| GET /state | Full agent state |
| WS / | WebSocket for streaming |

AriaFlowFlowAgent additional:
| GET /flow-state | Flow-specific state (currentNode, nodeHistory, collectedData) |

---

Quick Reference

| 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 |

---

Example: Cloudflare Worker

`typescript
// Runtime Mode (Multi-Agent)
import { AriaFlowChatAgent } from '@ariaflowagents/cf-agent';

export class MyAgent extends AriaFlowChatAgent {
async createRuntimeConfig() {
return {
agents: [{ id: 'assistant', name: 'Assistant', systemPrompt: 'Helpful.' }],
defaultAgentId: 'assistant',
};
}
}

// OR Flow Mode (Single Flow)
import { AriaFlowFlowAgent } from '@ariaflowagents/cf-agent';

export class MyFlowAgent extends AriaFlowFlowAgent {
async createFlowConfig() {
return {
initialNode: 'greeting',
model: this.env.AI as any,
nodes: [{ name: 'greeting', taskPrompt: 'Hi!' }],
};
}
}

export default {
async fetch(request: Request, env: Env): Promise {
return MyAgent.fetch(request, env); // or MyFlowAgent
},
};
``