The Engineer Agent

Employee #1 of APEX OS

Purpose

The Engineer is the first autonomous AI employee. It builds software, manages infrastructure, and creates future AI employees.

Architecture

Brain: Letta agent (agent-4e3c3862-d0ba-47c6-8f2e-74249e1cfe4a) with GPT-4o via LiteLLM
Execution: n8n workflows (Engineer-Core: hGB9I4OKXyUOrBdX)
Knowledge: mem0 (pgvector) + Letta archival memory
Code: Gitea repositories (engineer user)
Deployment: Docker via Socket Proxy (write-enabled)
Tracking: PostgreSQL apex DB (projects, tasks, deployments, engineer_decisions)

Capabilities

✅ Software planning and task decomposition
✅ Code generation (GPT-4o, Claude 3.5 Sonnet via LiteLLM)
✅ Git operations (Gitea API — create repos, commit files, manage issues)
✅ Docker container deployment (via socket proxy with POST/EXEC/START/STOP)
✅ REST API creation and management
✅ n8n workflow creation and management (via API key)
✅ Node.js test execution (via n8n Execute Command)
✅ Log analysis and monitoring (Loki, Grafana, Prometheus)
✅ Documentation generation
✅ Creating other AI employees (via Letta multi-agent API)
✅ Shared knowledge queries (mem0 pgvector semantic search)
✅ Long-term memory (Letta archival memory)

Access Points

Service	Endpoint	Auth
Letta Agent API	`http://letta:8283/v1/agents/agent-4e3c3862-d0ba-47c6-8f2e-74249e1cfe4a/messages`	None (internal)
n8n Webhook	`https://n8n.apex.unstuck-path.com/webhook/engineer/task`	None (POST)
Gitea API	`http://gitea:3000/api/v1/`	Bearer token
LiteLLM	`http://litellm:4000/v1/`	Bearer token
Docker Proxy	`http://docker-socket-proxy:2375/`	None (internal)
PostgreSQL	`postgres:5432` (apex DB)	apex user

Usage

Via n8n Webhook

curl -X POST https://n8n.apex.unstuck-path.com/webhook/engineer/task \
  -H "Content-Type: application/json" \
  -d '{"task": "description of what to build", "context": "additional context"}'

Via Letta API (Direct)

curl -X POST http://letta:8283/v1/agents/agent-4e3c3862-d0ba-47c6-8f2e-74249e1cfe4a/messages \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Your task here"}]}'

Decision-Making Process

Receive task via webhook or direct API call
Letta agent (GPT-4o) analyzes and plans
Breaks into subtasks stored in tasks table
Executes each subtask via appropriate API
Logs decisions in engineer_decisions table
Updates project status in projects table
Stores lessons learned in archival memory

Project Tracking

All projects are tracked in the apex database:

projects — Project metadata and status
tasks — Individual task breakdown
deployments — Container deployment history
engineer_decisions — Decision rationale log

Created

Date: 2026-07-02
Phase: 5 (Engineer Agent Creation)
Status: Operational ✅

Phase 5.5: Management Layer (VP3 and VP4) - Complete

VP3: Company Dashboard

The APEX OS platform now has a real-time executive dashboard in Grafana showing:

System health and critical service status
Active projects and deployment pipeline
Engineering brain activity (reflections and decisions)
Auto-recovery system events
Constitution violation tracking

Access: http://grafana.apex.unstuck-path.com (admin credentials in phase1_credentials.md) Dashboard UID: a5jdct

VP4: Employee Factory

A standardized system for creating new AI employees:

Master Template: /opt/apex/templates/employee-template.json (APEX Constitution auto-injected)
Spawn Script: /opt/apex/tools/spawn_employee.sh
Usage: spawn_employee.sh "Role Name" "Specialized Task"

Test Employee Created:

Employee 3: Documentation Agent
Agent ID: agent-f8706c2d-51b5-4678-abc7-2864d9845e6a
Repository: engineer/documentation-agent-workspace
Status: Operational

See EMPLOYEE_FACTORY.md for complete documentation.

4.0 KiB Raw Blame History