Agent Development Environment Setup

Agent Development Environment Setup

Complete setup guide for building and running goal-driven agents with the Aden Agent Framework.

Quick Setup

# Run the automated setup script
./quickstart.sh

Note for Windows Users: Running the setup script on native Windows shells (PowerShell / Git Bash) may sometimes fail due to Python App Execution Aliases. It is strongly recommended to use WSL (Windows Subsystem for Linux) for a smoother setup experience.

This will:

• Check Python version (requires 3.11+)
• Install the core framework package (framework)
• Install the tools package (aden_tools)
• Initialize encrypted credential store (~/.hive/credentials)
• Configure default LLM provider
• Fix package compatibility issues (openai + litellm)
• Verify all installations

Windows Setup

Windows users should use WSL (Windows Subsystem for Linux) to set up and run agents.

1. Install WSL 2 if you haven't already:

   wsl --install
   

2. Open your WSL terminal, clone the repo, and run the quickstart script:

   ./quickstart.sh
   

Alpine Linux Setup

If you are using Alpine Linux (e.g., inside a Docker container), you must install system dependencies and use a virtual environment before running the setup script:

1. Install System Dependencies:

apk update
apk add bash git python3 py3-pip nodejs npm curl build-base python3-dev linux-headers libffi-dev

2. Set up Virtual Environment (Required for Python 3.12+):

uv venv
source .venv/bin/activate
# uv handles pip/setuptools/wheel automatically

3. Run the Quickstart Script:

./quickstart.sh

Manual Setup (Alternative)

If you prefer to set up manually or the script fails:

1. Sync Workspace Dependencies

# From repository root - this creates a single .venv at the root
uv sync

Note: The uv sync command uses the workspace configuration in pyproject.toml to install both core (framework) and tools (aden_tools) packages together. This is the recommended approach over individual pip install -e commands which may fail due to circular dependencies.

2. Activate the Virtual Environment

# Linux/macOS
source .venv/bin/activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

3. Verify Installation

uv run python -c "import framework; print('✓ framework OK')"
uv run python -c "import aden_tools; print('✓ aden_tools OK')"
uv run python -c "import litellm; print('✓ litellm OK')"

Windows Tip: On Windows, if the verification commands fail, ensure you are running them in WSL or after disabling Python App Execution Aliases in Windows Settings → Apps → App Execution Aliases.

Requirements

Python Version

• Minimum: Python 3.11
• Recommended: Python 3.11 or 3.12
• Tested on: Python 3.11, 3.12, 3.13

System Requirements

• pip (latest version)
• 2GB+ RAM
• Internet connection (for LLM API calls)
• For Windows users: WSL 2 is recommended for full compatibility.

API Keys

We recommend using quickstart.sh for LLM API credential setup and /hive-credentials for the tools credentials

Running Agents

The hive CLI is the primary interface for running agents:

# Browse and run agents interactively (Recommended)
hive tui

# Run a specific agent
hive run exports/my_agent --input '{"task": "Your input here"}'

# Run with TUI dashboard
hive run exports/my_agent --tui

CLI Command Reference

Using Python directly (alternative)

# From /hive/ directory
PYTHONPATH=exports uv run python -m agent_name COMMAND

Windows (PowerShell):

$env:PYTHONPATH="core;exports"
python -m agent_name COMMAND

Building New Agents and Run Flow

Build and run an agent using Claude Code CLI with the agent building skills:

1. Install Claude Skills (One-time)

./quickstart.sh

This verifies agent-related Claude Code skills are available:

• /hive - Complete workflow for building agents
• /hive-create - Step-by-step build guide
• /hive-concepts - Fundamental concepts
• /hive-patterns - Best practices
• /hive-test - Test and validate agents

Cursor IDE Support

Skills are also available in Cursor. To enable:

1. Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
2. Run MCP: Enable to enable MCP servers
3. Restart Cursor to load the MCP servers from .cursor/mcp.json
4. Type / in Agent chat and search for skills (e.g., /hive-create)

