Agentic AI 服务器

Prerequisites

• Rust 1.98 or later. Install via rustup
• Ollama for local LLM inference (recommended). See Install Ollama
• just as the command runner (recommended). See 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.98 or later
• Operating System: Linux, macOS, or Windows
• Memory: 2GB RAM (4GB or more 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

Run ARES as a standalone server. You can also embed it as a library in a Rust project.

Install from crates.io

cargo install ares-server --locked

Install with embedded Web UI

cargo install ares-server --locked --features ui

Install a model

ollama pull ministral-3:3b

3. Build and run

```bash

Build with default features (postgres + http + cli)

cargo build

Or: just build

Building with features

```bash

Or: just build

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

1. Clone and configure

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

Or run just to configure the project:

just setup ```

Optional in-process GGUF

cargo build --features llamacpp

Optional GGUF with CUDA

cargo build --features llamacpp-cuda

Configuration

ARES reads a TOML configuration file (ares.toml) with declarative configuration for all components. The server requires this file at startup.

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 server validates the configuration on load:

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

The validate_with_warnings() method reports unused configuration items (providers, models, and tools with no references).

Environment variables

These environment variables must be set because ares.toml references them:

```bash

Optional (for OpenAI provider)

OPENAI_API_KEY=sk-... ```

Dynamic configuration (TOON)

ARES also supports TOON (Token Oriented Object Notation) files for behavioral configuration with hot-reload support. These files complement ares.toml.

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 configuration 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

The server hot-reloads TOON files automatically after a change.

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

The CLI prints colored output for every command:

```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 in the database. Import and export use the TOON format:

```bash

API documentation

The interactive Swagger UI is available at http://localhost:3000/swagger-ui/

Note: The build must enable the swagger-ui feature:

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

API tests (hurl)

End-to-end API tests use 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 ```

Workflows

Workflows give 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