AI L1 Support Agent

Контролируемый AI-native процесс первой линии поддержки. Текущий статус:

• этап 1: архитектура и доменные контракты — готово;
• этап 2: MCP-инструменты и тестовые интеграции — готово;
• этап 3: первичная классификация (triage), правила безопасности, ответы из KB и оценка качества — готово;
• этап 4: LangGraph-оркестратор, контрольные точки и полный процесс обработки — готово;
• этап 5: E2E-демонстрация, безопасная наблюдаемость и расширенная оценка качества — готово;
• этап 6: формальный критерий качества, проверка стабильности и тестовая матрица Linux — готово;
• этап 7: автономный wheel, CI и подготовка публичного репозитория — готово.

По умолчанию проект работает полностью локально: читает зафиксированный снимок тикетов, пишет только в data/runtime/ и не изменяет публичный MockAPI.

Быстрый запуск: два сценария

Требования: Python 3.10–3.13 и uv.

uv sync --locked

Сценарий 1: воспроизводимый локальный запуск

Это основной режим для проверки логики, демонстрации и разработки. Он читает зафиксированный снимок заявок, не требует сети и сохраняет все изменения только в data/runtime/. TICKET_SOURCE=fixture уже является безопасным значением по умолчанию.

# Обработать одну заявку из локального снимка
uv run support-agent-workflow poll --limit 1

# Прогнать пять изолированных сквозных сценариев
uv run support-agent-demo --run-id quick-start

Повтор с тем же рабочим каталогом восстанавливает состояние из SQLite и не дублирует побочные действия. Для полностью нового прогона используйте другой --run-id демонстрации или задайте новые RUNTIME_PATH и SQLITE_PATH.

Сценарий 2: чтение реальной очереди MockAPI

Этот режим подтверждает интеграцию с открытым API из задания. Агент получает настоящую заявку по сети, но ответы, статусы, Telegram-сообщения и GitHub Issues по-прежнему записывает только локально. Удалённая очередь не изменяется.

$env:TICKET_SOURCE = "remote"
$env:TICKETS_API_URL = "https://6a7ad74c8c69b3eb4a179621.mockapi.io/tickets/tickets"
$env:ALLOW_REMOTE_WRITES = "false"
$env:RUNTIME_PATH = "data/runtime/remote-quick-start"
$env:SQLITE_PATH = "data/runtime/remote-quick-start/agent.sqlite3"

uv run support-agent-workflow poll --limit 1

Для следующего запуска в том же терминале можно вернуться к локальному снимку:

$env:TICKET_SOURCE = "fixture"

RemoteTicketSource намеренно поддерживает только чтение. ALLOW_REMOTE_WRITES=false зафиксирован как дополнительный предохранитель; удалённый адаптер записи в проекте вообще не реализован. Локальный overlay не синхронизируется с MockAPI, поэтому состояние разных экземпляров агента не является общим.

MockAPI является внешним сервисом. Если он или сеть недоступны, команда намеренно завершится ошибкой ticket API is unavailable, не переключаясь незаметно на локальные данные. В таком случае проверьте URL и повторите сетевой запуск позднее; автономный сценарий остаётся доступен.

Запуск MCP-сервера

uv run support-agent-mcp

Команда запускает MCP-сервер support-tools через stdio. Для локальной разработки .env необязателен: безопасные значения уже являются значениями по умолчанию. Для изменения настроек скопируйте .env.example в .env; секреты и рабочие файлы исключены из Git.

Установка собранного пакета

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

