Как Harness Engineering связан с наблюдаемостью (OpenTelemetry, LangSmith, трассировка)?

Краткий тезис

Harness Engineering — это архитектурный слой, отвечающий за управление агентами и их жизненным циклом. В агентных RAG-системах наблюдаемость (observability) критична, так как каждый шаг агента (мысль, действие, наблюдение) может быть недетерминирован и дорог. Harness предоставляет встроенные компоненты TraceManager, CostTracker, Logger и MetricsPort, которые интегрируются с OpenTelemetry (стандарт сбора трассировок и метрик) и LangSmith (платформа мониторинга LLM), обеспечивая полную прозрачность работы агентов, контроль затрат и быструю отладку.

1. Термин: Harness Engineering (слой управления агентами)

Harness Engineering — это шестой слой в архитектуре RAG|Agentic RAG (harness-one/observe), который отвечает за координацию, планирование, выполнение и наблюдаемость агентов. Он включает:

• Оркестрацию шагов (последовательность thought → action → observation);
• Управление состоянием (history|conversation history, контекст);
• Интеграцию с инструментами (API, базы знаний, калькуляторы);
• Наблюдаемость — встроенные механизмы для сбора метрик, трассировок и логов.

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

2. Почему наблюдаемость важна именно для агентов

В отличие от простого RAG (один запрос → один ответ), агентные системы выполняют несколько раундов внутренних шагов. Проблемы:

• Детерминизм: LLM может каждый раз генерировать разные цепочки мыслей.
• Стоимость: каждый шаг потребляет токены, если агент зациклится — расходы взлетят.
• Время: длинные цепочки замедляют ответ.
• Отладка: без трассировки невозможно воспроизвести поведение агента.

Наблюдаемость (observability) решает эти проблемы, предоставляя три столпа: метрики (счётчики, гистограммы), логи (структурированные записи событий) и трассировки (распределённый трейс шагов агента).

3. Компоненты observability в Harness

Harness включает четыре модуля наблюдения, которые работают как единая система:

Все модули объединены общей конфигурацией (например, имя сервиса, эндпоинт экспорта).

4. TraceManager: трассировка шагов агента

TraceManager — ядро наблюдаемости. Он создаёт распределённый трейс для каждого запроса пользователя, где каждый шаг агента — это span.

Пример структуры трейса:

Trace: "Ответь на вопрос: какой сегодня курс USD?"
  ├── Span: "agent_run" (id=req_123)
  │   ├── Span: "thought_1"  (LLM вызов для выбора действия)
  │   │   └── Attributes: prompt_tokens=150, response_tokens=30
  │   ├── Span: "action_1"   (вызов внешнего API)
  │   │   └── Attributes: endpoint="currency-api", latency_ms=210
  │   └── Span: "observation_1" (обработка результата API)
  │       └── Status: OK
  ├── Span: "thought_2"  (LLM вызов для генерации финального ответа)
  │   └── ...
  └── Span: "final_answer" (вывод пользователю)

TraceManager автоматически проставляет parent-child связи, сохраняет входные/выходные параметры (контекст, промпты, ответы LLM) и время выполнения. Эти данные можно экспортировать в OpenTelemetry Collector или напрямую в LangSmith.

5. CostTracker: учёт токенов и бюджетирование

CostTracker интегрируется с каждым вызовом LLM (через провайдеров OpenAI, Anthropic, локальные модели). Он:

• Фиксирует количество токенов (входных и выходных) на каждом шаге;
• Умножает на стоимость за токен (настраивается в конфиге);
• Суммирует стоимость за сессию, день, пользователя;
• Генерирует алерты при превышении лимитов (например, более 1$ за один запрос).

Метрики передаются в MetricsPort и отображаются в дашборде Grafana с панелями «Стоимость за последние 24 часа», «Средняя стоимость на запрос», «Топ дорогих агентов».

Пример алерта (Prometheus rule):

- alert: HighCostPerSession
  expr: sum(harness_cost_total{session="current"}) > 0.5
  for: 1m
  labels:
    severity: warning

6. Logger: структурированное логирование

Logger форматирует все события в JSON, что упрощает парсинг и поиск. Пример записи:

{
  "timestamp": "2025-04-10T12:34:56.789Z",
  "level": "INFO",
  "trace_id": "req_123",
  "message": "Thought step completed",
  "agent_step": 1,
  "llm_model": "gpt-4o",
  "tokens_used": 180,
  "duration_ms": 450
}

