Cloudflare Agents — трассировка, replay и подтверждение действий в production

Cloudflare Agents — новый раздел Cloudflare Dashboard и продуктовый слой, который компания начала с observability. По состоянию на 15 августа 2026 года он группирует инструментированные агенты, сессии, запуски, экземпляры, заявленный фреймворком расход токенов и agent-aware traces. Cloudflare называет tracing первой частью продукта. Runtime, долговечное выполнение, контроль модельных запросов и интерфейсы подтверждения по-прежнему реализуются отдельными компонентами.

Четыре слоя агентной системы

Название Cloudflare Agents легко спутать с Agents SDK, поскольку оба продукта относятся к одному стеку. На практике у них разные зоны ответственности.

Эти компоненты дополняют друг друга. В Cloudflare Agents попадает телеметрия, которую создаёт поддерживаемая интеграция или ваш код через custom spans. AI Gateway ведёт собственный контур логов и аналитики модельных запросов; прямое автоматическое объединение этих журналов документация не обещает.

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

Что именно показывает Cloudflare Agents

В панели Cloudflare появляется отдельный раздел Agents. Он группирует телеметрию по логическому агенту и показывает:

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

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

Session replay восстанавливает контекст

Session replay собирает записанную историю сессии:

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

Session replay — просмотр записанных данных, а не повторный запуск агента. Внешние API не вызываются заново, инструменты не выполняются, состояние системы не меняется.

Такой replay полезен, когда нужно выяснить:

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

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

Trace представляет один turn, то есть один запрос к агенту и его ответ, в виде временного водопада.

Базовая структура выглядит так:

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

Внутри можно увидеть:

• начало и длительность каждой операции;
• вложенные вызовы субагентов;
• модель и количество токенов;
• вызванный инструмент;
• обращения к D1, KV, Durable Objects и внешним API;
• ошибки и тайм-ауты;
• событие запроса подтверждения.

Workers tracing показывает инфраструктурные операции. Agent tracing добавляет spans, которые связывают вызов модели, инструмент или поддерживаемого субагента с конкретным агентом, сессией и turn. Сама трасса не определяет мотив решения модели. Контекст можно восстановить через Session replay, если нужные payload были записаны.

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

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

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

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

Cloudflare умеет экспортировать трассы через OTLP. Прямой OpenTelemetry API внутри Workers на дату проверки ещё не поддерживается, поэтому произвольный OTel-инструмент потребует адаптации через Workers custom spans.

Пример для AI SDK v7:

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 обозначает конкретный экземпляр или окружение;
• conversation ID связывает ходы одной сессии.

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

Запись payload и защита данных

Сообщения, системные инструкции и результаты инструментов могут содержать персональные данные, документы и секреты. Настройки по умолчанию различаются: Think и wrapAISDK() не записывают payload сообщений и инструментов, а Flue v2+ сохраняет содержимое по умолчанию. Для Flue отключите его через createCloudflareTracing({ content: false }), если данные нельзя хранить.

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

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

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

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

Где реализуется human-in-the-loop

Agent tracing может показать span tool_approval, но раздел Agents не создаёт универсальную очередь подтверждений и не определяет политику доступа. Приложение само реализует паузу, пользовательский интерфейс, проверку личности и прав, запись решения и продолжение выполнения. Cloudflare документирует три основных паттерна.

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

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

const approval = await this.waitForApproval<{ approvedBy: string }>(
  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.

Если метод требует подтверждения:

1. Runtime записывает ожидающее действие и его аргументы.
2. Текущий проход прекращается до выполнения опасного вызова.
3. Приложение показывает действие человеку.
4. После подтверждения код запускается ещё раз с тем же executionId.
5. Connector calls со статусом applied возвращают сохранённые результаты вместо повторного вызова.
6. Runtime вызывает подтверждённый connector method.
7. Код продолжает работу до завершения или следующего approval.

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

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

Этот механизм требует детерминированной последовательности вызовов. Если при повторном проходе изменится connector, метод или набор аргументов, runtime завершит исполнение с ошибкой replay divergence.

Отклонение завершает execution, но не отменяет connector calls, выполненные до паузы. Rollback запускается отдельно и работает как компенсация только для методов, у которых connector реализует revert.

Runtime не повторяет вызовы, уже отмеченные как applied, однако это не гарантирует end-to-end exactly-once для внешнего API при сетевых сбоях и неоднозначном результате. Для критичных действий сохраняйте собственный журнал, передавайте idempotency key и проверяйте фактическое состояние внешней системы.

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

Роль AI Gateway

Agent tracing показывает инструментированные операции внутри turn и не является полным или lossless-журналом. AI Gateway работает на уровне модельных запросов и ведёт собственные логи и аналитику.

Через AI Gateway можно:

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

Типичный production-контур использует оба продукта:

• Cloudflare Agents отвечает на вопрос: «Что сделал агент во время этого запуска?»
• AI Gateway отвечает на вопрос: «Какой запрос ушёл модели, сколько он стоил и как был обработан?»

Не включайте кэширование для запросов, результат которых зависит от свежего состояния, прав пользователя или уникального контекста. Возврат устаревшего ответа может выглядеть как ошибка агента, хотя причина находится на уровне шлюза.

Операционный сценарий проверки

После настройки проведите один контролируемый запуск:

1. Отправьте агенту запрос с известным результатом.
2. Заставьте его вызвать безопасный инструмент чтения.
3. Добавьте действие, требующее подтверждения.
4. Отклоните первый запрос и проверьте отсутствие внешнего изменения.
5. После отклонения начните новый execution и подтвердите действие: отклонённый Code Mode execution возобновить нельзя.
6. Проверьте отсутствие дубля side effect и работу idempotency key.
7. Откройте Session replay и найдите контекст выбора инструмента.
8. Откройте Trace и проверьте вложенные spans.
9. Сопоставьте модельный вызов с записью AI Gateway.
10. Убедитесь, что трасса не содержит секретов.

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

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

Быстрый production-чеклист

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

По состоянию на 15 августа 2026 года Agent tracing находится в beta и использует тарификацию Workers Observability.

До 1 октября 2026 года tracing доступен бесплатно. После этой даты документация указывает:

• Workers Free: 200 000 событий в день, хранение 3 дня;
• Workers Paid: 20 млн событий в месяц, затем $0,60 за дополнительный миллион, хранение 7 дней.

Каждый span считается отдельным событием. Полная Workers trace может содержать больше spans, чем показывает интерфейс Agents.

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

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

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

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

• Анонс Cloudflare Agents
• Документация Agent tracing
• Human-in-the-loop patterns
• Как работает durable Code Mode
• Cloudflare Workflows
• Cloudflare AI Gateway

По теме

Продолжение темы: сначала разберите runtime агента, затем сопоставьте production-наблюдение с безопасностью инструментальных вызовов.

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

Cloudflare Agents SDK — stateful AI-агенты на Durable Objects

Связанные материалы

• Статья: Cloudflare OS: как компания собрала внутренний ИИ-воркспейс и раздала его всем сотрудникам
• Блог: Cloudflare показал почту для ИИ-агентов
• База знаний: MCP и безопасность — prompt injection, tool poisoning и как защититься

Если вы проектируете production-контур для агентов, заранее разделите наблюдение, долговечное выполнение, доступ к моделям и подтверждение внешних действий. Это особенно полезно командам, которым нужен управляемый переход от прототипа к рабочей системе.

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