RelayOS — Multi-Agent AI Workforce Orchestration Platform
I designed and built a multi-agent operations platform where a Relay Manager coordinates specialist agents, manages AI-to-AI and human-in-the-loop handoffs, persists workflow state, governs tool access, and verifies work before completion.
Coordinating work across agents and humans.
The coordination problem
As multiple AI agents take on connected work, the system needs clear ownership, priorities, handoffs, human approval, shared workflow state, and verification before work is considered complete.
The orchestration model
I designed Relay Manager as the orchestration layer above the specialist agents. It assigns work, evaluates structured reports, resolves the next owner, calculates priority, creates handoffs, resumes approved work, and runs completion verification.
A full-stack orchestration layer for specialist agents.
A manager agent coordinates specialist agents and human decisions.
Agent → Agent
The Social Agent diagnoses campaign performance and can recommend Design work. Relay Manager resolves the next assignment, persists the Social → Design handoff context, dispatches Design, and verifies the resulting brief.
Agent → Human → Agent
External-facing work creates a reviewer-bound approval. The workflow pauses in WAITING_FOR_HUMAN, records the decision and reviewer identity, then resumes exactly once and returns the approved context to the agent.
Manager-controlled priority
The LLM cannot set final priority. Relay Manager persists bounded business inputs and calculates P0–P3 through a deterministic formula so urgency is inspectable and reproducible.
Completion verification
Completion requires a valid structured report, artifacts, evidence, and no unresolved blockers. Verification results are persisted; only PASS can transition work to COMPLETED.
Governed MCP tool access with auditable execution.
RelayOS implements an official FastMCP stdio server plus a transaction-aware governed registry. The V1 tool is deliberately read-only and allowlisted: get_campaign_performance accepts a constrained campaign ID, returns fictional local metrics, and logs sanitized success/failure events.
What MCP enables
- Standardized tool contract for agent access
- Explicit allowlist rather than arbitrary execution
- Pydantic argument validation
- Auditable invocation events tied to workflow state
Governance
Tool access is constrained to the registered capability. The agent does not receive filesystem, shell, direct SQL, credential, or unrestricted network access, and invocation results are recorded as sanitized audit events.
Persistent data and a containerized full-stack runtime.
PostgreSQL + SQLAlchemy + Alembic
SQLAlchemy 2.x models persist WorkItems, agent runs, reports, assignments, handoffs, approvals, verification results, priorities, and append-style activity events. Alembic owns schema evolution; PostgreSQL 16 runs as the production-like relational store.
Docker + Docker Compose
The Next.js frontend, FastAPI backend, and PostgreSQL database run as isolated Docker Compose services with health-dependent startup, migrations, explicit service configuration, and persistent database storage.
Built across AI orchestration, backend, frontend, and infrastructure.
Agent systems
- Multi-agent orchestration
- MCP implementation
- Human-in-the-loop approval/resume
- OpenAI structured runtime
- State machine + deterministic routing
- Persistent audit traces
Full-stack engineering
- FastAPI backend
- Next.js / React / TypeScript frontend
- PostgreSQL + SQLAlchemy
- Alembic migrations
- Docker + Docker Compose
- Cross-service runtime debugging
Mapped the containerized stack to an AWS deployment architecture.
I designed an AWS deployment plan that maps container images to ECR, the FastAPI service to ECS Fargate behind ALB, PostgreSQL to RDS, application secrets to Secrets Manager, observability to CloudWatch, and DNS/TLS to Route 53 and ACM.