Skip to main content
Glama
deenesjakoruzh
tainguyen07

agent-workflow-mcp

by tainguyen07
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

agent-workflow-mcp

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

プロダクショングレードのマルチエージェントワークフローオーケストレーターで、Model Context Protocol (MCP) 上に構築されています。プランナー / エグゼキューター / クリティックのエージェントスタックが型付きツール利用ループを駆動し、MCP ツールサーバーと通信しながら、永続的でリプレイ可能な実行トレースを記録します。

なぜ

多くのエージェントフレームワークはチャットのループで止まってしまいます。agent-workflow-mcp はさらに先へ進みます。決定的なプランニング、構造化されたツール呼び出し、MCP ネイティブのツール発見、バックオフ付きリトライ、永続的な実行状態、そしてエンドツーエンドでリプレイできるトレースログを実現しています。クラッシュ後は中断したところから再開し、長時間にわたって無人で稼働し続けることを前提に設計されています。

Related MCP server: MEMGRAPH-MCP

特徴

  • プランナー / エグゼキューター / クリティック — 目標を型付きプランに分解し、ツール呼び出しをディスパッチし、各ステップを確定する前に検証するエージェント群です。

  • MCP クライアント + サーバー — stdio 上および WebSocket 上のトランスポートに対応し、完全な JSON-RPC 2.0 プロトコルサポートとキャパビリティネゴシエーション（能力交渉）を備えています。

  • ツール利用ループ — リトライの上限、指数バックオフ、スキーマ検証、停止条件に基づくフックにより、ループが暴走しません。

  • 永続的な実行状態 — すべてのステップ、ツール呼び出し、中間メッセージをイベントログに追記し、リプレイまたは再開を可能にします。

  • OpenTelemetry スタイルのトレーシング — スパン ID、親リンク、トークン使用量の記録、エージェントの役割ごとのレイテンシヒストグラムを提供します。

  • 型付き設定 — Pydantic v2 による型付き設定と、プロファイルベースのオーバーライド（default、dev、prod）に対応しています。

  • プラグ可能なプロバイダー — 組み込みの Anthropic アダプターに加え、OpenAI、Bedrock、ローカルバックエンド向けのクリーンな Provider プロトコルを提供します。

  • CLI — serve、run、replay、trace のサブコマンドと、スクリプト処理に便利な JSON 出力を備えています。

  • テストカバレッジ 92% — リトライ処理とリプレイ処理のロジックに対するプロパティベースのテストを実施しています。

アーキテクチャ

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.

設定

キー

型

デフォルト値

説明

provider.name

str

anthropic

LLM プロバイダーのバックエンド。

provider.model

str

claude-sonnet-5-20251001

モデル識別子。

provider.max_tokens

int

4096

1 回の呼び出しあたりの出力上限。

agents.max_steps

int

25

プランのステップ数の上限。

retry.max_attempts

int

5

ツール呼び出しあたりのリトライ回数。

retry.base_delay_ms

int

250

指数バックオフの基準値。

tracing.exporter

str

console

console または otlp。

storage.backend

str

sqlite

memory または sqlite。

storage.path

str

~/.awm/runs.db

SQLite のパス。

mcp.transport

str

stdio

stdio または ws。

ベンチマーク / 結果

Ryzen 9 5950X、64 GB RAM、NVMe SSD、claude-sonnet-5-20251001 の環境で測定しました。

シナリオ

ステップ数

実時間

トークン（入力 / 出力）

ツール呼び出し回数

成功率

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（再開時のみ）

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

プロジェクト構成

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

カバレッジは CI 上で 90% に設定されています。リトライループのプロパティベーステストは tests/test_retry.py にあります。

ロードマップ

  • v0.4 — OpenTelemetry OTLP エクスポーター（進行中）

  • v0.5 — ツール呼び出しの CLI へのストリーミング（進行中）

  • v0.6 — Docker / WASM によるサンドボックス化（進行中）

  • v1.0 — 外部 MCP サーバー向けの安定プロトコル契約の策定

コントリビューション

PR は歓迎です。PR を出す前に make check を実行してください。参加することで、行動規範（Code of Conduct） に同意したものと見なします。

ライセンス

MIT © Tai Nguyen

This server cannot be deployed

Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • JamJet

    jamjet-labs
    A
    license
    A
    quality
    A
    maintenance
    Durable, agent-native AI runtime with native MCP client and server support. Rust core for performance with Python SDK for workflow authoring. Features graph-based workflows, durable execution, A2A protocol support, and multi-agent coordination.
    8
    23
    Apache 2.0

  • MEMGRAPH-MCP

    MikeB317
    F
    license
    A
    quality
    D
    maintenance
    A durable multi-agent orchestrator for software development with explicit run graphs, checkpoint/resume capabilities, and project memory exposed through MCP resources and tools. It enables coordinated agent workflows for coding, review, repair, CI, and approval with SQLite-backed memory retrieval and pluggable research backends.
    10
    -