Cloudflare Agents: трассировка, просмотр сессий и подтверждение действий

Cloudflare Agents — раздел Cloudflare Dashboard для наблюдения за агентами, в которых настроена трассировка. По состоянию на 3 октября 2026 года в нём доступны сведения о моделях, сессиях, запусках, расходе токенов и агентных трассах. Материал показывает, как читать Session replay и Trace, включать трассировку (tracing), настраивать запись содержимого и проверять подтверждение действий.

Материал предназначен для разработчика уже работающего агента. Понадобятся доступ к Wrangler-конфигурации и телеметрии, знакомство с HTTP и безопасное тестовое действие. Tracing — запись измеряемых операций; replay в интерфейсе здесь означает просмотр сохранённой сессии. Политика доступа и подтверждения действий остаётся частью вашего приложения.

Компоненты вокруг Agent tracing

Эти компоненты работают на разных уровнях и закрывают разные задачи.

Agent tracing строится через автоматическую интеграцию или custom spans и отображается рядом с runtime-событиями в Workers traces. Think и Flue — готовые каркасы агента — автоматически записывают ходы. Прямые вызовы AI SDK и собственный цикл исполнения (harness) требуют дополнительной настройки. Полная Workers trace может включать операции SDK и другие операции Worker, которых нет в агентном представлении.

graph LR
    A[Пользователь или событие] --> B[Агент]
    B --> C[Модель]
    B --> D[Инструменты и внешние API]
    B --> E[Workflows]
    B --> H[Поддерживаемая интеграция или custom spans]
    H --> I[Workers tracing]
    I --> G[Agents в Dashboard]

Что показывает раздел Agents

Вкладка Agents в Cloudflare Dashboard группирует трассы агентов и субагентов. В обзоре для каждого агента доступны модель, число сессий и запусков, а также общий расход токенов. Для отдельной трассы показываются продолжительность, статус и разбивка токенов.

Сессия состоит из одного или нескольких ходов. Ход, или turn, — один запрос к агенту и его ответ.

Для диагностики используются два представления: Session replay и Trace.

Session replay восстанавливает записанный контекст

Session replay показывает записанную историю разговора по нескольким ходам, включая сообщения, рассуждения, вызовы инструментов и работу субагентов. Состав данных зависит от настроек записи содержимого.

Это просмотр сохранённых данных. Представление не запускает новый ход агента и не вызывает инструменты заново.

Session replay помогает выяснить:

• какой контекст был у модели перед выбором инструмента;
• почему задача была передана субагенту;
• откуда появился некорректный аргумент;
• как предыдущие сообщения повлияли на результат.

Trace показывает выполнение одного хода

Trace представляет операции одного turn в виде временного водопада:

invoke_agent booking-agent
├── chat model-name
└── execute_tool create_booking
    └── tool_approval create_booking

invoke_agent охватывает весь ход. Модельные вызовы, инструменты и approvals отображаются вложенными spans, то есть интервалами измеряемых операций. Работа субагента находится под операцией, которая его вызвала.

Workers tracing добавляет автоматические операции: исходящие fetch-вызовы, обращения к KV, R2, Durable Objects и другим bindings, а также обработчики Worker. Agent tracing связывает модель, инструмент и субагента с конкретными агентом и разговором.

Трасса показывает последовательность и длительность операций, но не объясняет мотив решения модели. Контекст можно восстановить через Session replay, если соответствующие payload были записаны.

Как включить трассировку

Включите Workers tracing в конфигурации Wrangler:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "observability": {
    "traces": {
      "enabled": true
    }
  }
}

Без явно заданной выборки Workers tracing записывает 100% запросов: значение head_sampling_rate по умолчанию равно 1. Для высоконагруженного приложения долю можно уменьшить, например до 5%:

{
  "observability": {
    "traces": {
      "enabled": true,
      "head_sampling_rate": 0.05
    }
  }
}

Выборка выполняется в начале запроса. Незаписанные запросы не создают tracing overhead.

Дальнейшая настройка зависит от агентного фреймворка.

Cloudflare поддерживает экспорт трасс через OTLP. В документации, сверенной 3 октября, Workers не поддерживает OpenTelemetry API напрямую, поэтому собственному harness потребуется адаптация через Workers custom spans.

Фрагмент для AI SDK v7 внутри существующего приложения. Пакет agents на дату проверки — 0.26.0; переменная model должна быть заранее настроена на выбранного провайдера. Сам фрагмент не создаёт модель и не является готовым Worker. Модельный вызов может оплачиваться провайдеру отдельно:

import * as ai from "ai";
import { wrapAISDK } from "agents/observability/ai";

