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

기능

  • 플래너 / 실행기 / 비평가 에이전트는 목표를 타입이 지정된 계획으로 분해하고 도구 호출을 지시하며 각 단계를 커밋하기 전에 검토합니다.

  • stdio 및 WebSocket을 통한 MCP 클라이언트 + 서버 전송 계층, 완전한 JSON-RPC 2.0 프로토콜 지원 및 기능 협상 포함.

  • 제한된 재시도, 지수 백오프, 스키마 검증, 및 정지 조건 훅이 있는 도구 사용 루프로 루프가 통제 불능이 되는 것을 방지합니다.

  • 지속형 실행 상태: 모든 단계, 도구 호출, 중간 메시지가 이벤트 로그에 추가되어 재생 또는 재개할 수 있습니다.

  • OpenTelemetry 스타일 추적 - 스팬 ID, 부모 링크, 토큰 계정, 에이전트 역할별 대기 시간 히스토그램.

  • Pydantic v2 기반 타입 지정 설정 및 프로필 기반 재정의(default, dev, prod).

  • 플러그형 공급자: OpenAI, Bedrock이 어떤 로컬 백엔드용 깔끔한 Provider 프로토콜을 갖춘 내장 Anthropic 어댑터.

  • 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

호출당 최대 출력 토큰.

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%로 강제됩니다. 재시도 루프에 대한 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

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
    -