Plataforma de Flujo de Trabajo para Agentes y MCP

Un flujo de trabajo de incidentes con aprobación que recopila evidencia a través de herramientas MCP de solo lectura, ejecuta una única acción idempotente exacta, verifica el resultado y preserva un registro de auditoría duradero.

Descripción General

Los flujos de trabajo de agentes introducen riesgos más allá de las API de solicitud/respuesta ordinarias: la salida de herramientas externas puede ser hostil, los reintentos pueden duplicar efectos secundarios, las aprobaciones pueden volverse obsoletas y una respuesta exitosa de la herramienta puede no reflejar el estado persistido.

Este proyecto implementa un flujo de trabajo de respuesta a incidentes deliberadamente acotado en torno a esos modos de fallo. Un planificador determinista descubre y llama a herramientas de lectura aprobadas a través del Protocolo de Contexto de Modelo (MCP), propone un ticket, se pausa para la aprobación humana, vincula esa aprobación a un resumen SHA-256 de la acción, realiza una escritura idempotente en la base de datos y verifica el resultado almacenado. No utiliza un LLM; el enfoque está en la orquestación confiable y los límites de control.

Related MCP server: OpenXNet MCP Server

Características Clave

• Descubrimiento de herramientas MCP y llamadas a través de JSON-RPC stdio

• Servidor MCP de solo lectura separado con herramientas de estado del servicio y búsqueda en runbooks

• Lista blanca a nivel de aplicación independiente del descubrimiento de herramientas MCP

• Máquina de estados de flujo de trabajo explícita con aplicación de límite de pasos

• Aprobación o denegación humana antes de la escritura consecuente

• Vinculación del resumen SHA-256 de la aprobación a la acción propuesta completa

• Claves de idempotencia estables que evitan la creación duplicada de tickets durante los reintentos

• Verificación independiente posterior a la escritura contra SQLite

• Ejecuciones, aprobaciones, tickets y eventos de auditoría ordenados duraderos

• Puntos finales FastAPI autenticados con Bearer, flujos de trabajo CLI, CI y pruebas deterministas

Arquitectura

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

El par MCP puede proporcionar observaciones pero no tiene autoridad de escritura. La creación de tickets permanece dentro de la aplicación y no puede ocurrir hasta que el hash de aprobación enviado coincida con la propuesta actual.

Máquina de Estados del Flujo de Trabajo

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

API

Todos los puntos finales /v1 requieren Authorization: Bearer <AGENT_API_TOKEN>.

Pila Tecnológica

Cómo Funciona

1. Un cliente crea una ejecución para un servicio y un síntoma reportado.

2. El flujo de trabajo descubre herramientas MCP, las intersecta con su propia lista blanca de lectura y recopila observaciones acotadas.

3. La salida de la herramienta se almacena como evidencia no confiable y nunca se interpreta como instrucciones del flujo de trabajo.

4. La aplicación crea una acción de ticket propuesta, una clave de idempotencia estable y un hash de acción SHA-256 canónico.

5. El flujo de trabajo persiste awaiting_approval y regresa sin realizar una escritura.

6. Un humano envía una aprobación o denegación para el hash exacto. Las propuestas cambiadas o desactualizadas se rechazan con HTTP 409.

7. Una acción aprobada crea el ticket de forma idempotente, lo lee de SQLite y marca la ejecución como completa solo después de la verificación.

8. Si la ejecución falla después de la aprobación, /resume puede reintentar de forma segura porque la clave de idempotencia permanece estable.

Decisiones de Ingeniería

• El descubrimiento no otorga autoridad. El flujo de trabajo intersecta los resultados de MCP con una lista blanca de lectura codificada, por lo que un par no puede obtener permiso anunciando otra herramienta.

• Las observaciones externas siguen siendo datos. La salida de la herramienta tiene límite de longitud, se marca como no confiable en el evento de auditoría y se usa solo como evidencia del ticket.

• La aprobación está direccionada por contenido. JSON canónico y SHA-256 vinculan la aprobación a cada campo de la acción propuesta y evitan la sustitución de carga útil.

• Las escrituras son idempotentes y verificadas. Una clave de idempotencia única maneja la ambigüedad de reintento, mientras que una lectura separada confirma el registro persistido.

• El estado cruza los límites de efectos secundarios de forma duradera. El estado y los eventos de auditoría se escriben antes y después de la aprobación, ejecución, verificación, fallo y finalización.

• El planificador es intencionalmente determinista. Esto mantiene el modelo de seguridad inspeccionable mientras preserva un límite de planificador reemplazable para el uso futuro de modelos evaluados.

Estructura del Proyecto

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

Primeros Pasos

Requisito previo: 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

La API se ejecuta en http://127.0.0.1:8000; la documentación interactiva está disponible en /docs.

Ejemplo de Uso

Crear una ejecución:

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"}'

La respuesta contiene el ID de ejecución, la acción propuesta completa y action_hash. Después de revisarlos, apruebe esa acción exacta:

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"}'

Inspeccione el historial de eventos reproducible:

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

Pruebas

pytest
ruff check .
mypy

El conjunto verifica autenticación, descubrimiento y llamadas MCP, rechazo por falta de coincidencia de aprobación, comportamiento de denegación, manejo de salida no confiable, límites de salida y pasos, prevención de ejecución duplicada, creación idempotente de tickets, recuperación de fallos, verificación independiente e historial de auditoría ordenado.

Lo Que Este Proyecto Demuestra

• Diseño de flujo de trabajo de agente y máquina de estados duradero

• Integración MCP y límites de proceso JSON-RPC

• Controles de aprobación humano en el circuito para acciones consecuentes

• Idempotencia, recuperación de fallos y verificación de poscondición

• Manejo consciente de la seguridad de la salida no confiable de herramientas

• Diseño de API tipada y persistencia SQLite

• Pruebas automatizadas y aplicación de calidad basada en CI

Hoja de Ruta

• Reemplazar el token de portador de desarrollo con autenticación OIDC y autorización basada en roles

• Conectar el límite de escritura a un proveedor de tickets real a través de un adaptador idempotente

• Mover la ejecución a trabajadores en segundo plano duraderos con control de concurrencia

• Agregar métricas, trazado, registros operativos estructurados y alertas

• Evaluar un planificador LLM contra la línea base determinista antes de otorgarle responsabilidad de planificación acotada

Consulte Arquitectura, Referencia de API y Política de Seguridad para más detalles.