@ariaflowagents/core

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

Install

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

`ts
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();
`

Related Packages

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 |

$3

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

`bash
npm install @ariaflowagents/cf-agent
`

Runtime (multi-agent):
`typescript
import { AriaFlowChatAgent } from '@ariaflowagents/cf-agent';

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

Flow (structured conversation):
`typescript
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.

$3

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

`bash
npm install @ariaflowagents/hono-server
`

Runtime server:
`typescript
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:
`typescript
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

$3

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

$3

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)

$3

Natural language date parsing for conversational agents using Chrono:

`typescript
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"

$3

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

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