Aetheros - Autonomous AI Agent Platform

Production-grade autonomous AI agent system with closed-loop optimization, multi-agent orchestration, and self-improving execution loops.

This is the architecture class used for:

• AI sales automation platforms
• Enterprise agent systems
• Autonomous SaaS growth engines

---

🔥 Features

Core Architecture

• LangGraph Orchestration - Deterministic state machine for agent workflows
• Self-Improving Loop - Plan → Act → Observe → Evaluate → Improve → Repeat
• MCP Tool Servers - Modular, composable tool execution layer
• Policy Engine - Guardrails, permissions, rate limiting, and safety enforcement
• Observability Stack - OpenTelemetry tracing + structured logging + metrics
• Redis Job Queue - Asynchronous execution with retry and backoff
• FastAPI Backend - Production-ready REST API
• Next.js Dashboard - Real-time job monitoring, logs, and metrics

Agent Workflow

User Input
   ↓
Planner Node (creates execution plan)
   ↓
Tool Selector Node (picks next tool)
   ↓
Executor Node (runs tool with policy check)
   ↓
Evaluator Node (scores execution quality)
   ↓
Improver Node (optimizes plan if score < 0.7)
   ↓
Result

---

📁 Monorepo Structure

aetheros/
├── apps/
│   ├── api/                 # FastAPI backend
│   ├── worker/              # Async job processors (Redis RQ)
│   ├── agent/               # LangGraph agent workflows
│   └── dashboard/           # Next.js monitoring UI
│
├── packages/
│   ├── mcp/                 # MCP tool servers (web search, HTTP, database)
│   ├── policies/            # Policy engine with guardrails
│   ├── observability/       # OpenTelemetry tracing + metrics
│   └── core/                # Shared utils, config, types
│
├── infra/
│   ├── docker/              # Dockerfiles for all services
│   └── k8s/                 # Kubernetes manifests (optional)
│
├── tests/                   # Unit + integration tests
├── docker-compose.yml       # Full system orchestration
├── .env.example             # Environment template
└── README.md

---

🚀 Quick Start

Prerequisites

• Docker & Docker Compose - Install Docker
• Python 3.11+ (for local development)
• Node.js 18+ (for dashboard development)
• Anthropic API Key (or configure for OpenAI/local LLM)

Option 1: Docker Compose (Recommended)

1. Clone and configure

cd aetheros
cp .env.example .env

2. Edit .env and add your API key

ANTHROPIC_API_KEY=your-api-key-here
LLM_PROVIDER=anthropic
MODEL_NAME=claude-3-5-sonnet-20241022

3. Start the full system

docker-compose up --build

This launches:

• API - http://localhost:8000
• Dashboard - http://localhost:3001
• Redis - localhost:6379
• MCP Tools - Ports 8001-8003

Option 2: Local Development

Backend Setup

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r apps/api/requirements.txt

# Set environment variables
export ANTHROPIC_API_KEY=your-api-key-here

# Run the API
uvicorn apps.api.main:app --reload --port 8000

# Run the worker (in separate terminal)
python -m apps.worker.worker

MCP Tools (Optional - run individually)

# Web Search
uvicorn packages.mcp.web_search:app --reload --port 8001

# HTTP Request
uvicorn packages.mcp.http_tool:app --reload --port 8002

# Database
uvicorn packages.mcp.database_tool:app --reload --port 8003

Dashboard Setup

cd apps/dashboard
npm install
npm run dev

Dashboard runs at: http://localhost:3001

---

📡 API Endpoints

Submit Agent Job

POST /run-agent
{
  "user_input": "Search for the latest AI trends and summarize them",
  "context": {}
}

Response:
{
  "job_id": "abc-123-def",
  "status": "running",
  "created_at": "2026-04-11T10:00:00"
}

Check Job Status

GET /status/{job_id}

Response:
{
  "job_id": "abc-123-def",
  "status": "completed",
  "score": 0.85,
  "tool_calls_count": 3,
  "steps_executed": 5,
  "result": {...}
}

Get Execution Logs

GET /logs/{job_id}

Response:
{
  "job_id": "abc-123-def",
  "logs": [...],
  "total": 15
}

List All Jobs

GET /jobs?limit=50&offset=0

Response:
{
  "jobs": [
    {"job_id": "...", "status": "completed", "score": 0.85},
    ...
  ],
  "total": 120
}

System Metrics

GET /metrics

Response:
{
  "counters": {"agent.completed": 10, "agent.failed": 2},
  "timings": {
    "web_search": {"avg_ms": 450, "count": 30}
  }
}

Health Check

GET /health

Response:
{
  "status": "healthy",
  "version": "1.0.0",
  "llm_provider": "anthropic"
}

---

🧠 Configuration

LLM Providers

Anthropic (Default)

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
MODEL_NAME=claude-3-5-sonnet-20241022

OpenAI

LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...
MODEL_NAME=gpt-4-turbo

Local LLM (LM Studio/Ollama)

LLM_PROVIDER=local
MODEL_NAME=local-model
BASE_URL=http://localhost:1234/v1

Policy Engine

Configure safety guardrails:

POLICY_MAX_TOOL_CALLS_PER_RUN=50
POLICY_RATE_LIMIT_WINDOW=60
POLICY_MAX_REQUESTS_PER_WINDOW=100
POLICY_ALLOWED_TOOLS=web_search,http_request,database_query,database_write

