Ares

Agentic Retrieval Enhanced Server. Rust. Multi-provider LLM. Tool calling. RAG. MCP. Extensible via ContextProvider trait. Run standalone or embed as a library.

---

A.R.E.S is a production-grade agentic AI server built in Rust. Multi-provider LLM routing, structured tool calling, RAG, MCP integration, multi-tenant auth, and workflow orchestration. Extensible via ContextProvider trait and base_router() for building managed platforms on top.

Built by DIRMACS. Documentation

Features

• Multi-provider LLM: Ollama, OpenAI, Anthropic Claude, LlamaCpp (direct GGUF loading)
• TOML configuration: declarative, hot-reloading
• Configurable agents: define via TOON with custom models, tools, and prompts
• Workflow engine: declarative execution with agent routing
• Tool calling: type-safe function calling with automatic schema generation
• ToolCoordinator: provider-agnostic multi-turn tool calling for all LLM clients
• Per-agent tool filtering: restrict which tools each agent can access
• Streaming: real-time responses from all providers
• Auth: JWT with Argon2 password hashing
• Database: PostgreSQL with multi-tenant isolation, optional vector stores (ares-vector, Qdrant, LanceDB)
• MCP: pluggable Model Context Protocol server integration
• Multi-agent orchestration: specialized agent routing
• RAG: pure-Rust vector store, multi-strategy search (semantic, BM25, fuzzy, hybrid), reranking
• Memory: user personalization and context management
• Deep research: multi-step research with parallel subagents
• Web search: built-in via daedra
• OpenAPI: automatic documentation generation
• Config validation: circular reference detection and unused config warnings
• Loop detection: 3-tier escalation (warn → force alternative → halt) for repetitive outputs
• Crash recovery: checkpoint serialization — save agent state at each step, restore on restart

Installation

A.R.E.S can be used as a standalone server or as a library in your Rust project.

As a Library

Add to your project:

cargo add ares-server

Basic usage:

use ares::{Provider, LLMClient};

#[tokio::main]
async fn main() -> Result> {
    // Create an Ollama provider
    let provider = Provider::Ollama {
        base_url: "http://localhost:11434".to_string(),
        model: "llama3.2:3b".to_string(),
    };

    // Create a client and generate a response
    let client = provider.create_client().await?;
    let response = client.generate("Hello, world!").await?;
    println!("{}", response);

    Ok(())
}

As a Binary

# Install from crates.io (basic installation)
cargo install ares-server

# Install with embedded Web UI
cargo install ares-server --features ui

# Initialize a new project (creates ares.toml and config files)
ares-server init

# Run the server
ares-server

CLI Commands

A.R.E.S provides a full-featured CLI with colored output:

# Initialize a new project with all configuration files
ares-server init

# Initialize with custom options
ares-server init --provider openai --port 8080 --host 0.0.0.0

# Initialize with minimal configuration
ares-server init --minimal

# View configuration summary
ares-server config

# Validate configuration
ares-server config --validate

# List all configured agents
ares-server agent list

# Show details for a specific agent
ares-server agent show orchestrator

# Start the server
ares-server

# Start with verbose logging
ares-server --verbose

# Use a custom config file
ares-server --config custom.toml

# Disable colored output
ares-server --no-color init

Init Command Options

| Option | Description | |--------|-------------| | --force, -f | Overwrite existing files | | --minimal, -m | Create minimal configuration | | --no-examples | Skip creating TOON example files | | --provider | LLM provider: ollama, openai, or both | | --host | Server host address (default: 127.0.0.1) | | --port | Server port (default: 3000) |

Quick Start (Development)

Prerequisites

• Rust 1.91+: Install via rustup
• Ollama (recommended): For local LLM inference - Install Ollama
• just (recommended): Command runner - Install just

1. Clone and Setup

git clone https://github.com/dirmacs/ares.git
cd ares
cp .env.example .env

# Or use just to set up everything:
just setup

2. Start Ollama (Recommended)

# Install a model
ollama pull ministral-3:3b
# Or: just ollama-pull

# Ollama runs automatically as a service, or start manually:
ollama serve

3. Build and Run

# Build with default features (local-db + ollama)
cargo build
# Or: just build

# Run the server
cargo run
# Or: just run

Server runs on http://localhost:3000

Feature Flags

A.R.E.S uses Cargo features for conditional compilation:

LLM Providers

| Feature | Description | Default | |---------|-------------|---------| | ollama | Ollama local inference | ✅ Yes | | openai | OpenAI API (and compatible) | No | | anthropic | Anthropic Claude API | No | | llamacpp | Direct GGUF model loading | No | | llamacpp-cuda | LlamaCpp with CUDA | No | | llamacpp-metal | LlamaCpp with Metal (macOS) | No | | llamacpp-vulkan | LlamaCpp with Vulkan | No |

Database & Vector Stores

