A service-boundary-aware coordination architecture for heterogeneous LLM code agents.
"Service boundaries, not agent roles, are the appropriate primitive for coordinating LLM agents in real software development."
Existing multi-agent frameworks (ChatDev, MetaGPT) organize agents around roles within a single simulated organization. AgentNexus takes a different approach: it coordinates agents at the service granularity, matching how real software systems are actually structured.
Each service registers as a sub-project, publishes versioned Markdown documents (requirements, design, API specs, config), and subscribes to documents from services it depends on. When a document changes, subscribers receive a diff-aware notification containing both the structured diff and the full latest content — enabling targeted, context-aware code modifications.
Versioned document store— SHA-256 dedup, full version history, per-service namespacing** Publish-subscribe notifications**— subscribe by exact doc ID or doc type** Diff-aware updates**—get_my_updates_with_context
returns unified diff + full content in one callLifecycle stage tracking— explicitdesign → development → testing → deployment → upgrade
per service, with milestone snapshots on transitionsService-Driven Agent Onboarding (SDAOP)—generate_instruction_file
auto-generates IDE steering files (AGENTS.md, CLAUDE.md, Kiro steering, Cursor rules) for any connecting agentMCP HTTP server— streamable-HTTP transport, multiple agents connect simultaneously** Out-of-band write endpoint**—POST /api/documents
accepts full content via HTTP body (zero LLM token cost)FTS5 full-text search—search_documents
with BM25 ranking, phrase/prefix/boolean query supportPlanner AI layer—planner_chat
,planner_plan
,planner_overview
MCP tools + configurable LLM backendWeb Dashboard— browser-based UI to explore spaces, projects, and documents with full-text search** AI Chat**— built-in chat panel powered by Planner LLM for conversational document Q&A and service planning** 281 tests**— unit + property-based (Hypothesis)
┌─────────────────────────────────────────────────────┐
│ Project Space │
│ │
│ ┌──────────────┐ subscribe ┌───────────────┐ │
│ │ search- │ ──────────────► │ search-admin- │ │
│ │ service │ │ frontend │ │
│ │ │ notification │ │ │
│ │ api/v5 ──────┼────────────────►│ │ │
│ └──────────────┘ └───────────────┘ │
│ │
│ AgentNexus MCP Server │
│ http://0.0.0.0:10086/mcp │
└─────────────────────────────────────────────────────┘
When a backend service updates its API document, the frontend agent is automatically notified with a structured diff — no human coordination needed:
Backend Agent AgentNexus Frontend Agent
│ │ │
│── push_document ──────▶│ │
│ (api, new version) │── notification ─────────▶│
│ │ │── get_my_updates_with_context()
│ │◀─────────────────────────│
│ │── diff + full content ──▶│
│ │ │── apply targeted code changes
│ │ │── ack_update() ────────────▶│
│ │ │
The diff payload looks like:
{
"doc_id": "backend-service/api",
"new_version": 5,
"diff": "@@ -42,6 +42,12 @@\n+## PUT /admin/docs/{doc_id}\n+Update a document in-place...",
"latest_content": "# API Spec\n\n..."
}
pip install -e ".[dev]"
python -m alembic upgrade head
python src/main.py
{
"mcpServers": {
"doc-exchange": {
"url": "http://localhost:10086/mcp"
}
}
}
create_space(name="my-project")
register_project(name="backend-api", type="development", project_space_id="<space_id>")
push_document(project_id="<project_id>", doc_id="<project_id>/api", content="# API Spec...")
add_subscription(subscriber_project_id="<frontend_id>", project_space_id="<space_id>", target_doc_id="<backend_id>/api")
get_my_updates_with_context(project_id="<frontend_id>")
Once the server is running, open ** http://localhost:10086/** in your browser.
Features:
Browse— navigate spaces, sub-projects, and documents in a tree view** Search**— full-text search across all documents in a space** AI Chat**— ask questions about your project documents using natural language
LLM configuration:AI Chat requiresPLANNER_LLM_API_KEY
to be set. SetPLANNER_LLM_PROVIDER
(openai
oranthropic
) andPLANNER_LLM_MODEL
as needed. Leave the key unset to disable AI features while keeping all browse/search functionality.
For zero-token document ingestion (bypasses MCP tool-call LLM context), use the HTTP endpoint directly:
curl -X POST http://localhost:10086/api/documents \
-H "Content-Type: application/json" \
-d '{
"project_id": "<project_id>",
"doc_id": "<project_id>/requirement",
"content": "# Requirements\n\nContent here..."
}'
This uses the same DocumentService.push
pipeline as push_document
(same validation, FTS index update, notifications) but the document content never enters LLM context — making it practical for large documents.
| Tool | Description |
|---|---|
create_space |
|
| Create a Project Space | |
register_project |
|
| Register a sub-project (service) | |
list_projects |
|
| List all sub-projects in a space | |
list_documents |
|
| List all documents in a sub-project | |
push_document |
|
| Push a new document version (full content) | |
get_document |
|
| Retrieve a document (latest or specific version) | |
get_my_updates_with_context |
|
| Get unread notifications with diff + full content | |
ack_update |
|
| Mark a notification as read | |
get_my_tasks |
|
| Get pending tasks for a project | |
get_config |
|
| Get config document for a stage | |
add_subscription |
|
| Add a subscription rule | |
publish_draft |
|
| Confirm a draft document | |
generate_instruction_file |
|
| Generate IDE onboarding file (SDAOP) | |
get_project_id_by_name |
|
| Look up project_id by name | |
search_documents |
|
| Full-text search across documents in a space | |
planner_chat |
|
| Conversational Q&A with LLM over project documents (streaming) | |
planner_plan |
|
| Generate service-split proposal from a description | |
planner_overview |
|
| Get a high-level overview of a project space |
| Environment Variable | Default | Description |
|---|---|---|
DOC_EXCHANGE_DB_URL |
||
sqlite:///doc_exchange.db |
||
| Database URL | ||
DOC_EXCHANGE_DOCS_ROOT |
||
./workspace |
||
Workspace root (docs live under {root}/{space_id}/docs/ ) |
||
DOC_EXCHANGE_HOST |
||
0.0.0.0 |
||
| Server bind host | ||
DOC_EXCHANGE_PORT |
||
10086 |
||
| Server port | ||
DOC_EXCHANGE_DEFAULT_SPACE_ID |
||
default |
||
| Default space ID for bootstrap imports | ||
PLANNER_LLM_PROVIDER |
||
openai |
||
LLM provider for Planner AI (openai |
anthropic ) |
|
PLANNER_LLM_MODEL |
||
| (provider default) | LLM model name | |
PLANNER_LLM_API_KEY |
||
| (none) | API key; leave empty to disable AI features |
Each sub-project's IDE agent uses an onboarding file (steering file, CLAUDE.md, AGENTS.md, etc.) to auto-check for updates at session start. Generate one with:
generate_instruction_file(project_name="my-service", project_space_id="<space_id>", client_type="kiro")
Supported client_type
values: kiro
, claude
, codex
, cursor
.
This is the Service-Driven Agent Onboarding Protocol (SDAOP) — the MCP service generates the onboarding document itself, so agents require zero manual configuration. See the v3 paper for the formal protocol definition.
python -m pytest tests/ -q
The accompanying research papers are available in the paper/ directory:
— v3 (current): adds SDAOPpaper/agentnexus-v3.md
— v2paper/agentnexus.md
dugubuyan.
AgentNexus: A Service-Boundary-Aware Coordination Architecture for Heterogeneous LLM Code Agents (v3).Zenodo, 2026.[https://doi.org/10.5281/zenodo.20603176]
MIT