Skip to content

Latest commit

 

History

History
213 lines (159 loc) · 6.01 KB

getting-started.md

File metadata and controls

213 lines (159 loc) · 6.01 KB

Getting Started

This guide will help you set up the Aden Agent Framework and build your first agent.

Prerequisites

  • Python 3.11+ (Download) - Python 3.12 or 3.13 recommended
  • pip - Package installer for Python (comes with Python)
  • git - Version control
  • Claude Code (Install) - Optional, for using building skills

Quick Start

The fastest way to get started:

# 1. Clone the repository
git clone https://github.com/adenhq/hive.git
cd hive

# 2. Run automated setup
./quickstart.sh

# 3. Verify installation (optional, quickstart.sh already verifies)
uv run python -c "import framework; import aden_tools; print('✓ Setup complete')"

Building Your First Agent

Option 1: Using Claude Code Skills (Recommended)

# Setup already done via quickstart.sh above

# Start Claude Code and build an agent
claude> /hive

Follow the interactive prompts to:

  1. Define your agent's goal
  2. Design the workflow (nodes and edges)
  3. Generate the agent package
  4. Test the agent

Option 2: Create Agent Manually

Note: The exports/ directory is where your agents are created. It is not included in the repository (gitignored) because agents are user-generated via Claude Code skills or created manually.

# Create exports directory if it doesn't exist
mkdir -p exports/my_agent

# Create your agent structure
cd exports/my_agent
# Create agent.json, tools.py, README.md (see developer-guide.md for structure)

# Validate the agent
PYTHONPATH=exports uv run python -m my_agent validate

Option 3: Manual Code-First (Minimal Example)

If you prefer to start with code rather than CLI wizards, check out the manual agent example:

# View the minimal example
cat core/examples/manual_agent.py

# Run it (no API keys required)
uv run python core/examples/manual_agent.py

This demonstrates the core runtime loop using pure Python functions, skipping the complexity of LLM setup and file-based configuration.

Project Structure

hive/
├── core/                   # Core Framework
│   ├── framework/          # Agent runtime, graph executor
│   │   ├── builder/        # Agent builder utilities
│   │   ├── credentials/    # Credential management
│   │   ├── graph/          # GraphExecutor - executes node graphs
│   │   ├── llm/            # LLM provider integrations
│   │   ├── mcp/            # MCP server integration
│   │   ├── runner/         # AgentRunner - loads and runs agents
│   │   ├── runtime/        # Runtime environment
│   │   ├── schemas/        # Data schemas
│   │   ├── storage/        # File-based persistence
│   │   ├── testing/        # Testing utilities
│   │   └── tui/            # Terminal UI dashboard
│   └── pyproject.toml      # Package metadata
│
├── tools/                  # MCP Tools Package
│   ├── mcp_server.py       # MCP server entry point
│   └── src/aden_tools/     # Tools for agent capabilities
│       └── tools/          # Individual tool implementations
│           ├── web_search_tool/
│           ├── web_scrape_tool/
│           └── file_system_toolkits/
│
├── exports/                # Agent Packages (user-generated, not in repo)
│   └── your_agent/         # Your agents created via /hive
│
├── examples/
│   └── templates/          # Pre-built template agents
│
├── .claude/                # Claude Code Skills
│   └── skills/
│       ├── hive/
│       ├── hive-create/
│       ├── hive-concepts/
│       ├── hive-patterns/
│       └── hive-test/
│
└── docs/                   # Documentation

Running an Agent

# 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

API Keys Setup

For running agents with real LLMs:

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export ANTHROPIC_API_KEY="your-key-here"
export OPENAI_API_KEY="your-key-here"        # Optional
export BRAVE_SEARCH_API_KEY="your-key-here"  # Optional, for web search

Get your API keys:

Testing Your Agent

# Using Claude Code
claude> /hive-test

# Or manually
PYTHONPATH=exports uv run python -m my_agent test

# Run with specific test type
PYTHONPATH=exports uv run python -m my_agent test --type constraint
PYTHONPATH=exports uv run python -m my_agent test --type success

Next Steps

  1. TUI Dashboard: Run hive tui to explore agents interactively
  2. Detailed Setup: See environment-setup.md
  3. Developer Guide: See developer-guide.md
  4. Build Agents: Use /hive skill in Claude Code
  5. Custom Tools: Learn to integrate MCP servers
  6. Join Community: Discord

Troubleshooting

ModuleNotFoundError: No module named 'framework'

# Reinstall framework package
cd core
uv pip install -e .

ModuleNotFoundError: No module named 'aden_tools'

# Reinstall tools package
cd tools
uv pip install -e .

LLM API Errors

# Verify API key is set
echo $ANTHROPIC_API_KEY

Package Installation Issues

# Remove and reinstall
pip uninstall -y framework tools
./quickstart.sh

Getting Help