AriaFlow Config Guide

A comprehensive guide to creating and managing AriaFlow agent configurations.

Overview

The AriaFlow Config package (@ariaflowagents/config) provides:

• Configuration loading from ari aflow.jsonc files
• Agent and flow definition parsing
• Tool registration and loading
• Runtime creation from config

Installation

npm install @ariaflowagents/config

Configuration File

Basic Structure

{
  "$schema": "https://ariaflow.ai/config.json",
  "name": "my-agent",
  "version": "1.0.0",
  "runtime": {
    "defaultAgent": "chat",
    "defaultModel": "default"
  },
  "models": {
    "default": "openai:gpt-4o-mini"
  },
  "agents": { /* ... */ },
  "tools": { /* ... */ },
  "providers": { /* ... */ }
}

Runtime Configuration

Default Agent & Model

{
  "runtime": {
    "defaultAgent": "chat",
    "defaultModel": "default"
  }
}

Model Registry

Define available models with providers:

{
  "models": {
    "default": "openai:gpt-4o-mini",
    "gpt-4": "openai:gpt-4",
    "claude-3": "anthropic:claude-3-5-sonnet-20241022"
  }
}

Auto Retrieve (always-on)

Calls a retriever tool before every model run and injects the context.

{
  "runtime": {
    "autoRetrieve": {
      "type": "tool",
      "toolName": "cag_retrieve"
    }
  }
}

Structured Triage

Force triage responses into a schema and route without leaking triage text.

{
  "runtime": {
    "triageMode": "structured",
    "triageAgent": "triage"
  }
}

Always Route Through Triage

Useful when every user turn should be re-routed.

{
  "runtime": {
    "alwaysRouteThroughTriage": true
  }
}

Agents

Agents are the core components that handle user interactions.

LLM Agent

{
  "agents": {
    "chat": {
      "type": "llm",
      "description": "A helpful assistant",
      "prompt": {
        "inline": "You are a helpful assistant. Be concise."
      },
      "tools": ["search", "calculator"]
    }
  }
}

Triage Agent

Routes users to specialized agents:

{
  "agents": {
    "triage": {
      "type": "triage",
      "description": "Routes customers to the right department",
      "prompt": { "file": "./prompts/triage.md" },
      "routes": [
        {
          "agentId": "sales",
          "description": "Handles sales inquiries"
        },
        {
          "agentId": "support",
          "description": "Handles support issues"
        }
      ],
      "defaultAgent": "sales"
    }
  }
}

Flow Agent

Guided workflow agents:

{
  "agents": {
    "booking": {
      "type": "flow",
      "description": "Hotel booking flow",
      "prompt": { "file": "./prompts/booking.md" },
      "flowRef": "booking-flow",
      "mode": "hybrid"
    }
  }
}

Inline Prompt

For simple agents, use inline prompts:

{
  "agents": {
    "chat": {
      "type": "llm",
      "description": "A helpful assistant",
      "prompt": {
        "inline": "You are a helpful assistant. Be concise and friendly."
      }
    }
  }
}

File-based Prompt

For complex prompts, use external files:

{
  "agents": {
    "support": {
      "type": "llm",
      "description": "Customer support",
      "prompt": { "file": "./prompts/support.md" }
    }
  }
}

Create the prompt file:

# System Prompt

You are a customer support agent for our company.

## Guidelines
- Be empathetic and patient
- Always verify customer identity before sharing sensitive info
- Escalate complex issues to human agents

## Tools Available
- create_ticket: Create support tickets

Tools

External Tools

Define tools that agents can use:

{
  "tools": {
    "search": {
      "type": "module",
      "entry": "./tools/search/index.ts"
    },
    "calculator": {
      "type": "module",
      "entry": "./tools/calculator/index.ts"
    }
  }
}

Tool implementation (tools/search/index.ts):

import type { ToolDefinition } from '@ariaflowagents/core';

export const tool: ToolDefinition = {
  description: 'Search for information',
  inputSchema: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'Search query' }
    },
    required: ['query']
  },
  execute: async (input: unknown) => {
    const { query } = input as { query: string };
    // Implementation
    return { results: [...] };
  }
};

export default tool;

Skill Loader

Load skills from a directory:

{
  "tools": {
    "skill": {
      "type": "skill-loader",
      "paths": ["./skill"]
    }
  }
}

Flows

Define reusable workflow patterns:

