DEV Community

Patrick
Patrick

Posted on

The Inbox/Outbox Pattern: How AI Agents Coordinate Without Stepping on Each Other

#aiagents #devops #productivity #programming

Most multi-agent systems fail the same way: two agents try to act on the same thing at the same time, and the result is either a conflict or a silent overwrite.

The fix isn't a central orchestrator. It's a simple inbox/outbox pattern.

The Problem: Agents That Shout Into the Void

When agents share state directly — writing to the same files, calling the same APIs, updating the same records — you get race conditions. Agent A reads a value, Agent B updates it, Agent A writes back with stale data. Nobody notices until something breaks.

Most teams respond by adding a central controller to sequence everything. But that creates a single point of failure and a bottleneck.

There's a better way.

The Inbox/Outbox Pattern

Each agent gets two files:

  • inbox.json — incoming tasks and signals from other agents
  • outbox.json — completed work, alerts, and handoffs waiting to be picked up

No agent writes directly to another agent's state. Instead, it drops a message in the target's inbox. No agent reads directly from shared state; it processes its own inbox first, then acts.

// outbox.json — Agent A drops work for Agent B
{
  "to": "agent-b",
  "from": "agent-a",
  "type": "task",
  "payload": {
    "action": "send_newsletter",
    "template": "weekly-digest",
    "segment": "free-tier"
  },
  "timestamp": "2026-03-09T21:00:00Z"
}
Enter fullscreen mode Exit fullscreen mode 
// inbox.json — Agent B picks this up at boot
{
  "pending": [
    {
      "from": "agent-a",
      "type": "task",
      "action": "send_newsletter",
      "received_at": "2026-03-09T21:00:05Z"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

The Boot Sequence Rule

Every agent should start with this:

BOOT SEQUENCE:
1. Read inbox.json — process any pending messages
2. Read current-task.json — resume interrupted work
3. Read context-snapshot.json — load relevant context
4. Begin normal operation
Enter fullscreen mode Exit fullscreen mode

This guarantees that inter-agent signals are never missed, even across restarts.

Why This Works

No conflicts. Agents only write to their own outbox and their own state files. Cross-agent communication is always async and explicit.

Auditable. Every message is logged. You can replay the sequence of events that led to any outcome.

Resilient. If Agent B crashes mid-task, the inbox message is still there. It picks up on restart.

Observable. A full inbox is a signal. If Agent B's inbox has 14 unprocessed messages, something is wrong — and you can see it immediately.

Adding It to Your SOUL.md 

## Coordination Rules
- On boot: read inbox.json before starting any new work
- Never write directly to another agent's state files
- Cross-agent requests go to outbox.json with target, action, and payload
- After completing a task: write result to outbox.json for the requesting agent
- If inbox has more than 5 pending items: escalate to ops channel
Enter fullscreen mode Exit fullscreen mode

The Full Coordination Stack

The inbox/outbox pattern pairs naturally with the other reliability patterns:

  • Ownership zones — each agent owns specific files, no overlap
  • Dead letter queue — failed tasks from outbox go to failed-tasks.json
  • Escalation rule — inbox overflow triggers human review
  • Handoff pattern — outbox message includes full context for the next agent

Together, these four patterns give you a multi-agent system that coordinates reliably without a central controller.

This is one of the core patterns in the Ask Patrick Library — a collection of battle-tested AI agent configurations updated regularly. If you're building multi-agent systems, the coordination configs are in Library #22.

Top comments (0)