# Show HN: AgentNexus – coordinate LLM agents by service boundary, not role > Source: > Published: 2026-06-13 12:25:15+00:00 **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 call**Lifecycle stage tracking**— explicit`design → development → testing → deployment → upgrade` per service, with milestone snapshots on transitions**Service-Driven Agent Onboarding (SDAOP)**—`generate_instruction_file` auto-generates IDE steering files (AGENTS.md, CLAUDE.md, Kiro steering, Cursor rules) for any connecting agent**MCP 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 support**Planner AI layer**—`planner_chat` ,`planner_plan` ,`planner_overview` MCP tools + configurable LLM backend**Web 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..." } # Install pip install -e ".[dev]" # Initialize database python -m alembic upgrade head # Start server (default: http://0.0.0.0:10086/mcp) python src/main.py { "mcpServers": { "doc-exchange": { "url": "http://localhost:10086/mcp" } } } # Create a project space create_space(name="my-project") # Register a service register_project(name="backend-api", type="development", project_space_id="") # Push a document push_document(project_id="", doc_id="/api", content="# API Spec...") # Subscribe frontend to backend's API docs add_subscription(subscriber_project_id="", project_space_id="", target_doc_id="/api") # Check updates (returns diff + full content) get_my_updates_with_context(project_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 requires`PLANNER_LLM_API_KEY` to be set. Set`PLANNER_LLM_PROVIDER` (`openai` or`anthropic` ) and`PLANNER_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": "", "doc_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="", 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](/dugubuyan/agent-nexus/blob/main/paper/agentnexus-v3.md) for the formal protocol definition. ``` python -m pytest tests/ -q ``` The accompanying research papers are available in the [ paper/](/dugubuyan/agent-nexus/blob/main/paper) directory: — v3 (current): adds SDAOP`paper/agentnexus-v3.md` — v2`paper/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