@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
  },
};