Why I Stopped Organizing AI Agents by Role (and Built a Document Exchange Center Instead)

Alex — Mon, 01 Jun 2026 09:46:12 +0000

Most multi-agent frameworks for software development organize agents around roles: a product manager agent, a developer agent, a tester agent. ChatDev and MetaGPT pioneered this approach, and it works well for monolithic tasks.

But I ran into a wall when I tried to apply it to a real system with multiple independently-deployed services.

The Problem with Role-Based Coordination

Imagine you have a backend search service and a frontend management console. The backend team implements a new API endpoint. The frontend needs to adapt.

In a role-based framework, there's no natural mechanism for this. Both agents are "developers" in the same simulated organization. There's no concept of service boundaries, no versioned contracts, no way to say "the backend changed, and the frontend needs to know exactly what changed."

The coordination problem in multi-service development isn't "which role should handle this task" — it's "which service needs to know about this change, and what exactly changed."

That reframing led me to build something different.

AgentNexus: Coordinating Agents at the Service Granularity

AgentNexus is a document exchange center that treats each service as a first-class citizen. Instead of roles, it uses service boundaries as the coordination primitive.

Here's how it works:

Each service registers as a sub-project with its own document namespace
Services publish versioned Markdown documents: requirements, design specs, API docs, config
Services subscribe to documents from other services they depend on
When a subscribed document changes, the subscriber receives a diff-aware notification containing both the structured diff and the full latest content

The whole thing is exposed as an MCP (Model Context Protocol) server running in streamable-HTTP mode, so multiple agents can connect simultaneously from different machines.

The Diff-Aware Update Protocol

This is the part I'm most proud of. When an agent calls get_my_updates_with_context, it gets back:

{
  "update_id": "...",
  "doc_id": "backend-service/api",
  "doc_type": "api",
  "new_version": 5,
  "diff": "@@ -42,6 +42,12 @@\n+## PUT /admin/docs/{doc_id}\n+\n+Update a document in-place...",
  "latest_content": "# API Spec\n\n..."
}

The agent gets both what changed (to perform targeted modifications) and the full current state (to maintain correct context). Providing only the diff risks missing context; providing only the full document makes it hard to identify what needs to change in the code.

A Concrete Example

Here's the end-to-end flow when the backend implements a new endpoint:

Backend agent updates search-service/api via push_document
AgentNexus computes the diff and generates a notification for search-admin-frontend
Frontend agent calls get_my_updates_with_context, receives the diff showing the new endpoint
Frontend agent removes the mock implementation and integrates the real endpoint
Frontend agent updates its own requirement document to remove the "backend not yet implemented" annotation
Frontend agent calls ack_update to mark the notification as read

No human coordination required beyond the initial subscription configuration.

Lifecycle Stage as a First-Class Entity

One more thing that bothered me about role-playing frameworks: they have no concept of where a service is in its development lifecycle.

AgentNexus tracks each service's stage explicitly: design → development → testing → deployment → upgrade. Stage transitions are real operations that:

Create immutable milestone snapshots of all published documents
Generate cross-service notifications
Produce stage-switch tasks for affected services

When a service transitions from development to testing, that's a meaningful event — not just a prompt instruction to an agent playing the role of "scrum master."

What I Built

The implementation is in Python using FastMCP, SQLAlchemy/SQLite, and watchdog. It runs as a persistent MCP server at http://0.0.0.0:10086/mcp.

Key MCP tools:

push_document / patch_document — publish full or incremental updates
get_my_updates_with_context — one-call update check with diff + full content
add_subscription — subscribe by exact doc ID or doc type
get_my_tasks — retrieve pending tasks generated by document changes
generate_steering_file — generate IDE agent instruction files automatically

The patch_document tool is worth calling out: instead of sending the full document content on every update, agents can send a unified diff patch. This avoids hitting tool-call payload size limits in IDEs like Kiro or Cursor when documents get large.

250 tests (unit + property-based with Hypothesis). The system has been running in production coordinating two services for over a month.

Comparison with Role-Centric Frameworks

Dimension	ChatDev / MetaGPT	AgentNexus
Coordination unit	Agent role	Service (sub-project)
Lifecycle tracking	Implicit in workflow	Explicit stage per service
Change propagation	Shared context	Pub-sub with versioned diff
Service boundaries	Not enforced	First-class namespace
Multi-codebase	Single codebase assumed	Native multi-repo

Try It

git clone https://github.com/dugubuyan/agent-nexus
pip install -e ".[dev]"
python -m alembic upgrade head
python src/main.py
# MCP server running at http://0.0.0.0:10086/mcp

Connect from any MCP client:

{
  "mcpServers": {
    "doc-exchange": {
      "url": "http://localhost:10086/mcp"
    }
  }
}

The accompanying research paper is on Zenodo: doi.org/10.5281/zenodo.19692217

If you're building multi-service systems with LLM agents and running into coordination problems, I'd love to hear what you're working on.

DEV Community: Alex