A framework for structured conversational AI agents
npm install @ariaflowagents/coreAriaFlow core runtime and agent primitives for building structured, multi-agent conversations.
``bash`
npm install @ariaflowagents/core
This package exports:
- Agents: Agent, LLMAgent, FlowAgent, TriageAgent, CompositeAgentRuntime
- Runtime: , createRuntimeFlowManager
- Flows: , FlowGraph, FlowNode, createFlowTransitionSessionManager
- Session: , SessionStore, MemoryStorecreateTool
- Tools: , createHandoffToolPromptTemplateBuilder
- Prompts: , PromptBuilderHookRunner
- Hooks: , loggingHooks, createMetricsHooksToolEnforcer
- Guards: , StopConditionscreateDateParser
- Utils: , parseDate, parseDateRange, formatDateForSpeech, formatTimeForSpeech
`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();
`
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 |
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.
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.
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
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)
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"
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
],
};
``