Files

T

RichardTang-Aden bd31323876 Merge pull request #1999 from Jai-Harrish/docs/remove-stray-orchestration-text

docs: remove stray 'orchestration' text from project structure

2026-01-28 13:54:33 -08:00

19 KiB

Raw Blame History

Developer Guide

This guide covers everything you need to know to develop with the Aden Agent Framework.

Repository Overview
Initial Setup
Project Structure
Building Agents
Testing Agents
Code Style & Conventions
Git Workflow
Common Tasks
Troubleshooting

Repository Overview

Aden Agent Framework is a Python-based system for building goal-driven, self-improving AI agents.

Package	Directory	Description	Tech Stack
framework	`/core`	Core runtime, graph executor, protocols	Python 3.11+
tools	`/tools`	19 MCP tools for agent capabilities	Python 3.11+
exports	`/exports`	Agent packages and examples	Python 3.11+
skills	`.claude`	Claude Code skills for building/testing	Markdown

Key Principles

Goal-Driven Development: Define objectives, framework generates agent graphs
Self-Improving: Agents adapt and evolve based on failures
SDK-Wrapped Nodes: Built-in memory, monitoring, and tool access
Human-in-the-Loop: Intervention points for human oversight
Production-Ready: Evaluation, testing, and deployment infrastructure

Initial Setup

Prerequisites

Ensure you have installed:

Python 3.11+ - Download (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)

Verify installation:

python --version    # Should be 3.11+
pip --version       # Should be latest
git --version       # Any recent version

Step-by-Step Setup

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

# 2. Run automated Python setup
./scripts/setup-python.sh

The setup script performs these actions:

Checks Python version (3.11+)
Installs framework package from /core (editable mode)
Installs aden_tools package from /tools (editable mode)
Fixes package compatibility (upgrades openai for litellm)
Verifies all installations

API Keys (Optional)

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 tool

Get API keys:

Anthropic: console.anthropic.com
OpenAI: platform.openai.com
Brave Search: brave.com/search/api

Install Claude Code Skills

# Install building-agents and testing-agent skills
./quickstart.sh

This installs agent-related Claude Code skills:

/building-agents-core - Fundamental agent concepts
/building-agents-construction - Step-by-step agent building
/building-agents-patterns - Best practices and design patterns
/testing-agent - Test and validate agents
/agent-workflow - End-to-end guided workflow

Verify Setup

# Verify package imports
python -c "import framework; print('✓ framework OK')"
python -c "import aden_tools; print('✓ aden_tools OK')"
python -c "import litellm; print('✓ litellm OK')"

# Run an example agent
PYTHONPATH=core:exports python -m support_ticket_agent validate

Project Structure

