← Создание агентов на Cloudflare / agents / runtime / operations / observability

Трассировка

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

Активность агента отображается рядом с событиями времени выполнения, такими как вызовы fetch, чтения KV и запросы D1, в Трассировки Workers.

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

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

[observability.traces]
enabled = true

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

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

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

Отследить, что сделал агент, можно двумя способами: Воспроизведение Session и Trace.

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

Trace это водопадная диаграмма операций, выполненных за один ход. Она показывает, когда началась каждая операция, сколько времени она заняла и какая операция её вызвала.

Каждый ход порождает трассировку, состоящую из spans, по одному на каждую измеряемую операцию:

invoke_agent {agent class}
├── chat {model}
└── execute_tool {tool}
    └── tool_approval {tool}

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

Спаны Agent используют три поля для идентификации работы, отображаемой на панели управления:

• Имя агента идентифицирует логическую реализацию агента. Используйте общее имя, например booking-agent.
• ID агента идентифицирует стабильный экземпляр агента или ресурс, например booking-agent-production.
• Идентификатор разговора идентифицирует текущий разговор или сессию.

Не выводите имя агента из запроса, разговора или идентификатора пользователя. Из-за этого в дашборде появится слишком много разных имён агентов.

Сообщения и пейлоады инструментов могут содержать персональные данные. Записывайте только те пейлоады, которые безопасно хранить. Каждая интеграция по-своему управляет записью пейлоадов, поэтому настраивайте это в соответствующем Настройка фреймворка раздел.

Think и wrapAISDK() используйте storeMessages чтобы записывать входящие и исходящие сообщения в chat spans. Они используют storeTools чтобы записывать аргументы и результаты в execute_tool spans.

Управление трассировкой и полезной нагрузкой зависит от интеграции. Think и Flue инструментируют ходы автоматически. Прямые вызовы AI SDK и собственные каркасы требуют дополнительной настройки.

Think автоматически инструментирует вашего агента и генерирует стандартная структура спана. Дополнительная настройка трассировки не требуется.

По умолчанию Think не сохраняет payload сообщений и инструментов. Чтобы записывать их, переопределите свойства в классе агента:

import { Think } from "@cloudflare/think";

export class MyAgent extends Think {
	storeMessages = true;
	storeTools = true;
}

import { Think } from "@cloudflare/think";

export class MyAgent extends Think<Env> {
	override storeMessages = true;
	override storeTools = true;
}

Flue v2+ ↗ также автоматически инструментирует вашего агента и генерирует стандартная структура спана. Дополнительная настройка трассировки не требуется.

По умолчанию Flue сохраняет сообщения, системные инструкции, определения инструментов, аргументы и результаты. Чтобы прекратить их запись, установите content в false:

import { instrument } from "@flue/runtime";
import { createCloudflareTracing } from "@flue/runtime/cloudflare";

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

import { instrument } from "@flue/runtime";
import { createCloudflareTracing } from "@flue/runtime/cloudflare";

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

Для прямого AI SDK ↗ вызовов оберните пространство имён один раз:

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

const tracedAI = wrapAISDK(ai);

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

const tracedAI = wrapAISDK(ai);

wrapAISDK() поддерживает AI SDK версий 6 и 7. Он инструментирует generateText, streamText, generateObject, а также streamObject, создавая invoke_agent родителю до начала работы модели и инструментов.

В отличие от Think, прямой вызов AI SDK не имеет экземпляра Agent, из которого можно вывести идентификатор для dashboard. Укажите поля идентичности агента при каждом вызове.

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

Используйте встроенные поля телеметрии AI SDK v7 для передачи идентификации. Вы можете добавить дополнительный скалярный контекст, например тенант или маршрут, чтобы упростить запросы к трейсам:

await tracedAI.generateText({
	model,
	prompt: "Find an available appointment",
	runtimeContext: {
		agentId: "booking-agent-production",
		conversationId: "conversation-123",
		tenantId: "tenant-42",
	},
	telemetry: {
		functionId: "booking-agent",
		includeRuntimeContext: {
			agentId: true,
			conversationId: true,
			tenantId: true,
		},
	},
});

