← Vytvářejte agenty na Cloudflare / agents / runtime / operations / observability

Trasování

Trasování agenta vám pomáhá pochopit, co agent dělal v každém kole, včetně volání modelu, běhů nástrojů a žádostí o schválení. Trasování použijte k prošetření neočekávaného chování, vyhledání pomalých operací a kontrole využití tokenů.

Aktivita agenta se zobrazuje spolu s událostmi runtime, jako jsou volání fetch, čtení KV a dotazy D1, v Trasy Workers.

Povolte trasování v konfiguraci Wrangler:

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

[observability.traces]
enabled = true

Otevřete Karta Agents ↗ v Cloudflare Dashboard, abyste zobrazili sledované agenty a podřízené agenty. Přehled u každého agenta zobrazuje jeho model, počet relací, počet běhů a celkové využití tokenů.

Relace je konverzace složená z jednoho nebo více kol. Kolo je jeden požadavek na agenta a jeho odpověď.

Vyberte agenta a zobrazte jeho trasování. Každé trasování obsahuje dobu trvání, rozpis tokenů a stav.

Co agent udělal, můžete sledovat dvěma způsoby: Přehrávání Session a Trasování.

Přehrávání Session zobrazuje zaznamenanou konverzaci v průběhu jednotlivých kol, včetně zpráv, uvažování, volání nástrojů a aktivity podřízených agentů. To, co se zobrazí, závisí na vašem nastavení záznamu payloadu.

Trasování je vodopádové zobrazení operací provedených během jednoho kola. Ukazuje, kdy každá operace začala, jak dlouho trvala a která operace ji vyvolala.

Každé kolo vytvoří trasování složené ze spanů, jeden pro každou časovanou operaci:

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

invoke_agent span pokrývá celé kolo. Volání modelu, běhy nástrojů a schválení se zobrazují jako vnořené spany. Práce podřízeného agenta se zobrazuje pod operací, která ji vyvolala.

Spany agenta používají k identifikaci práce zobrazené v dashboardu tři pole:

• Název agenta identifikuje logickou implementaci agenta. Použijte sdílený název, například booking-agent.
• Agent ID identifikuje stabilní instanci agenta nebo prostředek, například booking-agent-production.
• ID konverzace identifikuje aktuální konverzaci nebo relaci.

Název agenta neodvozujte z požadavku, konverzace ani identifikátoru uživatele. Vzniklo by tak v dashboardu příliš mnoho odlišných názvů agentů.

Zprávy a nástrojové payloady mohou obsahovat osobně identifikovatelné údaje. Zaznamenávejte pouze payloady, které je bezpečné ukládat. Každá integrace řídí zaznamenávání payloadů jinak, proto to nakonfigurujte v příslušné Nastavení frameworku sekce.

Think a wrapAISDK() použít storeMessages k zaznamenávání vstupních a výstupních zpráv do chat spany. Používají storeTools k zaznamenávání argumentů a výsledků do execute_tool spany.

Ovládání trasování a payloadů závisí na integraci. Think a Flue instrumentují kola automaticky. Přímá volání AI SDK a vlastní harnessy vyžadují další nastavení.

Think automaticky agenta instrumentuje a vyvolává standardní struktura spanu. Není vyžadováno žádné další nastavení trasování.

Think ve výchozím nastavení neukládá payloady zpráv ani nástrojů. Pokud je chcete zaznamenávat, přepište vlastnosti ve třídě agenta:

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+ ↗ také automaticky instrumentuje vašeho agenta a vysílá standardní struktura spanu. Není vyžadováno žádné další nastavení trasování.

Flue ve výchozím nastavení ukládá zprávy, systémové instrukce, definice nástrojů, argumenty a výsledky. Chcete-li jejich záznam zastavit, nastavte content na 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 }));

Pro přímé AI SDK ↗ volání obalte jmenný prostor jednorázově:

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() podporuje AI SDK v6 a v7. Instrumentuje generateText, streamText, generateObject, a streamObject, čímž vytvoří invoke_agent nadřazený prvek dříve, než začne práce modelu a nástrojů.