uv build
uv venv .wheel-venv
uv pip install --python .wheel-venv/Scripts/python.exe dist/*.whl
.wheel-venv/Scripts/support-agent-eval.exe --runs 2

Исходный архив и wheel собираются в dist/; каталог намеренно не хранится в Git.

Полный процесс обработки

Команда support-agent-workflow запускает LangGraph с сохраняемыми контрольными точками поверх тех же сервисов, которые опубликованы как MCP-инструменты:

# Один тикет или вся очередь новых тикетов
uv run support-agent-workflow start 3
uv run support-agent-workflow poll --limit 10

# Состояние после рестарта процесса
uv run support-agent-workflow status 3

# Безопасная хронология метаданных контрольных точек и инструментов без содержимого заявки
uv run support-agent-workflow trace 3

# Возобновление ожидания пользователя или инженера
uv run support-agent-workflow user <ticket-id> "Уточнённые симптомы"
uv run support-agent-workflow engineer <ticket-id> "Подтверждённое решение" --author l2 --confirmed

Одна заявка всегда использует идентификатор потока support-ticket:<ticket-id>. Контрольные точки хранятся в SQLite, а все записи в заявки, Telegram, GitHub и черновики дополнительно защищены стабильными ключами идемпотентности. Поэтому восстановление контрольной точки и повтор узла не создают дубликаты побочных действий.

Воспроизводимая демонстрация

support-agent-demo запускает пять синтетических E2E-сценариев в отдельном каталоге, не затрагивая обычный data/runtime/agent.sqlite3:

uv run support-agent-demo
uv run support-agent-demo --run-id interview-demo

Покрыты ответ из KB, эскалация L2 и одноразовое решение, отчёт об ошибке и переиспользуемое решение, уточнение пользователя с повторной классификацией, низкая уверенность и safe_review. Завершённый запуск повторно читает сохранённый demo-report.json; незавершённый каталог с тем же ID не перезаписывается. В отчёте есть фазы, количество контрольных точек и событий аудита, но нет текстов заявок и содержимого вызовов инструментов.

Проверка

uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest --cov --cov-report=term-missing
uv run support-agent-eval --runs 3 --output data/runtime/evaluation.json
uv run support-agent-eval --case-id http-500-software-bug

GitHub Actions проверяет форматирование, Ruff, строгий mypy, pytest с покрытием ветвей и стабильность тестового провайдера на Python 3.10 и 3.13. Отдельное задание собирает sdist/wheel, устанавливает wheel вне исходного репозитория и запускает оценку качества, демонстрацию и CLI процесса. Проверка через LM Studio не входит в CI, потому что требует локальную модель; её зафиксированный прогон описан ниже.

Тесты используют официальный MCP-клиент в памяти и отдельно запускают точку входа stdio. Оценка качества прогоняет 20 подготовленных бизнес-сценариев классификации и решения через выбранный LLM_PROVIDER, измеряет время каждого сценария и всего запуска; по умолчанию используется воспроизводимый провайдер на основе правил.

Из 20 сценариев 13 помечены как safety_critical. Критерий качества выполнен, только если доля успешных попыток не ниже 90%, все критические попытки успешны, ошибки провайдера и схемы отсутствуют, а повторные запуски каждого сценария дают одинаковый смысловой результат. --runs 3 проверяет не 20, а 60 попыток; хэш исходного набора сохраняется в JSON-отчёте.

Первичная классификация и база знаний

Первичная классификация возвращает строгий TriageDecision: достаточность и перечень недостающих фактов, категорию, приоритет, маршрут, оценку уверенности (confidence), извлечённые факты и флаги риска. После ответа модели детерминированная политика отдельно проверяет:

• недостаток фактов — запросить конкретное уточнение;
• низкую уверенность при достаточных фактах — safe_review;
• модельный priority — нормализовать независимой бизнес-политикой по явным признакам;
• инъекцию инструкций — проигнорировать и отметить флагом;
• лимит уточнений — передать в безопасную очередь исключений.

Поиск в KB выполняется до эскалации. Автоматический ответ разрешён только при совпадении категории, порога релевантности и отсутствии exclusions статьи. Ответ состоит из текста статьи и обязательной ссылки KB:<article_id>; свободной генерации решения нет.

Проверенные ответы пользователя не теряются после повторной классификации: они участвуют в поиске и проверке применимости статьи, добавляются в выжимку для L2, отчёт об ошибке и контекст будущего черновика статьи. Telegram-эскалация и GitHub Issue всегда содержат ссылку на исходную заявку, построенную от настроенного TICKETS_API_URL.

LM Studio

Адаптер LM Studio уже реализован через совместимый с OpenAI строго структурированный ответ:

LLM_PROVIDER=lmstudio
LLM_BASE_URL=http://127.0.0.1:1234/v1
LLM_MODEL=google/gemma-4-12b-qat
LLM_API_KEY=
LLM_REASONING=none

После запуска локального сервера выбранную модель можно проверить командой uv run support-agent-eval. google/gemma-4-12b-qat Q4_0 прошла текущий набор 20/20 за 74,9 секунды и E2E-демонстрацию 5/5 за 22,9 секунды при контексте 13 056 токенов. Провайдер на основе правил остаётся безопасным значением по умолчанию для тестов и воспроизводимой демонстрации. Подробнее: проверка LM Studio.

MCP-инструменты

Группа	Инструменты
Заявки	tickets_list_new, tickets_get, tickets_update_classification, tickets_add_reply, tickets_change_status
База знаний	knowledge_search, knowledge_get_article, knowledge_create_draft
Эскалация	telegram_notify_l2, github_create_bug
Обратная связь	feedback_add, feedback_list

Входные и выходные JSON Schema формируются MCP SDK из строгих Pydantic-моделей. Все изменяющие инструменты требуют стабильный idempotency_key, журналируются в SQLite и имеют соответствующие MCP annotations. knowledge_create_draft создаёт только черновик со статусом pending_human_review; инструмента автоматической публикации намеренно нет.

Данные и безопасность

• TICKET_SOURCE=fixture — воспроизводимый режим по умолчанию.
• TICKET_SOURCE=remote — чтение публичного MockAPI без права записи.
• ALLOW_REMOTE_WRITES=false — зарезервированный явный предохранитель; текущий адаптер вообще не реализует удалённые записи.
• data/runtime/ — SQLite, локальные изменения, исходящие сообщения и тестовые Issues; каталог исключён из Git.
• data/knowledge_base/ — опубликованные тестовые статьи, которые входят в репозиторий.
• data/fixtures/ — зафиксированные входные данные для тестов.
• data/demo/ — пять синтетических заявок для изолированной E2E-демонстрации.
• trace намеренно возвращает только метаданные. Полное состояние контрольной точки остаётся локально в SQLite и должно защищаться как рабочие данные поддержки.

Документы

• Финальная архитектура
• Устройство проекта и руководство по защите
• ADR-001: управляемый процесс и модульный MCP-сервер
• Контракты домена
• Правила первичной классификации и маршрутизации
• Отчёт по этапу 1
• Отчёт по этапу 2
• Отчёт по этапу 3
• Отчёт по этапу 4
• Отчёт по этапу 5
• Отчёт по этапу 6
• Отчёт по этапу 7
• Сценарий демонстрации и сдачи
• Проверка модели в LM Studio
• ADR-002: LangGraph и сохраняемые контрольные точки

Проект распространяется по лицензии MIT. Правила безопасного сообщения об уязвимостях описаны в SECURITY.md.

Машиночитаемые контракты

• Нормализованная заявка
• Результат первичной классификации
• Кандидат в базу знаний

Локальный снимок данных находится в data/fixtures/tickets.snapshot.json. Он используется для воспроизводимых тестов; удалённый MockAPI рассматривается как источник только для чтения.