await tracedAI.generateText({
	model,
	prompt: "Find an available appointment",
	runtimeContext: {
		agentId: "booking-agent-production",
		conversationId: "conversation-123",
		tenantId: "tenant-42",
	},
	telemetry: {
		functionId: "booking-agent",
		includeRuntimeContext: {
			agentId: true,
			conversationId: true,
			tenantId: true,
		},
	},
});

Это сопоставляет functionId, agentId, а также conversationId к gen_ai.agent.name, gen_ai.agent.id, а также gen_ai.conversation.id. Остальные включённые скалярные значения используют cloudflare.agents.runtime_context.* пространство имён.

AI SDK v6 использует experimental_telemetry.metadata для той же идентичности и дополнительных данных span:

await tracedAI.generateText({
	model,
	prompt: "Find an available appointment",
	experimental_telemetry: {
		functionId: "booking-agent",
		metadata: {
			agentId: "booking-agent-production",
			conversationId: "conversation-123",
			tenantId: "tenant-42",
		},
	},
});

await tracedAI.generateText({
	model,
	prompt: "Find an available appointment",
	experimental_telemetry: {
		functionId: "booking-agent",
		metadata: {
			agentId: "booking-agent-production",
			conversationId: "conversation-123",
			tenantId: "tenant-42",
		},
	},
});

Дополнительные скалярные метаданные используют cloudflare.agents.metadata.* пространство имён.

wrapAISDK() по умолчанию не сохраняет сообщения или полезные нагрузки инструментов. Чтобы записывать их с AI SDK v6 или v7, передайте параметры хранения при обёртывании пространства имён:

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

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

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

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

Если ваш агент не использует ни один из поддерживаемых на данный момент фреймворков, инструментируйте его с помощью Workers API для пользовательских spans. Создайте invoke_agent span для каждого хода, с chat spans для вызовов модели, execute_tool spans для запусков инструментов и tool_approval spans для подтверждений.

Названия span, атрибуты и примеры реализации см. в Эталонные реализации OpenTelemetry GenAI ↗. Адаптируйте эти примеры под API пользовательских spans Workers.

Добавьте эти атрибуты в оба invoke_agent и chat spans, чтобы дашборд Agents мог связать телеметрию с агентом и беседой:

Для пользовательских span добавляйте атрибуты payload вручную. Используйте gen_ai.input.messages, gen_ai.output.messages, а также gen_ai.system_instructions на спанах модели. Используйте gen_ai.tool.call.arguments и gen_ai.tool.call.result на спанах инструментов. API пользовательских спанов принимает только скалярные значения атрибутов, поэтому сериализуйте структурированные полезные нагрузки с помощью JSON.stringify(). Эти значения записываются при каждом сэмплировании вызова. Добавляйте только те данные полезной нагрузки, которые безопасно хранить.

Атрибуты span следуют Семантические соглашения OpenTelemetry Generative AI ↗, чтобы их мог использовать любой инструмент, читающий данные OpenTelemetry. Чтобы отправлять трассировки во внешний пункт назначения, настроить конечную точку OpenTelemetry Protocol (OTLP) в Workers Observability.

Трассировки Agent используют Трассировка Workers и следуют тарификации Workers Observability.

Вкладка Agents показывает операции вашего агента. Полная трассировка Worker может включать дополнительные spans из внутренних механизмов SDK и других операций уровня Worker. Чтобы просмотреть полную трассировку, выберите Просмотреть в Observability.

Каждый span считается одним событием observability, включая spans, не отображаемые в представлении Agents. Трассировка бесплатна, пока функция находится в бета-версии. Начиная с 1 октября 2026 года трассировка будет включена в действующие тарифы Workers Observability:

• Используйте трейсы агента для отладки и наблюдаемости. Трейсы не являются полной записью разговора без потерь данных.
• На размер полезной нагрузки распространяются ограничения размера span. Длинные сообщения, цепочки рассуждений, аргументы инструментов и результаты могут быть обрезаны. Эти ограничения могут меняться.
• Воспроизведение Session не отображает изображения.