| Feature | Description | Default | |---------|-------------|---------| | postgres | PostgreSQL database | ✅ Yes | | ares-vector | Pure-Rust embedded HNSW vector store | ✅ Yes | | qdrant | Qdrant vector database | No | | pgvector | PostgreSQL pgvector extension | No | | chromadb | ChromaDB embedding database | No | | pinecone | Pinecone managed vector database | No | | lancedb | LanceDB vector database | No |

UI & Documentation

| Feature | Description | Default | |---------|-------------|---------| | ui | Embedded Leptos web UI served from backend | No | | swagger-ui | Interactive API documentation at /swagger-ui/ | No |

> Note: swagger-ui was made optional in v0.2.5 to reduce binary size and build time. The feature requires network access during build to download Swagger UI assets.

Embeddings

| Feature | Description | Default | |---------|-------------|---------| | local-embeddings | Local ONNX embedding models via fastembed | No |

> Warning: The local-embeddings feature does NOT work on Windows MSVC due to ort-sys linker errors. Use WSL, Linux, or macOS for local embeddings, or use remote embedding APIs instead.

Feature Bundles

| Feature | Includes | |---------|----------| | all-llm | ollama + openai + llamacpp + anthropic | | all-db | postgres + all vector stores | | full | All optional features (except UI and local-embeddings): ollama, openai, llamacpp, anthropic, postgres, qdrant, ares-vector, mcp, swagger-ui | | full-ui | All optional features + UI (except local-embeddings) | | full-local-embeddings | Full + local-embeddings (Linux/macOS only) | | full-ui-local-embeddings | Full + UI + local-embeddings (Linux/macOS only) | | minimal | No optional features |

> Note: local-embeddings is excluded from full and full-ui bundles due to Windows MSVC compatibility issues. Use full-local-embeddings or full-ui-local-embeddings on Linux/macOS.

Building with Features

# Default (ollama + local-db)
cargo build
# Or: just build

# With OpenAI support
cargo build --features "openai"
# Or: just build-features "openai"

# With direct GGUF loading
cargo build --features "llamacpp"

# With CUDA GPU acceleration
cargo build --features "llamacpp-cuda"

# Full feature set
cargo build --features "full"
# Or: just build-all

# With embedded Web UI
cargo build --features "ui"

# With Swagger UI (interactive API docs)
cargo build --features "swagger-ui"

# Full feature set with UI
cargo build --features "full-ui"

# Release build
cargo build --release
# Or: just build-release

Configuration

A.R.E.S uses a TOML configuration file (ares.toml) for declarative configuration of all components. The server requires this file to start.

Quick Start

# Copy the example config
cp ares.example.toml ares.toml

# Set required environment variables
export JWT_SECRET="your-secret-key-at-least-32-characters"
export API_KEY="your-api-key"

Configuration File (ares.toml)

The configuration file defines providers, models, agents, tools, and workflows:

# Server settings
[server]
host = "127.0.0.1"
port = 3000
log_level = "info"

# Authentication (secrets loaded from env vars)
[auth]
jwt_secret_env = "JWT_SECRET"
api_key_env = "API_KEY"

# Database
[database]
url = "./data/ares.db"

# LLM Providers (define named providers)
[providers.ollama-local]
type = "ollama"
base_url = "http://localhost:11434"
default_model = "ministral-3:3b"

[providers.openai]  # Optional
type = "openai"
api_key_env = "OPENAI_API_KEY"
default_model = "gpt-4"

# Models (reference providers, set parameters)
[models.fast]
provider = "ollama-local"
model = "ministral-3:3b"
temperature = 0.7
max_tokens = 256

[models.balanced]
provider = "ollama-local"
model = "ministral-3:3b"
temperature = 0.7
max_tokens = 512

[models.smart]
provider = "ollama-local"
model = "qwen3-vl:2b"
temperature = 0.3
max_tokens = 1024

# Tools (define available tools)
[tools.calculator]
enabled = true
timeout_secs = 10

[tools.web_search]
enabled = true
timeout_secs = 30

# Agents (reference models and tools)
[agents.router]
model = "fast"
system_prompt = "You route requests to specialized agents..."

[agents.product]
model = "balanced"
tools = ["calculator"]                     # Tool filtering: only calculator
system_prompt = "You are a Product Agent..."

[agents.research]
model = "smart"
tools = ["web_search", "calculator"]       # Multiple tools
system_prompt = "You conduct research..."

# Workflows (define agent routing)
[workflows.default]
entry_agent = "router"
fallback_agent = "product"
max_depth = 5

[workflows.research_flow]
entry_agent = "research"
max_depth = 10

Per-Agent Tool Filtering

Each agent can specify which tools it has access to:

[agents.restricted]
model = "balanced"
tools = ["calculator"]  # Only calculator, no web search

