convez.ai
AgenteAutomaçãoAvançado
dugubuyan

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 GitHub
InicialPluginScore · de 0 a 100

Arquitetura 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-nexus

1 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

Estrelas
8
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 3 meses
Versão
v1.1.0
Issues abertas
0
Contribuidores
1

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.

License: MIT Python 3.11+ Tests DOI agent-nexus MCP server Available on CodeGuilds

"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_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
  • 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

ToolDescription
create_spaceCreate a Project Space
register_projectRegister a sub-project (service)
list_projectsList all sub-projects in a space
list_documentsList all documents in a sub-project
push_documentPush a new document version (full content)
patch_documentApply a unified diff patch to a document
get_documentRetrieve a document (latest or specific version)
get_my_updates_with_contextGet unread notifications with diff + full content
ack_updateMark a notification as read
get_my_tasksGet pending tasks for a project
get_configGet config document for a stage
add_subscriptionAdd a subscription rule
publish_draftConfirm a draft document
generate_instruction_fileGenerate IDE onboarding file (SDAOP)
get_project_id_by_nameLook up project_id by name

Configuration

Environment VariableDefaultDescription
DOC_EXCHANGE_DB_URLsqlite:///doc_exchange.dbDatabase URL
DOC_EXCHANGE_DOCS_ROOT./workspaceWorkspace root (docs live under {root}/{space_id}/docs/)
DOC_EXCHANGE_HOST0.0.0.0Server bind host
DOC_EXCHANGE_PORT10086Server port
DOC_EXCHANGE_DEFAULT_SPACE_IDdefaultDefault 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:

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

Ver o original no GitHub

Bom para

Relacionados