Skip to content

ENVIRONMENT_SETUP.md

Latest commit

 

History

History
379 lines (261 loc) · 8.21 KB

ENVIRONMENT_SETUP.md

File metadata and controls

379 lines (261 loc) · 8.21 KB

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
./scripts/setup-python.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)
  • Fix package compatibility issues (openai + litellm)
  • Verify all installations

Manual Setup (Alternative)

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

1. Install Core Framework

cd core
pip install -e .

2. Install Tools Package

cd tools
pip install -e .

3. Upgrade OpenAI Package

# litellm requires openai >= 1.0.0
pip install --upgrade "openai>=1.0.0"

4. Verify Installation

python -c "import framework; print('✓ framework OK')"
python -c "import aden_tools; print('✓ aden_tools OK')"
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 (Optional)

For running agents with real LLMs:

export ANTHROPIC_API_KEY="your-key-here"

Running Agents

All agent commands must be run from the project root with PYTHONPATH set:

# From /hive/ directory
PYTHONPATH=core:exports python -m agent_name COMMAND

Example: Support Ticket Agent

# Validate agent structure
PYTHONPATH=core:exports python -m support_ticket_agent validate

# Show agent information
PYTHONPATH=core:exports python -m support_ticket_agent info

# Run agent with input
PYTHONPATH=core:exports python -m support_ticket_agent run --input '{
  "ticket_content": "My login is broken. Error 401.",
  "customer_id": "CUST-123",
  "ticket_id": "TKT-456"
}'

# Run in mock mode (no LLM calls)
PYTHONPATH=core:exports python -m support_ticket_agent run --mock --input '{...}'

Example: Other Agents

# Market Research Agent
PYTHONPATH=core:exports python -m market_research_agent info

# Outbound Sales Agent
PYTHONPATH=core:exports python -m outbound_sales_agent validate

# Personal Assistant Agent
PYTHONPATH=core:exports python -m personal_assistant_agent run --input '{...}'

Building New Agents

Use Claude Code CLI with the agent building skills:

1. Install Skills (One-time)

./quickstart.sh

This installs:

  • /building-agents - Build new agents
  • /testing-agent - Test agents

2. Build an Agent

claude> /building-agents

Follow the prompts to:

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

3. Test Your Agent

claude> /testing-agent

Creates comprehensive test suites for your agent.

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
python3 -m venv .venv

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

# Then run setup
./scripts/setup-python.sh

Always activate the venv before running agents:

source .venv/bin/activate
PYTHONPATH=core:exports python -m your_agent_name demo

"ModuleNotFoundError: No module named 'framework'"

Solution: Install the core package:

cd core && pip install -e .

"ModuleNotFoundError: No module named 'aden_tools'"

Solution: Install the tools package:

cd tools && pip install -e .

Or run the setup script:

./scripts/setup-python.sh

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

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

Solution: Upgrade openai:

pip install --upgrade "openai>=1.0.0"

"No module named 'support_ticket_agent'"

Cause: Not running from project root or missing PYTHONPATH

Solution: Ensure you're in the project root directory and use:

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
pip uninstall -y framework tools

# Reinstall correctly
./scripts/setup-python.sh

Package Structure

The Hive framework consists of three Python packages:

hive/
├── core/                    # Core framework (runtime, graph executor, LLM providers)
│   ├── framework/
│   ├── pyproject.toml
│   └── requirements.txt
│
├── tools/                   # Tools and MCP servers
│   ├── src/
│   │   └── aden_tools/     # Actual package location
│   ├── pyproject.toml
│   └── README.md
│
└── exports/                 # Agent packages (your agents go here)
    ├── support_ticket_agent/
    ├── market_research_agent/
    ├── outbound_sales_agent/
    └── personal_assistant_agent/

Why PYTHONPATH is Required

The packages are installed in editable mode (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)

./scripts/setup-python.sh

2. Build Agent (Claude Code)

claude> /building-agents
Enter goal: "Build an agent that processes customer support tickets"

3. Validate Agent

PYTHONPATH=core:exports python -m support_ticket_agent validate

4. Test Agent

claude> /testing-agent

5. Run Agent

PYTHONPATH=core:exports python -m support_ticket_agent run --input '{...}'

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

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

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

Additional Resources

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 /testing-agent
  5. Document required environment variables

Support