agent-workflow-mcp

Промышленный оркестратор мультиагентных рабочих процессов, построенный на Model Context Protocol (MCP). Стек агентов планировщик/исполнитель/критик управляет типизированным циклом вызова инструментов, взаимодействует с MCP-серверами инструментов и записывает устойчивые, воспроизводимые трейсы запусков.

Зачем

Большинство агентных фреймворков ограничиваются чат-циклом. agent-workflow-mcp идёт дальше: детерминированное планирование, структурированные вызовы инструментов, MCP-нативное обнаружение инструментов, повторные попытки с задержкой, устойчивое состояние запуска и журнал трассировки, который можно воспроизвести от начала до конца. Спроектирован для работы без присмотра в течение нескольких часов и продолжения с места остановки после сбоя.

Related MCP server: MEMGRAPH-MCP

Возможности

• Планировщик / Исполнитель / Критик — агенты, которые разбивают цель на типизированный план, отправляют вызовы инструментов и критикуют каждый шаг перед фиксацией.

• MCP-клиент и сервер — транспорт через stdio и WebSocket, с полной поддержкой протокола JSON-RPC 2.0 и согласованием возможностей.

• Цикл использования инструментов с ограниченным числом повторных попыток, экспоненциальной задержкой, проверкой схемы и хуком остановки по критериям, чтобы циклы не выходили из-под контроля.

• Устойчивое состояние запуска: каждый шаг, вызов инструмента и промежуточное сообщение добавляются в журнал событий, который можно воспроизвести или продолжить.

• Трассировка в стиле OpenTelemetry с идентификаторами спанов, связями с родительскими спанами, учётом токенов и гистограммами задержек по ролям агентов.

• Типизированная конфигурация через Pydantic v2 с переопределениями на основе профилей (default, dev, prod).

• Подключаемые провайдеры: встроенный адаптер Anthropic с чистым протоколом Provider для OpenAI, Bedrock или локальных бэкендов.

• CLI с подкомандами serve, run, replay, trace и выводом в JSON для скриптов.

• Покрытие тестами 92%, property-based тесты для логики повторных попыток и воспроизведения.

Архитектура

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]

Установка

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

Быстрый старт

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

Ожидаемый вывод:

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

Конфигурация

Бенчмарки / Результаты

Измерено на Ryzen 9 5950X, 64 ГБ ОЗУ, NVMe SSD, на модели claude-sonnet-5-20251001.

Структура проекта

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

Тестирование

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

Покрытие контролируется на уровне 90% в CI. Property-based тесты для цикла повторных попыток находятся в tests/test_retry.py.

Дорожная карта

• v0.4 — экспортёр OpenTelemetry OTLP (в разработке)

• v0.5 — потоковая передача вызовов инструментов обратно в CLI

• v0.6 — подключаемая песочница для инструментов (Docker / WASM)

• v1.0 — стабильный контракт протокола для внешних MCP-серверов

Участие в разработке

PR приветствуются. Перед открытием PR выполните make check. Участвуя, вы соглашаетесь с Кодексом поведения.

Лицензия

MIT © Tai Nguyen