에이전트 및 MCP 워크플로우 플랫폼

승인 게이트가 있는 인시던트 워크플로우로, 읽기 전용 MCP 도구를 통해 증거를 수집하고, 정확히 하나의 동일한 멱등적 작업을 실행하며, 결과를 검증하고, 지속 가능한 감사 추적을 보존합니다.

개요

에이전틱 워크플로우는 일반적인 요청/응답 API 이상의 위험을 도입합니다: 외부 도구 출력이 적대적일 수 있고, 재시도가 부수 효과를 중복할 수 있으며, 승인이 오래될 수 있고, 성공적인 도구 응답이 지속된 상태를 반영하지 않을 수 있습니다.

이 프로젝트는 이러한 실패 모드에 초점을 맞춰 의도적으로 제한된 인시던트 응답 워크플로우를 구현합니다. 결정론적 플래너가 Model Context Protocol (MCP)을 통해 승인된 읽기 도구를 발견하고 호출하며, 티켓을 제안하고, 사람의 승인을 기다리며, 해당 승인을 SHA-256 액션 다이제스트에 바인딩하고, 멱등적 데이터베이스 쓰기를 수행하며, 저장된 결과를 검증합니다. LLM을 사용하지 않으며, 신뢰할 수 있는 오케스트레이션과 제어 경계에 중점을 둡니다.

Related MCP server: OpenXNet MCP Server

주요 기능

• JSON-RPC stdio를 통한 MCP 도구 발견 및 호출

• service-status 및 runbook-search 도구를 갖춘 별도의 읽기 전용 MCP 서버

• MCP 도구 발견과 독립적인 애플리케이션 수준의 허용 목록

• 단계 예산 제한이 있는 명시적 워크플로우 상태 머신

• 결과적 쓰기 전 사람의 승인 또는 거부

• 완전한 제안된 액션에 승인을 바인딩하는 SHA-256 다이제스트

• 재시도 중 중복 티켓 생성을 방지하는 안정적인 멱등성 키

• SQLite에 대한 독립적인 사후 쓰기 검증

• 지속 가능한 실행, 승인, 티켓 및 순서가 있는 감사 이벤트

• Bearer 인증된 FastAPI 엔드포인트, CLI 워크플로우, CI 및 결정론적 테스트

아키텍처

flowchart LR
    C[API Client] --> A[FastAPI]
    A --> W[Workflow Service]
    W --> P[Deterministic Planner]
    W --> M[MCP Stdio Client]
    M --> S[Read-Only MCP Server]
    W --> D[(SQLite Store)]
    H[Human Approver] --> A
    A --> W
    W --> T[Idempotent Ticket Write]
    T --> D
    D --> V[Verification]
    V --> W

MCP 피어는 관찰을 제공할 수 있지만 쓰기 권한은 없습니다. 티켓 생성은 애플리케이션 내부에 남아 있으며, 제출된 승인 해시가 현재 제안과 일치할 때까지 발생할 수 없습니다.

워크플로우 상태 머신

