@economic/agents 2.14.3 → 2.15.0

package/README.md

@@ -651,30 +651,41 @@ When configured:
 AI telemetry is emitted per turn from the `ai` SDK's OpenTelemetry spans:
 
 - **Audit logs** → one JSON object per turn in `AGENTS_AUDIT_LOGS` (model, actor, IP, prompt, response, tool calls).
-- **Analytics** → typed per-turn and per-tool events. By default these are written to
-  `AGENTS_ANALYTICS` using the existing Analytics Engine schema.
+- **Analytics** → typed per-turn and per-tool events, written to `AGENTS_ANALYTICS` using the
+  existing Analytics Engine schema.
+- **Tracing** → completed turns and message feedback, handed to the handlers you return from
+  `getTracingHandlers()`.
 
-Additional analytics destinations can receive the same events by overriding
-`getAnalyticsHandlers()`. Analytics Engine remains enabled whenever `AGENTS_ANALYTICS` is bound:
+Override `getTracingHandlers()` to send turns and message feedback to a tracing or analytics
+service. Each handler's `handle` receives a `TracingEvent`, a `turn` or a `feedback` event told
+apart by `type`. Both carry their OpenTelemetry `spans`, so a handler that only forwards spans
+doesn't need to check:
 
 ```typescript
-import type { AnalyticsHandler } from "@economic/agents";
+import type { TracingHandler } from "@economic/agents";
 
-const warehouse: AnalyticsHandler = {
-  name: "warehouse",
-  async handle(event) {
-    await sendToWarehouse(event);
-  },
+const tracing: TracingHandler = {
+  name: "tracing-service",
+  handle: (event) => sendToTracingService(event.spans),
 };
 
-getAnalyticsHandlers() {
-  return [warehouse];
+getTracingHandlers() {
+  return [tracing];
 }
 ```
 
-Handler failures are isolated and recorded as operational errors. Delivery runs through the
-agent's lifetime management without blocking the response. `prompt.received` includes the raw
-prompt for destinations such as conversation classification; handlers must treat it as sensitive.
+A `turn` event comes when a turn ends: who it was for, its request `context` (as tools see it) and
+`spans`, the `ai` SDK's OpenTelemetry spans under the turn's `ai.streamText` span. A turn
+continuing an earlier one, e.g. after a tool approval, sits under that turn in the same trace. A
+`feedback` event comes when a user rates an assistant message: `messageId`, `rating`, `comment` and
+`spans`, the rating as a `gen_ai.evaluation.*` span under the turn that first answered the message
+(none when the rating was removed).
+Hand the spans to any OpenTelemetry exporter or span processor as they are; `examples/assistant`
+has a complete handler.
+
+Spans and `context` can hold prompts, tool results and credentials, so pick what you send. Handlers
+run in the background; a failure is logged as `agent.tracing.handler.failed` and never affects the
+chat.
 
 Separately, the SDK writes structured operational logs for completed/failed LLM and tool calls, turn duration, framework failures, and selected recovery warnings. Prompt, response, tool argument, and tool result content is excluded. These records use the stable fields `source`, `event`, `level`, `timestamp`, `agentName`, `agentClass`, `durableObjectName`, and `attributes`, while preserving Cloudflare's diagnostic events.
 
@@ -703,8 +714,7 @@ Imported from `@economic/agents` unless noted.
 | `ToolContext`                                                            | `RequestContext & { _userContext?: UserContext }`.                                  |
 | `AgentEnv`                                                               | The bindings the runtime expects.                                                   |
 | `AgentConnectionState` / `AgentConnectionStatus` / `AgentConnectionType` | Connection state shared with the client.                                            |
-| `AnalyticsHandler` / `AnalyticsEvent`                                    | Typed, consumer-configured product-analytics destinations.                          |
-| `createAnalyticsEngineHandler(dataset)`                                  | Analytics Engine destination using the existing v2 positional schema.               |
+| `TracingHandler` / `TracingEvent`                                        | Consumer-defined destinations for completed turns and message feedback.             |
 
 ### Members
 