const tracedAI = wrapAISDK(ai);

await tracedAI.generateText({
  model,
  prompt: "Проверь доступные окна для встречи",
  runtimeContext: {
    agentId: "booking-agent-production",
    conversationId: "conversation-123"
  },
  telemetry: {
    functionId: "booking-agent",
    includeRuntimeContext: {
      agentId: true,
      conversationId: true
    }
  }
});

Для AI SDK v6 идентификаторы передаются через experimental_telemetry.metadata. Конфигурацию v7 нельзя переносить в проект на v6 без адаптации.

Используйте стабильные идентификаторы:

• agent name обозначает логическую реализацию, например booking-agent;
• agent ID обозначает стабильный экземпляр или ресурс, например production-окружение;
• conversation ID объединяет ходы одного разговора.

Не выводите agent name из идентификатора пользователя, разговора или запроса. Иначе в Dashboard появится множество отдельных логических агентов.

Запись содержимого и защита данных

Сообщения, системные инструкции, аргументы и результаты инструментов могут содержать персональные данные, документы и секреты. Настройки интеграций различаются:

• Think и wrapAISDK() не записывают содержимое сообщений и инструментов по умолчанию;
• Flue v2+ по умолчанию сохраняет сообщения, системные инструкции, определения инструментов, аргументы и результаты.

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

instrument(createCloudflareTracing({ content: false }));

Для контролируемого окружения запись в Think или wrapAISDK() можно включить явно. Пример для AI SDK:

const tracedAI = wrapAISDK(ai, {
  storeMessages: true,
  storeTools: true
});

Практический порядок настройки:

1. Включите структурные spans без содержимого.
2. Проверьте, достаточно ли метаданных для диагностики.
3. Добавляйте payload только для безопасных типов запросов.
4. Маскируйте идентификаторы и приватные поля до отправки телеметрии.
5. Настройте экспорт в OTLP-совместимую систему, если правила хранения запрещают использовать Dashboard как единственное хранилище.

Workers Observability также позволяет задать persist: false. Трассы будут экспортироваться во внешнюю систему без сохранения в Cloudflare Dashboard.

Где реализуется подтверждение человеком

Human-in-the-loop означает, что действие требует решения человека перед выполнением. MCP (Model Context Protocol) — протокол подключения внешних инструментов и контекста; запрос данных по этому протоколу ещё не создаёт прикладную политику доступа.

Agent tracing может показать span tool_approval, но само подтверждение требует прикладного процесса: паузы, интерфейса, проверки личности и прав, записи решения и продолжения выполнения.

Cloudflare документирует три основных паттерна.

Workflow approval подходит для долгого ожидания

В примере ниже this — экземпляр AgentWorkflow из agents/workflows, step — шаг его метода run(), а performAction() — действие вашего приложения. Это фрагмент жизненного цикла, а не самостоятельная программа.

waitForApproval() создаёт долговечный gate на базе Cloudflare Workflows. Ожидание может продолжаться месяцами и дольше без постоянно работающего Agent.

const approval = await this.waitForApproval(step, {
  timeout: "7 days"
});

if (!approval) {
  await step.reportError("Истёк срок подтверждения");
  throw new Error("Approval timeout");
}

await step.do("apply approved action", async () => {
  return performAction();
});

Приложение должно отдельно реализовать:

• список ожидающих решений;
• интерфейс approve и reject;
• проверку личности и прав подтверждающего;
• тайм-аут и эскалацию;
• журнал решения;
• идемпотентность конечного действия.

Как работает execution replay в Code Mode

Durable Code Mode использует собственный механизм replay. Модель генерирует код, а runtime перехватывает обращения к connectors.

Если метод connector помечен requiresApproval: true:

1. Runtime записывает ожидающий метод и его аргументы.
2. Выполнение приостанавливается до вызова connector.
3. Приложение показывает ожидающее действие человеку.
4. Подтверждение запускает новый проход с теми же исходным кодом и execution ID.
5. Завершённые ранее вызовы воспроизводятся из долговечного журнала.
6. Подтверждённый connector выполняется.
7. Код продолжает работу.

Первый проход:
read_customer ── выполнено
update_record ── пауза

После подтверждения:
read_customer ── сохранённый результат
update_record ── выполняется
следующий шаг ── продолжение

Ожидающие подтверждения и история execution переживают завершение запроса и hibernation Durable Object. Replay не даёт внешнему API гарантии exactly-once, то есть ровно одного внешнего эффекта. Для критичных действий используйте ключ идемпотентности (idempotency key) и проверяйте фактическое состояние внешней системы.

