Package Exports

@ariaflowagents/core
@ariaflowagents/core/agents
@ariaflowagents/core/flows
@ariaflowagents/core/guards
@ariaflowagents/core/hooks
@ariaflowagents/core/prompts
@ariaflowagents/core/runtime
@ariaflowagents/core/session
@ariaflowagents/core/tools
@ariaflowagents/core/types

Readme

@ariaflowagents/core

AriaFlow core runtime and agent primitives for building structured, multi-agent conversations.

Install

npm install @ariaflowagents/core

Exports

This package exports:

Agents: Agent, LLMAgent, FlowAgent, TriageAgent, CompositeAgent
Runtime: Runtime, createRuntime
Flows: FlowManager, FlowGraph, FlowNode, createFlowTransition
Session: SessionManager, SessionStore, MemoryStore
Tools: createTool, createHandoffTool
Prompts: PromptTemplateBuilder, PromptBuilder
Hooks: HookRunner, loggingHooks, createMetricsHooks
Guards: ToolEnforcer, StopConditions
Utils: createDateParser, parseDate, parseDateRange, formatDateForSpeech, formatTimeForSpeech

Quick start

import { Runtime, createDateParser, type AgentConfig } from '@ariaflowagents/core';
import { openai } from '@ai-sdk/openai';

// Create date parsing tool for natural language dates
const dateParser = createDateParser();

const supportAgent: AgentConfig = {
  id: 'support',
  name: 'Support Agent',
  systemPrompt: 'You are a helpful support agent that can help book appointments.',
  model: openai('gpt-4o-mini') as any,
  tools: {
    parse_date: dateParser,
  },
};

const runtime = new Runtime({
  agents: [supportAgent],
  defaultAgentId: 'support',
  defaultModel: openai('gpt-4o-mini') as any,
});

const run = async () => {
  for await (const part of runtime.stream({ input: 'Hello there' })) {
    if (part.type === 'text-delta') {
      process.stdout.write(part.text);
    }
  }
};

run();

AriaFlow provides additional packages for specific deployment targets:

Package	Description	Use When
`@ariaflowagents/cf-agent`	Cloudflare Durable Objects for Runtime and AgentFlowManager	Deploying to Cloudflare Workers
`@ariaflowagents/hono-server`	Hono router for HTTP/WebSocket serving	Running a Node.js or Bun server

Cloudflare Workers

Use @ariaflowagents/cf-agent for serverless deployment on Cloudflare:

npm install @ariaflowagents/cf-agent

Runtime (multi-agent):

import { AriaFlowChatAgent } from '@ariaflowagents/cf-agent';

export class MyChatAgent extends AriaFlowChatAgent {
  async createRuntime() {
    return {
      agents: [supportAgent],
      defaultAgentId: 'support',
    };
  }
}

Flow (structured conversation):

import { AriaFlowFlowAgent } from '@ariaflowagents/cf-agent';

export class ReservationAgent extends AriaFlowFlowAgent {
  async createFlowConfig() {
    return {
      initialNode: 'greeting',
      model: openai('gpt-4o-mini') as object,
      nodes: [...],
    };
  }
}

See @ariaflowagents/cf-agent for full documentation.

Hono Server

Use @ariaflowagents/hono-server for HTTP/WebSocket hosting:

npm install @ariaflowagents/hono-server

Runtime server:

import { Hono } from 'hono';
import { serve } from '@hono/node-server';
import { createNodeWebSocket } from '@hono/node-ws';
import { Runtime } from '@ariaflowagents/core';
import { createAriaChatRouter } from '@ariaflowagents/hono-server';

const runtime = new Runtime({ agents: [...] });
const app = new Hono();
app.route('/', createAriaChatRouter({ runtime }));

serve({ fetch: app.fetch, port: 3000 });

Flow server:

import { AgentFlowManager } from '@ariaflowagents/core';
import { createAriaFlowRouter } from '@ariaflowagents/hono-server';

const flowManager = new AgentFlowManager({ nodes: [...] });
app.route('/', createAriaFlowRouter({ flowManager, sessionId: 'my-flow' }));

See @ariaflowagents/hono-server for full documentation.

Core Concepts

Runtime (Multi-Agent)

The Runtime class orchestrates multiple agents with seamless handoffs:

TriageAgent: Routes requests to the appropriate specialist
Agent Handoffs: Transfer conversation context between agents
Session Persistence: Maintains conversation state

AgentFlowManager (Single Flow)

The AgentFlowManager class manages structured, node-based conversations:

Flow Nodes: Each node has a specific purpose and tools
State Transitions: Tools drive transitions via createFlowTransition()
Flow Hooks: Observe lifecycle events (onFlowStart, onTransition, etc.)
Context Strategies: Control memory management (append, reset, summarize)

Date Parsing Utilities

Natural language date parsing for conversational agents using Chrono:

import { createDateParser, parseDate, formatDateForSpeech } from '@ariaflowagents/core';

// As a tool for agents
const dateParser = createDateParser();
const result = await dateParser.execute({ text: 'tomorrow at 3pm' });
// { success: true, startDate: '2026-01-18T15:00:00Z', ... }

// Standalone function
const parsed = parseDate('next Friday');
// { date: Date, text: 'next Friday', confidence: 1.0 }

// TTS-friendly formatting
formatDateForSpeech(new Date('2026-01-18')); // "Saturday, January 18, 2026"

Supported expressions:

Relative: "tomorrow", "today", "yesterday", "in 3 days"
Weekdays: "next Friday", "this weekend", "Monday morning"
Specific dates: "March 15th", "December 25th, 2026"
With time: "tomorrow at 3pm", "next Tuesday at 2:30pm"

Date Parser in Flows

Use the date parser within flow nodes for booking and scheduling:

import { createDateParser, createFlowTransition } from '@ariaflowagents/core';
import { tool } from 'ai';
import { z } from 'zod';

const dateParserTool = createDateParser();

const bookingFlow = {
  nodes: [
    {
      id: 'collect_date',
      prompt: 'What date would you like to book?',
      tools: {
        parse_date: tool({
          description: 'Parse the date from user input',
          inputSchema: z.object({
            dateText: z.string().describe('Natural language date'),
          }),
          execute: async ({ dateText }) => {
            const result = await dateParserTool.execute({ text: dateText });
            if (result.success) {
              return createFlowTransition('collect_time', { 
                date: result.startDate.split('T')[0] 
              });
            }
            return { error: 'Could not parse date' };
          },
        }),
      },
    },
    // ... more nodes
  ],
};