Agent to Agent to Human - Shared State Files as Communication
Agent to Agent to Human - Shared State Files as Communication
The fanciest multi-agent communication system I have seen was a distributed message queue with pub/sub, dead letter queues, and exactly-once delivery guarantees. It took two weeks to build and broke constantly.
The simplest one that actually works? A shared state file.
Why Files Beat Message Queues
A text file that agents append to is debuggable by a human with a text editor. A message queue requires specialized tooling, monitoring dashboards, and knowledge of the queue's semantics to understand what happened.
When something goes wrong - and it will - you want to open a file and read it chronologically. Not query a message broker, filter by topic, and reconstruct event ordering from timestamps.
The Shared State Pattern
Each agent writes structured entries to a shared file. Entries include: timestamp, agent ID, action taken, result, and any state changes. The file is append-only - agents never modify previous entries. This gives you an immutable log of everything that happened.
A human can read this file at any time to understand the current state. They can add their own entries - corrections, overrides, new instructions. The agents pick up human entries on their next read cycle.
Making It Work
The practical requirements are minimal. Use file locking to prevent concurrent write corruption. Keep entries structured (JSON lines or structured markdown). Set a maximum file size and rotate when it gets too large.
The key insight is that the communication channel should be the simplest thing that works. Agents do not need real-time messaging. They need a shared understanding of state. A file provides that with zero infrastructure overhead.
When to Graduate
You outgrow shared files when you have more than five agents, when you need sub-second coordination, or when agents run on different machines. Until then, the file is simpler, faster to debug, and more reliable than any alternative.
Fazm is an open source macOS AI agent. Open source on GitHub.