Уровни:

• DEBUG — полный вывод промптов (только при отладке);
• INFO — обычные шаги, вызовы инструментов;
• ERROR — ошибки LLM, таймауты, некорректные наблюдения.

Логи можно отправлять в ELK Stack (Elasticsearch, Logstash, Kibana) или Loki (Grafana Loki) для полнотекстового поиска и построения дашбордов.

7. MetricsPort: экспорт метрик в Prometheus/OpenTelemetry

MetricsPort — встроенный HTTP-сервер (обычно на порту 8080/metrics), который отдаёт метрики в формате OpenTelemetry (protobuf) или Prometheus (text). Основные метрики:

Эти метрики можно визуализировать в Grafana, настроить алерты на аномалии.

8. Интеграция с OpenTelemetry

OpenTelemetry (OTel) — открытый стандарт для сбора телеметрии. Harness использует OTel SDK для автоматического создания spans и метрик. Преимущества:

• Vendor-agnostic: можно экспортировать в Jaeger, Zipkin, Datadog, New Relic;
• Контекстная передача: trace_id пробрасывается через все вызовы (включая асинхронные);
• Семплинг: для снижения нагрузки можно собирать только 10% трассировок.

Настройка в конфиге Harness (YAML):

observe:
  opentelemetry:
    endpoint: "otel-collector:4317"
    sampler: "parentbased_traceidratio"
    sampler_ratio: 0.1

9. Интеграция с LangSmith

LangSmith — платформа для наблюдения и отладки LLM-приложений от LangChain. Harness может отправлять:

• Трассировки (runs) — каждый шаг агента становится отдельным run с промптом, ответом, длительностью;
• Метрики (feedback) — оценка ответа (LMM-as-judge);
• Стоимость — автоматически рассчитывается, если указана модель;
• Сравнение агентов — A/B тестирование разных конфигураций.

LangSmith даёт дашборды для анализа, поиск по runs и экспорт данных. В Harness достаточно указать API-ключ LangSmith:

observe:
  langsmith:
    api_key: "ls_..."
    project: "harness-agent-v2"

10. Как observability помогает в отладке и оптимизации агентов

Реальные сценарии использования:

1. Обнаружение зацикливания: если агент делает 20+ шагов на один запрос, алерт в Grafana сигнализирует о проблеме. TraceManager показывает, на каком шаге он застрял (повторяющийся thought).
2. Утечка контекста: Logger уровня DEBUG показывает, что в контекст попало слишком много истории → увеличивается количество токенов → CostTracker фиксирует рост стоимости.
3. Сравнение провайдеров: MetricsPort показывает, что модель A дороже, но точнее — можно принять решение о замене.
4. Отладка ошибок инструмента: TraceManager сохраняет ответ API — видно, что инструмент вернул 500 ошибку, и агент некорректно обработал это.

Пет-проект для закрепления

Задача: Реализовать простого агента, который отвечает на вопросы о погоде, и подключить к нему модуль наблюдаемости из Harness (имитация).

Инструменты: Python, LangChain, OpenTelemetry SDK, LangSmith (бесплатный тариф), Prometheus + Grafana (локально через Docker).

Шаги:

1. Создать агента на LangChain с инструментом get_weather(city).
2. Добавить в код декораторы для трассировки через OpenTelemetry: обернуть каждый шаг (thought, action) в span.
3. Настроить экспорт в OTel Collector (Jaeger для визуализации трассировок).
4. Подключить LangSmith: установить langsmith, передать LANGCHAIN_TRACING_V2=true при запуске.
5. Добавить логирование в формате JSON с помощью библиотеки structlog.
6. Запустить Prometheus для сбора метрик (счётчики шагов, токенов) и Grafana для дашборда.
7. Протестировать: задать агенту несколько вопросов, отследить трейс в Jaeger, найти самый дорогой запрос в LangSmith, построить график количества шагов в Grafana.

Ожидаемый результат: Работающий агент с дашбордом Grafana, показывающим latency и стоимость, возможность просмотреть трейс каждого запроса в Jaeger и проанализировать runs в LangSmith.

Связь с другими вопросами

Навигация

• Предыдущий: 753
• Следующий: 755
• Индекс: 00. Индекс разборов