agent-workflow-mcp

Produktionsreifer Multi-Agent-Workflow-Orchestrator auf Basis des Model Context Protocol (MCP). Ein Planner/Executor/Critic-Agenten-Stack steuert eine typisierte Tool-Use-Schleife, kommuniziert mit MCP-Tool-Servern und schreibt dauerhafte, wiedergebbare Ausführungs-Traces.

Warum

Die meisten Agent-Frameworks enden bei einer Chat-Schleife. agent-workflow-mcp geht weiter: deterministische Planung, strukturierte Tool-Aufrufe, MCP-native Tool-Erkennung, Wiederholungen mit Backoff, dauerhafter Ausführungszustand und ein Trace-Log, das du Ende-zu-Ende wiedergeben kannst. Entwickelt, um stundenlang unbeaufsichtigt zu laufen und nach einem Absturz genau dort weiterzumachen, wo es aufgehört hat.

Related MCP server: MEMGRAPH-MCP

Funktionen

• Planner / Executor / Critic-Agenten, die ein Ziel in einen typisierten Plan zerlegen, Tool-Aufrufe absetzen und jeden Schritt kritisieren, bevor er übernommen wird.

• MCP-Client- und -Server-Transport über stdio und WebSocket, mit vollständiger JSON-RPC-2.0-Protokollunterstützung und Aushandlung von Fähigkeiten.

• Tool-Use-Schleife mit begrenzten Wiederholungen, exponentiellem Backoff, Schema-Validierung und einem Stop-on-Criteria-Hook, damit Schleifen nicht außer Kontrolle geraten.

• Dauerhafter Ausführungszustand: Jeder Schritt, jeder Tool-Aufruf und jede Zwischennachricht wird an ein Ereignisprotokoll angehängt, das wiedergegeben oder fortgesetzt werden kann.

• OpenTelemetry-artiges Tracing mit Span-IDs, Parent-Links, Token-Erfassung und Latenz-Histogrammen pro Agentenrolle.

• Typisierte Konfiguration über Pydantic v2 mit profilbasierten Überschreibungen (default, dev, prod).

• Austauschbare Provider: Integrierter Anthropic-Adapter mit einem sauberen Provider-Protokoll für OpenAI, Bedrock oder lokale Backends.

• CLI mit den Unterbefehlen serve, run, replay, trace und JSON-Ausgabe für Skripte.

• 92 % Testabdeckung, eigenschaftsbasierte Tests für die Wiederholungs- und Wiedergabelogik.

Architektur

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]

Installation

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]"

Schnellstart

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

Erwartete Ausgabe:

[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.

Konfiguration

Benchmarks / Ergebnisse

Gemessen auf einem Ryzen 9 5950X, 64 GB RAM, NVMe-SSD, mit claude-sonnet-5-20251001.

Projektstruktur

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

Tests

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

In CI wird eine Testabdeckung von 90 % erzwungen. Eigenschaftsbasierte Tests für die Wiederholungsschleife befinden sich in tests/test_retry.py.

Roadmap

• v0.4 — OpenTelemetry-OTLP-Exporter (in Arbeit)

• v0.5 — Streaming von Tool-Aufrufen zurück an die CLI

• v0.6 — Austauschbares Tool-Sandboxing (Docker / WASM)

• v1.0 — Stabiler Protokollvertrag für externe MCP-Server

Mitwirken

PRs sind willkommen. Führe vor dem Eröffnen eines PRs make check aus. Mit deiner Teilnahme stimmst du dem Verhaltenskodex zu.

Lizenz

MIT © Tai Nguyen