AgentNexus - Central de Coordenação de Agentes LLM
dugubuyan/agent-nexus
Coordenação de agentes LLM por limites de serviço, com versionamento e diffs
Ver no GitHubArquitetura de coordenação ciente de limites de serviço para agentes LLM heterogêneos em Python. Implementa repositório versionado de Markdown com notificações pub-sub e protocolo de atualização sensível a diffs, permitindo que múltiplos agentes coordenem-se como em sistemas reais.
Instalação
npx convez-ai dugubuyan/agent-nexus1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Coordenar múltiplos agentes de IA desenvolvendo diferentes microsserviços
- Sincronizar documentação de API entre agentes frontend e backend automaticamente
- Implementar notificações baseadas em mudanças estruturadas entre serviços dependentes
Veredito

AgentNexus é uma solução sofisticada para coordenação multi-agente em arquiteturas de microsserviços, com suporte robusto a versionamento e diffs. Exige domínio avançado de Python e conceitos de coordenação distribuída, mas oferece fundações sólidas (250 testes) para cenários complexos de desenvolvimento colaborativo entre agentes.
README
A tradução para o português deste README ainda está na fila.
AgentNexus
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."
Overview
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.
Key Features
- 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_contextreturns unified diff + full content in one call - Lifecycle stage tracking — explicit
design → development → testing → deployment → upgradeper service, with milestone snapshots on transitions - Service-Driven Agent Onboarding (SDAOP) —
generate_instruction_fileauto-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
- FileWatcher ingestion — auto-ingest Markdown files from
/docs/directory as draft documents - 250 tests — unit + property-based (Hypothesis)
Architecture
┌─────────────────────────────────────────────────────┐
│ Project Space │
│ │
│ ┌──────────────┐ subscribe ┌───────────────┐ │
│ │ search- │ ──────────────► │ search-admin- │ │
│ │ service │ │ frontend │ │
│ │ │ notification │ │ │
│ │ api/v5 ──────┼────────────────►│ │ │
│ └──────────────┘ └───────────────┘ │
│ │
│ AgentNexus MCP Server │
│ http://0.0.0.0:10086/mcp │
└─────────────────────────────────────────────────────┘
How It Works
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..."
}
Quick Start
# 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
Connect from Kiro / any MCP client
{
"mcpServers": {
"doc-exchange": {
"url": "http://localhost:10086/mcp"
}
}
}
First steps
# Create a project space
create_space(name="my-project")
# Register a service
register_project(name="backend-api", type="development", project_space_id="<space_id>")
# Push a document
push_document(project_id="<project_id>", doc_id="<project_id>/api", content="# API Spec...")
# Subscribe frontend to backend's API docs
add_subscription(subscriber_project_id="<frontend_id>", project_space_id="<space_id>", target_doc_id="<backend_id>/api")
# Check updates (returns diff + full content)
get_my_updates_with_context(project_id="<frontend_id>")
MCP Tools
| 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) |
patch_document | Apply a unified diff patch to a document |
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 |
Configuration
| 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 for FileWatcher |
Steering File Integration
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.
Running Tests
python -m pytest tests/ -q
Paper
The accompanying research papers are available in the paper/ directory:
paper/agentnexus-v3.md— v3 (current): adds SDAOPpaper/agentnexus.md— v2
dugubuyan. AgentNexus: A Service-Boundary-Aware Coordination Architecture for Heterogeneous LLM Code Agents (v3). Zenodo, 2026. https://doi.org/10.5281/zenodo.20603176
License
MIT