Code Mode имеет экспериментальный статус и может получать breaking changes.

Полезные сценарии

Разбор ошибочного вызова инструмента

Задача: выяснить, почему агент выбрал неверный инструмент или аргумент.

Что сделать: найдите проблемный turn в Trace, затем откройте Session replay и сопоставьте вызов с записанными сообщениями и предыдущими ходами.

Проверяемый результат: видны последовательность операций и доступный модели контекст. Если payload не записывался или был обрезан, установить причину только по трассе может быть невозможно.

Проверка защищённого действия

Задача: убедиться, что опасный connector не выполняется до решения человека.

Что сделать: вызовите метод connector с requiresApproval, проверьте pending approval, отклоните контролируемый execution, затем запустите отдельный тестовый execution и подтвердите действие.

Проверяемый результат: до подтверждения фактический метод connector не вызывается. После подтверждения runtime запускает разрешённый вызов и продолжает execution. Для внешнего API отдельно проверяйте фактическое состояние: replay не гарантирует ровно один side effect end-to-end.

Поиск медленного участка

Задача: определить, где агент теряет время.

Что сделать: откройте waterfall и сравните продолжительность chat, execute_tool, исходящих HTTP-вызовов и обращений к bindings.

Проверяемый результат: найден span, который формирует основную задержку. Учтите, что tool_approval показывает событие внутри Worker invocation и не измеряет время ожидания человека между invocations.

Контролируемая проверка настройки

Материал основан на официальной документации; приведённый сценарий следует выполнить в собственном тестовом окружении.

1. Отправьте агенту запрос с известным результатом.
2. Вызовите безопасный инструмент чтения.
3. Добавьте действие, требующее подтверждения.
4. Отклоните первый тестовый execution и проверьте отсутствие внешнего изменения.
5. Начните отдельный тестовый execution и подтвердите действие.
6. Проверьте фактическое состояние внешней системы, отсутствие нежелательного дубля и работу ключа идемпотентности.
7. Откройте Session replay и найдите доступный контекст выбора инструмента.
8. Откройте Trace и проверьте вложенные spans.
9. Если нужен полный контекст, откройте View in Observability и сопоставьте агентное представление с полной Workers trace.
10. Убедитесь, что трасса не содержит секретов.

Признаки успешной настройки:

• агент появился во вкладке Agents;
• сессия объединяет связанные turns;
• trace содержит invoke_agent, chat и execute_tool;
• approval находится рядом с защищённым инструментом;
• отклонённое действие не изменило внешнюю систему;
• фактическое состояние внешней системы соответствует ожидаемому результату;
• записанные payload не содержат секретов.

Чеклист перед рабочим запуском

Ограничения и стоимость

Условия заново сверены 3 октября 2026 года. Документация Workers tracing всё ещё обозначает автоматическую трассировку как early beta и указывает хранение трасс семь дней. В ней начало учёта сохранённых трасс по общим тарифам Observability перенесено на 1 декабря 2026 года.

Опубликованная схема с 1 декабря:

Это общие квоты аккаунта для перечисленных в документации журналов и трасс. Приём и хранение считаются отдельно. Объём приёма включает данные события и атрибуты до сжатия; выборка уменьшает количество сохраняемых данных. Enterprise переходит на новые условия при продлении договора.

До 1 декабря отдельно действует таблица Workers Logs: Free — 200 000 событий в день с хранением три дня; Paid — 20 млн в месяц, далее $0,60 за млн, хранение семь дней. Это условия журналов Workers Logs, а не подтверждение такого тарифа для каждого span Agent tracing. Перед запуском проверьте свой план и раздел Billable Usage. Workers traces, Observability pricing, Workers Logs pricing.

Учитывайте ограничения:

• трассы не являются полной записью разговора без потерь;
• длинные сообщения, рассуждения, аргументы и результаты могут обрезаться;
• Session replay не показывает изображения;
• approval span не измеряет ожидание решения между Worker invocations;
• состав payload зависит от интеграции и её настроек;
• Code Mode остаётся экспериментальным.

Для юридически значимого аудита храните отдельный append-only журнал решений и фактических внешних изменений.

Официальные ссылки

• Документация Agent tracing
• Human-in-the-loop patterns
• Cloudflare Code Mode
• Workers tracing: выборка, лимиты и стоимость
• Анонс Agent tracing от 4 августа 2026 года

Следующий шаг

Если ещё не выбрана модель и схема её вызова, откройте Workers AI и AI Gateway.

Для контроля важного действия полезно заранее определить, кто его подтверждает и где проверяется фактический результат.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov