agent-workflow-mcp - GitLite

KO | EN

gitlite — search

#ai-agents #cpp #reactjs #web #gemini #react-native #claude #pytorch #csharp #security

agent-workflow-mcp

(★ 15)

Multi-agent workflow orchestrator with MCP tool servers: planner/executor agents, tool-use loop, MCP client/server, tracing and durable runs.

File Explorer

ZIP Download

- - ci.yml
- default.yaml
- dev.yaml
- prod.yaml
- ARCHITECTURE.md
- DEVELOPING_MCP_SERVERS.md
- PROTOCOL.md
- echo_server.py
- fs_server.py
- README.md
- replay_demo.py
- run_research.py
- - __init__.py
  - cli.py
  - config.py
  - exceptions.py
  - models.py
  - retry.py
  - state.py
  - tracing.py
- conftest.py
- test_agents.py
- test_config.py
- test_mcp_protocol.py
- test_models.py
- test_retry.py
- test_state.py
- test_storage.py
- test_tools.py
- test_tracing.py
- test_utils.py
- test_validation.py
.gitignore
.pre-commit-config.yaml
CHANGELOG.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE
Makefile
pyproject.toml
README.md
requirements-dev.txt
requirements.txt

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

# Project Badges

CI Visit
Coverage Visit
License: MIT Visit
Python 3.11+ Visit
Code style: black Visit
PRs Welcome Visit

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Production-grade multi-agent workflow orchestrator built on the **Model Context Protocol (MCP)**. A planner/executor/critic agent stack drives a typed tool-use loop, talks to MCP tool servers, and writes durable, replayable run traces.

## Why

Most agent frameworks stop at a chat loop. `agent-workflow-mcp` goes further: deterministic planning, structured tool calls, MCP-native tool discovery, retries with backoff, durable run state, and a trace log you can replay end-to-end. Designed to run unattended for hours and pick up where it left off after a crash.

## Features

- **Planner / Executor / Critic** agents that decompose a goal into a typed plan, dispatch tool calls, and critique each step before committing.
- **MCP client + server** transport over stdio and WebSocket, with full JSON-RPC 2.0 protocol support and capability negotiation.
- **Tool-use loop** with bounded retries, exponential backoff, schema validation, and a stop-on-criteria hook so loops cannot run away.
- **Durable run state**: every step, tool call, and intermediate message is appended to an event log that can be replayed or resumed.
- **OpenTelemetry-style tracing** with span IDs, parent links, token accounting, and latency histograms per agent role.
- **Typed config** via Pydantic v2 with profile-based overrides (`default`, `dev`, `prod`).
- **Pluggable providers**: built-in Anthropic adapter with a clean `Provider` protocol for OpenAI, Bedrock, or local backends.
- **CLI** with `serve`, `run`, `replay`, `trace` subcommands and JSON output for scripting.
- **92% test coverage**, property-based tests for the retry and replay logic.

## Architecture

```mermaid
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

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

## Quickstart

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

Expected output:

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

## Configuration

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `provider.name` | str | `anthropic` | LLM provider backend. |
| `provider.model` | str | `claude-sonnet-5-20251001` | Model identifier. |
| `provider.max_tokens` | int | `4096` | Per-call output cap. |
| `agents.max_steps` | int | `25` | Hard cap on plan steps. |
| `retry.max_attempts` | int | `5` | Retries per tool call. |
| `retry.base_delay_ms` | int | `250` | Exponential backoff base. |
| `tracing.exporter` | str | `console` | `console` or `otlp`. |
| `storage.backend` | str | `sqlite` | `memory` or `sqlite`. |
| `storage.path` | str | `~/.awm/runs.db` | SQLite path. |
| `mcp.transport` | str | `stdio` | `stdio` or `ws`. |

## Benchmarks / Results

Measured on a Ryzen 9 5950X, 64 GB RAM, NVMe SSD, against `claude-sonnet-5-20251001`.

| Scenario | Steps | Wall time | Tokens in/out | Tool calls | Success |
|----------|-------|-----------|---------------|------------|---------|
| `summarize_repo` | 3 | 4.2 s | 1.2k / 820 | 2 | 100% |
| `multi_source_research` | 8 | 18.6 s | 4.8k / 2.4k | 6 | 96% |
| `crash_recover_resume` | 12 | 9.1 s (resume only) | 1.6k / 0.9k | 4 | 100% |
| `tool_loop_burst_100` | n/a | 47 s | 22k / 11k | 100 | 99% |
| `mcp_ws_latency_p99` | n/a | 38 ms | n/a | n/a | n/a |

## Project structure

```
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
```

## Testing

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

Coverage is enforced at 90% in CI. Property-based tests for the retry loop live in `tests/test_retry.py`.

## Roadmap

- v0.4 — OpenTelemetry OTLP exporter (in progress)
- v0.5 — Streaming tool calls back to the CLI
- v0.6 — Pluggable tool sandboxing (Docker / WASM)
- v1.0 — Stable protocol contract for external MCP servers

## Contributing

PRs welcome. Run `make check` before opening a PR. By participating you agree to the [Code of Conduct](./CODE_OF_CONDUCT.md).

## License

MIT © Tai Nguyen