Agentic AI 服务器

Prerequisites

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

Set required environment variables

export JWT_SECRET="your-secret-key-at-least-32-characters" export API_KEY="your-api-key" ```

Requirements

Minimum Requirements

• Rust: 1.91 or later
• Operating System: Linux, macOS, or Windows
• Memory: 2GB RAM (4GB+ recommended for larger models)

Optional Requirements

• Ollama: For local LLM inference (recommended)
• Node.js runtime: Bun, npm, or Deno (required for UI development)
• Docker: For containerized deployment
• GPU: NVIDIA (CUDA) or Apple Silicon (Metal) for accelerated inference

Install development dependencies

just setup

Installation

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

Install from crates.io (basic installation)

cargo install ares-server

Install with embedded Web UI

cargo install ares-server --features ui

1. Clone and Setup

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

Install a model

ollama pull ministral-3:3b

3. Build and Run

```bash

Build with default features (local-db + ollama)

cargo build

Or: just build

Building with Features

```bash

Or: just build

Or: just build-features "openai"

Or: just build-all

Release build

cargo build --release

Or: just build-release

```

Admin & Deployment API

Admin endpoints require the X-Admin-Secret header.

Trigger Deploy

curl -X POST http://localhost:3000/api/admin/deploy \
  -H "X-Admin-Secret: $ADMIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"target": "ares"}'

Response:

{"id": "deploy-abc123", "status": "running", "message": "Deploy started"}

Check Deploy Status

curl http://localhost:3000/api/admin/deploy/deploy-abc123 \
  -H "X-Admin-Secret: $ADMIN_SECRET"

List Recent Deploys

curl http://localhost:3000/api/admin/deploys \
  -H "X-Admin-Secret: $ADMIN_SECRET"

Service Health

curl http://localhost:3000/api/admin/services \
  -H "X-Admin-Secret: $ADMIN_SECRET"

Response:

{
  "ares": {"status": "active", "pid": "12345", "port": 3000},
  "postgresql": {"status": "active", "pid": "456", "port": 5432}
}

Service Logs

curl http://localhost:3000/api/admin/services/ares/logs \
  -H "X-Admin-Secret: $ADMIN_SECRET"

Install Hurl

brew install hurl # macOS

Build & Run

just build # Build (debug) just build-release # Build (release) just build-ui # Build with embedded UI just run # Run server just run-ui # Run with embedded UI just run-debug # Run with debug logging

Docker

just docker-up # Start dev services just docker-down # Stop services just docker-logs # View logs

Or start via Docker

just docker-services ```

UI Build Errors (Node.js runtime required)

```bash

Solution: Install a Node.js runtime

Option 1: Install Bun (recommended)

curl -fsSL https://bun.sh/install | bash

Option 2: Install Node.js

brew install node # macOS

WASM Build Errors

```bash

Install trunk

cargo install trunk --locked ```

Development Setup

```bash

Quick Start (Development)

Quick Start

```bash

Copy the example config

cp ares.example.toml ares.toml

Quick Contribution Guide

```bash

Initialize a new project (creates ares.toml and config files)

ares-server init

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

Use a custom config file

ares-server --config custom.toml

Init Command Options

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.

Configuration File (ares.toml)

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

```toml

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"

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.

Environment Variables

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

```bash

Optional (for OpenAI provider)

OPENAI_API_KEY=sk-... ```

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 for details.

ToolCallingConfig Options

Set the environment variable and run ignored tests

OLLAMA_LIVE_TESTS=1 cargo test --test ollama_live_tests -- --ignored

Configuration File Not Found

```bash

Error: Configuration file 'ares.toml' not found!

Missing Environment Variables

```bash

Error: MissingEnvVar("JWT_SECRET")

Solution: Set up environment variables

cp .env.example .env

Edit .env and set JWT_SECRET (min 32 characters) and API_KEY

```

CLI Commands

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

```bash

With Swagger UI (interactive API docs)

cargo build --features "swagger-ui"

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

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..."

User-Created Agents API

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

```bash

API Documentation

Interactive Swagger UI available at: http://localhost:3000/swagger-ui/

Note: Swagger UI requires the swagger-ui feature to be enabled at build time:

> cargo build --features "swagger-ui"
> # Or use the full bundle:
> cargo build --features "full"
> 

API Tests (Hurl)

End-to-end API tests using Hurl:

```bash

Run API tests (server must be running)

just hurl

CLI Commands

just init # Initialize project (ares-server init) just init-openai # Initialize with OpenAI provider just config # Show configuration summary just agents # List all agents just agent <name> # Show agent details

Workflows (define agent routing)

[workflows.default] entry_agent = "router" fallback_agent = "product" max_depth = 5

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

Key Components

• AresConfigManager: Thread-safe configuration management with hot-reloading
• ProviderRegistry: Creates LLM clients based on model configuration
• AgentRegistry: Creates ConfigurableAgents from TOML configuration
• ToolRegistry: Manages available tools and their configurations
• ConfigurableAgent: Generic agent implementation that uses config for behavior
• WorkflowEngine: Executes declarative workflows defined in TOML

Workflows

Workflows enable multi-agent orchestration. Define workflows in ares.toml:

[workflows.default]
entry_agent = "router"           # Starting agent
fallback_agent = "orchestrator"  # Used if routing fails
max_depth = 5                    # Maximum agent chain depth
max_iterations = 10              # Maximum total iterations

List Available Workflows

curl http://localhost:3000/api/workflows \
  -H "Authorization: Bearer <access_token>"

Response:

["default", "research"]

Execute a Workflow

curl -X POST http://localhost:3000/api/workflows/default \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are our Q4 product sales figures?"
  }'

Response:

{
  "final_response": "Based on the Q4 data, our product sales were...",
  "steps_executed": 3,
  "agents_used": ["router", "sales", "product"],
  "reasoning_path": [
    {
      "agent_name": "router",
      "input": "What are our Q4 product sales figures?",
      "output": "sales",
      "timestamp": 1702500000,
      "duration_ms": 150
    },
    {
      "agent_name": "sales",
      "input": "What are our Q4 product sales figures?",
      "output": "For Q4 sales data, I'll need to check...",
      "timestamp": 1702500001,
      "duration_ms": 800
    },
    {
      "agent_name": "product",
      "input": "What are our Q4 product sales figures?",
      "output": "Based on the Q4 data, our product sales were...",
      "timestamp": 1702500002,
      "duration_ms": 650
    }
  ]
}

Workflow with Context

curl -X POST http://localhost:3000/api/workflows/default \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the sales figures?",
    "context": {
      "department": "electronics",
      "quarter": "Q4"
    }
  }'

Unit & Integration Tests (Mocked)

```bash

Troubleshooting