Платформа агентного рабочего процесса и MCP

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

Обзор

Агентные рабочие процессы вводят риски, выходящие за рамки обычных API запросов/ответов: вывод внешних инструментов может быть враждебным, повторные попытки могут дублировать побочные эффекты, утверждения могут устареть, а успешный ответ инструмента может не отражать сохраненное состояние.

Этот проект реализует намеренно ограниченный рабочий процесс реагирования на инциденты, ориентированный на эти режимы сбоев. Детерминированный планировщик обнаруживает и вызывает утвержденные инструменты чтения через протокол контекста модели (MCP), предлагает тикет, приостанавливается для утверждения человеком, связывает это утверждение с дайджестом действия SHA-256, выполняет идемпотентную запись в базу данных и проверяет сохраненный результат. Он не использует LLM; основное внимание уделяется надежной оркестровке и границам контроля.

Related MCP server: mcp-policy-gateway

Ключевые особенности

• Обнаружение и вызовы MCP-инструментов через JSON-RPC stdio

• Отдельный MCP-сервер только для чтения с инструментами service-status и runbook-search

• Разрешительный список на уровне приложения, независимый от обнаружения MCP-инструментов

• Явный конечный автомат рабочего процесса с контролем бюджета шагов

• Утверждение или отклонение человеком перед ответственной записью

• Привязка утверждения к полному предложенному действию через дайджест SHA-256

• Стабильные ключи идемпотентности, предотвращающие создание дублирующих тикетов при повторных попытках

• Независимая проверка после записи с помощью SQLite

• Долговечные запуски, утверждения, тикеты и упорядоченные аудиторские события

• FastAPI-эндпоинты с аутентификацией Bearer, 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 и Политика безопасности для получения дополнительной информации.