{"slug": "show-hn-agentnexus-coordinate-llm-agents-by-service-boundary-not-role", "title": "Show HN: AgentNexus – coordinate LLM agents by service boundary, not role", "summary": "AgentNexus, a new open-source framework, coordinates multiple LLM agents by service boundaries rather than roles, enabling automatic diff-aware notifications when documents change. The system uses a versioned document store with publish-subscribe mechanics, lifecycle stage tracking, and an MCP HTTP server to facilitate real-world software development workflows.", "body_md": "**A service-boundary-aware coordination architecture for heterogeneous LLM code agents.**\n\n\"Service boundaries, not agent roles, are the appropriate primitive for coordinating LLM agents in real software development.\"\n\nExisting 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.\n\nEach 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.\n\n**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`\n\nreturns unified diff + full content in one call**Lifecycle stage tracking**— explicit`design → development → testing → deployment → upgrade`\n\nper service, with milestone snapshots on transitions**Service-Driven Agent Onboarding (SDAOP)**—`generate_instruction_file`\n\nauto-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`\n\naccepts full content via HTTP body (zero LLM token cost)**FTS5 full-text search**—`search_documents`\n\nwith BM25 ranking, phrase/prefix/boolean query support**Planner AI layer**—`planner_chat`\n\n,`planner_plan`\n\n,`planner_overview`\n\nMCP 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)\n\n```\n┌─────────────────────────────────────────────────────┐\n│                  Project Space                       │\n│                                                      │\n│  ┌──────────────┐    subscribe    ┌───────────────┐  │\n│  │ search-      │ ──────────────► │ search-admin- │  │\n│  │ service      │                 │ frontend      │  │\n│  │              │  notification   │               │  │\n│  │ api/v5 ──────┼────────────────►│               │  │\n│  └──────────────┘                 └───────────────┘  │\n│                                                      │\n│              AgentNexus MCP Server                   │\n│              http://0.0.0.0:10086/mcp                │\n└─────────────────────────────────────────────────────┘\n```\n\nWhen a backend service updates its API document, the frontend agent is automatically notified with a structured diff — no human coordination needed:\n\n```\nBackend Agent              AgentNexus               Frontend Agent\n      │                        │                          │\n      │── push_document ──────▶│                          │\n      │   (api, new version)   │── notification ─────────▶│\n      │                        │                          │── get_my_updates_with_context()\n      │                        │◀─────────────────────────│\n      │                        │── diff + full content ──▶│\n      │                        │                          │── apply targeted code changes\n      │                        │                          │── ack_update() ────────────▶│\n      │                        │                          │\n```\n\nThe diff payload looks like:\n\n```\n{\n  \"doc_id\": \"backend-service/api\",\n  \"new_version\": 5,\n  \"diff\": \"@@ -42,6 +42,12 @@\\n+## PUT /admin/docs/{doc_id}\\n+Update a document in-place...\",\n  \"latest_content\": \"# API Spec\\n\\n...\"\n}\n# Install\npip install -e \".[dev]\"\n\n# Initialize database\npython -m alembic upgrade head\n\n# Start server (default: http://0.0.0.0:10086/mcp)\npython src/main.py\n{\n  \"mcpServers\": {\n    \"doc-exchange\": {\n      \"url\": \"http://localhost:10086/mcp\"\n    }\n  }\n}\n# Create a project space\ncreate_space(name=\"my-project\")\n\n# Register a service\nregister_project(name=\"backend-api\", type=\"development\", project_space_id=\"<space_id>\")\n\n# Push a document\npush_document(project_id=\"<project_id>\", doc_id=\"<project_id>/api\", content=\"# API Spec...\")\n\n# Subscribe frontend to backend's API docs\nadd_subscription(subscriber_project_id=\"<frontend_id>\", project_space_id=\"<space_id>\", target_doc_id=\"<backend_id>/api\")\n\n# Check updates (returns diff + full content)\nget_my_updates_with_context(project_id=\"<frontend_id>\")\n```\n\nOnce the server is running, open ** http://localhost:10086/** in your browser.\n\nFeatures:\n\n**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\n\nLLM configuration:AI Chat requires`PLANNER_LLM_API_KEY`\n\nto be set. Set`PLANNER_LLM_PROVIDER`\n\n(`openai`\n\nor`anthropic`\n\n) and`PLANNER_LLM_MODEL`\n\nas needed. Leave the key unset to disable AI features while keeping all browse/search functionality.\n\nFor zero-token document ingestion (bypasses MCP tool-call LLM context), use the HTTP endpoint directly:\n\n```\ncurl -X POST http://localhost:10086/api/documents \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"project_id\": \"<project_id>\",\n    \"doc_id\": \"<project_id>/requirement\",\n    \"content\": \"# Requirements\\n\\nContent here...\"\n  }'\n```\n\nThis uses the same `DocumentService.push`\n\npipeline as `push_document`\n\n(same validation, FTS index update, notifications) but the document content never enters LLM context — making it practical for large documents.\n\n| Tool | Description |\n|---|---|\n`create_space` |\nCreate a Project Space |\n`register_project` |\nRegister a sub-project (service) |\n`list_projects` |\nList all sub-projects in a space |\n`list_documents` |\nList all documents in a sub-project |\n`push_document` |\nPush a new document version (full content) |\n`get_document` |\nRetrieve a document (latest or specific version) |\n`get_my_updates_with_context` |\nGet unread notifications with diff + full content |\n`ack_update` |\nMark a notification as read |\n`get_my_tasks` |\nGet pending tasks for a project |\n`get_config` |\nGet config document for a stage |\n`add_subscription` |\nAdd a subscription rule |\n`publish_draft` |\nConfirm a draft document |\n`generate_instruction_file` |\nGenerate IDE onboarding file (SDAOP) |\n`get_project_id_by_name` |\nLook up project_id by name |\n`search_documents` |\nFull-text search across documents in a space |\n`planner_chat` |\nConversational Q&A with LLM over project documents (streaming) |\n`planner_plan` |\nGenerate service-split proposal from a description |\n`planner_overview` |\nGet a high-level overview of a project space |\n\n| Environment Variable | Default | Description |\n|---|---|---|\n`DOC_EXCHANGE_DB_URL` |\n`sqlite:///doc_exchange.db` |\nDatabase URL |\n`DOC_EXCHANGE_DOCS_ROOT` |\n`./workspace` |\nWorkspace root (docs live under `{root}/{space_id}/docs/` ) |\n`DOC_EXCHANGE_HOST` |\n`0.0.0.0` |\nServer bind host |\n`DOC_EXCHANGE_PORT` |\n`10086` |\nServer port |\n`DOC_EXCHANGE_DEFAULT_SPACE_ID` |\n`default` |\nDefault space ID for bootstrap imports |\n`PLANNER_LLM_PROVIDER` |\n`openai` |\nLLM provider for Planner AI (`openai` | `anthropic` ) |\n`PLANNER_LLM_MODEL` |\n(provider default) | LLM model name |\n`PLANNER_LLM_API_KEY` |\n(none) | API key; leave empty to disable AI features |\n\nEach 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:\n\n```\ngenerate_instruction_file(project_name=\"my-service\", project_space_id=\"<space_id>\", client_type=\"kiro\")\n```\n\nSupported `client_type`\n\nvalues: `kiro`\n\n, `claude`\n\n, `codex`\n\n, `cursor`\n\n.\n\nThis 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.\n\n```\npython -m pytest tests/ -q\n```\n\nThe accompanying research papers are available in the [ paper/](/dugubuyan/agent-nexus/blob/main/paper) directory:\n\n— v3 (current): adds SDAOP`paper/agentnexus-v3.md`\n\n— v2`paper/agentnexus.md`\n\ndugubuyan.\n\nAgentNexus: A Service-Boundary-Aware Coordination Architecture for Heterogeneous LLM Code Agents (v3).Zenodo, 2026.[https://doi.org/10.5281/zenodo.20603176]\n\nMIT", "url": "https://wpnews.pro/news/show-hn-agentnexus-coordinate-llm-agents-by-service-boundary-not-role", "canonical_source": "https://github.com/dugubuyan/agent-nexus", "published_at": "2026-06-13 12:25:15+00:00", "updated_at": "2026-06-13 12:50:20.743972+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "large-language-models", "ai-infrastructure"], "entities": ["AgentNexus", "ChatDev", "MetaGPT", "MCP"], "alternates": {"html": "https://wpnews.pro/news/show-hn-agentnexus-coordinate-llm-agents-by-service-boundary-not-role", "markdown": "https://wpnews.pro/news/show-hn-agentnexus-coordinate-llm-agents-by-service-boundary-not-role.md", "text": "https://wpnews.pro/news/show-hn-agentnexus-coordinate-llm-agents-by-service-boundary-not-role.txt", "jsonld": "https://wpnews.pro/news/show-hn-agentnexus-coordinate-llm-agents-by-service-boundary-not-role.jsonld"}}