RelayOS — Multi-Agent AI Orchestration & Production Delivery Platform
RelayOS is an AI workforce platform designed to coordinate work across specialized AI agents and people. A central Relay Manager decides what should happen next, delegates to the right agent or human, manages handoffs and approvals, and keeps work moving through verification to completion.
The hard part is not adding more agents. It is coordinating consequences.
From isolated agents to an operating system
Once several agents touch the same objective, the problem changes. The system needs ownership, priority, handoffs, shared state, human judgment, recovery behavior, and a definition of “done” that does not depend on one model response.
The product thesis
I treated RelayOS as an operating layer above individual agent capabilities. Relay Manager owns orchestration while specialist agents execute bounded work. Humans enter at explicit decision points rather than being an afterthought or an emergency fallback.
Relay Manager turns agent activity into a managed work lifecycle.
Explicit lifecycle
Work moves through CREATED, READY, IN_PROGRESS, WAITING_FOR_AGENT, WAITING_FOR_HUMAN, BLOCKED, VERIFYING, COMPLETED, or FAILED. The orchestration layer—not an unconstrained LLM—controls transitions.
Manager + specialists
Relay Manager coordinates Lead, Social, and Design agents, evaluates their structured outputs, resolves the next owner, persists handoffs, applies deterministic priority, and decides whether work can proceed, pause, resume, or complete.
LangGraph orchestrates the flow; PostgreSQL remains the durable source of truth.
AI → AI
A Social Agent can diagnose campaign performance and create a persisted Social → Design handoff. Relay Manager reconstructs the next assignment from stored business state rather than passing an opaque conversation forward.
AI → Human → AI
Consequential work creates a reviewer-bound approval and pauses in WAITING_FOR_HUMAN. A valid human decision is persisted, duplicate approval is rejected idempotently, and the graph resumes from durable IDs rather than relying on in-memory context.
Deterministic priority
The LLM supplies bounded business inputs; final P0–P3 priority is calculated by policy. That keeps urgency reproducible, inspectable, and independent of model wording.
Verification before completion
A work item reaches COMPLETED only after structured output, required artifacts, validation signals, and blocker checks pass. Verification is persisted so completion history remains inspectable.
Tools, model outputs, and human decisions all cross explicit boundaries.
RelayOS combines structured OpenAI outputs, governed MCP access, deterministic policies, and append-style audit traces. The goal is not merely to make agents capable; it is to make their actions bounded and reviewable.
Governed MCP
- Official FastMCP stdio server
- Allowlisted tool registry
- Pydantic argument validation
- Sanitized invocation events tied to workflow state
- No shell, filesystem, direct SQL, credentials, or unrestricted network access
Structured consequences
- Pydantic WorkReport structured outputs
- Reviewer-bound approvals
- Deterministic priority and transition policy
- Persistent assignments, handoffs, verification, and audit history
- Human judgment remains explicit where external consequences matter
RelayOS brings orchestration, durable state, and product experience into one full-stack system.
Application + data layer
FastAPI exposes the backend workflow API; Next.js / React / TypeScript provides the product UI. SQLAlchemy 2.x models persist work items, reports, assignments, handoffs, approvals, priorities, verification, and activity. Alembic owns schema evolution against PostgreSQL 16.
Containerized runtime
Frontend, backend, and PostgreSQL run as isolated Docker services with health-aware startup, migrations, persistent storage, and environment-specific configuration. Local regression validates the same core behavior before cloud release.
Operational boundaries
Liveness and readiness are separated, database pooling is bounded, OpenAI calls use explicit timeout/retry policy, request IDs support correlation, and production startup is separated from migration and seed behavior.
Engineering quality
The system is covered by backend regression tests, frontend type/build checks, PostgreSQL/Alembic validation, Docker builds, Compose runtime checks, security scans, and representative workflow smoke tests.
From local system to a least-privilege AWS release path.
Terraform-managed AWS stack
I provisioned VPC networking, ALB, ECS/Fargate services, ECR repositories, private TLS-enforced RDS PostgreSQL, Secrets Manager containers, CloudWatch, IAM roles, GitHub OIDC, and cost guardrails as infrastructure as code.
Manually gated CI/CD
CI validates backend/PostgreSQL, frontend, Docker, and infrastructure on code changes. Production deployment is separately initiated through GitHub Actions, assumes a least-privilege AWS role through OIDC, pushes immutable SHA-tagged images, runs migration, deploys backend/frontend, and waits for health before the release is accepted.
Real deployment failures shaped a more resilient system.
Real deployment failures
- The original RDS backup configuration was incompatible with the active AWS account constraints
- OIDC subject / JWT claim handling required correction
- Percent-encoded RDS credentials exposed an Alembic interpolation bug
- Frontend ECS liveness behavior required a runtime fix
- Cloud deployment health and agent mode required final hardening
Controlled recovery
Rather than weakening security controls, I stopped the deployment, removed the partial stack, applied the smallest compatible RDS configuration change, re-planned the infrastructure, and successfully re-ran the release.
Release outcome
Deployment run #9 passed end to end, and run #10 passed again after task replacement. The cloud smoke test exercised frontend, backend, RDS-backed persistence, AI→AI workflow, AI→Human→AI approval/resume, verification, and audit behavior.
Lifecycle management
RelayOS remains under active development, with additional product and agent capabilities planned. After validating the AWS deployment, workflow execution, persistence across redeployment, and release repeatability, I decommissioned the temporary cloud environment to avoid unnecessary infrastructure costs during the next development phase. Terraform-managed resources were cleanly removed, while deployment configuration, operational logs, and validation records were preserved for future releases.