Agente de triaje de tickets con IA — LangGraph + MCP

Un flujo de trabajo de soporte con forma de producción que clasifica solicitudes desordenadas, extrae evidencia de archivos PDF adjuntos, llama a dos sistemas internos a través de MCP, redacta una respuesta fundamentada y deriva los casos inciertos a un humano en lugar de adivinar.

Cuadro de resultados de evaluación

Estos son resultados reproducibles del corpus sintético incluido, medidos en una máquina de desarrollo local con Windows. La latencia varía según el hardware; el evaluador informa de cada resultado por caso en artifacts/scorecard.json. Los cinco casos difíciles cubren evidencia faltante, identificadores en conflicto, un adjunto ilegible, una solicitud ambigua y un registro ausente del sistema interno. El artefacto también registra su tiempo de generación, hash del corpus, versión de Python, identificador de commit y transporte de herramientas para que los resultados obsoletos sean visibles.

Por qué existe este proyecto

La mayoría de las demostraciones de agentes muestran solo el camino feliz. Esta hace que la abstención sea un comportamiento probado. El agente puede devolver uno de dos resultados acotados:

• drafted — se extrajeron los identificadores requeridos, se completaron ambas comprobaciones MCP de solo lectura y se verificaron las referencias proporcionadas.

• escalated — la confianza o la evidencia no cumplieron la política, por lo que el agente emite una respuesta de espera no comprometida, una cola humana, la evidencia faltante y una razón auditable.

Esa decisión no está oculta en un prompt. Es un borde condicional explícito en la máquina de estados de LangGraph y una métrica en CI.

Qué hace

Email + PDF
    │
    ▼
classify ──► extract ──► intake safety gate
                              │
                    unsafe ───┴─── safe
                       │              │
                       ▼              ▼
                  human queue    MCP tool 1: customer account
                                      │
                                 MCP tool 2: billing / incident
                                      │
                                post-tool safety gate
                                  │              │
                             unverified       verified
                                  │              │
                                  ▼              ▼
                             human queue   grounded draft

Las dos herramientas MCP son deliberadamente limitadas y de solo lectura:

1. lookup_customer_account realiza una coincidencia exacta de cuenta/correo electrónico.

2. lookup_billing_or_incident comprueba facturación, incidencia de servicio o contexto de soporte acotado.

El grafo siempre utiliza un contrato de herramienta MCP neutral al transporte. La evaluación sin conexión utiliza el adaptador rápido en proceso; Docker Compose ejecuta la interfaz de usuario del portafolio contra un servidor MCP persistente y real de JSON-RPC sobre stdio. Ambos transportes se prueban mediante integración, por lo que la orquestación nunca depende de la elección de despliegue.

Ejecútalo localmente

Requisitos previos: Python 3.11–3.13 y uv.

git clone https://github.com/Mohemed-Amine-Chalhy/ai-ticket-triage.git
cd ai-ticket-triage
uv sync --extra dev --locked
uv run uvicorn ai_ticket_triage.web:app --reload

Abre http://127.0.0.1:8000. La interfaz web incluye los 20 ejemplos etiquetados, un cargador de PDF, el rastro del grafo, los campos extraídos, la evidencia de llamadas MCP, la decisión final y el cuadro de resultados.

El comando anterior utiliza el adaptador rápido en proceso. Para ejecutar la interfaz exacta mostrada en la demostración de MCP, inicia el contenedor bloqueado en su lugar; Compose habilita el servidor stdio persistente por defecto:

docker compose up --build

Regenera las cuatro imágenes de prueba del portafolio a partir del cuadro de resultados actual y una ejecución de prueba verbosa real:

make proof

No se requiere clave API. Todos los nombres, correos electrónicos, cuentas, facturas, servicios e incidentes son ficticios; los correos utilizan el dominio reservado example.test.

Demostración CLI

Ejecuta un fixture respondible:

uv run ticket-triage triage --case billing_duplicate_charge

Ejecuta un caso de fallo e inspecciona la transferencia humana:

uv run ticket-triage triage --case failure_unreadable_attachment

Ejecuta un PDF real:

uv run ticket-triage triage \
  --text "I was charged twice; details are attached." \
  --pdf data/sample_attachments/duplicate-charge.pdf

