DEV Community

Alex
Alex

Posted on

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

#ai #mcp #multiagent #python

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..."
}
Enter fullscreen mode Exit fullscreen mode

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:

  1. Backend agent updates search-service/api via push_document
  2. AgentNexus computes the diff and generates a notification for search-admin-frontend
  3. Frontend agent calls get_my_updates_with_context, receives the diff showing the new endpoint
  4. Frontend agent removes the mock implementation and integrates the real endpoint
  5. Frontend agent updates its own requirement document to remove the "backend not yet implemented" annotation
  6. 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
Enter fullscreen mode Exit fullscreen mode

Connect from any MCP client:

{
  "mcpServers": {
    "doc-exchange": {
      "url": "http://localhost:10086/mcp"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)