@@ -714,7 +724,7 @@ Imported from `@economic/agents` unless noted.
 | `getSystemPrompt(ctx?)`                        | `Agent`     | Required. System prompt.                                               |
 | `getTools()`                                   | `Agent`     | Always-on tools (default `{}`).                                        |
 | `getSkills()`                                  | `Agent`     | Local skills (default `[]`).                                           |
-| `getAnalyticsHandlers()`                       | `Agent`     | Additional analytics destinations; Analytics Engine remains automatic. |
+| `getTracingHandlers()`                         | `Agent`     | Destinations for completed turns and message feedback (default: `[]`). |
 | `getAnalyticsAttributes()`                     | `Agent`     | Additional dimensions included on every analytics event.               |
 | `static getJwtAuthConfig(env)`                 | `Agent`     | Optional JWT verification and actor binding.                           |
 | `getUserContext(jwtToken)`                     | `Agent`     | Optional per-user context after auth.                                  |

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 import { Agent as Agent$1, AgentOptions, Connection, ConnectionContext, SubAgentClass } from "agents";
 import { Action as Action$1, ActionApprovalPolicy, ActionConfig, ActionContext as ActionContext$1, ActionIdempotencyKey, ActionPermissionSpec, ChatResponseResult, PrepareStepContext, Session, Think, ToolCallContext, ToolCallDecision, TurnConfig, TurnContext, skills } from "@cloudflare/think";
 import { FlexibleSchema, JSONValue, LanguageModel, ModelMessage, Tool as Tool$1, ToolExecutionOptions, UIMessage } from "ai";
+import { ReadableSpan } from "@opentelemetry/sdk-trace-base";
 import { Observability } from "agents/observability";
 import { createCompactFunction } from "agents/experimental/memory/utils";
 import { SkillSource as SkillSource$1 } from "agents/skills";
@@ -114,6 +115,76 @@ type Tool<Context extends Record<string, unknown> = Record<string, unknown>, INP
 };
 declare function tool<Context extends Record<string, unknown> = Record<string, unknown>, INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONValue | unknown | never = any>(definition: Tool<Context, INPUT, OUTPUT>): Tool$1<INPUT, OUTPUT>;
 //#endregion
+//#region src/server/features/telemetry/exchange.d.ts
+interface SpanIds {
+  traceId: string;
+  spanId: string;
+}
+interface MessageRating {
+  messageId: string;
+  /** 1 thumbs up, -1 thumbs down, 0 rating removed. */
+  rating: 1 | -1 | 0;
+  comment?: string;
+}
+interface TurnExchange extends SpanIds {
+  /** An earlier turn already answered the user message, e.g. before a tool approval. */
+  continues: boolean;
+}
+//#endregion
+//#region src/server/features/telemetry/tracing.d.ts
+interface TracingIdentity {
+  agentName: string;
+  /** The Durable Object — the chat, for a `ChatAgent`. */
+  durableObjectName: string;
+  actorId: string;
+}
+/** A completed turn and the OpenTelemetry spans the `ai` SDK recorded for it. */
+interface TracedTurn extends TracingIdentity {
+  type: "turn";
+  /** The turn's request context, as tools receive it. Can hold credentials. */
+  context: Readonly<Record<string, unknown>>;
+  /**
+   * The turn's `ai.streamText` span and, under it, its model and tool calls. A
+   * turn continuing an earlier one, e.g. after a tool approval, sits under that
+   * turn's span in the same trace.
+   */
+  spans: readonly ReadableSpan[];
+}
+/** A user's rating of an assistant message, given any time after the turn. */
+interface TracedFeedback extends TracingIdentity, MessageRating {
+  type: "feedback";
+  /**
+   * The rating as a `gen_ai.evaluation.*` span under the turn that first
+   * answered the message's user message. Empty when the rating was removed.
+   */
+  spans: readonly ReadableSpan[];
+}
+type TracingEvent = TracedTurn | TracedFeedback;
+/** Receives completed turns and message feedback, e.g. for a tracing service. */
+interface TracingHandler {
+  readonly name?: string;
+  handle(event: TracingEvent): void | Promise<void>;
+}
+/** What a turn's tracer needs: where its spans go and the exchange it belongs to. */
+interface TurnTracing {
+  onTurnSpans(spans: readonly ReadableSpan[]): void;
+  exchange?: TurnExchange;
+}
+interface TracingOptions {
+  getIdentity(): TracingIdentity;
+  getHandlers(): readonly TracingHandler[];
+  keepAlive<T>(callback: () => Promise<T>): Promise<T>;
+}
+/** Hands completed turns and message ratings to an agent's tracing handlers, in the background. */
+declare class Tracing {
+  private readonly options;
+  constructor(options: TracingOptions);
+  /** Nothing when no handlers are configured. */
+  turn(context: Readonly<Record<string, unknown>>, messages: readonly UIMessage[]): Promise<TurnTracing | undefined>;
+  feedback(messages: readonly UIMessage[], rating: MessageRating): void;
+  private sendFeedback;
+}
+//#endregion
 //#region src/server/features/analytics/types.d.ts
 type AnalyticsAttribute = string | number | boolean;
 type AnalyticsAttributes = Readonly<Record<string, AnalyticsAttribute>>;
