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

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

state = {
  activeAgentId: 'orders',      // Current agent
  lastHandoffReason: 'Order inquiry',
  updatedAt: 1234567890,
}

AriaFlowFlowAgent - Structured Flow

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

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

State (Flow mode):

state = {
  currentNode: 'collect_date',   // Current node
  nodeHistory: ['greeting', 'collect_party_size', 'collect_date'],
  updatedAt: 1234567890,
}

Context Strategies

Control conversation history behavior:

{
  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

// 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<Response> {
    return MyAgent.fetch(request, env);  // or MyFlowAgent
  },
};