Na rozdíl od Think nemá přímé volání AI SDK žádnou instanci Agent, ze které by bylo možné odvodit identitu v dashboardu. Zadejte pole identity agenta při každém volání.

Zahrnujte pouze kontext, který je bezpečné uchovávat. Nezahrnujte přihlašovací údaje, tokeny, uživatelský vstup ani jiné tajné údaje.

Použijte nativní pole telemetrie AI SDK v7 k poskytnutí identity. Můžete přidat i další skalární kontext, například tenant nebo trasu, aby bylo trasování snazší dotazovat:

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,
		},
	},
});

Tím se mapuje functionId, agentId, a conversationId na gen_ai.agent.name, gen_ai.agent.id, a gen_ai.conversation.id. Ostatní zahrnuté skalární hodnoty používají cloudflare.agents.runtime_context.* namespace.

AI SDK v6 používá experimental_telemetry.metadata pro stejnou identitu a doplňková data spanu:

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",
		},
	},
});

Doplňková skalární metadata používají cloudflare.agents.metadata.* namespace.

wrapAISDK() ve výchozím stavu neukládá obsah zpráv ani nástrojů. Chcete-li je zaznamenávat s AI SDK v6 nebo v7, předejte při obalování jmenného prostoru možnosti úložiště:

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,
});

Pokud váš agent nepoužívá žádný z aktuálně podporovaných frameworků, instrumentujte ho pomocí Vlastní API pro spany Workers. Vytvořte invoke_agent span pro každé kolo, s chat spany pro volání modelu, execute_tool spany pro běhy nástrojů a tool_approval spany pro schválení.

Názvy spanů, atributy a příklady implementace najdete v Referenční implementace OpenTelemetry GenAI ↗. Přizpůsobte tyto příklady pro Workers custom spans API.

Přidejte tyto atributy do obou invoke_agent a chat spany, aby dashboard Agents mohl telemetrii přiřadit k agentovi a konverzaci:

Pro vlastní spany přidejte atributy payloadu ručně. Použijte gen_ai.input.messages, gen_ai.output.messages, a gen_ai.system_instructions na spanech modelu. Použijte gen_ai.tool.call.arguments a gen_ai.tool.call.result na spanech nástrojů. Vlastní rozhraní API pro spany přijímá pouze skalární hodnoty atributů, proto strukturované payloady serializujte pomocí JSON.stringify(). Tyto hodnoty se zaznamenávají vždy, když je dané volání vzorkováno (sampled). Přidávejte jen takové payloady, které je bezpečné ukládat.

Atributy spanu se řídí Sémantické konvence OpenTelemetry pro generativní AI ↗, takže je může zpracovat jakýkoli nástroj, který čte data OpenTelemetry. Chcete-li odesílat trasování do externího cíle, nakonfigurovat koncový bod OpenTelemetry Protocol (OTLP) ve Workers Observability.

Trasování agenta používá Trasování Workers a řídí se ceníkem Workers Observability.

Zobrazení Agents ukazuje operace vašeho agenta. Úplné trasování Workeru může obsahovat další spany z vnitřních částí SDK a dalších operací na úrovni Workeru. Chcete-li prozkoumat úplné trasování, vyberte Zobrazit v Observability.

Každý span se počítá jako jedna událost pozorovatelnosti, včetně spanů, které se nezobrazují v zobrazení Agents. Trasování je v beta verzi zdarma. Od 1. října 2026 bude trasování zahrnuto do stávajícího ceníku Workers Observability:

• Použijte trasování agenta pro ladění a observabilitu. Trasování není úplným ani bezeztrátovým záznamem konverzace.
• Data payloadu podléhají limitům velikosti span. Dlouhé zprávy, uvažování, argumenty nástrojů a výsledky mohou být zkráceny. Tyto limity se mohou měnit.
• Přehrávání Session nezobrazuje obrázky.