Observability агента: traces, spans, tool calls и разбор отказов

Короткий ответ

Observability агента: traces, spans, tool calls и разбор отказов — это production-задача, а не демонстрационный prompt. Практический принцип: собирать end-to-end trace, чтобы восстановить модельные вызовы, tools, handoffs, latency, ошибки и approvals. Ключевое решение: без трассировки невозможно отличить ошибку retrieval от ошибки выбора tool, неправильного параметра или сбоя внешней системы. В инженерной среде результат принимается по evidence, traceability и воспроизводимой проверке, а не по уверенности формулировки модели.

Agent/RAG-платформы быстро меняются. Технические ссылки этой статьи проверены 02.10.2026; перед внедрением перепроверяются статусы API, preview/GA, лимиты, хранение данных и доступность функций.

Граница системы и предмет контроля

Агентный контур отличается от обычного чата наличием цикла действий. Модель не только формирует текст, но выбирает инструмент, передаёт типизированные аргументы, получает результат, обновляет состояние и решает, требуется ли следующий шаг. Поэтому объект проектирования — не prompt как строка, а полный runtime: модель, tools, permissions, state, approvals, verifier и журнал выполнения.

Для инженерного применения критично отделять рассуждение и предложение действий от изменения реальных данных. Чтение справочника, расчёт в детерминированном модуле, создание рабочей копии CAD-файла и выпуск утверждённой ревизии имеют разный риск. Права должны назначаться по операциям, а не по факту того, что «агенту нужен доступ к системе». Это позволяет увеличивать полезную автономность без потери управляемости.

Рабочее правилобез трассировки невозможно отличить ошибку retrieval от ошибки выбора tool, неправильного параметра или сбоя внешней системы. Это правило должно быть закреплено в runtime policy, а не существовать только как рекомендация пользователю.

Что должно быть определено до запуска

workflow IDФиксируется явно, имеет owner и проходит валидацию до использования в следующем шаге.

model callsВерсионируется как технический контракт; изменения проходят совместимость и regression до production.

tool callsВерсионируется как технический контракт; изменения проходят совместимость и regression до production.

handoffsФиксируется явно, имеет owner и проходит валидацию до использования в следующем шаге.

guardrail eventsФиксируется явно, имеет owner и проходит валидацию до использования в следующем шаге.

latency and usageОпределение, единица, denominator и период измерения фиксируются до сравнения вариантов.

Артефакты и архитектурные границы

Архитектуру агента удобно раскладывать на control plane и execution plane. В control plane находятся policy, identity, лимиты, approvals и выбор маршрута; в execution plane — конкретные tools, очереди, sandbox и внешние API. Такое разделение не даёт модели самостоятельно расширять собственные полномочия и позволяет независимо версионировать orchestration и исполнительные компоненты.

Контракт tool должен быть строже естественного языка: схема аргументов, единицы, enum, обязательность полей, idempotency key, ожидаемые ошибки и postcondition. Если инструмент меняет реальный объект, ответ «200 OK» недостаточен — нужен change receipt и повторное чтение состояния либо другой независимый verifier.

traceEvidence для аудита и сравнения версий; по нему восстанавливается фактическое выполнение.

span treeИмеет стабильный идентификатор, статус приёмки и связь с исходной задачей.

error eventИмеет стабильный идентификатор, статус приёмки и связь с исходной задачей.

cost recordEvidence для аудита и сравнения версий; по нему восстанавливается фактическое выполнение.

incident replay packetИмеет стабильный идентификатор, статус приёмки и связь с исходной задачей.

Практический workflow

Шаг 1. назначить workflow identifiers. Сначала исключите неоднозначность цели: агент не должен сам изобретать критерий завершения.

Шаг 2. включить spans для ключевых шагов. Tool contract валидируется отдельно от prompt и имеет тесты на неверные аргументы.

Шаг 3. логировать tool inputs/outputs безопасно. Write-операции отделяются отдельным permission и не наследуются от read-доступа.

Шаг 4. связать ошибки с taxonomy. Checkpoint сохраняет уже выполненные side effects и контекст следующего шага.

Шаг 5. добавить dashboards. Verifier должен быть независим от генеративного утверждения, где это возможно.

Шаг 6. создать процедуру incident replay. Trace должен позволять восстановить последовательность действий без чтения скрытого reasoning.

Шаг 7. использовать traces в regression evals. До повышения прав версия обязана пройти regression и негативные cases.

После tool-call проверяется не текстовый комментарий модели, а фактический результат инструмента: код возврата, схема ответа, изменённый объект и ожидаемая postcondition. Несовпадение переводит задачу в controlled exception и блокирует следующий side effect.

Инженерный сценарий

Входworkflow ID; model calls; tool calls; handoffs; guardrail events; latency and usage. Данные должны быть привязаны к проекту, revision и владельцу.

Действиесобирать end-to-end trace, чтобы восстановить модельные вызовы, tools, handoffs, latency, ошибки и approvals. Каждый tool-call проходит серверную валидацию и попадает в trace.

Контрольcorrelation ID через весь workflow; редакция чувствительных данных; единые error codes; метрики по шагам; связь trace с итоговым артефактом. Для критических изменений добавляется независимое подтверждение.

