agent-workflow-mcp

Orquestador de flujos de trabajo multiagente de nivel de producción construido sobre el Protocolo de Contexto de Modelo (MCP). Una pila de agentes planificador/ejecutor/crítico impulsa un bucle de uso de herramientas tipado, se comunica con servidores MCP y escribe trazas de ejecución duraderas y reproducibles.

Por qué

La mayoría de los frameworks de agentes se quedan en un simple bucle de chat. agent-workflow-mcp va más allá: planificación determinista, llamadas a herramientas estructuradas, descubrimiento de herramientas nativo de MCP, reintentos con retroceso exponencial, estado de ejecución persistente y un registro de trazas que puedes reproducir de principio a fin. Diseñado para funcionar sin supervisión durante horas y retomar desde donde quedó tras un fallo.

Related MCP server: MEMGRAPH-MCP

Características

• Agentes planificador / ejecutor / crítico que descomponen un objetivo en un plan tipado, despachan llamadas a herramientas y evalúan cada paso antes de confirmarlo.

• Cliente + servidor MCP con transporte sobre stdio y WebSocket, soporte completo del protocolo JSON-RPC 2.0 y negociación de capacidades.

• Bucle de uso de herramientas con reintentos limitados, retroceso exponencial, validación de esquemas y un criterio de detención para que los bucles no se descontrolen.

• Estado de ejecución duradero: cada paso, llamada a herramienta y mensaje intermedio se añade a un registro de eventos que se puede reproducir o reanudar.

• Trazabilidad estilo OpenTelemetry con IDs de tramo, enlaces a tramos padre, contabilidad de tokens y histogramas de latencia por rol de agente.

• Configuración tipada mediante Pydantic v2 con perfiles de configuración (default, dev, prod).

• Proveedores conectables: adaptador Anthropic integrado con un protocolo Provider limpio para OpenAI, Bedrock o backends locales.

• CLI con subcomandos serve, run, replay, trace y salida JSON para scripting.

• 91% de cobertura de pruebas, con pruebas basadas en propiedades para la lógica de reintentos y reproducción.

Arquitectura

flowchart LR
    U[User / CLI] --> C[CLI / API]
    C --> O[Orchestrator]
    O --> P[Planner]
    O --> E[Executor]
    O --> K[Critic]
    P --> |plan| S[(Run State)]
    E --> |tool call| M[MCP Client]
    M --> |JSON-RPC| T[MCP Tool Servers]
    E --> |observation| S
    K --> |accept / revise| O
    S --> R[Replay]
    S --> TR[Tracer]
    TR --> OT[OTLP / Console]

Instalación

git clone https://github.com/tai-nguyen/agent-workflow-mcp.git
cd agent-workflow-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Inicio rápido

export ANTHROPIC_API_KEY=sk-ant-...
agent-workflow-mcp run "summarize the latest commits in this repo"

Salida esperada:

[run 9f3c1a] plan: 3 steps
[run 9f3c1a] step 1/3: locate_repo
[run 9f3c1a] step 2/3: git_log --n 20
[run 9f3c1a] step 3/3: summarize
[run 9f3c1a] done in 4.2s, 1,820 tokens

CLI

$ agent-workflow-mcp --help
Usage: agent-workflow-mcp [OPTIONS] COMMAND [ARGS]...

  Multi-agent workflow orchestrator with MCP tool servers.

Options:
  --config PATH   Path to config profile (default: config/default.yaml).
  --log-level     DEBUG / INFO / WARNING / ERROR.
  --json          Emit machine-readable JSON on stdout.
  --version       Show version.
  -h, --help       Show this help.

Commands:
  run      Execute a goal end-to-end.
  serve    Start the MCP server (stdio or ws).
  replay   Replay a run from its event log.
  trace    Print a trace tree for a run.

Configuración

Benchmarks / Resultados

Medido en un Ryzen 9 5950X, 64 GB de RAM, SSD NVMe, contra claude-sonnet-5-20251001.

Estructura del proyecto

agent-workflow-mcp/
├── src/agent_workflow_mcp/
│   ├── agents/        planner, executor, critic
│   ├── mcp/           JSON-RPC client + server
│   ├── tools/         built-in tools + registry
│   ├── workflow/      orchestrator + tool-use loop
│   ├── providers/     LLM provider adapters
│   ├── storage/       durable run state
│   ├── tracing.py     OTel-style spans
│   ├── retry.py       backoff + jitter
│   ├── state.py       run state machine
│   └── cli.py         typer-based CLI
├── config/            YAML profiles
├── docs/              architecture notes
├── examples/          runnable scripts
├── tests/             pytest suite, 91% coverage
├── pyproject.toml
├── requirements.txt
└── requirements-dev.txt

Pruebas

pytest --cov=agent_workflow_mcp --cov-report=term-missing

La cobertura se exige al 90% en CI. Las pruebas basadas en propiedades para el bucle de reintentos se encuentran en tests/test_retry.py.

Hoja de ruta

• v0.4 — Exportador OTLP de OpenTelemetry (en progreso)

• v0.5 — Transmisión de llamadas a herramientas de vuelta a la CLI

• v0.6 — Aislamiento de herramientas conectable (Docker / WASM)

• v1.0 — Contrato de protocolo estable para servidores MCP externos

Contribuciones

Las contribuciones son bienvenidas. Ejecuta make check antes de abrir un pull request. Al participar aceptas el Código de Conducta.

Licencia

MIT © Tai Nguyen