[agents.full_access]
model = "balanced"
tools = ["calculator", "web_search"]  # Both tools

If tools is empty or omitted, the agent has no tool access.

Configuration Validation

The configuration is validated on load with:

• Reference checking: Models must reference valid providers, agents must reference valid models
• Circular reference detection: Workflows cannot have circular agent references
• Environment variables: All referenced env vars must be set

For warnings about unused configuration items (providers, models, tools not referenced by anything), the validate_with_warnings() method is available.

Hot Reloading

Configuration changes are automatically detected and applied without restarting the server. Edit ares.toml and the changes will be picked up within 500ms.

Environment Variables

The following environment variables must be set (referenced by ares.toml):

# Required
JWT_SECRET=your-secret-key-at-least-32-characters
API_KEY=your-api-key

# Optional (for OpenAI provider)
OPENAI_API_KEY=sk-...

Provider Priority

When multiple providers are configured, they are selected in this order:

1. LlamaCpp - If LLAMACPP_MODEL_PATH is set
2. OpenAI - If OPENAI_API_KEY is set
3. Ollama - Default fallback (no API key required)

Dynamic Configuration (TOON)

In addition to ares.toml, A.R.E.S supports TOON (Token Oriented Object Notation) files for behavioral configuration with hot-reloading:

config/
├── agents/
│   ├── router.toon
│   ├── orchestrator.toon
│   └── product.toon
├── models/
│   ├── fast.toon
│   └── balanced.toon
├── tools/
│   └── calculator.toon
├── workflows/
│   └── default.toon
└── mcps/
    └── filesystem.toon

Example TOON agent config (config/agents/router.toon):

name: router
model: fast
max_tool_iterations: 5
parallel_tools: false
tools[0]:
system_prompt: |
  You are a router agent that directs requests to specialized agents.

Enable TOON configs in ares.toml:

[config]
agents_dir = "config/agents"
models_dir = "config/models"
tools_dir = "config/tools"
workflows_dir = "config/workflows"
mcps_dir = "config/mcps"
hot_reload = true

TOON files are automatically hot-reloaded when changed. See [docs/DIR-12-research.md](docs/DIR-12-research.md) for details.

User-Created Agents API

Users can create custom agents stored in the database with TOON import/export:

# Create a custom agent
curl -X POST http://localhost:3000/api/agents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "model": "balanced",
    "system_prompt": "You are a helpful assistant.",
    "tools": ["calculator"]
  }'

# Export as TOON
curl http://localhost:3000/api/agents/{id}/export \
  -H "Authorization: Bearer $TOKEN"

# Import from TOON
curl -X POST http://localhost:3000/api/agents/import \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: text/plain" \
  -d 'name: imported-agent
model: fast
system_prompt: |
  You are an imported agent.'

Extending ARES

ARES is designed as a library that extension crates can build upon. Two key extension points:

base_router() — Composable HTTP Router

use ares::{base_router, AppState};

// Build your own binary on top of ARES
let app = base_router(state.clone())
    .merge(my_custom_routes(state.clone()))
    .layer(my_custom_middleware());

axum::serve(listener, app).await?;

ContextProvider — Pluggable Context Injection

Inject external context into every agent call before LLM invocation:

use ares::agents::context_provider::ContextProvider;
use async_trait::async_trait;

struct MyContextProvider { /* your state */ }

#[async_trait]
impl ContextProvider for MyContextProvider {
    async fn get_context(&self, agent_name: &str, tenant_id: &str) -> Option {
        // Fetch context from your knowledge base, vector DB, etc.
        // Returns None if no context available (agents use system prompt only)
        Some("Relevant context for this agent...".to_string())
    }
}

// Wire it into AppState
let state = AppState {
    context_provider: Arc::new(MyContextProvider { /* ... */ }),
    // ... other fields
};

By default, ARES uses NoOpContextProvider (returns None — agents run with system prompt only). Extension crates implement this trait to inject domain-specific knowledge.

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                            ares.toml (Configuration)                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐     │
│  │providers │  │ models   │  │ agents   │  │  tools   │  │workflows │     │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  └──────────┘     │
└──────────────────────────────┬──────────────────────────────────────────────┘
                               │ Hot Reload
┌──────────────────────────────▼──────────────────────────────────────────────┐
│                         AresConfigManager                                    │
│                    (Thread-safe config access)                               │
└──────────────────────────────┬──────────────────────────────────────────────┘
                               │
       ┌───────────────────────┼───────────────────────────┐
       │                       │                           │
┌──────▼──────┐         ┌──────▼──────┐            ┌──────▼──────┐
│  Provider

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [dirmacs](https://github.com/dirmacs)
- **Source:** [dirmacs/ares](https://github.com/dirmacs/ares)
- **License:** MIT
- **Homepage:** https://dirmacs.github.io/ares

Install and usage instructions live in the source repository linked above.