evenage 0.1.0

EvenAge - A transparent, Docker-native, observable, distributed agent framework. A superset of CrewAI with explicit communication, real distributed runtime, and local observability.

EvenAge

A transparent, Docker-native, observable, distributed agent framework.

EvenAge is a superset of CrewAI that removes excessive abstractions and introduces real distributed runtime, local observability, and explicit agent communication.

🎯 Philosophy

CrewAI is too abstract, making it nearly impossible to understand or debug what's happening under the hood.

EvenAge fixes this by being:

• Transparent — All logic (task flow, prompts, tool calls) visible and traceable
• Pluggable — Configure your own queues, databases, models, or tools
• Observable — Every agent action recorded via OpenTelemetry
• Containerized — Everything runs inside Docker for predictable behavior

In short: EvenAge = CrewAI with explicit communication, Docker-native execution, local observability, and zero hidden magic.

🏗️ Architecture

Communication Model

Unlike CrewAI's internal synchronous calls, EvenAge uses Redis Streams for explicit message passing:

Controller → Redis Queue → Agent Worker → Redis Response Stream

Each agent runs in its own container and consumes tasks from a dedicated Redis stream.

Services

• PostgreSQL (with pgvector) — Stores traces, job history, agent metadata
• Redis — Message bus for task distribution
• MinIO — S3-compatible storage for artifacts and large payloads
• Jaeger — OpenTelemetry trace collection and visualization
• Prometheus — Metrics collection and monitoring
• API Server — FastAPI server for job submission and queries
• Worker Containers — One per agent, consumes and processes tasks
• Dashboard — Real-time monitoring and agent interaction

🚀 Quick Start

Installation

# Clone the repository
cd lib/evenage

# Install locally (for now)
pip install -e .

Create a Project

# Initialize a new project
evenage init my_project

# Navigate to project
cd my_project

# Add agents
evenage add agent summarizer
evenage add agent analyzer

# Start the environment
evenage run dev

This will start all services and open the dashboard at http://localhost:5173.

📦 Project Structure

my_project/
├── evenage.yml              # Project configuration
├── docker-compose.yml       # Docker services (auto-generated)
├── Dockerfile               # Container definition
├── .env                     # Environment variables
├── agents/                  # Agent configurations
│   ├── summarizer/
│   │   └── agent.yml
│   └── analyzer/
│       └── agent.yml
├── tools/                   # Custom tools
│   └── my_tool.py
└── pipelines/               # Pipeline definitions
    └── analysis_pipeline.yml

🤖 Creating Agents

Add an Agent

evenage add agent researcher

This will:

1. Create agents/researcher/agent.yml
2. Add worker service to docker-compose.yml
3. Register agent in evenage.yml

Agent Configuration

agents/researcher/agent.yml:

name: researcher
role: Research Specialist
goal: Find and analyze information from various sources
backstory: An expert researcher with years of experience
llm: gpt-4
tools:
  - web_search
  - document_reader
max_iterations: 15
allow_delegation: false
verbose: true

🔧 Custom Tools

Add a Tool

evenage add tool web_search

Edit tools/web_search.py:

def web_search(query: str, max_results: int = 5) -> str:
    """Search the web for information."""
    # Implementation here
    return results

📋 Pipelines

Create pipelines/analysis.yml:

name: document_analysis
description: Analyze documents and generate insights
tasks:
  - name: summarize
    description: Summarize the document: {document}
    agent: summarizer
    expected_output: A concise summary
    
  - name: analyze
    description: Analyze the summary for key insights
    agent: analyzer
    context: [summarize]
    expected_output: Key insights and recommendations

Run a Pipeline

evenage run job pipelines/analysis.yml --input document="report.pdf"

🔍 Observability

View Traces

Navigate to Jaeger at http://localhost:16686 to see:

• Task execution traces
• LLM API calls
• Tool invocations
• Error spans

View Metrics

Navigate to Prometheus at http://localhost:9090 to query:

• evenage_agent_task_duration_seconds — Task execution time
• evenage_queue_depth — Pending tasks per agent
• evenage_tokens_total — Token usage
• evenage_errors_total — Error counts

Agent Logs

# View logs for an agent
evenage logs summarizer

# Follow logs in real-time
evenage logs summarizer -f

🌐 API Reference

Submit Job

curl -X POST http://localhost:8000/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_name": "analysis",
    "inputs": {"document": "report.pdf"}
  }'

Get Job Status

curl http://localhost:8000/jobs/{job_id}

List Agents

curl http://localhost:8000/agents

📊 Dashboard

Access the dashboard at http://localhost:5173 to:

• View all active agents
• Monitor real-time logs
• Inspect OpenTelemetry traces
• Interact with individual agents
• Visualize job workflows
• Check system health metrics

🐳 Docker Commands

# Start all services
evenage run dev

# View logs
evenage logs <agent_name>

# Stop all services
evenage stop

# Rebuild containers
docker compose up -d --build

⚙️ Configuration

Environment Variables

Edit .env to customize:

DATABASE_URL=postgresql://postgres:postgres@postgres:5432/evenage
REDIS_URL=redis://redis:6379
MINIO_ENDPOINT=minio:9000
OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4318
API_HOST=0.0.0.0
API_PORT=8000

Project Configuration

Edit evenage.yml:

project:
  name: my_project
  broker: redis
  database: postgres
  storage: minio
  tracing: true
  metrics: true
  agents:
    - summarizer
    - analyzer

🔄 Message Format

Task Message

{
  "task_id": "uuid",
  "job_id": "uuid",
  "source_agent": "controller",
  "target_agent": "summarizer",
  "payload": {
    "description": "Summarize this document",
    "context": "...",
    "expected_output": "..."
  },
  "trace_parent": "trace-id",
  "created_at": "timestamp"
}

Response Message

{
  "task_id": "uuid",
  "job_id": "uuid",
  "agent_name": "summarizer",
  "status": "completed",
  "result": {"output": "..."},
  "metrics": {
    "tokens": 2200,
    "latency_ms": 5200
  },
  "trace_parent": "trace-id",
  "completed_at": "timestamp"
}

🔧 Development

Prerequisites

• Python 3.10+
• Docker & Docker Compose
• Git

Setup

# Clone repository
git clone https://github.com/evenage/evenage.git
cd evenage

# Install dependencies
cd lib/evenage
pip install -e .[dev]

# Run tests
pytest

📝 CLI Reference

evenage init [project_name]        # Initialize new project
evenage add agent <name>           # Add new agent
evenage add tool <name>            # Add custom tool
evenage run dev                    # Start development environment
evenage run job <pipeline> [opts]  # Run a pipeline
evenage logs <agent> [-f]          # View agent logs
evenage stop                       # Stop all services

🆚 EvenAge vs CrewAI

Feature	CrewAI	EvenAge
Communication	Hidden internal calls	Explicit Redis message bus
Runtime	In-memory Python	Docker containers per agent
Observability	Limited logging	Full OpenTelemetry + Prometheus
Scalability	Single process	Distributed workers
Transparency	Opaque orchestration	Visible task flow
Storage	In-memory	MinIO/S3 for artifacts
Monitoring	None	Dashboard + Jaeger + Prometheus
Configuration	Code-based	YAML + Docker Compose

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE for details.

🔗 Links

• Documentation: Coming soon
• GitHub: https://github.com/evenage/evenage
• Issues: https://github.com/evenage/evenage/issues

---

Built with transparency in mind. No hidden magic. Just distributed agents.