{
  "flows": {
    "booking-flow": {
      "steps": [
        {
          "id": "collect-info",
          "tool": "collect_info"
        },
        {
          "id": "confirm",
          "tool": "confirm_booking"
        }
      ]
    }
  }
}

Providers

Configure API providers:

{
  "providers": {
    "openai": {
      "apiKey": "OPENAI_API_KEY",
      "baseUrl": "https://api.openai.com/v1"
    },
    "anthropic": {
      "apiKey": "ANTHROPIC_API_KEY"
    }
  }
}

Loading Configuration

Basic Loading

import { loadAriaflowConfig } from '@ariaflowagents/config';

const config = await loadAriaflowConfig({
  configPath: './ari aflow.jsonc'
});

With Model Registry

import { loadAriaflowConfigWithResult } from '@ariaflowagents/config';
import { openai } from '@ai-sdk/openai';

const model = openai('gpt-4o-mini') as any;

const { config, summary, warnings } = await loadAriaflowConfigWithResult({
  configPath: './ari aflow.jsonc',
  modelRegistry: {
    default: model,
    'openai:gpt-4o-mini': model
  }
});

console.log(`Loaded ${summary.agents} agents`);

Create Runtime

import { createRuntimeFromConfig } from '@ariaflowagents/config';

const { config } = await loadAriaflowConfigWithResult({
  configPath: './ari aflow.jsonc'
});

const runtime = createRuntimeFromConfig(config);

Directory Structure

my-agent/
├── ariaflow.jsonc              # Main configuration
├── .ariaflow/
│   ├── prompts/
│   │   ├── system.md           # System prompts
│   │   ├── chat.md             # Agent prompts
│   │   └── triage.md           # Triage prompts
│   ├── tools/
│   │   ├── search/
│   │   │   ├── index.ts        # Tool implementation
│   │   │   └── tool.json       # Tool metadata
│   │   └── calculator/
│   │       ├── index.ts
│   │       └── tool.json
│   ├── skill/
│   │   └── my-skill/
│   │       └── SKILL.md
│   └── flow/
│       └── booking-flow.json   # Flow definitions
└── package.json                # Optional: Tool dependencies

Example: Complete Configuration

{
  "$schema": "https://ariaflow.ai/config.json",
  "name": "support-agent",
  "version": "1.0.0",
  "runtime": {
    "defaultAgent": "triage",
    "defaultModel": "gpt-4o-mini"
  },
  "models": {
    "default": "openai:gpt-4o-mini",
    "gpt-4": "openai:gpt-4"
  },
  "agents": {
    "triage": {
      "type": "triage",
      "description": "Routes support requests",
      "prompt": { "file": "./prompts/triage.md" },
      "routes": [
        { "agentId": "billing", "description": "Billing inquiries" },
        { "agentId": "technical", "description": "Technical support" }
      ],
      "defaultAgent": "billing"
    },
    "billing": {
      "type": "llm",
      "description": "Handles billing questions",
      "prompt": { "file": "./prompts/billing.md" },
      "tools": ["create_ticket"]
    },
    "technical": {
      "type": "llm",
      "description": "Technical support",
      "prompt": { "file": "./prompts/technical.md" },
      "tools": ["diagnose", "create_ticket"]
    }
  },
  "tools": {
    "create_ticket": {
      "type": "module",
      "entry": "./tools/create_ticket/index.ts"
    },
    "diagnose": {
      "type": "module",
      "entry": "./tools/diagnose/index.ts"
    }
  },
  "providers": {
    "openai": {
      "apiKey": "OPENAI_API_KEY"
    }
  }
}

Configuration Reference

Root Properties

Runtime Properties

Agent Properties

Prompt Properties

Best Practices

1. Use file-based prompts for complex prompts (>100 lines)
2. Organize tools in separate directories with tool.json metadata
3. Use triage agents for multi-agent routing
4. Version your config using semantic versioning
5. Test locally using the Hono server before deployment
6. Use environment variables for API keys

Integration with Hono Server

import { loadAriaflowConfigWithResult, createRuntimeFromConfig } from '@ariaflowagents/config';
import { createAriaChatRouter } from '@ariaflowagents/hono-server';

const { config, summary } = await loadAriaflowConfigWithResult({
  configPath: './ari aflow.jsonc',
  modelRegistry: { default: model }
});

const runtime = createRuntimeFromConfig(config);

const app = new Hono();
app.route('/', createAriaChatRouter({ runtime }));