created -> gathering -> awaiting_approval -> executing -> verifying -> completed
                |              |               |            |
                v              v               v            v
              failed        cancelled        failed       failed
                                                 |
                                                 `-- resume with matching approval

API

모든 /v1 엔드포인트는 Authorization: Bearer <AGENT_API_TOKEN>이 필요합니다.

기술 스택

작동 방식

1. 클라이언트가 서비스와 보고된 증상에 대한 실행을 생성합니다.

2. 워크플로우가 MCP 도구를 발견하고, 자체 읽기 허용 목록과 교차하여 제한된 관찰을 수집합니다.

3. 도구 출력은 신뢰할 수 없는 증거로 저장되며 워크플로우 명령으로 해석되지 않습니다.

4. 애플리케이션이 하나의 제안된 티켓 액션, 안정적인 멱등성 키 및 표준 SHA-256 액션 해시를 생성합니다.

5. 워크플로우가 awaiting_approval 상태로 유지되고 쓰기를 수행하지 않고 반환됩니다.

6. 사람이 정확한 해시에 대한 승인 또는 거부를 제출합니다. 변경되거나 오래된 제안은 HTTP 409로 거부됩니다.

7. 승인된 액션이 멱등적으로 티켓을 생성하고, SQLite에서 다시 읽어 검증한 후에만 실행을 완료로 표시합니다.

8. 승인 후 실행이 실패하면 /resume이 멱등성 키가 안정적으로 유지되므로 안전하게 재시도할 수 있습니다.

엔지니어링 결정 사항

• 발견이 권한을 부여하지 않습니다. 워크플로우는 MCP 결과를 하드코딩된 읽기 허용 목록과 교차하므로, 피어가 다른 도구를 광고하여 권한을 얻을 수 없습니다.

• 외부 관찰은 데이터로 남습니다. 도구 출력은 길이가 제한되고 감사 이벤트에서 신뢰할 수 없음으로 표시되며 티켓 증거로만 사용됩니다.

• 승인은 콘텐츠 주소 지정 방식입니다. 표준 JSON 및 SHA-256이 제안된 액션의 모든 필드에 승인을 바인딩하고 페이로드 대체를 방지합니다.

• 쓰기는 멱등적이며 검증됩니다. 고유한 멱등성 키가 재시도 모호성을 처리하고, 별도의 읽기가 지속된 레코드를 확인합니다.

• 상태는 부수 효과 경계를 넘어 지속적으로 유지됩니다. 상태 및 감사 이벤트는 승인, 실행, 검증, 실패 및 완료 전후에 기록됩니다.

• 플래너는 의도적으로 결정론적입니다. 이는 미래 평가 모델 사용을 위한 대체 가능한 플래너 경계를 보존하면서 안전 모델을 검사 가능하게 유지합니다.

프로젝트 구조

agent-mcp-workflow-platform/
|-- src/agent_platform/
|   |-- workflow.py          # State machine, planner, approval, execution, verification
|   |-- tools.py             # MCP stdio client and deterministic test client
|   |-- mcp_server.py        # Local read-only MCP server
|   |-- database.py          # SQLite schema and durable workflow store
|   |-- models.py            # Typed run, action, approval, event, and tool contracts
|   |-- api.py               # Authenticated FastAPI endpoints
|   |-- settings.py          # Environment-based configuration
|   `-- cli.py               # Database, MCP discovery, demo, and server commands
|-- tests/                   # Workflow safety, retry, MCP, and API tests
|-- docs/                    # Architecture and API reference
|-- .github/workflows/ci.yml
|-- SECURITY.md
|-- CONTRIBUTING.md
`-- pyproject.toml

시작하기

필수 조건: Python 3.12+.

cd agent-mcp-workflow-platform
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
Copy-Item .env.example .env
agent-workflow init-db
agent-workflow mcp-tools
agent-workflow serve

API는 http://127.0.0.1:8000에서 실행되며, 대화형 문서는 /docs에서 확인할 수 있습니다.

사용 예시

실행 생성:

curl -X POST http://127.0.0.1:8000/v1/runs \
  -H "Authorization: Bearer change-me" \
  -H "Content-Type: application/json" \
  -d '{"service":"payments-api","symptom":"Elevated 5xx responses"}'

응답에는 실행 ID, 완전한 제안된 액션 및 action_hash가 포함됩니다. 검토 후 정확한 액션을 승인합니다:

curl -X POST http://127.0.0.1:8000/v1/runs/RUN_ID/approval \
  -H "Authorization: Bearer change-me" \
  -H "Content-Type: application/json" \
  -d '{"approved":true,"action_hash":"HASH_FROM_PROPOSAL"}'

재생 가능한 이벤트 기록을 검사합니다:

curl http://127.0.0.1:8000/v1/runs/RUN_ID/events \
  -H "Authorization: Bearer change-me"

테스트

pytest
ruff check .
mypy

테스트 스위트는 인증, MCP 발견 및 호출, 승인 불일치 거부, 거부 동작, 신뢰할 수 없는 출력 처리, 출력 및 단계 제한, 중복 실행 방지, 멱등적 티켓 생성, 실패 복구, 독립적 검증 및 순서가 있는 감사 기록을 검증합니다.

이 프로젝트가 보여주는 것

• 지속 가능한 에이전트 워크플로우 및 상태 머신 설계

• MCP 통합 및 JSON-RPC 프로세스 경계

• 결과적 액션에 대한 인간 참여 승인 제어

• 멱등성, 실패 복구 및 사후 조건 검증

• 신뢰할 수 없는 도구 출력의 보안 중심 처리

• 타입이 있는 API 및 SQLite 지속성 설계

• 자동화된 테스트 및 CI 기반 품질 보장

로드맵

• 개발 Bearer 토큰을 OIDC 인증 및 역할 기반 권한 부여로 교체

• 멱등적 어댑터를 통해 실제 티켓팅 제공자에 쓰기 경계 연결

• 동시성 제어가 있는 지속 가능한 백그라운드 작업자로 실행 이동

• 메트릭, 추적, 구조화된 운영 로그 및 알림 추가

• LLM 플래너에게 제한된 계획 책임을 부여하기 전에 결정론적 기준선과 비교 평가

자세한 내용은 아키텍처, API 참조 및 보안 정책을 참조하세요.