hive/                                    # Repository root
│
├── .github/                             # GitHub configuration
│   ├── workflows/
│   │   ├── ci.yml                       # Runs on every PR
│   │   └── release.yml                  # Runs on tags
│   ├── ISSUE_TEMPLATE/                  # Bug report & feature request templates
│   ├── PULL_REQUEST_TEMPLATE.md         # PR description template
│   └── CODEOWNERS                       # Auto-assign reviewers
│
├── .claude/                             # Claude Code Skills
│   └── skills/                          # Skills for building
│       ├── building-agents-core/
|       |   ├── SKILL.md                 # Main skill definition
│       |   └── examples
│       ├── building-agents-patterns/
|       |   ├── SKILL.md
│       |   └── examples
│       ├── building-agents-construction/
|       |   ├── SKILL.md
│       |   └── examples
│       ├── testing-agent/               # Skills for testing agents
│       │   ├── SKILL.md
│       |   └── examples
│       └── agent-workflow/              # Complete workflow 
|           ├── SKILL.md
│           └── examples
│
├── core/                                # CORE FRAMEWORK PACKAGE
│   ├── framework/                       # Main package code
│   │   ├── runner/                      # AgentRunner - loads and runs agents
│   │   ├── executor/                    # GraphExecutor - executes node graphs
│   │   ├── protocols/                   # Standard protocols (hooks, tracing, etc.)
│   │   ├── llm/                         # LLM provider integrations (Anthropic, OpenAI, etc.)
│   │   ├── memory/                      # Memory systems (STM, LTM/RLM)
│   │   ├── tools/                       # Tool registry and management
│   │   └── __init__.py
│   ├── pyproject.toml                   # Package metadata and dependencies
│   ├── requirements.txt                 # Python dependencies
│   ├── README.md                        # Framework documentation
│   ├── MCP_INTEGRATION_GUIDE.md         # MCP server integration guide
│   └── docs/                            # Protocol documentation
│
├── tools/                               # TOOLS PACKAGE (19 MCP tools)
│   ├── src/
│   │   └── aden_tools/
│   │       ├── tools/                   # Individual tool implementations
│   │       │   ├── web_search_tool/
│   │       │   ├── web_scrape_tool/
│   │       │   ├── file_system_toolkits/
│   │       │   └── ...                  # 19 tools total
│   │       ├── mcp_server.py            # HTTP MCP server
│   │       └── __init__.py
│   ├── pyproject.toml                   # Package metadata
│   ├── requirements.txt                 # Python dependencies
│   └── README.md                        # Tools documentation
│
├── exports/                             # AGENT PACKAGES
│   ├── support_ticket_agent/            # Example: Support ticket handler
│   ├── market_research_agent/           # Example: Market research
│   ├── outbound_sales_agent/            # Example: Sales outreach
│   ├── personal_assistant_agent/        # Example: Personal assistant
│   └── ...                              # More agent examples
│
├── docs/                                # Documentation
│   ├── getting-started.md               # Quick start guide
│   ├── configuration.md                 # Configuration reference
│   ├── architecture.md                  # System architecture
│   └── articles/                        # Technical articles
│
├── scripts/                             # Build & utility scripts
│   ├── setup-python.sh                  # Python environment setup
│   └── setup.sh                         # Legacy setup script
│
├── quickstart.sh                        # Install Claude Code skills
├── ENVIRONMENT_SETUP.md                 # Complete Python setup guide
├── README.md                            # Project overview
├── DEVELOPER.md                         # This file
├── CONTRIBUTING.md                      # Contribution guidelines
├── CHANGELOG.md                         # Version history
├── ROADMAP.md                           # Product roadmap
├── LICENSE                              # Apache 2.0 License
├── CODE_OF_CONDUCT.md                   # Community guidelines
└── SECURITY.md                          # Security policy

Building Agents

Using Claude Code Skills

The fastest way to build agents is using the Claude Code skills:

# Install skills (one-time)
./quickstart.sh

# Build a new agent
claude> /building-agents-construction

# Test the agent
claude> /testing-agent

Agent Development Workflow

Define Your Goal

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

Design the Workflow
- The skill guides you through defining nodes
- Each node is a unit of work (LLM call, function, router)
- Edges define how execution flows
Generate the Agent
- The skill generates a complete Python package in exports/
- Includes: agent.json, tools.py, README.md

Validate the Agent

PYTHONPATH=core:exports python -m your_agent_name validate

Test the Agent
```
claude> /testing-agent
```

Manual Agent Development

If you prefer to build agents manually:

# exports/my_agent/agent.json
{
  "goal": {
    "goal_id": "support_ticket",
    "name": "Support Ticket Handler",
    "description": "Process customer support tickets",
    "success_criteria": "Ticket is categorized, prioritized, and routed correctly"
  },
  "nodes": [
    {
      "node_id": "analyze",
      "name": "Analyze Ticket",
      "node_type": "llm_generate",
      "system_prompt": "Analyze this support ticket...",
      "input_keys": ["ticket_content"],
      "output_keys": ["category", "priority"]
    }
  ],
  "edges": [
    {
      "edge_id": "start_to_analyze",
      "source": "START",
      "target": "analyze",
      "condition": "on_success"
    }
  ]
}