Redis Queue

REDIS_HOST=localhost
REDIS_PORT=6379
WORKER_CONCURRENCY=10
WORKER_MAX_RETRIES=3

---

🧪 Running Tests

# Unit tests
pytest tests/test_core_utils.py -v
pytest tests/test_policy_engine.py -v

# Integration tests (requires API running)
pytest tests/test_integration.py -v

# All tests
pytest tests/ -v

---

🏗️ Architecture Deep Dive

1. Agent Orchestration (LangGraph)

The agent uses a state graph with deterministic transitions:

planner → tool_selector → executor → evaluator → improver → ...
                                    ↓
                                   END

Key Nodes:

• Planner: Creates step-by-step execution plan from user input
• Tool Selector: Picks next tool and parameters from plan
• Executor: Runs tool with policy enforcement
• Evaluator: Scores execution quality (0.0-1.0)
• Improver: Optimizes plan if score < 0.7 threshold

2. Self-Improving Loop

The system learns and improves automatically:

Plan → Act → Observe → Evaluate → Improve → Repeat

• Evaluation: LLM scores execution quality
• Improvement: If score < 0.7, regenerate better plan
• Termination: Stops when score >= 0.7 or max steps reached

3. MCP Tool Servers

Each tool runs as an independent service:

Service	Port	Tools
Web Search	8001	web_search
HTTP Request	8002	http_request
Database	8003	database_query, database_write

Adding new tools:

1. Create new MCP server in packages/mcp/
2. Register tool with register_tool()
3. Add to docker-compose.yml
4. Update POLICY_ALLOWED_TOOLS

4. Policy Engine

Safety layers:

• Tool Whitelist: Only allowed tools can execute
• Rate Limiting: Prevents API abuse
• Quota Management: Limits tool calls per run
• Pattern Detection: Blocks SQL injection, SSRF, etc.
• Cost Tracking: Estimates resource usage

5. Observability

Tracked metrics:

• Agent execution times
• Tool call durations
• Success/failure rates
• Evaluation scores
• Error traces

OpenTelemetry integration:

with tracer.start_span("executor") as span:
    result = execute_tool()
    span.set_attribute("success", result.success)

---

🔐 Security

• Input Sanitization: All user inputs validated
• SQL Injection Prevention: Query pattern detection
• SSRF Protection: Blocked dangerous host access
• Rate Limiting: Per-client request throttling
• Audit Logging: Every action tracked and logged

---

📊 Monitoring

Dashboard Features

• Real-time job status updates
• Execution logs with filtering
• Performance metrics and charts
• Tool execution breakdown
• Error tracking and debugging

Access Points

• Dashboard UI: http://localhost:3001
• API Docs: http://localhost:8000/docs
• Health Check: http://localhost:8000/health
• Metrics: http://localhost:8000/metrics

---

🚀 Scaling

Horizontal Scaling

Multiple Workers:

docker-compose up --scale worker=5

Load Balancer:

docker-compose up --scale api=3

Production Deployment

For production, consider:

• PostgreSQL instead of SQLite
• Redis Cluster for high availability
• Kubernetes for orchestration
• Langfuse for agent observability
• Prometheus + Grafana for metrics

---

🛠️ Extending the System

Adding New Tools

1. Create MCP server in packages/mcp/new_tool.py:

from packages.mcp.base import create_mcp_server, register_tool

app = create_mcp_server("New Tool")

async def my_handler(params):
    return {"success": True, "result": "..."}

register_tool(app, "my_tool", "Description", {...}, my_handler)

2. Register in orchestrator (apps/agent/workflow.py):

self.tool_handlers["my_tool"] = (my_handler, MCPToolType.CUSTOM)

3. Update policy in .env:

POLICY_ALLOWED_TOOLS=...,my_tool

Custom Agent Workflows

Modify apps/agent/workflow.py to:

• Add new nodes (researcher, writer, etc.)
• Change graph topology
• Implement custom evaluation logic
• Add multi-agent coordination

---

📝 Development Workflow

# 1. Make changes to code
# 2. Run tests
pytest tests/ -v

# 3. Start services
docker-compose up

# 4. Test via API or dashboard
curl -X POST http://localhost:8000/run-agent \
  -H "Content-Type: application/json" \
  -d '{"user_input": "Test task"}'

# 5. Monitor at http://localhost:3001

---

🐛 Troubleshooting

API won't start:

# Check LLM API key
echo $ANTHROPIC_API_KEY

# Test LLM connection
python -c "from langchain_anthropic import ChatAnthropic; llm = ChatAnthropic(); print(llm.invoke('test'))"

Worker not processing jobs:

# Check Redis connection
redis-cli ping

# View worker logs
docker-compose logs worker

Dashboard not loading:

# Check API is running
curl http://localhost:8000/health

# Verify NEXT_PUBLIC_API_URL
cat apps/dashboard/.env.local

---

📄 License

MIT License - see LICENSE file for details.

---

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Write tests for new functionality
4. Submit a PR

---

🎯 Roadmap

• PostgreSQL persistent memory
• Multi-agent coordination
• Langfuse integration
• Kubernetes manifests
• Stripe integration for SaaS
• Multi-tenant support
• Authentication & authorization
• Custom tool marketplace

---

Built with ❤️ for autonomous AI systems