@@ -163,20 +234,6 @@ type AnalyticsEventPayload = {
   messageId: string;
   rating: 1 | -1 | 0;
 };
-type AnalyticsEvent = AnalyticsEventPayload & {
-  schemaVersion: 1;
-  eventId: string;
-  timestamp: number;
-  agentName: string;
-  durableObjectName: string;
-  actorId: string;
-  attributes: AnalyticsAttributes;
-};
-/** Receives typed product-analytics events emitted by the SDK. */
-interface AnalyticsHandler {
-  readonly name?: string;
-  handle(event: AnalyticsEvent): void | Promise<void>;
-}
 interface AnalyticsEventContext {
   agentName: string;
   durableObjectName: string;
@@ -184,28 +241,16 @@ interface AnalyticsEventContext {
   attributes?: AnalyticsAttributes;
 }
 //#endregion
-//#region src/server/features/analytics/analytics-engine.d.ts
-/**
- * Creates a Cloudflare Analytics Engine destination for SDK analytics events.
- * It preserves the SDK v2 positional schema and never writes prompt content.
- */
-declare function createAnalyticsEngineHandler(dataset: AnalyticsEngineDataset): AnalyticsHandler;
-//#endregion
-//#region src/server/features/analytics/dispatcher.d.ts
-declare function createAnalyticsEvent(context: AnalyticsEventContext, payload: AnalyticsEventPayload): AnalyticsEvent;
-declare function dispatchAnalyticsEvent(handlers: readonly AnalyticsHandler[], event: AnalyticsEvent): Promise<void>;
-//#endregion
 //#region src/server/features/analytics/emitter.d.ts
 interface AnalyticsOptions {
   getContext(): AnalyticsEventContext;
-  getHandlers(): readonly AnalyticsHandler[];
+  /** Where events are written; analytics is off without it. */
+  getDataset(): AnalyticsEngineDataset | undefined;
   keepAlive<T>(callback: () => Promise<T>): Promise<T>;
 }
 declare class Analytics {
   private readonly options;
-  private handlers?;
   constructor(options: AnalyticsOptions);
-  private getHandlers;
   private emit;
   get enabled(): boolean;
   get context(): AnalyticsEventContext;
@@ -419,11 +464,12 @@ declare abstract class Agent<RequestContext extends Record<string, unknown> = Re
    */
   protected registerInstanceActivity(): Promise<void>;
   protected readonly analytics: Analytics;
+  protected readonly tracing: Tracing;
   /**
-   * Additional product-analytics destinations for this agent. Analytics Engine
-   * remains enabled whenever `AGENTS_ANALYTICS` is bound.
+   * Destinations for completed turns and message feedback, e.g. a tracing
+   * service. They run in the background; a failing one never affects the chat.
    */
-  getAnalyticsHandlers(): readonly AnalyticsHandler[];
+  getTracingHandlers(): readonly TracingHandler[];
   /** Business dimensions added to every analytics event. */
   getAnalyticsAttributes(): AnalyticsAttributes;
   observability?: Observability;
@@ -594,4 +640,4 @@ declare function routeAgentRequest<Env>(request: Request, env: Env, options?: Ag
 //#region src/server/index.d.ts
 declare function getCurrentToolContext(): any;
 //#endregion
-export { type Action, type ActionContext, Agent, type AgentConnectionStatus, type AgentConnectionType, type AgentEnv, type AnalyticsAttribute, type AnalyticsAttributes, type AnalyticsEvent, type AnalyticsEventPayload, type AnalyticsHandler, type AnalyticsUsage, Assistant, ChatAgent, type ExchangedToken, type InvocableSkill, type JwtAuthConfig, type RegisteredAction, type Skill, type SkillSource, type TokenExchangeConfig, type TokenExchangeResult, type Tool, type ToolContext, type ToolSet, type TurnSnapshot, type UnauthorizedPolicy, type UnauthorizedToolPolicy, action, createAnalyticsEngineHandler, createAnalyticsEvent, createJwtAuthConfig, dispatchAnalyticsEvent, exchangeToken, getCurrentToolContext, routeAgentRequest, skill, tool };
+export { type Action, type ActionContext, Agent, type AgentConnectionStatus, type AgentConnectionType, type AgentEnv, type AnalyticsAttribute, type AnalyticsAttributes, Assistant, ChatAgent, type ExchangedToken, type InvocableSkill, type JwtAuthConfig, type RegisteredAction, type Skill, type SkillSource, type TokenExchangeConfig, type TokenExchangeResult, type Tool, type ToolContext, type ToolSet, type TracedFeedback, type TracedTurn, type TracingEvent, type TracingHandler, type TurnSnapshot, type UnauthorizedPolicy, type UnauthorizedToolPolicy, action, createJwtAuthConfig, exchangeToken, getCurrentToolContext, routeAgentRequest, skill, tool };

package/dist/index.mjs

@@ -2,7 +2,8 @@ import { Agent as Agent$1, callable, getCurrentAgent, routeAgentRequest as route
 import { Think, action as action$1, skills } from "@cloudflare/think";
 import { Output, convertToModelMessages, generateText, jsonSchema, pruneMessages, tool as tool$1 } from "ai";
 import { createRemoteJWKSet, decodeJwt, errors, jwtVerify } from "jose";
-import { BasicTracerProvider, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { BasicTracerProvider, InMemorySpanExporter, RandomIdGenerator, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { ROOT_CONTEXT, TraceFlags, context, trace } from "@opentelemetry/api";
 import { genericObservability } from "agents/observability";
 import { applyToolUpdate, toolApprovalUpdate } from "agents/chat";
 import { createCompactFunction, estimateMessageTokens, estimateStringTokens, sanitizeToolPairs, truncateOlderMessages } from "agents/experimental/memory/utils";
@@ -584,6 +585,119 @@ function handleAnalyticsSpan(span, analytics) {
 	});
 }
 //#endregion
+//#region src/server/features/telemetry/exchange.ts
+async function getExchangeSpanIds(chatName, userMessageId) {
+	const bytes = new TextEncoder().encode(`${chatName}:${userMessageId}`);
+	const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+	const hex = Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("");
+	return {
+		traceId: hex.slice(0, 32),
+		spanId: hex.slice(32, 48)
+	};
+}
+/**
+* The exchange a turn belongs to: the last user message. The first turn
+* answering it is the root of the exchange's trace; later turns, e.g. after a
+* tool approval, continue that trace under it.
+*/
+async function getTurnExchange(chatName, messages) {
+	const userMessage = messages.findLast((message) => message.role === "user");
+	if (!userMessage) return;
+	return {
+		...await getExchangeSpanIds(chatName, userMessage.id),
+		continues: messages.at(-1) !== userMessage
+	};
+}
+/**
+* Gives a turn's `ai.streamText` span its exchange's ids. On a per-turn tracer
+* that span is the first one started and the only one without a parent.
+*/
+var TurnIdGenerator = class {
+	exchange;
+	random = new RandomIdGenerator();
+	turnSpanId;
+	constructor(exchange) {
+		this.exchange = exchange;
+		this.turnSpanId = exchange.spanId;
+	}
+	generateTraceId() {
+		return this.exchange.traceId;
+	}
+	generateSpanId() {
+		const spanId = this.turnSpanId ?? this.random.generateSpanId();
+		this.turnSpanId = void 0;
+		return spanId;
+	}
+};
+/**
+* A rating as a span under the turn that answered the rated message's user
+* message, described with OpenTelemetry's GenAI evaluation attributes. None
+* when the rating was removed or the message has no user message before it.
+*/
+async function createFeedbackSpan(chatName, messages, { messageId, rating, comment }) {
+	const index = messages.findIndex((message) => message.id === messageId);
+	const userMessage = messages.slice(0, Math.max(index, 0)).findLast((message) => message.role === "user");
+	if (!userMessage || rating === 0) return;
+	const exporter = new InMemorySpanExporter();
+	const provider = new BasicTracerProvider({ spanProcessors: [new SimpleSpanProcessor(exporter)] });
+	const parent = trace.setSpanContext(ROOT_CONTEXT, {
+		...await getExchangeSpanIds(chatName, userMessage.id),
+		traceFlags: TraceFlags.SAMPLED,
+		isRemote: true
+	});
+	const attributes = {
+		"gen_ai.evaluation.name": "user_feedback",
+		"gen_ai.evaluation.score.value": rating === 1 ? 1 : 0,
+		"gen_ai.evaluation.score.label": rating === 1 ? "positive" : "negative",
+		...comment ? { "gen_ai.evaluation.explanation": comment } : {}
+	};
+	provider.getTracer("@economic/agents").startSpan("user_feedback", { attributes }, parent).end();
+	await provider.forceFlush();
+	return exporter.getFinishedSpans()[0];
+}
+//#endregion
+//#region src/server/features/telemetry/turn-tracer.ts
+const TURN_SPAN_NAME = "ai.streamText";
+/**
+* Starts every span of a turn as a child of the turn's `ai.streamText` span.
+*
+* The `ai` SDK takes a span's parent from OpenTelemetry's active context, and
+* nothing tracks that here, so each of its spans would otherwise start a trace
+* of its own. A tracer is created per turn, so the turn span is known. With a
+* `parent`, the turn span itself starts under that span, e.g. the first turn
+* of the exchange it continues.
+*/
+var TurnTracer = class {
+	tracer;
+	parent;
+	turnSpan;
+	constructor(tracer, parent) {
+		this.tracer = tracer;
+		this.parent = parent;
+	}
+	startSpan(name, options, ctx = context.active()) {
+		if (name === TURN_SPAN_NAME) {
+			const parent = this.parent && {
+				traceId: this.parent.traceId,
+				spanId: this.parent.spanId,
+				traceFlags: TraceFlags.SAMPLED,
+				isRemote: true
+			};
+			this.turnSpan = this.tracer.startSpan(name, options, parent ? trace.setSpanContext(ctx, parent) : trace.deleteSpan(ctx));
+			return this.turnSpan;
+		}
+		const parent = this.turnSpan ? trace.setSpan(ctx, this.turnSpan) : ctx;
+		return this.tracer.startSpan(name, options, parent);
+	}
+	startActiveSpan(name, ...args) {
+		const fn = args[args.length - 1];
+		const options = args.length > 1 ? args[0] : void 0;
+		const ctx = args.length > 2 ? args[1] : context.active();
+		const span = this.startSpan(name, options, ctx);
+		return context.with(trace.setSpan(ctx, span), () => fn(span));
+	}
+};
+//#endregion
 //#region src/server/features/observability/index.ts
 const measuredEvents = /* @__PURE__ */ new Set(["chat:turn:finish"]);
 const warningEvents = /* @__PURE__ */ new Set([
@@ -721,16 +835,20 @@ var AgentSpanExporter = class {
 	auditLogs;
 	analytics;
 	context;
-	constructor(auditLogs, analytics, context) {
+	onTurnSpans;
+	turnSpans = [];
+	constructor(auditLogs, analytics, context, onTurnSpans) {
 		this.auditLogs = auditLogs;
 		this.analytics = analytics;
 		this.context = context;
+		this.onTurnSpans = onTurnSpans;
 	}
 	export(spans, resultCallback) {
 		(async () => {
 			try {
 				for (const span of spans) {
 					logAISpan(span, this.context);
+					this.collectTurnSpan(span);
 					if (span.name === "ai.streamText.doStream") {
 						rememberDoStream(span, this.context.durableObjectName);
 						attachToolCallsToChat(span, this.context.durableObjectName);
@@ -751,9 +869,84 @@ var AgentSpanExporter = class {
 		})();
 	}
 	async shutdown() {}
+	collectTurnSpan(span) {
+		if (!this.onTurnSpans) return;
+		this.turnSpans.push(span);
+		if (span.name !== "ai.streamText") return;
+		const spans = this.turnSpans;
+		this.turnSpans = [];
+		this.onTurnSpans(spans);
+	}
 };
-function createAgentTracer(auditLogs, analytics, context) {
-	return new BasicTracerProvider({ spanProcessors: [new SimpleSpanProcessor(new AgentSpanExporter(auditLogs, analytics, context))] }).getTracer("@economic/agents");
+function createAgentTracer(auditLogs, analytics, context, tracing) {
+	const exchange = tracing?.exchange;
+	return new TurnTracer(new BasicTracerProvider({
+		...exchange && !exchange.continues ? { idGenerator: new TurnIdGenerator(exchange) } : {},
+		spanProcessors: [new SimpleSpanProcessor(new AgentSpanExporter(auditLogs, analytics, context, tracing?.onTurnSpans))]
+	}).getTracer("@economic/agents"), exchange?.continues ? exchange : void 0);
+}
+//#endregion
+//#region src/server/features/telemetry/tracing.ts
+/** Hands completed turns and message ratings to an agent's tracing handlers, in the background. */
+var Tracing = class {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	/** Nothing when no handlers are configured. */
+	async turn(context, messages) {
+		try {
+			const handlers = this.options.getHandlers();
+			if (handlers.length === 0) return;
+			const identity = this.options.getIdentity();
+			return {
+				exchange: await getTurnExchange(identity.durableObjectName, messages),
+				onTurnSpans: (spans) => {
+					this.options.keepAlive(() => dispatch(handlers, {
+						type: "turn",
+						...identity,
+						context,
+						spans
+					}));
+				}
+			};
+		} catch (error) {
+			logOperationalError("agent.tracing.failed", error);
+			return;
+		}
+	}
+	feedback(messages, rating) {
+		this.sendFeedback(messages, rating).catch((error) => {
+			logOperationalError("agent.tracing.failed", error);
+		});
+	}
+	async sendFeedback(messages, rating) {
+		const handlers = this.options.getHandlers();
+		if (handlers.length === 0) return;
+		const identity = this.options.getIdentity();
+		await this.options.keepAlive(async () => {
+			const span = await createFeedbackSpan(identity.durableObjectName, messages, rating);
+			await dispatch(handlers, {
+				type: "feedback",
+				...identity,
+				...rating,
+				spans: span ? [span] : []
+			});
+		});
+	}
+};
+async function dispatch(handlers, event) {
+	await Promise.all(handlers.map(async (handler) => {
+		try {
+			await handler.handle(event);
+		} catch (error) {
+			logOperationalError("agent.tracing.handler.failed", error, {
+				agentName: event.agentName,
+				durableObjectName: event.durableObjectName,
+				attributes: { handler: handler.name ?? "handler" }
+			});
+		}
+	}));
 }
 //#endregion
 //#region src/server/features/analytics/utils.ts
@@ -770,16 +963,11 @@ const MAX_INDEX_BYTES = 96;
 const MAX_BLOB_BYTES = 16 * 1024;
 const encoder = new TextEncoder();
 /**
-* Creates a Cloudflare Analytics Engine destination for SDK analytics events.
-* It preserves the SDK v2 positional schema and never writes prompt content.
+* Writes an SDK analytics event to Cloudflare Analytics Engine. It preserves
+* the SDK v2 positional schema and never writes prompt content.
 */
-function createAnalyticsEngineHandler(dataset) {
-	return {
-		name: "Cloudflare Analytics Engine",
-		async handle(event) {
-			for (const point of toAnalyticsEnginePoints(event)) dataset.writeDataPoint(await boundAnalyticsPoint(point));
-		}
-	};
+async function writeAnalyticsEvent(dataset, event) {
+	for (const point of toAnalyticsEnginePoints(event)) dataset.writeDataPoint(await boundAnalyticsPoint(point));
 }
 async function boundAnalyticsPoint(point) {
 	return {
@@ -933,58 +1121,29 @@ function toAnalyticsEnginePoints(event) {
 	}
 }
 //#endregion
-//#region src/server/features/analytics/dispatcher.ts
-function createAnalyticsEvent(context, payload) {
-	return {
-		...payload,
-		schemaVersion: 1,
-		eventId: crypto.randomUUID(),
-		timestamp: Date.now(),
-		agentName: context.agentName,
-		durableObjectName: context.durableObjectName,
-		actorId: context.actorId,
-		attributes: context.attributes ?? {}
-	};
-}
-async function dispatchAnalyticsEvent(handlers, event) {
-	await Promise.all(handlers.map(async (handler) => {
-		try {
-			await handler.handle(event);
-		} catch (error) {
-			writeOperationalLog({
-				source: "@economic/agents",
-				event: "agent.analytics.handler.failed",
-				level: "error",
-				timestamp: Date.now(),
-				agentName: event.agentName,
-				durableObjectName: event.durableObjectName,
-				attributes: {
-					handler: handler.name ?? "handler",
-					error: error instanceof Error ? error.message : String(error)
-				}
-			});
-		}
-	}));
-}
-//#endregion
 //#region src/server/features/analytics/emitter.ts
 var Analytics = class {
 	options;
-	handlers;
 	constructor(options) {
 		this.options = options;
 	}
-	getHandlers() {
-		return this.handlers ??= this.options.getHandlers();
-	}
 	emit(payload) {
-		const handlers = this.getHandlers();
-		if (handlers.length === 0) return;
-		const eventPayload = typeof payload === "function" ? payload() : payload;
-		this.options.keepAlive(() => dispatchAnalyticsEvent(handlers, createAnalyticsEvent(this.context, eventPayload)));
+		const dataset = this.options.getDataset();
+		if (!dataset) return;
+		const event = createEvent(this.context, typeof payload === "function" ? payload() : payload);
+		this.options.keepAlive(async () => {
+			try {
+				await writeAnalyticsEvent(dataset, event);
+			} catch (error) {
+				logOperationalError("agent.analytics.write.failed", error, {
+					agentName: event.agentName,
+					durableObjectName: event.durableObjectName
+				});
+			}
+		});
 	}
 	get enabled() {
-		return this.getHandlers().length > 0;
+		return this.options.getDataset() !== void 0;
 	}
 	get context() {
 		return this.options.getContext();
@@ -1024,6 +1183,18 @@ var Analytics = class {
 		this.emit(payload);
 	}
 };
+function createEvent(context, payload) {
+	return {
+		...payload,
+		schemaVersion: 1,
+		eventId: crypto.randomUUID(),
+		timestamp: Date.now(),
+		agentName: context.agentName,
+		durableObjectName: context.durableObjectName,
+		actorId: context.actorId,
+		attributes: context.attributes ?? {}
+	};
+}
 //#endregion
 //#region src/server/features/registry.ts
 /**
@@ -1190,6 +1361,7 @@ var Agent = class extends Think {
 		const { tools, activeTools } = await this._prepareTools(ctx.tools, activeSkillName, true);
 		const baseSystem = await this.session.refreshSystemPrompt();
 		this._turn.baseSystem = [baseSystem, this._turn.skillsSystemBlock].filter(Boolean).join("\n\n");
+		const turnTracing = await this.tracing.turn(this._turn.context ?? {}, this.messages);
 		return {
 			system: this._turn.baseSystem,
 			model: this.getModel(this._turn.context),
@@ -1206,7 +1378,7 @@ var Agent = class extends Think {
 					actorId: this.getTelemetryActorId(),
 					clientIp: this.clientIp,
 					forwardedFor: this.forwardedFor
-				}),
+				}, turnTracing),
 				metadata: {
 					agentName: this.getTelemetryAgentName(),
 					version: "v2",
@@ -1735,14 +1907,23 @@ var Agent = class extends Think {
 			actorId: this.getTelemetryActorId(),
 			attributes: this.getAnalyticsAttributes()
 		}),
-		getHandlers: () => [...this.env.AGENTS_ANALYTICS ? [createAnalyticsEngineHandler(this.env.AGENTS_ANALYTICS)] : [], ...this.getAnalyticsHandlers()],
+		getDataset: () => this.env.AGENTS_ANALYTICS,
+		keepAlive: (callback) => this.keepAliveWhile(callback)
+	});
+	tracing = new Tracing({
+		getIdentity: () => ({
+			agentName: this.getTelemetryAgentName(),
+			durableObjectName: this.name,
+			actorId: this.getTelemetryActorId()
+		}),
+		getHandlers: () => this.getTracingHandlers(),
 		keepAlive: (callback) => this.keepAliveWhile(callback)
 	});
 	/**
-	* Additional product-analytics destinations for this agent. Analytics Engine
-	* remains enabled whenever `AGENTS_ANALYTICS` is bound.
+	* Destinations for completed turns and message feedback, e.g. a tracing
+	* service. They run in the background; a failing one never affects the chat.
 	*/
-	getAnalyticsHandlers() {
+	getTracingHandlers() {
 		return [];
 	}
 	/** Business dimensions added to every analytics event. */
@@ -2968,7 +3149,14 @@ var ChatAgent = class extends Agent {
 	async submitMessageFeedback(messageId, rating, comment) {
 		const result = submitMessageFeedback(this.sql.bind(this), messageId, rating, comment);
 		const parent = await this.getParentAgent();
-		if (rating === 1 || rating === -1 || rating === 0) this.analytics.feedbackSubmitted(messageId, rating);
+		if (rating === 1 || rating === -1 || rating === 0) {
+			this.analytics.feedbackSubmitted(messageId, rating);
+			this.tracing.feedback(this.messages, {
+				messageId,
+				rating,
+				comment
+			});
+		}
 		if (parent?.recordChatFeedback) try {
 			await parent.recordChatFeedback(this.name, messageId, rating);
 		} catch (error) {
@@ -3068,4 +3256,4 @@ function getCurrentToolContext() {
 	return getCurrentAgent().agent._lastBody;
 }
 //#endregion
-export { Agent, Assistant, ChatAgent, action, createAnalyticsEngineHandler, createAnalyticsEvent, createJwtAuthConfig, dispatchAnalyticsEvent, exchangeToken, getCurrentToolContext, routeAgentRequest, skill, tool };
+export { Agent, Assistant, ChatAgent, action, createJwtAuthConfig, exchangeToken, getCurrentToolContext, routeAgentRequest, skill, tool };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@economic/agents",
-  "version": "2.14.3",
+  "version": "2.15.0",
   "description": "A starter for creating a TypeScript package.",
   "license": "MIT",
   "files": [
@@ -26,6 +26,7 @@
     "@ai-sdk/google": "^3.0.73",
     "@cloudflare/ai-chat": "^0.11.0",
     "@cloudflare/think": "^0.17.0",
+    "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/sdk-trace-base": "^2.8.0",
     "agents": "^0.22.0",
     "ai": "^6.0.197",