Ejercita el límite real de MCP stdio:

uv run ticket-triage triage \
  --case billing_duplicate_charge \
  --transport stdio

Reproduce el cuadro de resultados

uv run ticket-triage-eval \
  --output artifacts/scorecard.json \
  --markdown-output artifacts/scorecard.md \
  --fail-on-runtime-error \
  --enforce-portfolio-targets

El evaluador puntúa cada etapa de forma independiente: coincidencia exacta de categoría, F1 a nivel de campo micro, comprobaciones declarativas de borrador, fundamentación semántica de la razón de transferencia, precisión/recuperación de escalado, falsos escalados, fallos en tiempo de ejecución y latencia p50/p95/máx. Consulta Metodología de evaluación.

Usa el servidor MCP de forma independiente

Inicia el servidor oficial del SDK incluido sobre stdio:

uv run ticket-triage-mcp

Configuración de ejemplo para un host MCP stdio local:

{
  "mcpServers": {
    "ticket-triage-tools": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/ai-ticket-triage",
        "run",
        "ticket-triage-mcp"
      ]
    }
  }
}

Este es un límite de herramienta neutral al transporte: otro agente compatible o host de escritorio puede usar los mismos dos contratos sin importar la aplicación LangGraph. Para hosts remotos, coloca el servidor detrás de un despliegue HTTP Streamable autenticado; la demostración del portafolio expone intencionalmente solo transportes stdio locales y en proceso.

Decisiones de ingeniería

Determinista por diseño

El clasificador, extractor y compositor de borradores por defecto son deterministas. Eso hace que las regresiones de seguridad sean reproducibles, mantiene la demostración pública sin credenciales y separa la calidad del flujo de trabajo de la varianza del modelo. Un modelo alojado puede reemplazar esos nodos detrás de los mismos contratos tipados; en un despliegue real, sus salidas candidatas deberían pasar igualmente por las mismas compuertas de evidencia y herramientas. Este repositorio no afirma que un benchmark sintético de 20 casos prediga la calidad de datos en vivo.

Mapa del repositorio

src/ai_ticket_triage/
├── agent.py          # LangGraph state machine and tool orchestration
├── classifier.py     # deterministic category scoring with evidence
├── extractor.py      # PDF/text extraction and conflict detection
├── confidence.py     # bounded-failure policy gates
├── drafting.py       # grounded replies and safe holding responses
├── mcp_server.py     # official MCP server; exactly two tools
├── mcp_client.py     # in-process and real stdio MCP gateways
├── internal_api.py   # mock read-only service adapters
├── evaluation.py     # corpus runner and scorecard metrics
├── web.py            # FastAPI application
└── static/           # responsive portfolio UI
data/cases/           # 20 synthetic labelled fixtures
tests/                # unit, API, workflow, evaluator, and MCP integration tests
artifacts/            # committed scorecard and proof outputs
assets/               # portfolio-ready architecture and result images
docs/                 # architecture, evaluation, security, runbook, portfolio copy

Comandos de calidad

uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest --cov=ai_ticket_triage --cov-report=term-missing
uv run ticket-triage-eval --fail-on-runtime-error --enforce-portfolio-targets
docker compose up --build

Documentación

• Arquitectura y flujo de decisiones

• Metodología de evaluación y diseño de casos

• Límites de seguridad y confianza

• Manual de operaciones

• Listado del portafolio, lista de verificación de pruebas y guion de 55 segundos

Limitaciones conocidas

• Solo PDFs basados en texto; los documentos escaneados necesitan OCR y un pipeline de escaneo de malware.

• Sistemas internos sintéticos de coincidencia exacta, no un CRM o plataforma de facturación en vivo.

• Fixtures en inglés y una taxonomía de cuatro clases.

• Sin cola duradera, autenticación, limitación de velocidad ni trazado distribuido en esta demostración local.

• La lógica de lenguaje determinista es una línea base de fiabilidad, no un sustituto de la evaluación en un conjunto de datos de producción representativo y revisado en privacidad.

Esas omisiones son límites intencionales de proyecto de fin de semana. Las interfaces aíslan cada preocupación de producción faltante para que pueda añadirse sin reescribir el grafo.

Licencia

MIT