Running Agents

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

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

# Run agent with input
PYTHONPATH=core:exports python -m agent_name run --input '{
  "ticket_content": "My login is broken",
  "customer_id": "CUST-123"
}'

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

Testing Agents

Using the Testing Agent Skill

# Run tests for an agent
claude> /testing-agent

This generates and runs:

Constraint tests - Verify agent respects constraints
Success tests - Verify agent achieves success criteria
Integration tests - End-to-end workflows

Manual Testing

# Run all tests for an agent
PYTHONPATH=core:exports python -m agent_name test

# Run specific test type
PYTHONPATH=core:exports python -m agent_name test --type constraint
PYTHONPATH=core:exports python -m agent_name test --type success

# Run with parallel execution
PYTHONPATH=core:exports python -m agent_name test --parallel 4

# Fail fast (stop on first failure)
PYTHONPATH=core:exports python -m agent_name test --fail-fast

Writing Custom Tests

# exports/my_agent/tests/test_custom.py
import pytest
from framework.runner import AgentRunner

def test_ticket_categorization():
    """Test that tickets are categorized correctly"""
    runner = AgentRunner.from_file("exports/my_agent/agent.json")

    result = runner.run({
        "ticket_content": "I can't log in to my account"
    })

    assert result["category"] == "authentication"
    assert result["priority"] in ["high", "medium", "low"]

Code Style & Conventions

Python Code Style

PEP 8 - Follow Python style guide
Type hints - Use for function signatures and class attributes
Docstrings - Document classes and public functions
Black - Code formatter (run with black .)

# Good
from typing import Optional, Dict, Any

def process_ticket(
    ticket_content: str,
    customer_id: str,
    priority: Optional[str] = None
) -> Dict[str, Any]:
    """
    Process a customer support ticket.

    Args:
        ticket_content: The content of the ticket
        customer_id: The customer's ID
        priority: Optional priority override

    Returns:
        Dictionary with processing results
    """
    # Implementation
    return {"status": "processed", "id": ticket_id}

# Avoid
def process_ticket(ticket_content, customer_id, priority=None):
    # No types, no docstring
    return {"status": "processed", "id": ticket_id}

Agent Package Structure

my_agent/
├── __init__.py              # Package initialization
├── __main__.py              # CLI entry point
├── agent.json               # Agent definition (nodes, edges, goal)
├── tools.py                 # Custom tools (optional)
├── mcp_servers.json         # MCP server config (optional)
├── README.md                # Agent documentation
└── tests/                   # Test files
    ├── __init__.py
    ├── test_constraint.py   # Constraint tests
    └── test_success.py      # Success criteria tests

File Naming

Type	Convention	Example
Modules	snake_case	`ticket_handler.py`
Classes	PascalCase	`TicketHandler`
Functions/Variables	snake_case	`process_ticket()`
Constants	UPPER_SNAKE_CASE	`MAX_RETRIES = 3`
Test files	`test_` prefix	`test_ticket_handler.py`
Agent packages	snake_case	`support_ticket_agent/`

Import Order

Standard library
Third-party packages
Framework imports
Local imports

# Standard library
import json
from typing import Dict, Any

# Third-party
import litellm
from pydantic import BaseModel

# Framework
from framework.runner import AgentRunner
from framework.context import NodeContext

# Local
from .tools import custom_tool

Git Workflow

Branch Naming

feature/add-user-authentication
bugfix/fix-login-redirect
hotfix/security-patch
chore/update-dependencies
docs/improve-readme

Commit Messages

Follow Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

feat - New feature
fix - Bug fix
docs - Documentation only
style - Formatting, missing semicolons, etc.
refactor - Code change that neither fixes a bug nor adds a feature
test - Adding or updating tests
chore - Maintenance tasks

Examples:

feat(auth): add JWT authentication

fix(api): handle null response from external service

