The Open Framework for Building Agents
/**
* Serializes model and tool payloads into span content attributes for the
* local trace viewer: prompt messages, the system prompt, responses, and
* tool arguments/results. Everything is capped so a giant payload cannot
* bloat a span segment past the reader's per-file limit, and message
* payloads stay valid JSON through every truncation path.
*/
/** Content attributes are capped so a giant payload cannot bloat a span segment. */
export const CONTENT_ATTRIBUTE_LIMIT = 32 * 1024;
import type { ContentSerializer, InputMessagesContent } from "../core/types.js";
export const aiSdkContentSerializer: ContentSerializer = {
json: contentAttribute,
text: textContentAttribute,
inputMessages: (messages) =>
genAiInputMessagesAttribute(messages, (value) =>
typeof value === "string" ? value : undefined,
),
instructions: genAiSystemInstructionsAttribute,
toolDefinitions: genAiToolDefinitionsAttribute,
outputMessages: genAiOutputMessagesAttribute,
toolResults: toolResultsContentAttribute,
};
const encoder = new TextEncoder();
const decoder = new TextDecoder();
const MARKER = "... [truncated]";
export function telemetryByteLength(text: string): number {
return encoder.encode(text).length;
}
export function truncateTelemetryText(text: string, maxBytes: number): string {
const prefix = text.slice(0, maxBytes + 1);
const bytes = encoder.encode(prefix);
if (prefix.length === text.length && bytes.length <= maxBytes) return text;
const marker = MARKER.slice(0, maxBytes);
let end = Math.max(0, maxBytes - marker.length);
while (end > 0 && (bytes[end]! & 0xc0) === 0x80) end -= 1;
return decoder.decode(bytes.subarray(0, end)) + marker;
}
export function boundedPrincipalId(value: unknown): string | undefined {
return typeof value === "string" &&
value.length > 0 &&
value.length <= 1024 &&
telemetryByteLength(value) <= 1024
? value
: undefined;
}
export function boundedTraceError(value: Error): Error {
const error = new Error(truncateTelemetryText(value.message, 4096));
error.name = truncateTelemetryText(value.name, 128);
error.stack = value.stack === undefined ? undefined : truncateTelemetryText(value.stack, 8192);
return error;
}
/** Serializes one payload value as capped JSON. */
export function contentAttribute(value: unknown): string | undefined {
if (value === undefined) return undefined;
let json: string | undefined;
try {
json = JSON.stringify(value);
} catch {
return undefined;
}
if (json === undefined) return undefined;
return textContentAttribute(json);
}
/** Serializes model messages using the OpenTelemetry GenAI message schema. */
export function genAiInputMessagesAttribute(
messages: unknown,
messageKind?: (value: unknown) => string | undefined,
): InputMessagesContent | undefined {
if (!Array.isArray(messages)) return undefined;
const formatted = messages.flatMap((message) => {
if (!isRecord(message) || message.role === "system" || typeof message.role !== "string") {
return [];
}
const parts = semanticParts(message.content);
if (parts.length === 0) return [];
const kind = message.role === "user" ? messageKind?.(message.kind) : undefined;
return [
kind === undefined ? { parts, role: message.role } : { kind, parts, role: message.role },
];
});
for (let start = 0; start < formatted.length; start += 1) {
const json = semanticJsonAttribute(formatted.slice(start));
if (json !== undefined) return { json, omitted: start };
}
const newest = truncateSingleSemanticMessage(formatted);
if (newest !== undefined) return { json: newest, omitted: formatted.length - 1 };
return { json: "[]", omitted: formatted.length };
}
/** Serializes the system prompt using the OpenTelemetry GenAI instruction schema. */
export function genAiSystemInstructionsAttribute(instructions: unknown): string | undefined {
const text = systemPromptText(instructions);
if (text === undefined) return undefined;
return fitSemanticText(text, (content) => [{ content, type: "text" }]);
}
/** Serializes one model response using the OpenTelemetry GenAI message schema. */
export function genAiOutputMessagesAttribute(
content: readonly unknown[],
finishReason: string,
): string | undefined {
const parts = semanticParts(content);
const reason = finishReason === "tool-calls" ? "tool_call" : finishReason;
const message = (messageParts: unknown) => [
{ finish_reason: reason, parts: messageParts, role: "assistant" },
];
// An oversized response keeps a truncated text form, as an oversized prompt does.
return (
semanticJsonAttribute(message(parts)) ??
fitSemanticText(
semanticMessageText(parts),
(text) => message([{ content: text, type: "text" }]),
true,
)
);
}
/** Serializes memory records using the OpenTelemetry GenAI memory-records schema. */
export function genAiMemoryRecordsAttribute(records: readonly unknown[]): string | undefined {
return semanticJsonAttribute(records);
}
/**
* Serializes provider-executed tool results, keeping the attribute valid
* JSON under the cap: when the full payload is too big, each entry's input
* and output collapse to capped text at progressively smaller budgets
* instead of cutting the JSON mid-string.
*/
export function toolResultsContentAttribute(
results: readonly Record<string, unknown>[],
): string | undefined {
if (results.length === 0) return undefined;
const full = stringifyContent(results);
if (full !== undefined && full.length <= CONTENT_ATTRIBUTE_LIMIT) return full;
for (let cap = CONTENT_ATTRIBUTE_LIMIT; cap >= 0; cap = cap >= 256 ? Math.floor(cap / 2) : -1) {
const json = stringifyContent(results.map((entry) => cappedToolResult(entry, cap)));
if (json !== undefined && json.length <= CONTENT_ATTRIBUTE_LIMIT) return json;
}
return undefined;
}
function cappedToolResult(entry: Record<string, unknown>, cap: number): Record<string, unknown> {
const out: Record<string, unknown> = { toolName: entry.toolName };
for (const key of ["input", "output", "error"]) {
if (!(key in entry)) continue;
const value = entry[key];
const text = typeof value === "string" ? value : (stringifyContent(value) ?? "");
out[key] = text.length <= cap ? text : `${text.slice(0, cap)}… [truncated]`;
}
return out;
}
/** Serializes tool definitions, dropping trailing entries to keep the JSON whole. */
export function genAiToolDefinitionsAttribute(tools: unknown): string | undefined {
if (!Array.isArray(tools)) return undefined;
const definitions = tools.flatMap((tool): Record<string, unknown>[] => {
if (!isRecord(tool) || typeof tool.name !== "string") return [];
const definition: Record<string, unknown> = { name: tool.name };
if (typeof tool.description === "string") definition.description = tool.description;
if (tool.inputSchema !== undefined) definition.parameters = tool.inputSchema;
return [definition];
});
if (definitions.length === 0) return undefined;
const serialized: string[] = [];
let length = 2;
for (const definition of definitions) {
const json = stringifyContent(definition);
if (json === undefined) break;
const nextLength = length + (serialized.length === 0 ? 0 : 1) + json.length;
if (nextLength > CONTENT_ATTRIBUTE_LIMIT) break;
serialized.push(json);
length = nextLength;
}
return `[${serialized.join(",")}]`;
}
/** Normalizes the AI SDK's `instructions` prompt to plain text. */
function systemPromptText(instructions: unknown): string | undefined {
if (typeof instructions === "string") return instructions.length === 0 ? undefined : instructions;
if (!isRecord(instructions) && !Array.isArray(instructions)) return undefined;
const messages = Array.isArray(instructions) ? instructions : [instructions];
const texts: string[] = [];
for (const message of messages) {
if (!isRecord(message)) continue;
if (typeof message.content === "string") texts.push(message.content);
else if (Array.isArray(message.content))
for (const part of message.content)
if (isRecord(part) && part.type === "text" && typeof part.text === "string")
texts.push(part.text);
}
const joined = texts.join("\n\n").trim();
return joined.length === 0 ? undefined : joined;
}
/** Caps plain text, marking the cut. */
export function textContentAttribute(text: string): string | undefined {
if (text.length === 0) return undefined;
return text.length <= CONTENT_ATTRIBUTE_LIMIT
? text
: `${text.slice(0, CONTENT_ATTRIBUTE_LIMIT)}… [truncated]`;
}
function stringifyContent(value: unknown): string | undefined {
try {
return JSON.stringify(value);
} catch {
return undefined;
}
}
function semanticJsonAttribute(value: unknown): string | undefined {
const json = stringifyContent(value);
return json !== undefined && json.length <= CONTENT_ATTRIBUTE_LIMIT ? json : undefined;
}
function truncateSingleSemanticMessage(
messages: readonly Record<string, unknown>[],
): string | undefined {
const message = messages.at(-1);
if (message === undefined || typeof message.role !== "string") return undefined;
const text = semanticMessageText(message.parts);
const base =
typeof message.kind === "string"
? { kind: message.kind, role: message.role }
: { role: message.role };
return fitSemanticText(
text,
(content) => [{ ...base, parts: [{ content, type: "text" }] }],
true,
);
}
function fitSemanticText(
text: string,
wrap: (content: string) => unknown,
alwaysMark = false,
): string | undefined {
if (!alwaysMark && text.length <= CONTENT_ATTRIBUTE_LIMIT) {
const full = semanticJsonAttribute(wrap(text));
if (full !== undefined) return full;
}
for (let length = Math.min(text.length, CONTENT_ATTRIBUTE_LIMIT); length > 0; length -= 256) {
const json = semanticJsonAttribute(wrap(`${text.slice(0, length)}… [truncated]`));
if (json !== undefined) return json;
}
return semanticJsonAttribute(wrap("… [truncated]"));
}
function semanticMessageText(parts: unknown): string {
if (!Array.isArray(parts)) return "";
let text = "";
for (const part of parts) {
if (!isRecord(part) || part.type !== "text" || typeof part.content !== "string") continue;
const separator = text.length === 0 ? "" : "\n";
const remaining = CONTENT_ATTRIBUTE_LIMIT + 1 - text.length - separator.length;
if (remaining <= 0) break;
text += separator + part.content.slice(0, remaining);
}
return text;
}
function semanticParts(content: unknown): Record<string, unknown>[] {
if (typeof content === "string") return [{ content, type: "text" }];
if (!Array.isArray(content)) return [];
const parts: Record<string, unknown>[] = [];
for (const part of content) {
const formatted = semanticPart(part);
if (formatted !== undefined) parts.push(formatted);
}
return parts;
}
function semanticPart(value: unknown): Record<string, unknown> | undefined {
if (!isRecord(value) || typeof value.type !== "string") return undefined;
switch (value.type) {
case "text":
case "reasoning": {
const content = typeof value.text === "string" ? value.text : value.content;
return typeof content === "string" ? { content, type: value.type } : undefined;
}
case "tool-call":
return {
arguments: value.input,
id: stringValue(value.toolCallId) ?? stringValue(value.callId) ?? null,
name: value.toolName,
type: "tool_call",
};
case "tool-result":
return {
id: stringValue(value.toolCallId) ?? stringValue(value.callId) ?? null,
response: toolResponse(value.output),
type: "tool_call_response",
};
case "tool-error":
return {
id: stringValue(value.toolCallId) ?? stringValue(value.callId) ?? null,
response: value.error instanceof Error ? value.error.message : value.error,
type: "tool_call_response",
};
default:
return { type: value.type };
}
}
function toolResponse(output: unknown): unknown {
if (!isRecord(output)) return output;
if (
(output.type === "text" ||
output.type === "error-text" ||
output.type === "json" ||
output.type === "error-json") &&
"value" in output
) {
return output.value;
}
if (output.type === "execution-denied") {
return { denied: true, reason: output.reason };
}
return output;
}
function stringValue(value: unknown): string | undefined {
return typeof value === "string" ? value : undefined;
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value);
}