2. Build an Agent

Claude Code:

claude> /hive

Codex CLI:

codex> use hive

Follow the prompts to:

1. Define your agent's goal
2. Design the workflow nodes
3. Connect nodes with edges
4. Generate the agent package under exports/

This step creates the initial agent structure required for further development.

3. Define Agent Logic

claude> /hive-concepts

Follow the prompts to:

1. Understand the agent architecture and file structure
2. Define the agent's goal, success criteria, and constraints
3. Learn node types (event_loop only)
4. Discover and validate available tools before use

This step establishes the core concepts and rules needed before building an agent.

4. Apply Agent Patterns

claude> /hive-patterns

Follow the prompts to:

1. Apply best-practice agent design patterns
2. Add pause/resume flows for multi-turn interactions
3. Improve robustness with routing, fallbacks, and retries
4. Avoid common anti-patterns during agent construction

This step helps optimize agent design before final testing.

5. Test Your Agent

claude> /hive-test

Follow the prompts to:

1. Generate test guidelines for constraints and success criteria
2. Write agent tests directly under exports/{agent}/tests/
3. Run goal-based evaluation tests
4. Debug failing tests and iterate on agent improvements

This step verifies that the agent meets its goals before production use.

Troubleshooting

"externally-managed-environment" error (PEP 668)

Cause: Python 3.12+ on macOS/Homebrew, WSL, or some Linux distros prevents system-wide pip installs.

Solution: Create and use a virtual environment:

# Create virtual environment
uv venv

# Activate it
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate   # Windows

# Then run setup
./quickstart.sh

Always activate the venv before running agents:

source .venv/bin/activate
PYTHONPATH=exports uv run python -m your_agent_name demo

PowerShell: “running scripts is disabled on this system”

Run once per session:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

"ModuleNotFoundError: No module named 'framework'"

Solution: Sync the workspace dependencies:

# From repository root
uv sync

"ModuleNotFoundError: No module named 'aden_tools'"

Solution: Sync the workspace dependencies:

# From repository root
uv sync

Or run the setup script:

./quickstart.sh

"ModuleNotFoundError: No module named 'openai._models'"

Cause: Outdated openai package (0.27.x) incompatible with litellm

Solution: Upgrade openai:

uv pip install --upgrade "openai>=1.0.0"

"No module named 'your_agent_name'"

Cause: Not running from project root, missing PYTHONPATH, or agent not yet created

Solution: Ensure you're in /hive/ and use:

Linux/macOS:

PYTHONPATH=exports uv run python -m your_agent_name validate

Windows:

$env:PYTHONPATH="core;exports"
python -m support_ticket_agent validate

Agent imports fail with "broken installation"

Symptom: pip list shows packages pointing to non-existent directories

Solution: Reinstall packages properly:

# Remove broken installations
uv pip uninstall framework tools

# Reinstall correctly
./quickstart.sh

Package Structure

The Hive framework consists of three Python packages:

hive/
├── .venv/                   # Single workspace venv (created by uv sync)
├── core/                    # Core framework (runtime, graph executor, LLM providers)
│   ├── framework/
│   └── pyproject.toml
│
├── tools/                   # Tools and MCP servers
│   ├── src/
│   │   └── aden_tools/     # Actual package location
│   └── pyproject.toml
│
├── exports/                 # Agent packages (user-created, gitignored)
│   └── your_agent_name/     # Created via /hive-create
│
└── examples/
    └── templates/           # Pre-built template agents

Virtual Environment Setup

Hive uses uv workspaces to manage dependencies. When you run uv sync from the repository root, a single .venv is created at the root containing both packages.

Benefits of Workspace Mode

• Single environment - No need to switch between multiple venvs
• Unified dependencies - Consistent package versions across core and tools
• Simpler development - One activation, access to everything

How It Works