Выходtrace; span tree; error event; cost record; incident replay packet. Финальный результат должен быть пригоден для повторной проверки без скрытого контекста.

Для agent workflow удобно иметь три режима: dry-run без side effects, execute-with-approval и bounded execution. Переход между ними определяется классом риска и зрелостью eval-набора.

Что измерять

trace coverageФиксируйте numerator/denominator и сегментируйте по типу/сложности задач; общий процент может скрыть critical slice.

p50/p95 latencyСмотрите распределение, минимум median и p95; отдельно выделяйте timeout/длинный хвост.

tool error rateПоказывайте абсолютное число и нормированную частоту; critical события не усредняйте с обычными.

mean time to diagnoseСмотрите распределение, минимум median и p95; отдельно выделяйте timeout/длинный хвост.

cost per successful taskНормируйте на успешную задачу требуемого качества и включайте review/support, а не только runtime.

Для агента итоговая точность без анализа траектории недостаточна. Одновременно контролируют success, выбор tools, число шагов, вмешательства человека, policy violations, latency и стоимость успешной задачи.

Критерии приёмки

Контроль	Минимальный критерий
Scope	Для «Observability агента: traces, spans, tool calls и разбор отказов» однозначно определено, что система делает и что остаётся вне её полномочий.
Data	Все входы имеют источник, revision/status и область применимости; неизвестные значения не подставляются автоматически.
Control	correlation ID через весь workflow; редакция чувствительных данных; единые error codes.
Evidence	Сохраняются trace, span tree, error event, cost record; по ним можно восстановить ход операции.
Quality	Минимум две профильные метрики контролируются на versioned eval-наборе: trace coverage и p50/p95 latency.
Release	Изменяющие действия имеют approval/rollback там, где цена ошибки выходит за согласованный риск.

Failure modes и защитные меры

Главная ошибка — считать правильный финальный ответ доказательством правильной траектории агента. В production проверяются выбранные tools, аргументы, approvals, фактические side effects и postconditions.

логи содержат секреты. Защитная мера: correlation ID через весь workflow; событие сохраняется как regression/incident case.
есть только финальный ответ без шагов. Защитная мера: редакция чувствительных данных; событие сохраняется как regression/incident case.
ошибки внешних API теряются. Защитная мера: единые error codes; событие сохраняется как regression/incident case.
нет связи версии prompt с trace. Защитная мера: метрики по шагам; событие сохраняется как regression/incident case.
нельзя воспроизвести инцидент. Защитная мера: связь trace с итоговым артефактом; событие сохраняется как regression/incident case.

Как переводить из пилота в production

Пилотный агент получает один класс задач и минимальный набор tools. Сначала снимаются traces в read-only/dry-run, затем добавляются approvals для side effects. Model upgrade и изменение tool schema проходят один и тот же regression suite; несовместимый schema change блокирует rollout.

Перед выдачей write-доступа отдельно тестируют timeouts, retry, duplicate delivery, partial failure и отмену задачи. Canary-версия получает ограниченную долю трафика и budget; превышение intervention/rollback threshold автоматически возвращает стабильную версию.

Traceability и эксплуатационная запись

Минимальный trace: task ID, actor identity, model/runtime, prompt/template, список доступных tools, каждый tool-call с аргументами и результатом, policy decision, approval, state transition, verifier и final status.

Чек-лист перед production

КонтрактScope, входы, tools и stop condition описаны до запуска.

ПраваRead/write, сеть и секреты ограничены минимально необходимым.

EvidenceКаждый критичный вывод или action связан с источником и trace.

EvalsЕсть обычные, граничные, негативные и regression cases.

RollbackДля side effect проверено восстановление, а не только наличие команды отката.

OwnerНазначен владелец качества процесса и владелец технической платформы.

Навигация по Wave AI R5 · часть 1 из 5

Часть «Агенты» содержит 7 связанных материалов. Серия идёт от архитектуры к контролю и измерению; каждая статья самостоятельна и ссылается на соседние элементы общего production-контура.

1. ИИ-агент в инженерной системе: runtime, tools, state и verifier 2. Один агент или multi-agent: как выбирать архитектуру без лишней оркестрации 3. Tool calling для инженера: типизированные контракты вместо «сделай что-нибудь»4. MCP и корпоративные инструменты: как подключать агент к системам без бесконтрольного доступа 5. Память агента: session state, проектный контекст и долгоживущие знания 6. Human-in-the-loop: где ставить approval gates в инженерном агенте 7. Observability агента: traces, spans, tool calls и разбор отказов

← Human-in-the-loop: где ставить approval gates в инженерном агенте RAG для инженерной документации: полная архитектура от источника до цитаты →R4: Decision log и traceability

Связать AI-контур с проверяемыми данными Fits Calc

Fits Calc целесообразно использовать как детерминированный расчётный и справочный слой: агент получает структурированные входы и результаты через контролируемые tools, а не воспроизводит инженерный расчёт свободным текстом. Это упрощает verifier, traceability и повторную проверку.

Открыть Fits Calc →

Источники и официальная документация

Проверено: 02.10.2026Production controls обязательныHuman approval — по риску действия