AgentRelay

• 

  Architecture Diagram

• 

  Main UI

• 

  Approval Flow

• 

  Agent Flow

• 

  Idempotency Implementation

🚀 Inspiration

AI agents can research, analyse data, and generate recommendations. But when several agents work together, important questions appear:

• Which agent can access sensitive information?
• Which actions can run automatically?
• When should a human approve an action?
• What happens if the same action is requested multiple times?

We built AgentRelay to explore how lightweight middleware can make multi-agent workflows safer without replacing the Agent Launchpad runtime.

Our goal was simple:

Let agents collaborate freely, while keeping data access and consequential actions under control.

💡 What it does

AgentRelay coordinates four specialised agents in a sales-recovery workflow:

• Research Agent investigates market conditions.
• Finance Agent analyses financial information.
• Strategy Agent combines accepted evidence into a recommendation.
• Outreach Agent prepares a customer email.

Research and Finance run in parallel. Their evidence is validated before it reaches Strategy. Outreach can propose an email, but it cannot send it directly.

The backend evaluates the proposed action, requests human approval, and sends it through a trusted executor only after the exact payload has been approved.

🤖 The agent workflow

AgentRelay is coordinated by a backend workflow service rather than allowing the frontend to call agents directly.

The workflow is:

Research + Finance → Evidence validation → Strategy → Outreach
                                                    ↓
                                     Policy → Approval → Execution

Each agent has defined capabilities, tools, and resource scopes. Agents receive only the context and protected resources required for their tasks.

The dashboard shows:

• Agent and task status
• Accepted and rejected evidence
• Protected-resource access decisions
• Policy decisions
• Human approval requests
• Execution receipts
• Audit trace events

🛡️ Governed autonomy

One principle guided the project:

Autonomous should not mean uncontrolled.

AgentRelay separates recommendations from actions that affect external systems.

For example:

• Drafting an email is generation.
• Sending an email is a protected action.
• Recommending a pricing change is analysis.
• Updating an external price is a higher-risk action.

Permissions and risks are defined by the backend, not by the agents. Unknown, prohibited, or under-permitted actions are denied.

Approvals are also bound to a hash of the exact action payload. If an action changes after approval is requested, the approval is invalidated.

📐 System architecture

The React dashboard communicates with a Fastify control plane. The backend coordinates agents, validates evidence, manages protected-resource grants, applies policies, and records workflow state.

At a high level, AgentRelay includes:

• React and TypeScript dashboard
• Fastify backend
• Codex CLI Agent runtime
• Volcengine Ark or Gemini model provider
• Workflow coordinator
• Capability router
• Resource Gateway
• Evidence validator
• Server-owned policy registry
• Human approval service
• Protected email executor
• Atomic idempotency ledger
• Persistent JSON stores
• Audit tracing

The frontend submits user goals and approval decisions, but orchestration, permissions, credentials, and execution remain behind the backend boundary.

🛠️ How we built it

We used React, TypeScript, and Vite for the dashboard, with Fastify and TypeScript for the backend.

Codex CLI runs the agents using Volcengine Ark or Gemini. Workflow sessions, tasks, evidence, approvals, traces, and receipts are stored in atomic JSON files.

We also created controlled demo scenarios for policy denial, timeouts, resource-scope breaches, approval bypass attempts, and duplicate execution.

⚡ Challenges we faced

The main challenge was keeping permissions outside the model. We solved this by storing capabilities, resource scopes, and action policies on the server.

We also needed to prevent changed or repeated actions from executing. We bound approvals to the action payload and added an atomic idempotency ledger.

Model output was sometimes unpredictable, so we added structured validation and denied unknown or prohibited actions.

🧪 Safety scenarios

AgentRelay includes several scenarios that demonstrate its middleware controls:

• Policy denial: A prohibited action is rejected.
• Timeout and retry: Failed work is retried while dependent tasks remain blocked.
• Resource-scope breach: An agent is denied access to data outside its grant.
• Approval bypass: A protected action cannot execute without approval.
• Duplicate execution: Five concurrent attempts produce exactly one email.

These scenarios show both successful execution and how the system fails safely.

📚 What we learned

Our biggest lesson was that building a multi-agent system is not only about prompting.

The difficult questions became:

• Who is allowed to do what?
• Which evidence can be trusted?
• What information should move between agents?
• When should a human approve an action?
• How should failures and retries affect dependent work?
• How do we prevent duplicate side effects?

We learned that useful agent autonomy requires orchestration, validation, permissions, observability, failure recovery, and human control.

🏆 What we’re proud of

We built more than a set of agents producing independent responses.

AgentRelay provides a complete governed workflow in which:

• Agents have clear responsibilities.
• Tasks follow explicit dependencies.
• Evidence is validated before being shared.
• Protected data access is scoped and recorded.
• External actions require policy checks and approval.
• Duplicate requests execute only once.
• Every important decision appears in an audit trace.

The result is a lightweight middleware layer that turns Agent Launchpad into a safer, observable, multi-agent workflow platform.

Built With

• codex
• docker
• fastify
• gemini
• node.js
• react
• rest-api
• terraform
• typescript
• vite
• vitest
• volcengine
• zod