hive/docs/configuration.md

Configuration Guide

Aden Hive is a Python-based agent framework. Configuration is handled through environment variables and agent-level config files. There is no centralized config.yaml or Docker Compose setup.

Configuration Overview

Environment variables     (API keys, runtime flags)
Agent config.py           (per-agent settings: model, tools, storage)
pyproject.toml            (package metadata and dependencies)
.mcp.json                 (MCP server connections)

Environment Variables

LLM Providers (at least one required for real execution)

# Anthropic (primary provider)
export ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI (optional, for GPT models via LiteLLM)
export OPENAI_API_KEY="sk-..."

# Cerebras (optional, used by output cleaner and some nodes)
export CEREBRAS_API_KEY="..."

# Groq (optional, fast inference)
export GROQ_API_KEY="..."

The framework supports 100+ LLM providers through LiteLLM. Set the corresponding environment variable for your provider.

Search & Tools (optional)

# Web search for agents (Brave Search)
export BRAVE_SEARCH_API_KEY="..."

# Exa Search (alternative web search)
export EXA_API_KEY="..."

Runtime Flags

# Run agents without LLM calls (structure-only validation)
export MOCK_MODE=1

# Custom credentials storage path (default: ~/.aden/credentials)
export ADEN_CREDENTIALS_PATH="/custom/path"

# Custom agent storage path (default: /tmp)
export AGENT_STORAGE_PATH="/custom/storage"

Agent Configuration

Each agent package in exports/ contains its own config.py:

# exports/my_agent/config.py
CONFIG = {
    "model": "claude-haiku-4-5-20251001",  # Default LLM model
    "max_tokens": 4096,
    "temperature": 0.7,
    "tools": ["web_search", "pdf_read"],   # MCP tools to enable
    "storage_path": "/tmp/my_agent",       # Runtime data location
}

Agent Graph Specification

Agent behavior is defined in agent.json (or constructed in agent.py):

{
  "id": "my_agent",
  "name": "My Agent",
  "goal": {
    "success_criteria": [...],
    "constraints": [...]
  },
  "nodes": [...],
  "edges": [...]
}

See the Getting Started Guide for building agents.

MCP Server Configuration

MCP (Model Context Protocol) servers are configured in .mcp.json at the project root:

{
  "mcpServers": {
    "agent-builder": {
      "command": "core/.venv/bin/python",
      "args": ["-m", "framework.mcp.agent_builder_server"],
      "cwd": "."
    },
    "tools": {
      "command": "tools/.venv/bin/python",
      "args": ["-m", "aden_tools.mcp_server", "--stdio"],
      "cwd": "."
    }
  }
}

The tools MCP server exposes tools including web search, PDF reading, CSV processing, and file system operations.

Storage

Aden Hive uses file-based persistence (no database required):

{storage_path}/
  runs/{run_id}.json          # Complete execution traces
  indexes/
    by_goal/{goal_id}.json    # Runs indexed by goal
    by_status/{status}.json   # Runs indexed by status
    by_node/{node_id}.json    # Runs indexed by node
  summaries/{run_id}.json     # Quick-load run summaries

Storage is managed by framework.storage.FileStorage. No external database setup is needed.

IDE Setup

VS Code

Add to .vscode/settings.json:

{
  "python.analysis.extraPaths": [
    "${workspaceFolder}/core",
    "${workspaceFolder}/exports"
  ]
}

PyCharm

1. Open Project Settings > Project Structure
2. Mark core as Sources Root
3. Mark exports as Sources Root

Security Best Practices

1. Never commit API keys - Use environment variables or .env files
2. .env is git-ignored - Copy .env.example to .env at the project root and fill in your values
3. Use real provider keys in non-production environments - validate configuration with low-risk inputs before production rollout
4. Credential isolation - Each tool validates its own credentials at runtime

Troubleshooting

"ModuleNotFoundError: No module named 'framework'"

Install the core package:

cd core && uv pip install -e .

API key not found

Ensure the environment variable is set in your current shell session:

echo $ANTHROPIC_API_KEY  # Should print your key

On Windows PowerShell:

$env:ANTHROPIC_API_KEY = "sk-ant-..."

Agent not found

Run from the project root with PYTHONPATH:

PYTHONPATH=exports uv run python -m my_agent validate

See Environment Setup for detailed installation instructions.