ai-l1-support-agent
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ai-l1-support-agent Triage ticket #1024 and suggest next step from the knowledge base"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: helpdesk-mcp-server
Установка собранного пакета
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-bugGitHub 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-инструменты
Группа | Инструменты |
Заявки |
|
База знаний |
|
Эскалация |
|
Обратная связь |
|
Входные и выходные 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 и должно защищаться как рабочие данные поддержки.
Документы
Проект распространяется по лицензии MIT. Правила безопасного сообщения об уязвимостях описаны в SECURITY.md.
Машиночитаемые контракты
Локальный снимок данных находится в data/fixtures/tickets.snapshot.json. Он используется
для воспроизводимых тестов; удалённый MockAPI рассматривается как источник только для чтения.
Available Tools
12 toolsfeedback_addAdd a feedback eventAIdempotent
Add a mock user, L2 or developer response linked to the original ticket.
Inputs: request (required). Returns: event, replayed
feedback_listList ticket feedbackARead-only
List mock user and engineer responses for a ticket in chronological order.
Inputs: ticket_id (required). Returns: count, events, ticket_id
github_create_bugCreate a developer bug reportAIdempotent
Create a linked mock GitHub Issue without inventing missing logs or context.
Inputs: request (required). Returns: url, issue_id, replayed, ticket_id, +2 more
knowledge_create_draftCreate a knowledge draftAIdempotent
Create a local create/update draft that cannot bypass human review.
Inputs: request (required). Returns: path, draft_id, replayed, ticket_id, +2 more
knowledge_get_articleRead a knowledge articleARead-only
Read one published knowledge article by its stable ID.
Inputs: article_id (required). Returns: body, path, title, category, +4 more
knowledge_searchSearch the support knowledge baseARead-only
Search published Markdown articles by title, keywords and body tokens.
Inputs: query (required), limit, category. Returns: count, query, results
telegram_notify_l2Notify L2 supportAIdempotent
Write a concise L2 escalation into the mock Telegram outbox.
Inputs: request (required). Returns: replayed, ticket_id, message_id, destination, +1 more
tickets_add_replyReply to a ticketAIdempotent
Add a local mock reply and either wait for the user or close the ticket.
Inputs: message (required), ticket_id (required), idempotency_key (required), close_ticket. Returns: status, replayed, ticket_id, idempotency_key
tickets_change_statusChange effective ticket statusAIdempotent
Change status in the local overlay; the public MockAPI remains untouched.
Inputs: status (required), ticket_id (required), idempotency_key (required). Returns: status, replayed, ticket_id, idempotency_key
tickets_getGet a support ticketARead-only
Get one source ticket with local agent classification, replies and status overlay.
Inputs: ticket_id (required). Returns: Ticket with local overlay data applied.
tickets_list_newList new support ticketsARead-only
List tickets whose effective status is Новая, oldest first.
Inputs: limit. Returns: count, tickets
tickets_update_classificationStore agent classificationAIdempotent
Persist agent classification locally without rewriting source labels.
Inputs: category (required), priority (required), ticket_id (required), confidence (required), +1 more. Returns: category, priority, replayed, ticket_id, +2 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool targets a distinct action within its domain: ticket management, knowledge lookup, notification, bug creation, and feedback. The descriptions clearly differentiate overlapping concepts like tickets_add_reply vs feedback_add and update_classification vs change_status.
Tools largely follow a domain_verb_noun pattern (tickets_add_reply, knowledge_get_article, github_create_bug). Minor exceptions like feedback_add/feedback_list (implicit object) and tickets_list_new (adjective instead of noun) create slight inconsistency but remain predictable.
The 12 tools cover a well-scoped support agent workflow: ticket triage, knowledge access, escalation, bug reporting, and feedback. The count is within the ideal range and each tool serves a clear purpose.
Core ticket operations are covered, but there is no way to list tickets by status other than 'new', which prevents the agent from resuming work on in-progress or waiting tickets. Knowledge draft creation exists without management (list/update), leaving an incomplete workflow.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Build and manage AI-native customer support agents from Claude or any MCP client.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Related MCP Servers
- AlicenseCqualityDmaintenanceMCP server that exposes the complete Libredesk REST API (54 endpoints) as tools, enabling natural language management of conversations, contacts, agents, teams, and more for the open-source customer support desk.544MIT
- FlicenseNot gradedqualityDmaintenanceAn AI IT support agent that enables natural language interaction with IT helpdesk operations, including knowledge base search, ticket querying, password reset, and escalation, powered by LangGraph and MCP.-
- FlicenseNot gradedqualityCmaintenanceAn AI-native incident response server that exposes diagnostic tools (system status, error logs, ticket creation) via MCP, enabling LLM agents to autonomously assess and respond to incidents.-
- FlicenseNot gradedqualityDmaintenanceMCP server that triages GitHub issues by classifying, ranking priority, and assigning an engineer using a local LLM (Ollama) with full traceability.-