TowerWatch Ops Agent

Агентский слой поверх TowerWatch — проекта мониторинга качества сети — созданный для демонстрации трёх возможностей, необходимых корпоративному циклу разработки агентов: наборы для оценки, выбор модели с учётом стоимости и задержки и поиск инструментов. Один репозиторий, одна целостная история:

«Я взял свой публичный проект мониторинга и построил вокруг него агентский слой, который понадобился бы предприятию: инструментированный MCP-сервер с определёнными SLI, eval-харнесс в CI, ловящий посеянные регрессии, маршрутизатор моделей с учётом стоимости и семантический поиск инструментов с измеренной точностью выбора».

Вкратце

• Среда выполнения: Python 3 + FastMCP, управляется через uv.

• Предметная область: данные мониторинга сети TowerWatch, предоставляемые как инструменты агента.

• Транспорт: в первую очередь stdio; не имеющий состояния потоковый HTTP как цель повышенной сложности.

• Наблюдаемость: OpenTelemetry с первого вызова инструмента, в стек Prometheus/Grafana.

• Поверхность инструментов: семь инструментов — query_metrics, analyze_window, compare, query_log_events, get_monitor_status, get_runbook, run_speedtest. Контракты — в docs/design/.

• Статус: 🟡 Фаза 1 в процессе — сервер запускается, и один из семи инструментов реализован; пока не выполнен ни один критерий приёмки фазы 1. См. Статус.

Зачем этот проект

Он заполняет разрыв между «я читал про оценку и маршрутизацию агентов» и «я построил это и измерил». Каждый артефакт — таблицы eval, числа бенчмарков, графики precision@k — это лично собранные числа, а не утверждение из исследования. Предметная область — реальные данные проекта, которым автор уже владеет, так что история звучит как «я расширил свою собственную систему в продакшн-стиле», а не «я прошёл туториал».

Сборка выполняется в соответствии с собственными Agent Collaboration Principles автора: определение готовности каждой фазы — это набор независимо проверяемых артефактов: команда, которая выполняется, файл, который существует, дашборд, который отображается. Никаких «поверьте мне, это работает».

Related MCP server: production-grade-mcp-agentic-system

Три фазы

Проект — это одна сборка в трёх строго последовательных фазах. Полные спецификации находятся в docs/specs/; план сборки — это индекс. Требования были определены заранее в процессе планирования и реализованы как контракт — сначала появились спецификации, из них были выведены контракты инструментов, а ADR фиксируют каждое решение, определившее поверхность.

Последовательность строгая: eval'ы фазы 2 оценивают маршрутизатор фазы 3. Не меняйте порядок. Сквозной слой — исключение: он добавляется инкрементально и ничего не блокирует.

Структура репозитория

towerwatch-ops-agent/
├── README.md                       # this file — human-facing
├── CLAUDE.md                       # agent-facing anchor (read first if you're an agent)
├── pyproject.toml                  # PEP 621 single source of truth — deps, tooling config
├── docs/
│   ├── architecture.md             # intended shape (stub — not built yet)
│   ├── specs/                      # the governing build plan + 4 requirement specs
│   ├── design/                     # locked tool contracts (00–11) — authoritative
│   ├── adr/                        # architecture decision records
│   └── production-path.md          # personal-scale choices vs. enterprise needs
├── src/towerwatch_ops_agent/       # server, config, domain/, tools/, telemetry/
├── tests/                          # pytest suite — 95 tests
├── fixtures/stub/                  # hand-authored stub corpus (not the real one)
└── RATIONALE.md                    # deliberate choices that read as defects

Быстрый старт

Сервер запускается и обслуживает query_metrics. Остальные шесть инструментов ещё не реализованы.

# From repo root. uv manages the environment and lockfile.
uv sync                            # create .venv, install deps from pyproject.toml
uv run python -m towerwatch_ops_agent   # (Phase 1) launch the MCP server over stdio

Для интерактивного тестирования сервера (фаза 1) используется MCP Inspector:

npx @modelcontextprotocol/inspector uv run python -m towerwatch_ops_agent

Статус

🟡 Фаза 1 в процессе. MCP-сервер работает через stdio и обслуживает query_metrics от начала до конца на фикстуре. Пока не выполнен ни один из пяти критериев приёмки фазы 1 — список гейтов см. в spec-phase1-mcp-server.md.

Реализовано и работает:

• Каркас каталогов, pyproject.toml, .gitignore, лицензия MIT

• README, CLAUDE.md (с обязательными инвариантами), заглушка архитектуры

• План сборки и все четыре спецификации требований в docs/specs/

• Зафиксированные контракты инструментов — docs/design/ 00–11: соглашения, документация семи инструментов, интерфейсы навыков, схема спанов, манифест фикстур, дизайн eval

• ADR — docs/adr/, решения, стоящие за поверхностью инструментов

• MCP-сервер + корень композиции — server.py, config.py, stdio-транспорт

• query_metrics — 1 из 7 инструментов, с обязательным конвертом data_status

• FixtureClient + загрузчик манифеста — шов двойного режима из ADR-0002, только сторона фикстур

• Инструментирование спанов — один спан на вызов инструмента, секреты структурно исключены

• CI-воркфлоу — ruff, format, pyright, pytest на каждой голове ветки PR

• RATIONALE.md — осознанные решения, которые ревьюер иначе отметил бы как дефекты

Отложено (ещё не реализовано — см. CLAUDE.md о гейтах фаз):

• Оставшиеся шесть инструментов — analyze_window, compare, query_log_events, get_monitor_status, get_runbook, run_speedtest

• GrafanaCloudClient — «живая» половина протокола DataClient

• Курируемый корпус фикстур — fixtures/stub/ — это авторская заглушка из двух окон, доказывающая только формат, а не реальный детерминированный корпус

• OTel-экспортёр + SLI-дашборд — спаны создаются, но никуда не отправляются; нет MeterProvider, поэтому нет гистограмм длительности

• def_tokens.md — измерение токенного бюджета определений инструментов (скрипт существует, но ни разу не запускался)

• bench.md — крос-модельный бенчмарк стоимости/задержки

• Фаза 2 — eval-харнесс + CI + демонстрация посеянной регрессии

• Фаза 3 — маршрутизатор моделей + семантический поиск инструментов

• Навыки внутри репозитория в .claude/skills/ — diagnose-rca, evidence-pack, плюс навыки golden-path (add-tool, run-evals), созданные при первом ручном прохождении

• Измеряемый онбординг-eval (docs/onboarding-eval.md) — первый запуск после фазы 1

Для AI-ассистентов

Если вы агент, работающий в этом репозитории, сначала прочтите CLAUDE.md. В нём содержатся последовательность фаз, рабочий стандарт stateless-гейтов и явная карта того, что существует, а что ещё заглушка, чтобы вы не рассуждали о коде, которого пока нет. RATIONALE.md фиксирует осознанные решения, которые с первого взгляда выглядят как дефекты, — прочтите его, прежде чем сообщать о таком.