AI-агент триажа тикетов — LangGraph + MCP

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

Таблица оценки

Это воспроизводимые результаты на зафиксированном синтетическом корпусе, измеренные на локальной машине разработки под Windows. Задержка зависит от оборудования; оценщик сообщает результат по каждому случаю в artifacts/scorecard.json. Пять сложных случаев покрывают отсутствие доказательств, конфликтующие идентификаторы, нечитаемое вложение, неоднозначный запрос и запись, отсутствующую во внутренней системе. Артефакт также фиксирует время генерации, хэш корпуса, версию Python, идентификатор коммита и транспорт инструментов, чтобы устаревшие результаты были заметны.

Зачем существует этот проект

Большинство демо агентов показывают только счастливый путь. Этот делает воздержание от ответа тестируемым поведением. Агент может вернуть один из двух ограниченных результатов:

• drafted — необходимые идентификаторы извлечены, обе проверки MCP только на чтение выполнены, и предоставленные ссылки проверены.

• escalated — уверенность или доказательства не прошли политику, поэтому агент выдаёт необязывающий ответ-ожидание, очередь для человека, недостающие доказательства и проверяемую причину.

Это решение не спрятано в промпте. Это явное условное ребро в конечном автомате LangGraph и метрика в CI.

Что он делает

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

Два MCP-инструмента намеренно узкие и только на чтение:

1. lookup_customer_account выполняет точное совпадение по аккаунту/электронной почте.

2. lookup_billing_or_incident проверяет биллинг, инцидент обслуживания или ограниченный контекст поддержки.

Граф всегда использует один транспортно-нейтральный контракт MCP-инструмента. Офлайн-оценка использует быстрый внутрипроцессный адаптер; Docker Compose запускает портфельный UI против постоянного реального MCP-сервера JSON-RPC-over-stdio. Оба транспорта покрыты интеграционными тестами, поэтому оркестрация никогда не зависит от выбора развёртывания.

Запуск локально

Предварительные требования: Python 3.11–3.13 и 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

Откройте http://127.0.0.1:8000. Веб-UI включает все 20 размеченных примеров, загрузчик PDF, трассировку графа, извлечённые поля, доказательства вызовов MCP, итоговое решение и таблицу оценки.

Команда выше использует быстрый внутрипроцессный адаптер. Чтобы запустить именно тот UI, что показан в MCP-демо, запустите зафиксированный контейнер; Compose по умолчанию включает постоянный stdio-сервер:

docker compose up --build

Перегенерируйте все четыре портфельных доказательных изображения из текущей таблицы оценки и реального подробного тестового запуска:

make proof

API-ключ не требуется. Все имена, адреса электронной почты, аккаунты, счета, услуги и инциденты вымышлены; письма используют зарезервированный домен example.test.

CLI-демо

Запустите разрешимый фикстур:

uv run ticket-triage triage --case billing_duplicate_charge

Запустите случай с ошибкой и проверьте передачу человеку:

uv run ticket-triage triage --case failure_unreadable_attachment

Запустите реальный PDF:

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

Проверьте реальную границу stdio MCP:

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

Воспроизведение таблицы оценки

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

Оценщик оценивает каждый этап независимо: точное совпадение категории, микро-F1 на уровне полей, декларативные проверки черновика, семантическую обоснованность причины передачи, точность/полноту эскалации, ложные эскалации, ошибки выполнения и задержку p50/p95/max. См. Методология оценки.

Использование MCP-сервера независимо

Запустите встроенный сервер официального SDK через stdio:

uv run ticket-triage-mcp

Пример конфигурации для локального stdio MCP-хоста:

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

Это транспортно-нейтральная граница инструментов: другой совместимый агент или настольный хост может использовать те же два контракта без импорта приложения LangGraph. Для удалённых хостов разместите сервер за аутентифицированным развёртыванием Streamable HTTP; портфельное демо намеренно предоставляет только локальные stdio и внутрипроцессный транспорты.

Инженерные решения

Детерминированность по замыслу

Классификатор, экстрактор и составитель черновика по умолчанию детерминированы. Это делает регрессии безопасности воспроизводимыми, сохраняет публичное демо без учётных данных и отделяет качество рабочего процесса от вариативности моделей. Размещённая модель может заменить эти узлы за теми же типизированными контрактами; в реальном развёртывании её кандидатные выходы всё равно должны проходить через те же шлюзы доказательств и инструментов. Этот репозиторий не утверждает, что синтетический бенчмарк из 20 случаев предсказывает качество на живых данных.

Карта репозитория

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

Команды контроля качества

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

Документация

• Архитектура и поток решений

• Методология оценки и дизайн случаев

• Безопасность и границы доверия

• Эксплуатационный ранбук

• Портфельное описание, чек-лист доказательств и 55-секундный сценарий

Известные ограничения

• Только текстовые PDF; отсканированные документы требуют OCR и конвейер проверки на вредоносное ПО.

• Синтетические внутренние системы с точным совпадением, а не живая CRM или биллинговая платформа.

• Англоязычные фикстуры и таксономия из четырёх классов.

• Нет постоянной очереди, аутентификации, ограничения частоты запросов или распределённой трассировки в этом локальном демо.

• Детерминированная языковая логика — это базовый уровень надёжности, а не замена оценки на репрезентативном, проверенном на конфиденциальность производственном наборе данных.

Эти упущения — намеренные границы проекта выходного дня. Интерфейсы изолируют каждую отсутствующую производственную задачу, чтобы её можно было добавить без переписывания графа.

Лицензия

MIT