docs(readme): update installation instructions

chore(deps): update React to 18.2.0

Pull Request Process

Create a feature branch from main
Make your changes with clear commits
Run tests locally: npm run test
Run linting: npm run lint
Push and create a PR
Fill out the PR template
Request review from CODEOWNERS
Address feedback
Squash and merge when approved

Debugging

Backend Debugging

VS Code Debugging:

Add Node debug configuration:

{
  "type": "node",
  "request": "launch",
  "name": "Debug Backend",
  "runtimeExecutable": "npm",
  "runtimeArgs": ["run", "dev"],
  "cwd": "${workspaceFolder}/hive",
  "console": "integratedTerminal"
}

Set breakpoints in your code
Press F5 to start debugging

Logging:

import { logger } from "../utils/logger";

// Add debug logs
logger.debug("Processing request", {
  userId: req.user.id,
  body: req.body,
});

Common Tasks

Adding Python Dependencies

# Add to core framework
cd core
pip install <package>
# Then add to requirements.txt or pyproject.toml

# Add to tools package
cd tools
pip install <package>
# Then add to requirements.txt or pyproject.toml

# Reinstall in editable mode
pip install -e .

Creating a New Agent

# Option 1: Use Claude Code skill (recommended)
claude> /building-agents-construction

# Option 2: Create manually
# Note: exports/ is initially empty (gitignored). Create your agent directory:
mkdir -p exports/my_new_agent
cd exports/my_new_agent
# Create agent.json, tools.py, README.md (see Agent Package Structure below)

# Option 3: Use the agent builder MCP tools (advanced)
# See core/MCP_BUILDER_TOOLS_GUIDE.md

Adding Custom Tools to an Agent

# exports/my_agent/tools.py
from typing import Dict, Any

def my_custom_tool(param1: str, param2: int) -> Dict[str, Any]:
    """
    Description of what this tool does.

    Args:
        param1: Description of param1
        param2: Description of param2

    Returns:
        Dictionary with tool results
    """
    # Implementation
    return {"result": "success", "data": ...}

# Register tool in agent.json
{
  "nodes": [
    {
      "node_id": "use_tool",
      "node_type": "function",
      "tools": ["my_custom_tool"],
      ...
    }
  ]
}

Adding MCP Server Integration

# 1. Create mcp_servers.json in your agent package
# exports/my_agent/mcp_servers.json
{
  "tools": {
    "transport": "stdio",
    "command": "python",
    "args": ["-m", "aden_tools.mcp_server"],
    "cwd": "tools/",
    "description": "File system and web tools"
  }
}

# 2. Reference tools in agent.json
{
  "nodes": [
    {
      "node_id": "search",
      "tools": ["web_search", "web_scrape"],
      ...
    }
  ]
}

Setting Environment Variables

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

# Or create .env file (not committed to git)
echo 'ANTHROPIC_API_KEY=your-key-here' >> .env

Debugging Agent Execution

# Add debug logging to your agent
import logging
logging.basicConfig(level=logging.DEBUG)

# Run with verbose output
PYTHONPATH=core:exports python -m agent_name run --input '{...}' --verbose

# Use mock mode to test without LLM calls
PYTHONPATH=core:exports python -m agent_name run --mock --input '{...}'

Troubleshooting

Port Already in Use

# Find process using port
lsof -i :3000
lsof -i :4000

# Kill process
kill -9 <PID>

# Or change ports in config.yaml and regenerate

Docker Issues

# Reset Docker state
docker compose down -v
docker system prune -f
docker compose build --no-cache
docker compose up

Environment Variables Not Loading

# Regenerate from config.yaml
npm run generate:env

# Verify files exist
cat .env
cat hive/.env

# Restart dev servers after changing env

Getting Help

Documentation: Check the /docs folder
Issues: Search existing issues
Discord: Join our community
Code Review: Tag a maintainer on your PR

Happy coding! 🐝

19 KiB Raw Blame History