When you run ./quickstart.sh or uv sync:

1. /.venv/ - Single root virtual environment is created
2. Both framework (from core/) and aden_tools (from tools/) are installed
3. All dependencies (anthropic, litellm, beautifulsoup4, pandas, etc.) are resolved together

If you need to refresh the environment:

# From repository root
uv sync

Cross-Package Imports

The core and tools packages are intentionally independent:

• No cross-imports: framework does not import aden_tools directly, and vice versa
• Communication via MCP: Tools are exposed to agents through MCP servers, not direct Python imports
• Runtime integration: The agent runner loads tools via the MCP protocol at runtime

If you need to use both packages in a single script (e.g., for testing), prefer uv run with PYTHONPATH:

PYTHONPATH=tools/src uv run python your_script.py

MCP Server Configuration

The .mcp.json at project root configures MCP servers to run through uv run in each package directory:

{
  "mcpServers": {
    "agent-builder": {
      "command": "uv",
      "args": ["run", "-m", "framework.mcp.agent_builder_server"],
      "cwd": "core"
    },
    "tools": {
      "command": "uv",
      "args": ["run", "mcp_server.py", "--stdio"],
      "cwd": "tools"
    }
  }
}

This ensures each MCP server runs with the correct project environment managed by uv.

Why PYTHONPATH is Required

The packages are installed in editable mode (uv pip install -e), which means:

• framework and aden_tools are globally importable (no PYTHONPATH needed)
• exports is NOT installed as a package (PYTHONPATH required)

This design allows agents in exports/ to be:

• Developed independently
• Version controlled separately
• Deployed as standalone packages

Development Workflow

1. Setup (Once)

./quickstart.sh

2. Build Agent (Claude Code)

claude> /hive
Enter goal: "Build an agent that processes customer support tickets"

3. Validate Agent

PYTHONPATH=exports uv run python -m your_agent_name validate

4. Test Agent

claude> /hive-test

5. Run Agent

# Interactive dashboard
hive tui

# Or run directly
hive run exports/your_agent_name --input '{"task": "..."}'

IDE Setup

VSCode

Add to .vscode/settings.json:

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

PyCharm

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

Environment Variables

Required for LLM Operations

export ANTHROPIC_API_KEY="sk-ant-..."

Optional Configuration

# Fernet encryption key for credential store at ~/.hive/credentials
export HIVE_CREDENTIAL_KEY="your-fernet-key"

# Agent storage location (default: /tmp)
export AGENT_STORAGE_PATH="/custom/storage"

Opencode Setup

Opencode is fully supported as a coding agent.

Automatic Setup

Run the quickstart script in the root directory:

./quickstart.sh

Codex Setup

OpenAI Codex CLI (v0.101.0+) is supported with project-level config:

• .codex/config.toml — MCP server configuration (agent-builder)
• .agents/skills/ — Symlinks to Hive skills

These files are tracked in git and available on clone. To use Codex with Hive:

1. Run codex in the repo root
2. Type use hive to start the agent workflow

Quick verification:

test -f .codex/config.toml && echo "OK: Codex config" || echo "MISSING: .codex/config.toml"
test -d .agents/skills/hive && echo "OK: Skills" || echo "MISSING: .agents/skills/"

Additional Resources

• Framework Documentation: core/README.md
• Tools Documentation: tools/README.md
• Example Agents: examples/
• Agent Building Guide: .claude/skills/hive-create/SKILL.md
• Testing Guide: .claude/skills/hive-test/SKILL.md

Contributing

When contributing agent packages:

1. Place agents in exports/agent_name/
2. Follow the standard agent structure (see existing agents)
3. Include README.md with usage instructions
4. Add tests if using /hive-test
5. Document required environment variables

Support

• Issues: https://github.com/adenhq/hive/issues
• Discord: https://discord.com/invite/MXE49hrKDk
• Documentation: https://docs.adenhq.com/