🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
refactor(normalized-io): preserve typed tool result output (#18599)
marliessophiecef4b1bf55f4
diff --git a/packages/shared/src/server/topics/trace-input.ts b/packages/shared/src/server/topics/trace-input.tsindex 71c7457b09..a507975621 100644--- a/packages/shared/src/server/topics/trace-input.ts+++ b/packages/shared/src/server/topics/trace-input.ts@@ -12,7 +12,7 @@ import {} from "../transcript";/** Historical summaries are reusable only with the same transcript producer. */-export const TOPICS_TRANSCRIPT_VERSION = "shared-transcript-v2";+export const TOPICS_TRANSCRIPT_VERSION = "shared-transcript-v3";const MAX_OBSERVATIONS = 2_000;const MAX_SNAPSHOT_BYTES = 10 * 1024 * 1024;diff --git a/packages/shared/src/server/transcript/fixtures/fixtures.test.ts b/packages/shared/src/server/transcript/fixtures/fixtures.test.tsindex 5fcc0f1ecb..2cab58cf5b 100644--- a/packages/shared/src/server/transcript/fixtures/fixtures.test.ts+++ b/packages/shared/src/server/transcript/fixtures/fixtures.test.ts@@ -472,8 +472,10 @@ describe("transcript fixtures", () => {const observations = fixture.observations.map((observation) =>convertObservation(createObservation(observation)),);+ const snapshot = structuredClone(observations);expect(assembleTranscript(orderObservations(observations))).toEqual(fixture.expected,);+ expect(observations).toEqual(snapshot);});});diff --git a/packages/shared/src/server/transcript/fixtures/index.ts b/packages/shared/src/server/transcript/fixtures/index.tsindex 7e862f3c5a..c25d01c84a 100644--- a/packages/shared/src/server/transcript/fixtures/index.ts+++ b/packages/shared/src/server/transcript/fixtures/index.ts@@ -7,6 +7,7 @@ import { supportCopilotFollowUpFixture } from "./trace/support-copilot-follow-upimport { standaloneToolObservationFixture } from "./trace/standalone-tool-observation";import { inheritedConversationHistoryFixture } from "./trace/inherited-conversation-history";import { replayedToolCallsWithLateReasoningFixture } from "./trace/replayed-tool-calls-with-late-reasoning";+import { chartToolsWithOmittedContentFixture } from "./trace/chart-tools-with-omitted-content";export type { TranscriptFixture } from "./fixture-types";@@ -19,4 +20,5 @@ export const transcriptFixtures: TranscriptFixture[] = [supportCopilotFollowUpFixture,inheritedConversationHistoryFixture,replayedToolCallsWithLateReasoningFixture,+ chartToolsWithOmittedContentFixture,];diff --git a/packages/shared/src/server/transcript/fixtures/trace/chart-tools-with-omitted-content.ts b/packages/shared/src/server/transcript/fixtures/trace/chart-tools-with-omitted-content.tsnew file mode 100644index 0000000000..206cfed3d3--- /dev/null+++ b/packages/shared/src/server/transcript/fixtures/trace/chart-tools-with-omitted-content.ts@@ -0,0 +1,444 @@+import type { TranscriptFixture } from "../fixture-types";++const traceId = "chart-tools-with-omitted-content";+const projectId = "transcript-fixture-project";+const request = "Generate a revenue chart and export its supporting files.";+const answer = "The revenue chart and its supporting files are ready.";+const calls = {+ role: "assistant",+ tool_calls: [+ {+ id: "call-chart",+ type: "function",+ function: { name: "generate_chart", arguments: "{}" },+ },+ {+ id: "call-image",+ type: "function",+ function: { name: "download_chart", arguments: "{}" },+ },+ {+ id: "call-annotations",+ type: "function",+ function: { name: "inspect_annotations", arguments: "{}" },+ },+ {+ id: "call-metadata",+ type: "function",+ function: { name: "get_chart_metadata", arguments: "{}" },+ },+ {+ id: "call-export",+ type: "function",+ function: { name: "export_chart", arguments: "{}" },+ },+ ],+};++export const chartToolsWithOmittedContentFixture: TranscriptFixture = {+ name: "Chart tool outputs preserve mixed/media content across generation replay",+ description:+ "Five tool executions return mixed text/JSON/media/custom content, media alone, custom content alone, a user-defined omittedContent key, and an explicit result with sibling media. Each becomes one tool result, preserving normalized content when the next generation replays all results.",+ observations: [+ {+ project_id: projectId,+ trace_id: traceId,+ id: "chart-agent",+ parent_observation_id: null,+ type: "AGENT",+ name: "Chart assistant",+ start_time: "2026-01-01T12:00:00.000Z",+ end_time: "2026-01-01T12:00:10.000Z",+ input: request,+ output: answer,+ },+ {+ project_id: projectId,+ trace_id: traceId,+ id: "chart-generation",+ parent_observation_id: "chart-agent",+ type: "GENERATION",+ name: "Plan chart tools",+ start_time: "2026-01-01T12:00:01.000Z",+ end_time: "2026-01-01T12:00:02.000Z",+ input: JSON.stringify([{ role: "user", content: request }]),+ output: JSON.stringify(calls),+ },+ {+ project_id: projectId,+ trace_id: traceId,+ id: "chart-tool",+ parent_observation_id: "chart-generation",+ type: "TOOL",+ name: "generate_chart",+ start_time: "2026-01-01T12:00:02.000Z",+ end_time: "2026-01-01T12:00:03.000Z",+ input: "{}",+ output: JSON.stringify({+ role: "tool",+ content: [+ { type: "text", text: "Revenue chart generated." },+ { points: 12 },+ {+ type: "image_url",+ image_url: { url: "https://example.com/revenue.png" },+ },+ { type: "vendor-chart", value: { chartId: "revenue" } },+ ],+ }),+ },+ {+ project_id: projectId,+ trace_id: traceId,+ id: "image-tool",+ parent_observation_id: "chart-generation",+ type: "TOOL",+ name: "download_chart",+ start_time: "2026-01-01T12:00:03.000Z",+ end_time: "2026-01-01T12:00:04.000Z",+ input: "{}",+ output: JSON.stringify({+ role: "tool",+ content: [+ {+ type: "image_url",+ image_url: { url: "https://example.com/revenue.png" },+ },+ ],+ }),+ },+ {+ project_id: projectId,+ trace_id: traceId,+ id: "annotations-tool",+ parent_observation_id: "chart-generation",+ type: "TOOL",+ name: "inspect_annotations",+ start_time: "2026-01-01T12:00:04.000Z",+ end_time: "2026-01-01T12:00:05.000Z",+ input: "{}",+ output: JSON.stringify({+ role: "tool",+ content: [+ { type: "vendor-annotations", value: { chartId: "revenue" } },+ ],+ }),+ },+ {+ project_id: projectId,+ trace_id: traceId,+ id: "metadata-tool",+ parent_observation_id: "chart-generation",+ type: "TOOL",+ name: "get_chart_metadata",+ start_time: "2026-01-01T12:00:05.000Z",+ end_time: "2026-01-01T12:00:06.000Z",+ input: "{}",+ output: JSON.stringify({+ role: "tool",+ content: [+ { omittedContent: "User-provided value" },+ {+ type: "image_url",+ image_url: { url: "https://example.com/revenue.png" },+ },+ ],+ }),+ },+ {+ project_id: projectId,+ trace_id: traceId,+ id: "export-tool",+ parent_observation_id: "chart-generation",+ type: "TOOL",+ name: "export_chart",+ start_time: "2026-01-01T12:00:06.000Z",+ end_time: "2026-01-01T12:00:07.000Z",+ input: "{}",+ output: JSON.stringify({+ role: "tool",+ content: [+ {+ type: "tool-result",+ toolCallId: "call-export",+ toolName: "export_chart",+ output: { exported: true },+ },+ {+ type: "image_url",+ image_url: { url: "https://example.com/export.png" },+ },+ ],+ }),+ },+ {+ project_id: projectId,+ trace_id: traceId,+ id: "summary-generation",+ parent_observation_id: "chart-agent",+ type: "GENERATION",+ name: "Summarize chart results",+ start_time: "2026-01-01T12:00:08.000Z",+ end_time: "2026-01-01T12:00:09.000Z",+ input: JSON.stringify([+ { role: "user", content: request },+ calls,+ {+ role: "tool",+ tool_call_id: "call-chart",+ content: "Revenue chart generated.",+ },+ {+ role: "tool",+ tool_call_id: "call-image",+ content: "Chart image downloaded.",+ },+ {+ role: "tool",+ tool_call_id: "call-annotations",+ content: "Chart annotations inspected.",+ },+ {+ role: "tool",+ tool_call_id: "call-metadata",+ content: "Chart metadata retrieved.",+ },+ {+ role: "tool",+ tool_call_id: "call-export",+ content: "Chart exported.",+ },+ ]),+ output: JSON.stringify({ role: "assistant", content: answer }),+ },+ ],+ expected: {+ threads: [+ {+ conversationHistory: [],+ currentTurn: {+ nestingLevel: 1,+ observations: [+ { id: "chart-generation", traceId },+ { id: "chart-tool", traceId },+ { id: "image-tool", traceId },+ { id: "annotations-tool", traceId },+ { id: "metadata-tool", traceId },+ { id: "export-tool", traceId },+ { id: "summary-generation", traceId },+ ],+ messages: [+ {+ role: "user",+ source: "input",+ observationId: "chart-generation",+ traceId,+ startTime: new Date("2026-01-01T12:00:01.000Z"),+ endTime: new Date("2026-01-01T12:00:02.000Z"),+ parts: [{ type: "text", text: request }],+ },+ {+ role: "assistant",+ source: "output",+ observationId: "chart-generation",+ traceId,+ startTime: new Date("2026-01-01T12:00:01.000Z"),+ endTime: new Date("2026-01-01T12:00:02.000Z"),+ parts: [+ {+ type: "tool-call",+ toolCallId: "call-chart",+ toolName: "generate_chart",+ input: {},+ toolType: "function",+ },+ {+ type: "tool-call",+ toolCallId: "call-image",+ toolName: "download_chart",+ input: {},+ toolType: "function",+ },+ {+ type: "tool-call",+ toolCallId: "call-annotations",+ toolName: "inspect_annotations",+ input: {},+ toolType: "function",+ },+ {+ type: "tool-call",+ toolCallId: "call-metadata",+ toolName: "get_chart_metadata",+ input: {},+ toolType: "function",+ },+ {+ type: "tool-call",+ toolCallId: "call-export",+ toolName: "export_chart",+ input: {},+ toolType: "function",+ },+ ],+ },+ {+ role: "tool",+ source: "output",+ observationId: "chart-tool",+ traceId,+ startTime: new Date("2026-01-01T12:00:02.000Z"),+ endTime: new Date("2026-01-01T12:00:03.000Z"),+ parts: [+ {+ type: "tool-result",+ toolCallId: "call-chart",+ toolName: "generate_chart",+ output: {+ type: "content",+ value: [+ { type: "text", text: "Revenue chart generated." },+ { type: "data", value: { points: 12 } },+ {+ type: "file",+ mediaType: "image/*",+ content: {+ kind: "url",+ url: "https://example.com/revenue.png",+ },+ },+ {+ type: "custom",+ kind: "vendor-chart",+ value: {+ type: "vendor-chart",+ value: { chartId: "revenue" },+ },+ },+ ],+ },+ },+ ],+ },+ {+ role: "tool",+ source: "output",+ observationId: "image-tool",+ traceId,+ startTime: new Date("2026-01-01T12:00:03.000Z"),+ endTime: new Date("2026-01-01T12:00:04.000Z"),+ parts: [+ {+ type: "tool-result",+ toolCallId: "call-image",+ toolName: "download_chart",+ output: {+ type: "content",+ value: [+ {+ type: "file",+ mediaType: "image/*",+ content: {+ kind: "url",+ url: "https://example.com/revenue.png",+ },+ },+ ],+ },+ },+ ],+ },+ {+ role: "tool",+ source: "output",+ observationId: "annotations-tool",+ traceId,+ startTime: new Date("2026-01-01T12:00:04.000Z"),+ endTime: new Date("2026-01-01T12:00:05.000Z"),+ parts: [+ {+ type: "tool-result",+ toolCallId: "call-annotations",+ toolName: "inspect_annotations",+ output: {+ type: "content",+ value: [+ {+ type: "custom",+ kind: "vendor-annotations",+ value: {+ type: "vendor-annotations",+ value: { chartId: "revenue" },+ },+ },+ ],+ },+ },+ ],+ },+ {+ role: "tool",+ source: "output",+ observationId: "metadata-tool",+ traceId,+ startTime: new Date("2026-01-01T12:00:05.000Z"),+ endTime: new Date("2026-01-01T12:00:06.000Z"),+ parts: [+ {+ type: "tool-result",+ toolCallId: "call-metadata",+ toolName: "get_chart_metadata",+ output: {+ type: "content",+ value: [+ {+ type: "data",+ value: { omittedContent: "User-provided value" },+ },+ {+ type: "file",+ mediaType: "image/*",+ content: {+ kind: "url",+ url: "https://example.com/revenue.png",+ },+ },+ ],+ },+ },+ ],+ },+ {+ role: "tool",+ source: "output",+ observationId: "export-tool",+ traceId,+ startTime: new Date("2026-01-01T12:00:06.000Z"),+ endTime: new Date("2026-01-01T12:00:07.000Z"),+ parts: [+ {+ type: "tool-result",+ toolCallId: "call-export",+ toolName: "export_chart",+ output: {+ type: "json",+ value: { exported: true },+ },+ },+ ],+ },+ {+ role: "assistant",+ source: "output",+ observationId: "summary-generation",+ traceId,+ startTime: new Date("2026-01-01T12:00:08.000Z"),+ endTime: new Date("2026-01-01T12:00:09.000Z"),+ parts: [{ type: "text", text: answer }],+ },+ ],+ },+ },+ ],+ },+};diff --git a/packages/shared/src/server/transcript/fixtures/trace/openai-agents-spanish-handoff.ts b/packages/shared/src/server/transcript/fixtures/trace/openai-agents-spanish-handoff.tsindex 9af7a59029..21a32bb233 100644--- a/packages/shared/src/server/transcript/fixtures/trace/openai-agents-spanish-handoff.ts+++ b/packages/shared/src/server/transcript/fixtures/trace/openai-agents-spanish-handoff.ts@@ -514,7 +514,8 @@ export const openaiAgentsSpanishHandoffFixture = {type: "tool-result",toolCallId: "call_i81vsF01rKH8cDZ0SLQQBUA2",output: {- assistant: "Spanish agent",+ type: "json",+ value: { assistant: "Spanish agent" },},},],diff --git a/packages/shared/src/server/transcript/fixtures/trace/replayed-tool-calls-with-late-reasoning.ts b/packages/shared/src/server/transcript/fixtures/trace/replayed-tool-calls-with-late-reasoning.tsindex 4664e84b63..fdb568de6e 100644--- a/packages/shared/src/server/transcript/fixtures/trace/replayed-tool-calls-with-late-reasoning.ts+++ b/packages/shared/src/server/transcript/fixtures/trace/replayed-tool-calls-with-late-reasoning.ts@@ -167,7 +167,14 @@ export const replayedToolCallsWithLateReasoningFixture = {},...results.map((value, index) => ({role: "tool" as const,- parts: [{ type: "data" as const, value }],+ parts: [+ {+ type: "tool-result" as const,+ toolCallId: calls[index]!.id,+ toolName: calls[index]!.name,+ output: { type: "json" as const, value },+ },+ ],source: "output" as const,...provenance(`synthetic-block-tool-${index + 1}`,diff --git a/packages/shared/src/server/transcript/fixtures/trace/support-copilot-follow-up.ts b/packages/shared/src/server/transcript/fixtures/trace/support-copilot-follow-up.tsindex 4e8838d405..d6f4b06afe 100644--- a/packages/shared/src/server/transcript/fixtures/trace/support-copilot-follow-up.ts+++ b/packages/shared/src/server/transcript/fixtures/trace/support-copilot-follow-up.ts@@ -99,7 +99,7 @@ const replayedHistory: NormalizedMessage[] = [{type: "tool-result",toolCallId: findChargesToolCallId,- output: charges,+ output: { type: "json", value: charges },},],},@@ -123,7 +123,7 @@ const replayedHistory: NormalizedMessage[] = [{type: "tool-result",toolCallId: createRefundToolCallId,- output: refund,+ output: { type: "json", value: refund },},],},diff --git a/packages/shared/src/server/transcript/fixtures/trace/support-copilot-refund-loop.ts b/packages/shared/src/server/transcript/fixtures/trace/support-copilot-refund-loop.tsindex b96cc8613d..27463d5c6c 100644--- a/packages/shared/src/server/transcript/fixtures/trace/support-copilot-refund-loop.ts+++ b/packages/shared/src/server/transcript/fixtures/trace/support-copilot-refund-loop.ts@@ -445,7 +445,14 @@ export const supportCopilotRefundLoopFixture = {startTime: new Date("2026-08-31T12:33:17.441Z"),endTime: new Date("2026-08-31T12:33:18.118Z"),traceId,- parts: [{ type: "data", value: charges }],+ parts: [+ {+ type: "tool-result",+ toolCallId: findChargesToolCallId,+ toolName: "stripe_find_charges",+ output: { type: "json", value: charges },+ },+ ],},{role: "assistant",@@ -471,7 +478,14 @@ export const supportCopilotRefundLoopFixture = {startTime: new Date("2026-08-31T12:33:19.978Z"),endTime: new Date("2026-08-31T12:33:20.893Z"),traceId,- parts: [{ type: "data", value: refund }],+ parts: [+ {+ type: "tool-result",+ toolCallId: createRefundToolCallId,+ toolName: "stripe_create_refund",+ output: { type: "json", value: refund },+ },+ ],},{role: "assistant",diff --git a/packages/shared/src/server/transcript/fixtures/trace/vercel-ai-sdk-docs-tool-loop.ts b/packages/shared/src/server/transcript/fixtures/trace/vercel-ai-sdk-docs-tool-loop.tsindex bce6997033..6ea9a083bf 100644--- a/packages/shared/src/server/transcript/fixtures/trace/vercel-ai-sdk-docs-tool-loop.ts+++ b/packages/shared/src/server/transcript/fixtures/trace/vercel-ai-sdk-docs-tool-loop.ts@@ -762,10 +762,14 @@ export const vercelAiSdkDocsToolLoopFixture: TranscriptFixture = {source: "output",parts: [{- type: "text",text: '{"content": [{"type": "document", "record_type": "documentation", "url": "https://langfuse.com/docs/evaluation/evaluation-methods/scores-via-sdk", "title": "Scores via API/SDK", "source": {"content": [{"type": "text", "text": "Scores via API/SDK - Langfuse\\n[Docs](/docs)\\n[Evaluation](/docs/evaluation/overview)\\n[Evaluation Methods](/docs/evaluation/evaluation-methods/llm-as-a-judge)\\n[Scores via API/SDK](/docs/evaluation/evaluation-methods/scores-via-sdk)\\n# Scores via API/SDK\\nYou can use the Langfuse SDKs or API to add [scores](/docs/evaluation/scores/overview) to traces, observations, sessions and dataset runs. This is an evaluation method that allows you to set up custom evaluation workflows and extend the scoring capabilities of Langfuse. See the [data model](/docs/evaluation/scores/data-model#scores) for full details on the score object.\\nIf you want Langfuse to run deterministic Python or TypeScript logic for you, use [code evaluators](/docs/evaluation/evaluation-methods/code-evaluators). Use this page when your application, pipeline, or CI job computes scores and sends them to Langfuse via API or SDK.\\n## Ingesting Scores via API/SDKs\\nScores can be attached at different levels of granularity: to individual traces, to specific observations within a trace, or to full sessions.\\nSee the [API reference](/docs/api) for full details on the POST and GET endpoints for scores and score configs.\\n### Trace or Observation-level Scores\\nYou can add scores via the Langfuse SDKs or API. Scores can take one of four data types: **Numeric** , **Categorical** , **Boolean** , or **Text**. See [Score Types](/docs/evaluation/scores/overview#score-types) for details.\\nIf a score is ingested manually using a `trace_id` to link the score to a trace, it is not necessary to wait until the trace has been created. The score will show up in the scores table and will be linked to the trace once the trace with the same `trace_id` is created.\\nHere are examples by `Score` data types."}, {"type": "text", "text": "\\nFor trace and observation scores, `trace_id`/`traceId` is required and `observation_id`/`observationId` is optional. If you attach a score to an observation, always provide both the observation ID and the corresponding trace ID.\\nPython SDKJS/TS SDKAPI\\nNumericCategoricalBooleanText\\nNumeric score values must be provided as float.\\n \\n \\n```\\nfrom langfuse import get_client\\nlangfuse = get_client()\\n///# Method 1: Score via low-level method\\nlangfuse.create_score(\\n name=\\"correctness\\",\\n value=0.9,\\n trace_id=\\"trace_id_here\\",\\n observation_id=\\"observation_id_here\\", ///# optional\\n data_type=\\"NUMERIC\\", ///# optional, inferred if not provided\\n comment=\\"Factually correct\\", ///# optional\\n)\\n///# Method 2: Score current span/generation (within context)\\nwith langfuse.start_as_current_observation(as_type=\\"span\\", name=\\"my-operation\\") as span:\\n # Score the current span\\n span.score(\\n name=\\"correctness\\",\\n value=0.9,\\n data_type=\\"NUMERIC\\",\\n comment=\\"Factually correct\\"\\n )\\n # Score the trace\\n span.score_trace(\\n name=\\"overall_quality\\",\\n value=0.95,\\n data_type=\\"NUMERIC\\"\\n )\\n///# Method 3: Score via the current context\\nwith langfuse.start_as_current_observation(as_type=\\"span\\", name=\\"my-operation\\"):\\n # Score the current span\\n langfuse.score_current_span(\\n name=\\"correctness\\",\\n value=0.9,\\n data_type=\\"NUMERIC\\",\\n comment=\\"Factually correct\\"\\n )\\n # Score the trace\\n langfuse.score_current_trace(\\n name=\\"overall_quality\\",\\n value=0.95,\\n data_type=\\"NUMERIC\\"\\n )\\n```\\nCategorical score values must be provided as strings.\\n \\n \\n```\\nfrom langfuse import get_client\\nlangfuse = get_client()\\n///# Method 1: Score via low-level method\\nlangfuse.create_score(\\n name=\\"accuracy\\",\\n value=\\"partially correct\\",\\n trace_id=\\"trace_id_here\\",\\n observation_id=\\"observation_id_here\\", ///# optional\\n data_type=\\"CATEGORICAL\\", ///# optional, inferred if not provided\\n comment=\\"Some factual errors\\", ///# optional\\n)"}, {"type": "text", "text": "\\n///# Method 2: Score current span/generation (within context)\\nwith langfuse.start_as_current_observation(as_type=\\"span\\", name=\\"my-operation\\") as span:\\n # Score the current span\\n span.score(\\n name=\\"accuracy\\",\\n value=\\"partially correct\\",\\n data_type=\\"CATEGORICAL\\",\\n comment=\\"Some factual errors\\"\\n )\\n # Score the trace\\n span.score_trace(\\n name=\\"overall_quality\\",\\n value=\\"partially correct\\",\\n data_type=\\"CATEGORICAL\\"\\n )\\n///# Method 3: Score via the current context\\nwith langfuse.start_as_current_observation(as_type=\\"span\\", name=\\"my-operation\\"):\\n # Score the current span\\n langfuse.score_current_span(\\n name=\\"accuracy\\",\\n value=\\"partially correct\\",\\n data_type=\\"CATEGORICAL\\",\\n comment=\\"Some factual errors\\"\\n )\\n # Score the trace\\n langfuse.score_current_trace(\\n name=\\"overall_quality\\",\\n value=\\"partially correct\\",\\n data_type=\\"CATEGORICAL\\"\\n )\\n```\\nBoolean scores must be provided as a float, where `1` is true and `0` is false. When read via the [v3 scores API](https://api.reference.langfuse.com/#tag/scoresv3/GET/api/public/v3/scores), the value is returned as a boolean. See [API reference](/docs/api) for more details on POST/GET scores endpoints.\\n \\n \\n```\\nfrom langfuse import get_client\\nlangfuse = get_client()\\n///# Method 1: Score via low-level method\\nlangfuse.create_score(\\n name=\\"helpfulness\\",\\n value=0, ///# 0 or 1\\n trace_id=\\"trace_id_here\\",\\n observation_id=\\"observation_id_here\\", ///# optional\\n data_type=\\"BOOLEAN\\", ///# required, numeric values without data type would be inferred as NUMERIC\\n comment=\\"Incorrect answer\\", ///# optional\\n)\\n///# Method 2: Score current span/generation (within context)\\nwith langfuse.start_as_current_observation(as_type=\\"span\\", name=\\"my-operation\\") as span:\\n # Score the current span"}, {"type": "text", "text": "\\n span.score(\\n name=\\"helpfulness\\",\\n value=1, ///# 0 or 1\\n data_type=\\"BOOLEAN\\",\\n comment=\\"Very helpful response\\"\\n )\\n # Score the trace\\n span.score_trace(\\n name=\\"overall_quality\\",\\n value=1, ///# 0 or 1\\n data_type=\\"BOOLEAN\\"\\n )\\n///# Method 3: Score via the current context\\nwith langfuse.start_as_current_observation(as_type=\\"span\\", name=\\"my-operation\\"):\\n # Score the current span\\n langfuse.score_current_span(\\n name=\\"helpfulness\\",\\n value=1, ///# 0 or 1\\n data_type=\\"BOOLEAN\\",\\n comment=\\"Very helpful response\\"\\n )\\n # Score the trace\\n langfuse.score_current_trace(\\n name=\\"overall_quality\\",\\n value=1, ///# 0 or 1\\n data_type=\\"BOOLEAN\\"\\n )\\n```\\nText score values must be provided as strings between 1 and 500 characters.\\n \\n \\n```\\nfrom langfuse import get_client\\nlangfuse = get_client()\\n///# Method 1: Score via low-level method\\nlangfuse.create_score(\\n name=\\"reviewer_notes\\",\\n value=\\"The response was helpful but could be more concise.\\",\\n trace_id=\\"trace_id_here\\",\\n observation_id=\\"observation_id_here\\", ///# optional\\n data_type=\\"TEXT\\", ///# optional, inferred if not provided\\n comment=\\"Reviewed by QA team\\", ///# optional\\n)\\n///# Method 2: Score current span/generation (within context)\\nwith langfuse.start_as_current_observation(as_type=\\"span\\", name=\\"my-operation\\") as span:\\n # Score the current span\\n span.score(\\n name=\\"reviewer_notes\\",\\n value=\\"The response was helpful but could be more concise.\\",\\n data_type=\\"TEXT\\",\\n comment=\\"Reviewed by QA team\\"\\n )\\n # Score the trace\\n span.score_trace(\\n name=\\"overall_notes\\",\\n value=\\"Good quality overall, minor formatting issues.\\",\\n data_type=\\"TEXT\\"\\n )\\n///# Method 3: Score via the current context\\nwith langfuse.start_as_current_observation(as_type=\\"span\\", name=\\"my-operation\\"):\\n # Score the current span"}, {"type": "text", "text": "\\n langfuse.score_current_span(\\n name=\\"reviewer_notes\\",\\n value=\\"The response was helpful but could be more concise.\\",\\n data_type=\\"TEXT\\",\\n comment=\\"Reviewed by QA team\\"\\n )\\n # Score the trace\\n langfuse.score_current_trace(\\n name=\\"overall_notes\\",\\n value=\\"Good quality overall, minor formatting issues.\\",\\n data_type=\\"TEXT\\"\\n )\\n```\\nNumericCategoricalBooleanText\\nNumeric score values must be provided as float.\\n \\n \\n```\\nimport { LangfuseClient } from \\"@langfuse/client\\";\\nconst langfuse = new LangfuseClient();\\nlangfuse.score.create({\\n id: \\"unique_id\\", // optional, can be used as an idempotency key to update the score subsequently\\n traceId: message.traceId,\\n observationId: message.generationId, // optional\\n name: \\"correctness\\",\\n value: 0.9,\\n dataType: \\"NUMERIC\\", // optional, inferred if not provided\\n comment: \\"Factually correct\\", // optional\\n});\\n// Flush the scores in short-lived environments\\nawait langfuse.flush();\\n```\\nCategorical score values must be provided as strings.\\n \\n \\n```\\nimport { LangfuseClient } from \\"@langfuse/client\\";\\nconst langfuse = new LangfuseClient();\\nlangfuse.score.create({\\n id: \\"unique_id\\", // optional, can be used as an idempotency key to update the score subsequently\\n traceId: message.traceId,\\n observationId: message.generationId, // optional\\n name: \\"accuracy\\",\\n value: \\"partially correct\\",\\n dataType: \\"CATEGORICAL\\", // optional, inferred if not provided\\n comment: \\"Factually correct\\", // optional\\n});\\n// Flush the scores in short-lived environments\\nawait langfuse.flush();\\n```"}, {"type": "text", "text": "\\nBoolean scores must be provided as a float, where `1` is true and `0` is false. When read via the [v3 scores API](https://api.reference.langfuse.com/#tag/scoresv3/GET/api/public/v3/scores), the value is returned as a boolean. See [API reference](/docs/api) for more details on POST/GET scores endpoints.\\n \\n \\n```\\nimport { LangfuseClient } from \\"@langfuse/client\\";\\nconst langfuse = new LangfuseClient();\\nlangfuse.score.create({\\n id: \\"unique_id\\", // optional, can be used as an idempotency key to update the score subsequently\\n traceId: message.traceId,\\n observationId: message.generationId, // optional\\n name: \\"helpfulness\\",\\n value: 0, // 0 or 1\\n dataType: \\"BOOLEAN\\", // required, numeric values without data type would be inferred as NUMERIC\\n comment: \\"Incorrect answer\\", // optional\\n});\\n// Flush the scores in short-lived environments\\nawait langfuse.flush();\\n```\\nText score values must be provided as strings between 1 and 500 characters.\\n \\n \\n```\\nimport { LangfuseClient } from \\"@langfuse/client\\";\\nconst langfuse = new LangfuseClient();\\nlangfuse.score.create({\\n id: \\"unique_id\\", // optional, can be used as an idempotency key to update the score subsequently\\n traceId: message.traceId,\\n observationId: message.generationId, // optional\\n name: \\"reviewer_notes\\",\\n value: \\"The response was helpful but could be more concise.\\",\\n dataType: \\"TEXT\\", // optional, inferred if not provided\\n comment: \\"Reviewed by QA team\\", // optional\\n});\\n// Flush the scores in short-lived environments\\nawait langfuse.flush();\\n```"}, {"type": "text", "text": "\\nYou can also create scores directly via the [REST API](https://api.reference.langfuse.com/#tag/legacyscorev1/POST/api/public/scores). Authenticate using HTTP Basic Auth with your Langfuse Public Key as username and Secret Key as password.\\nNumericCategoricalBooleanText\\nNumeric score values must be provided as float.\\n \\n \\n```\\ncurl -X POST https://cloud.langfuse.com/api/public/scores \\\\\\n -u \\"pk-lf-...\\":\\"sk-lf-...\\" \\\\\\n -H \\"Content-Type: application/json\\" \\\\\\n -d \'{\\n \\"traceId\\": \\"trace_id_here\\",\\n \\"observationId\\": \\"observation_id_here\\",\\n \\"name\\": \\"correctness\\",\\n \\"value\\": 0.9,\\n \\"dataType\\": \\"NUMERIC\\",\\n \\"comment\\": \\"Factually correct\\"\\n }\'\\n```\\nCategorical score values must be provided as strings.\\n \\n \\n```\\ncurl -X POST https://cloud.langfuse.com/api/public/scores \\\\\\n -u \\"pk-lf-...\\":\\"sk-lf-...\\" \\\\\\n -H \\"Content-Type: application/json\\" \\\\\\n -d \'{\\n \\"traceId\\": \\"trace_id_here\\",\\n \\"observationId\\": \\"observation_id_here\\",\\n \\"name\\": \\"accuracy\\",\\n \\"value\\": \\"partially correct\\",\\n \\"dataType\\": \\"CATEGORICAL\\",\\n \\"comment\\": \\"Some factual errors\\"\\n }\'\\n```\\nBoolean scores must be provided as a float, where `1` is true and `0` is false. When read via the [v3 scores API](https://api.reference.langfuse.com/#tag/scoresv3/GET/api/public/v3/scores), the value is returned as a boolean.\\n \\n \\n```\\ncurl -X POST https://cloud.langfuse.com/api/public/scores \\\\\\n -u \\"pk-lf-...\\":\\"sk-lf-...\\" \\\\\\n -H \\"Content-Type: application/json\\" \\\\\\n -d \'{\\n \\"traceId\\": \\"trace_id_here\\",\\n \\"observationId\\": \\"observation_id_here\\",\\n \\"name\\": \\"helpfulness\\",\\n \\"value\\": 0,\\n \\"dataType\\": \\"BOOLEAN\\",\\n \\"comment\\": \\"Incorrect answer\\"\\n }\'\\n```\\nText score values must be provided as strings between 1 and 500 characters.\\n \\n \\n```\\ncurl -X POST https://cloud.langfuse.com/api/public/scores \\\\\\n -u \\"pk-lf-...\\":\\"sk-lf-...\\" \\\\"}, {"type": "text", "text": "\\n comment=\\"Factually correct\\",\\n config_id=\\"12345-6565-3453654-43543\\",\\n data_type=\\"CATEGORICAL\\"\\n )\\n```\\nWhen ingesting boolean scores, you can provide the value as a float. If you provide a configId, the score\'s name and config\'s name must match as well as their data types.\\n \\n \\n```\\nfrom langfuse import get_client\\nlangfuse = get_client()\\n///# Method 1: Score via low-level method\\nlangfuse.create_score(\\n trace_id=\\"trace_id_here\\",\\n observation_id=\\"observation_id_here\\", ///# optional\\n name=\\"helpfulness\\",\\n value=1,\\n comment=\\"Factually correct\\", ///# optional\\n score_id=\\"unique_id\\", ///# optional, can be used as an idempotency key to update the score subsequently\\n config_id=\\"93547-6565-3453654-43543\\", ///# optional, can be used to infer the score data type and validate the score value\\n data_type=\\"BOOLEAN\\" # optional, possibly inferred\\n)\\n///# Method 2: Score within context\\nwith langfuse.start_as_current_observation(as_type=\\"span\\", name=\\"my-operation\\") as span:\\n span.score(\\n name=\\"helpfulness\\",\\n value=1,\\n comment=\\"Factually correct\\",\\n config_id=\\"93547-6565-3453654-43543\\",\\n data_type=\\"BOOLEAN\\"\\n )\\n```\\nWhen ingesting text scores, provide the value as a string (1–500 characters). If you provide a configId, the score\'s name and config\'s name must match as well as their data types.\\n \\n \\n```\\nfrom langfuse import get_client\\nlangfuse = get_client()\\n///# Method 1: Score via low-level method\\nlangfuse.create_score(\\n trace_id=\\"trace_id_here\\",\\n observation_id=\\"observation_id_here\\", ///# optional\\n name=\\"reviewer_notes\\",\\n value=\\"The response was helpful but could be more concise.\\",\\n comment=\\"Reviewed by QA team\\", ///# optional"}, {"type": "text", "text": "\\n score_id=\\"unique_id\\", ///# optional, can be used as an idempotency key to update the score subsequently\\n config_id=\\"24680-6565-3453654-43543\\", ///# optional\\n data_type=\\"TEXT\\" # optional, possibly inferred\\n)\\n///# Method 2: Score within context\\nwith langfuse.start_as_current_observation(as_type=\\"span\\", name=\\"my-operation\\") as span:\\n span.score(\\n name=\\"reviewer_notes\\",\\n value=\\"The response was helpful but could be more concise.\\",\\n comment=\\"Reviewed by QA team\\",\\n config_id=\\"24680-6565-3453654-43543\\",\\n data_type=\\"TEXT\\"\\n )\\n```\\nNumeric ScoresCategorical ScoresBoolean ScoresText Scores\\nWhen ingesting numeric scores, you can provide the value as a float. If you provide a configId, the score value will be validated against the config\'s numeric range, which might be defined by a minimum and/or maximum value.\\n \\n \\n```\\nimport { LangfuseClient } from \\"@langfuse/client\\";\\nconst langfuse = new LangfuseClient();\\nlangfuse.score.create({\\n traceId: message.traceId,\\n observationId: message.generationId, // optional\\n name: \\"accuracy\\",\\n value: 0.9,\\n comment: \\"Factually correct\\", // optional\\n id: \\"unique_id\\", // optional, can be used as an idempotency key to update the score subsequently\\n configId: \\"78545-6565-3453654-43543\\", // optional, to ensure that the score follows a specific min/max value range\\n dataType: \\"NUMERIC\\", // optional, possibly inferred\\n});\\n// Flush the scores in short-lived environments\\nawait langfuse.flush();\\n```\\nCategorical scores are used to evaluate data that falls into specific categories. When ingesting categorical scores, you can provide the value as a string. If you provide a configId, the score value will be validated against the config\'s categories.\\n \\n \\n```"}, {"type": "text", "text": "\\nimport { LangfuseClient } from \\"@langfuse/client\\";\\nconst langfuse = new LangfuseClient();\\nlangfuse.score.create({\\n traceId: message.traceId,\\n observationId: message.generationId, // optional\\n name: \\"correctness\\",\\n value: \\"correct\\",\\n comment: \\"Factually correct\\", // optional\\n id: \\"unique_id\\", // optional, can be used as an idempotency key to update the score subsequently\\n configId: \\"12345-6565-3453654-43543\\", // optional, to ensure that a score maps to a specific category defined in a score config\\n dataType: \\"CATEGORICAL\\", // optional, possibly inferred\\n});\\n// Flush the scores in short-lived environments\\nawait langfuse.flush();\\n```\\nWhen ingesting boolean scores, you can provide the value as a float. If you provide a configId, the score\'s name and config\'s name must match as well as their data types.\\n \\n \\n```\\nimport { LangfuseClient } from \\"@langfuse/client\\";\\nconst langfuse = new LangfuseClient();\\nlangfuse.score.create({\\n traceId: message.traceId,\\n observationId: message.generationId, // optional\\n name: \\"helpfulness\\",\\n value: 1,\\n comment: \\"Factually correct\\", // optional\\n id: \\"unique_id\\", // optional, can be used as an idempotency key to update the score subsequently\\n configId: \\"93547-6565-3453654-43543\\", // optional, can be used to infer the score data type and validate the score value\\n dataType: \\"BOOLEAN\\", // optional, possibly inferred\\n});\\n// Flush the scores in short-lived environments\\nawait langfuse.flush();\\n```\\nWhen ingesting text scores, provide the value as a string (1–500 characters). If you provide a configId, the score\'s name and config\'s name must match as well as their data types.\\n \\n \\n```\\nimport { LangfuseClient } from \\"@langfuse/client\\";\\nconst langfuse = new LangfuseClient();\\nlangfuse.score.create({\\n traceId: message.traceId,\\n observationId: message.generationId, // optional\\n name: \\"reviewer_notes\\",\\n value: \\"The response was helpful but could be more concise.\\","}, {"type": "text", "text": "\\nWhen ingesting boolean scores, you can provide the value as a float. If you provide a configId, the score\'s name and config\'s name must match as well as their data types.\\n \\n \\n```\\ncurl -X POST https://cloud.langfuse.com/api/public/scores \\\\\\n -u \\"pk-lf-...\\":\\"sk-lf-...\\" \\\\\\n -H \\"Content-Type: application/json\\" \\\\\\n -d \'{\\n \\"id\\": \\"unique_id\\",\\n \\"traceId\\": \\"trace_id_here\\",\\n \\"observationId\\": \\"observation_id_here\\",\\n \\"name\\": \\"helpfulness\\",\\n \\"value\\": 1,\\n \\"dataType\\": \\"BOOLEAN\\",\\n \\"configId\\": \\"93547-6565-3453654-43543\\",\\n \\"comment\\": \\"Factually correct\\"\\n }\'\\n```\\nWhen ingesting text scores, provide the value as a string (1–500 characters). If you provide a configId, the score\'s name and config\'s name must match as well as their data types.\\n \\n \\n```\\ncurl -X POST https://cloud.langfuse.com/api/public/scores \\\\\\n -u \\"pk-lf-...\\":\\"sk-lf-...\\" \\\\\\n -H \\"Content-Type: application/json\\" \\\\\\n -d \'{\\n \\"id\\": \\"unique_id\\",\\n \\"traceId\\": \\"trace_id_here\\",\\n \\"observationId\\": \\"observation_id_here\\",\\n \\"name\\": \\"reviewer_notes\\",\\n \\"value\\": \\"The response was helpful but could be more concise.\\",\\n \\"dataType\\": \\"TEXT\\",\\n \\"configId\\": \\"24680-6565-3453654-43543\\",\\n \\"comment\\": \\"Reviewed by QA team\\"\\n }\'\\n```\\nSee [API reference](/docs/api) for more details on POST/GET score configs endpoints.\\n### Inferred Score Properties\\nCertain score properties might be inferred based on your input:\\n * **If you don\'t provide a score data type** it will always be inferred. See tables below for details."}, {"type": "text", "text": "\\n * **For boolean and categorical scores** , we will provide the score value in both numerical and string format where possible. The score value format that is not provided as input, i.e. the translated value is referred to as the inferred value in the tables below.\\n * **On read via the[v3 scores API](https://api.reference.langfuse.com/#tag/scoresv3/GET/api/public/v3/scores)**, boolean scores are returned as a single boolean `value`.\\n * **For categorical scores** , the string representation is always provided and a numerical mapping of the category will be produced only if a `ScoreConfig` was provided.\\nDetailed Examples:\\nNumeric ScoresCategorical ScoresBoolean ScoresText Scores\\nFor example, let\'s assume you\'d like to ingest a numeric score to measure **accuracy**. We have included a table of possible score ingestion scenarios below.\\nValue| Data Type| Config Id| Description| Inferred Data Type| Valid \\n---|---|---|---|---|--- \\n`0.9`| `Null`| `Null`| Data type is inferred| `NUMERIC`| Yes \\n`0.9`| `NUMERIC`| `Null`| No properties inferred| | Yes \\n`depth`| `NUMERIC`| `Null`| Error: data type of value does not match provided data type| | No \\n`0.9`| `NUMERIC`| `78545`| No properties inferred| | Conditional on config validation \\n`0.9`| `Null`| `78545`| Data type inferred| `NUMERIC`| Conditional on config validation \\n`depth`| `NUMERIC`| `78545`| Error: data type of value does not match provided data type| | No \\n \\nFor example, let\'s assume you\'d like to ingest a categorical score to measure **correctness**. We have included a table of possible score ingestion scenarios below."}, {"type": "text", "text": "Value| Data Type| Config Id| Description| Inferred Data Type| Inferred Value representation| Valid \\n---|---|---|---|---|---|--- \\n`correct`| `Null`| `Null`| Data type is inferred| `CATEGORICAL`| | Yes \\n`correct`| `CATEGORICAL`| `Null`| No properties inferred| | | Yes \\n`1`| `CATEGORICAL`| `Null`| Error: data type of value does not match provided data type| | | No \\n`correct`| `CATEGORICAL`| `12345`| Numeric value inferred| | `4` numeric config category mapping| Conditional on config validation \\n`correct`| `NULL`| `12345`| Data type inferred| `CATEGORICAL`| | Conditional on config validation \\n`1`| `CATEGORICAL`| `12345`| Error: data type of value does not match provided data type| | | No \\n \\nFor example, let\'s assume you\'d like to ingest a boolean score to measure **helpfulness**. We have included a table of possible score ingestion scenarios below.\\nValue| Data Type| Config Id| Description| Inferred Data Type| Inferred Value representation| Valid \\n---|---|---|---|---|---|--- \\n`1`| `BOOLEAN`| `Null`| Value\'s string equivalent inferred| | `True`| Yes \\n`true`| `BOOLEAN`| `Null`| Error: data type of value does not match provided data type| | | No \\n`3`| `BOOLEAN`| `Null`| Error: boolean data type expects `0` or `1` as input value| | | No \\n`0.9`| `Null`| `93547`| Data type and value\'s string equivalent inferred| `BOOLEAN`| `True`| Conditional on config validation \\n`depth`| `BOOLEAN`| `93547`| Error: data type of value does not match provided data type| | | No \\n \\nFor example, let\'s assume you\'d like to ingest a text score to capture **reviewer notes**. Text scores must be non-empty strings of at most 500 characters.\\nValue| Data Type| Config Id| Description| Inferred Data Type| Valid "}, {"type": "text", "text": "---|---|---|---|---|--- \\n`\\"Good response\\"`| `Null`| `Null`| Data type is inferred| `TEXT`| Yes \\n`\\"Good response\\"`| `TEXT`| `Null`| No properties inferred| | Yes \\n`0.9`| `TEXT`| `Null`| Error: data type of value does not match provided data type| | No \\n`\\"Good response\\"`| `TEXT`| `24680`| No properties inferred| | Conditional on config validation \\n`\\"Good response\\"`| `Null`| `24680`| Data type inferred| `TEXT`| Conditional on config validation \\n`\\"\\"`| `TEXT`| `Null`| Error: text scores must be non-empty| | No \\n \\n## Update Existing Scores via API/SDKs\\nWhen creating a score, you can provide an optional `id` (JS/TS) / `score_id` (Python) parameter. A re-ingested score overwrites an existing one only when its `id`, `name`, and `timestamp` (at date granularity, `toDate(timestamp)`) all match — a matching `id` alone is not sufficient, and any difference creates a duplicate instead of an update.\\nTo overwrite a score without fetching existing scores first, set a stable `id` as an idempotency key when initially creating the score, and keep the `name` and `timestamp` unchanged on subsequent calls. See Preventing Duplicate Scores for details.\\n## Related guides\\nGuides\\n * [Collecting user feedback\\nCapture explicit and implicit user feedback as scores on your traces, including in-app ratings sent via our Browser SDK.\\n](/guides/user-feedback-loop)\\n * [Custom evaluation data pipeline\\nContinuously monitor quality by fetching traces, running custom evaluations, and ingesting scores back into Langfuse.\\n](/guides/cookbook/example_external_evaluation_pipelines)\\n * [Guardrails and security checks"}, {"type": "text", "text": "\\nCheck whether output contains a certain keyword, matches a required structure or format, or exceeds a length limit.\\n](/guides/cookbook/security-and-guardrails)\\n * [Custom internal workflow tooling\\nBuild internal tooling for human-in-the-loop workflows, ingesting scores back into Langfuse following your custom schema.\\n](/guides/human-in-the-loop-scoring)\\n * [Session-level quality tracking\\nScore full conversations, such as support chats or agent threads, by attaching scores via sessionId in the SDK or API.\\n](/guides/cookbook/example_evaluating_multi_turn_conversations)\\n* * *\\n* * *\\nLast edited 7/22/2026\\n"}], "type": "content"}}, {"type": "document", "record_type": "documentation", "url": "https://langfuse.com/docs/evaluation/evaluation-methods/scores-via-sdk", "title": "Scores via API/SDK", "source": {"content": [{"type": "text", "text": "# Scores via API/SDK\\nYou can use the Langfuse SDKs or API to add [scores](/docs/evaluation/scores/overview) to traces, observations, sessions and dataset runs. This is an evaluation method that allows you to set up custom evaluation workflows and extend the scoring capabilities of Langfuse. See the [data model](/docs/evaluation/scores/data-model#scores) for full details on the score object.\\nIf you want Langfuse to run deterministic Python or TypeScript logic for you, use [code evaluators](/docs/evaluation/evaluation-methods/code-evaluators). Use this page when your application, pipeline, or CI job computes scores and sends them to Langfuse via API or SDK.\\n\\n## Ingesting Scores via API/SDKs\\nScores can be attached at different levels of granularity: to individual traces, to specific observations within a trace, or to full sessions.\\nSee the [API reference](/docs/api) for full details on the POST and GET endpoints for scores and score configs.\\n### Trace or Observation-level Scores\\nYou can add scores via the Langfuse SDKs or API. Scores can take one of four data types: **Numeric** , **Categorical** , **Boolean** , or **Text**. See [Score Types](/docs/evaluation/scores/overview#score-types) for details.\\nIf a score is ingested manually using a `trace_id` to link the score to a trace, it is not necessary to wait until the trace has been created. The score will show up in the scores table and will be linked to the trace once the trace with the same `trace_id` is created.\\nHere are examples by `Score` data types.\\nFor trace and observation scores, `trace_id`/`traceId` is required and `observation_id`/`observationId` is optional. If you attach a score to an observation, always provide both the observation ID and the corresponding trace ID.\\nPython SDKJS/TS SDKAPI\\nNumericCategoricalBooleanText\\nNumeric score values must be provided as float.\\n \\n \\n```"}, {"type": "text", "text": "\\nfrom langfuse import get_client\\nlangfuse = get_client()\\n# Method 1: Score via low-level method\\nlangfuse.create_score(\\n name=\\"correctness\\",\\n value=0.9,\\n trace_id=\\"trace_id_here\\",\\n observation_id=\\"observation_id_here\\", # optional\\n data_type=\\"NUMERIC\\", # optional, inferred if not provided\\n comment=\\"Factually correct\\", # optional\\n)\\n# Method 2: Score current span/generation (within context)\\nwith langfuse.start_as_current_observation(as_type=\\"span\\", name=\\"my-operation\\") as span:\\n # Score the current span\\n span.score(\\n name=\\"correctness\\",\\n value=0.9,\\n data_type=\\"NUMERIC\\",\\n comment=\\"Factually correct\\"\\n )\\n # Score the trace\\n span.score_trace(\\n name=\\"overall_quality\\",\\n value=0.95,\\n data_type=\\"NUMERIC\\"\\n )\\n# Method 3: Score via the current context\\nwith langfuse.start_as_current_observation(as_type=\\"span\\", name=\\"my-operation\\"):\\n # Score the current span\\n langfuse.score_current_span(\\n name=\\"correctness\\",\\n value=0.9,\\n data_type=\\"NUMERIC\\",\\n comment=\\"Factually correct\\"\\n )\\n # Score the trace\\n langfuse.score_current_trace(\\n name=\\"overall_quality\\",\\n value=0.95,\\n data_type=\\"NUMERIC\\"\\n )\\n```\\nCategorical score values must be provided as strings.\\n \\n \\n```\\nfrom langfuse import get_client\\nlangfuse = get_client()\\n# Method 1: Score via low-level method\\nlangfuse.create_score(\\n name=\\"accuracy\\",\\n value=\\"partially correct\\",\\n trace_id=\\"trace_id_here\\",\\n observation_id=\\"observation_id_here\\", # optional\\n data_type=\\"CATEGORICAL\\", # optional, inferred if not provided\\n comment=\\"Some factual errors\\", # optional\\n)\\n# Method 2: Score current span/generation (within context)\\nwith langfuse.start_as_current_observation(as_type=\\"span\\", name=\\"my-operation\\") as span:\\n # Score the current span\\n span.score(\\n name=\\"accuracy\\",\\n value=\\"partially correct\\",\\n data_type=\\"CATEGORICAL\\",\\n comment=\\"Some factual errors\\"\\n )\\n # Score the trace\\n span.score_trace(\\n name=\\"overall_quality\\",\\n value=\\"partially correct\\","}, {"type": "text", "text": "\\n data_type=\\"CATEGORICAL\\"\\n )\\n# Method 3: Score via the current context\\nwith langfuse.start_as_current_observation(as_type=\\"span\\", name=\\"my-operation\\"):\\n # Score the current span\\n langfuse.score_current_span(\\n name=\\"accuracy\\",\\n value=\\"partially correct\\",\\n data_type=\\"CATEGORICAL\\",\\n comment=\\"Some factual errors\\"\\n )\\n # Score the trace\\n langfuse.score_current_trace(\\n name=\\"overall_quality\\",\\n value=\\"partially correct\\",\\n data_type=\\"CATEGORICAL\\"\\n )\\n```\\nBoolean scores must be provided as a float, where `1` is true and `0` is false. When read via the [v3 scores API](https://api.reference.langfuse.com/#tag/scoresv3/GET/api/public/v3/scores), the value is returned as a boolean. See [API reference](/docs/api) for more details on POST/GET scores endpoints.\\n \\n \\n```\\nfrom langfuse import get_client\\nlangfuse = get_client()\\n# Method 1: Score via low-level method\\nlangfuse.create_score(\\n name=\\"helpfulness\\",\\n value=0, # 0 or 1\\n trace_id=\\"trace_id_here\\",\\n observation_id=\\"observation_id_here\\", # optional\\n data_type=\\"BOOLEAN\\", # required, numeric values without data type would be inferred as NUMERIC\\n comment=\\"Incorrect answer\\", # optional\\n)\\n# Method 2: Score current span/generation (within context)\\nwith langfuse.start_as_current_observation(as_type=\\"span\\", name=\\"my-operation\\") as span:\\n # Score the current span\\n span.score(\\n name=\\"helpfulness\\",\\n value=1, # 0 or 1\\n data_type=\\"BOOLEAN\\",\\n comment=\\"Very helpful response\\"\\n )\\n # Score the trace\\n span.score_trace(\\n name=\\"overall_quality\\",\\n value=1, # 0 or 1\\n data_type=\\"BOOLEAN\\"\\n )\\n# Method 3: Score via the current context\\nwith langfuse.start_as_current_observation(as_type=\\"span\\", name=\\"my-operation\\"):\\n # Score the current span\\n langfuse.score_current_span(\\n name=\\"helpfulness\\","}, {"type": "text", "text": "\\n value=1, # 0 or 1\\n data_type=\\"BOOLEAN\\",\\n comment=\\"Very helpful response\\"\\n )\\n # Score the trace\\n langfuse.score_current_trace(\\n name=\\"overall_quality\\",\\n value=1, # 0 or 1\\n data_type=\\"BOOLEAN\\"\\n )\\n```\\nText score values must be provided as strings between 1 and 500 characters.\\n \\n \\n```\\nfrom langfuse import get_client\\nlangfuse = get_client()\\n# Method 1: Score via low-level method\\nlangfuse.create_score(\\n name=\\"reviewer_notes\\",\\n value=\\"The response was helpful but could be more concise.\\",\\n trace_id=\\"trace_id_here\\",\\n observation_id=\\"observation_id_here\\", # optional\\n data_type=\\"TEXT\\", # optional, inferred if not provided\\n comment=\\"Reviewed by QA team\\", # optional\\n)\\n# Method 2: Score current span/generation (within context)\\nwith langfuse.start_as_current_observation(as_type=\\"span\\", name=\\"my-operation\\") as span:\\n # Score the current span\\n span.score(\\n name=\\"reviewer_notes\\",\\n value=\\"The response was helpful but could be more concise.\\",\\n data_type=\\"TEXT\\",\\n comment=\\"Reviewed by QA team\\"\\n )\\n # Score the trace\\n span.score_trace(\\n name=\\"overall_notes\\",\\n value=\\"Good quality overall, minor formatting issues.\\",\\n data_type=\\"TEXT\\"\\n )\\n# Method 3: Score via the current context\\nwith langfuse.start_as_current_observation(as_type=\\"span\\", name=\\"my-operation\\"):\\n # Score the current span\\n langfuse.score_current_span(\\n name=\\"reviewer_notes\\",\\n value=\\"The response was helpful but could be more concise.\\",\\n data_type=\\"TEXT\\",\\n comment=\\"Reviewed by QA team\\"\\n )\\n # Score the trace\\n langfuse.score_current_trace(\\n name=\\"overall_notes\\",\\n value=\\"Good quality overall, minor formatting issues.\\",\\n data_type=\\"TEXT\\"\\n )\\n```\\nNumericCategoricalBooleanText\\nNumeric score values must be provided as float.\\n \\n \\n```"}, {"type": "text", "text": "\\nimport { LangfuseClient } from \\"@langfuse/client\\";\\nconst langfuse = new LangfuseClient();\\nlangfuse.score.create({\\n id: \\"unique_id\\", // optional, can be used as an idempotency key to update the score subsequently\\n traceId: message.traceId,\\n observationId: message.generationId, // optional\\n name: \\"correctness\\",\\n value: 0.9,\\n dataType: \\"NUMERIC\\", // optional, inferred if not provided\\n comment: \\"Factually correct\\", // optional\\n});\\n// Flush the scores in short-lived environments\\nawait langfuse.flush();\\n```\\nCategorical score values must be provided as strings.\\n \\n \\n```\\nimport { LangfuseClient } from \\"@langfuse/client\\";\\nconst langfuse = new LangfuseClient();\\nlangfuse.score.create({\\n id: \\"unique_id\\", // optional, can be used as an idempotency key to update the score subsequently\\n traceId: message.traceId,\\n observationId: message.generationId, // optional\\n name: \\"accuracy\\",\\n value: \\"partially correct\\",\\n dataType: \\"CATEGORICAL\\", // optional, inferred if not provided\\n comment: \\"Factually correct\\", // optional\\n});\\n// Flush the scores in short-lived environments\\nawait langfuse.flush();\\n```\\nBoolean scores must be provided as a float, where `1` is true and `0` is false. When read via the [v3 scores API](https://api.reference.langfuse.com/#tag/scoresv3/GET/api/public/v3/scores), the value is returned as a boolean. See [API reference](/docs/api) for more details on POST/GET scores endpoints.\\n \\n \\n```\\nimport { LangfuseClient } from \\"@langfuse/client\\";\\nconst langfuse = new LangfuseClient();\\nlangfuse.score.create({\\n id: \\"unique_id\\", // optional, can be used as an idempotency key to update the score subsequently\\n traceId: message.traceId,\\n observationId: message.generationId, // optional"}, {"type": "text", "text": "\\nnpm install @langfuse/browser\\n```\\n \\n \\n```\\nimport { LangfuseBrowserClient } from \\"@langfuse/browser\\";\\nconst langfuse = new LangfuseBrowserClient({\\n publicKey: process.env.NEXT_PUBLIC_LANGFUSE_PUBLIC_KEY!,\\n baseUrl: process.env.NEXT_PUBLIC_LANGFUSE_BASE_URL, // optional, defaults to https://cloud.langfuse.com\\n});\\nawait langfuse.score({\\n traceId: message.traceId,\\n observationId: message.generationId, // optional\\n id: `user-feedback-${message.traceId}`, // optional, use as an idempotency key\\n name: \\"user-feedback\\",\\n value: 1, // 1 for positive, 0 for negative\\n dataType: \\"BOOLEAN\\",\\n comment: \\"Helpful answer\\", // optional\\n});\\n```\\n`score()` returns `{ id }` after ingestion succeeds. No `flush()` call is required.\\n### Session-level Scores\\nTo score an entire session (without attaching the score to a trace or observation), provide only `session_id` (Python SDK) or `sessionId` (JS/TS SDK and API).\\nPython SDKJS/TS SDKAPI\\n \\n \\n```\\nfrom langfuse import get_client\\nlangfuse = get_client()\\nlangfuse.create_score(\\n name=\\"session_quality\\",\\n value=0.85,\\n session_id=\\"session_id_here\\",\\n data_type=\\"NUMERIC\\",\\n comment=\\"Overall conversation quality\\"\\n)\\n```\\n \\n \\n```\\nimport { LangfuseClient } from \\"@langfuse/client\\";\\nconst langfuse = new LangfuseClient();\\nlangfuse.score.create({\\n name: \\"session_quality\\",\\n value: 0.85,\\n sessionId: \\"session_id_here\\",\\n dataType: \\"NUMERIC\\",\\n comment: \\"Overall conversation quality\\",\\n});\\nawait langfuse.flush();\\n```\\n \\n \\n```\\ncurl -X POST https://cloud.langfuse.com/api/public/scores \\\\\\n -u \\"pk-lf-...\\":\\"sk-lf-...\\" \\\\\\n -H \\"Content-Type: application/json\\" \\\\\\n -d \'{\\n \\"sessionId\\": \\"session_id_here\\",\\n \\"name\\": \\"session_quality\\",\\n \\"value\\": 0.85,\\n \\"dataType\\": \\"NUMERIC\\",\\n \\"comment\\": \\"Overall conversation quality\\"\\n }\'\\n```\\n"}], "type": "content"}}, {"type": "document", "record_type": "documentation", "url": "https://langfuse.com/docs/evaluation/evaluation-methods/scores-via-sdk", "title": "Scores via API/SDK", "source": {"content": [{"type": "text", "text": "## Advanced\\n### Preventing Duplicate Scores\\nBy default, Langfuse allows for multiple scores of the same `name` on the same trace. This is useful if you\'d like to track the evolution of a score over time or if e.g. you\'ve received multiple user feedback scores on the same trace.\\nIn some cases, you want to prevent this behavior or overwrite an existing score. A score is identified by three fields — its `id`, its `name`, and its date (`toDate(timestamp)`) — and a new score only replaces an existing one when all three match. To achieve this, create an **idempotency key** and pass it as the `id` (JS/TS) / `score_id` (Python) when creating the score (for example `trace_id-score_name`), and keep the `name` and `timestamp` unchanged across calls. If any of the three differs — for example the same `id` with a different `name` — you get an additional score rather than a replacement.\\nDo not send partial score updates (only the changed fields) and rely on Langfuse to merge them into the existing record. This merge only happens for a limited window after creation, is deprecated, and will be removed. Always send the complete score.\\nSee [How to update traces, observations, and scores](/faq/all/tracing-data-updates#updating-scores) for more details on Langfuse\'s immutable data model.\\n### Enforcing a Score Config\\nScore configs are helpful when you want to standardize your scores for future analysis.\\nTo enforce a score config, you can provide a `configId` when creating a score to reference a `ScoreConfig` that was previously created. `Score Configs` can be defined in the Langfuse UI or via our API. [See our guide on how to create and manage score configs](/faq/all/manage-score-configs).\\nWhenever you provide a `ScoreConfig`, the score data will be validated against the config. The following rules apply:\\n * **Score Name** : Must equal the config\'s name"}, {"type": "text", "text": "\\n * **Score Data Type** : When provided, must match the config\'s data type\\n * **Score Value when Type is`NUMERIC`**: Value must be within the min and max values defined in the config (if provided, min and max are optional and otherwise are assumed as -∞ and +∞ respectively)\\n * **Score Value when Type is`CATEGORICAL`**: Value must map to one of the categories defined in the config\\n * **Score Value when Type is`BOOLEAN`**: Value must equal `0` or `1`\\n * **Score Value when Type is`TEXT`**: Value must be a non-empty string of at most 500 characters\\nPython SDKJS/TS SDKAPI\\nNumeric ScoresCategorical ScoresBoolean ScoresText Scores\\nWhen ingesting numeric scores, you can provide the value as a float. If you provide a configId, the score value will be validated against the config\'s numeric range, which might be defined by a minimum and/or maximum value.\\n \\n \\n```\\nfrom langfuse import get_client\\nlangfuse = get_client()\\n# Method 1: Score via low-level method\\nlangfuse.create_score(\\n trace_id=\\"trace_id_here\\",\\n observation_id=\\"observation_id_here\\", # optional\\n session_id=\\"session_id_here\\", # optional, ID of the session the score relates to\\n name=\\"accuracy\\",\\n value=0.9,\\n comment=\\"Factually correct\\", # optional\\n score_id=\\"unique_id\\", # optional, can be used as an idempotency key to update the score subsequently\\n config_id=\\"78545-6565-3453654-43543\\", # optional, to ensure that the score follows a specific min/max value range\\n data_type=\\"NUMERIC\\" # optional, possibly inferred\\n)\\n# Method 2: Score within context\\nwith langfuse.start_as_current_observation(as_type=\\"span\\", name=\\"my-operation\\") as span:\\n span.score(\\n name=\\"accuracy\\",\\n value=0.9,\\n comment=\\"Factually correct\\",\\n config_id=\\"78545-6565-3453654-43543\\",\\n data_type=\\"NUMERIC\\"\\n )\\n```"}, {"type": "text", "text": "\\nWhen ingesting numeric scores, you can provide the value as a float. If you provide a configId, the score value will be validated against the config\'s numeric range, which might be defined by a minimum and/or maximum value.\\n \\n \\n```\\nimport { LangfuseClient } from \\"@langfuse/client\\";\\nconst langfuse = new LangfuseClient();\\nlangfuse.score.create({\\n traceId: message.traceId,\\n observationId: message.generationId, // optional\\n name: \\"accuracy\\",\\n value: 0.9,\\n comment: \\"Factually correct\\", // optional\\n id: \\"unique_id\\", // optional, can be used as an idempotency key to update the score subsequently\\n configId: \\"78545-6565-3453654-43543\\", // optional, to ensure that the score follows a specific min/max value range\\n dataType: \\"NUMERIC\\", // optional, possibly inferred\\n});\\n// Flush the scores in short-lived environments\\nawait langfuse.flush();\\n```\\nCategorical scores are used to evaluate data that falls into specific categories. When ingesting categorical scores, you can provide the value as a string. If you provide a configId, the score value will be validated against the config\'s categories.\\n \\n \\n```\\nimport { LangfuseClient } from \\"@langfuse/client\\";\\nconst langfuse = new LangfuseClient();\\nlangfuse.score.create({\\n traceId: message.traceId,\\n observationId: message.generationId, // optional\\n name: \\"correctness\\",\\n value: \\"correct\\",\\n comment: \\"Factually correct\\", // optional\\n id: \\"unique_id\\", // optional, can be used as an idempotency key to update the score subsequently\\n configId: \\"12345-6565-3453654-43543\\", // optional, to ensure that a score maps to a specific category defined in a score config\\n dataType: \\"CATEGORICAL\\", // optional, possibly inferred\\n});"}, {"type": "text", "text": "\\nYou can also enforce score configs via the [REST API](https://api.reference.langfuse.com/#tag/legacyscorev1/POST/api/public/scores) by providing a `configId`.\\nNumeric ScoresCategorical ScoresBoolean ScoresText Scores\\nWhen ingesting numeric scores, you can provide the value as a float. If you provide a configId, the score value will be validated against the config\'s numeric range.\\n \\n \\n```\\ncurl -X POST https://cloud.langfuse.com/api/public/scores \\\\\\n -u \\"pk-lf-...\\":\\"sk-lf-...\\" \\\\\\n -H \\"Content-Type: application/json\\" \\\\\\n -d \'{\\n \\"id\\": \\"unique_id\\",\\n \\"traceId\\": \\"trace_id_here\\",\\n \\"observationId\\": \\"observation_id_here\\",\\n \\"name\\": \\"accuracy\\",\\n \\"value\\": 0.9,\\n \\"dataType\\": \\"NUMERIC\\",\\n \\"configId\\": \\"78545-6565-3453654-43543\\",\\n \\"comment\\": \\"Factually correct\\"\\n }\'\\n```\\nCategorical scores are used to evaluate data that falls into specific categories. If you provide a configId, the score value will be validated against the config\'s categories.\\n \\n \\n```\\ncurl -X POST https://cloud.langfuse.com/api/public/scores \\\\\\n -u \\"pk-lf-...\\":\\"sk-lf-...\\" \\\\\\n -H \\"Content-Type: application/json\\" \\\\\\n -d \'{\\n \\"id\\": \\"unique_id\\",\\n \\"traceId\\": \\"trace_id_here\\",\\n \\"observationId\\": \\"observation_id_here\\",\\n \\"name\\": \\"correctness\\",\\n \\"value\\": \\"correct\\",\\n \\"dataType\\": \\"CATEGORICAL\\",\\n \\"configId\\": \\"12345-6565-3453654-43543\\",\\n \\"comment\\": \\"Factually correct\\"\\n }\'\\n```\\nWhen ingesting boolean scores, you can provide the value as a float. If you provide a configId, the score\'s name and config\'s name must match as well as their data types.\\n \\n \\n```\\ncurl -X POST https://cloud.langfuse.com/api/public/scores \\\\\\n -u \\"pk-lf-...\\":\\"sk-lf-...\\" \\\\\\n -H \\"Content-Type: application/json\\" \\\\\\n -d \'{\\n \\"id\\": \\"unique_id\\",\\n \\"traceId\\": \\"trace_id_here\\",\\n \\"observationId\\": \\"observation_id_here\\",\\n \\"name\\": \\"helpfulness\\","}, {"type": "text", "text": "\\n \\"value\\": 1,\\n \\"dataType\\": \\"BOOLEAN\\",\\n \\"configId\\": \\"93547-6565-3453654-43543\\",\\n \\"comment\\": \\"Factually correct\\"\\n }\'\\n```\\nWhen ingesting text scores, provide the value as a string (1–500 characters). If you provide a configId, the score\'s name and config\'s name must match as well as their data types.\\n \\n \\n```\\ncurl -X POST https://cloud.langfuse.com/api/public/scores \\\\\\n -u \\"pk-lf-...\\":\\"sk-lf-...\\" \\\\\\n -H \\"Content-Type: application/json\\" \\\\\\n -d \'{\\n \\"id\\": \\"unique_id\\",\\n \\"traceId\\": \\"trace_id_here\\",\\n \\"observationId\\": \\"observation_id_here\\",\\n \\"name\\": \\"reviewer_notes\\",\\n \\"value\\": \\"The response was helpful but could be more concise.\\",\\n \\"dataType\\": \\"TEXT\\",\\n \\"configId\\": \\"24680-6565-3453654-43543\\",\\n \\"comment\\": \\"Reviewed by QA team\\"\\n }\'\\n```\\nSee [API reference](/docs/api) for more details on POST/GET score configs endpoints.\\n### Inferred Score Properties\\nCertain score properties might be inferred based on your input:\\n * **If you don\'t provide a score data type** it will always be inferred. See tables below for details.\\n * **For boolean and categorical scores** , we will provide the score value in both numerical and string format where possible. The score value format that is not provided as input, i.e. the translated value is referred to as the inferred value in the tables below.\\n * **On read via the[v3 scores API](https://api.reference.langfuse.com/#tag/scoresv3/GET/api/public/v3/scores)**, boolean scores are returned as a single boolean `value`.\\n * **For categorical scores** , the string representation is always provided and a numerical mapping of the category will be produced only if a `ScoreConfig` was provided.\\nDetailed Examples:"}, {"type": "text", "text": "\\nNumeric ScoresCategorical ScoresBoolean ScoresText Scores\\nFor example, let\'s assume you\'d like to ingest a numeric score to measure **accuracy**. We have included a table of possible score ingestion scenarios below.\\nValue| Data Type| Config Id| Description| Inferred Data Type| Valid \\n---|---|---|---|---|--- \\n`0.9`| `Null`| `Null`| Data type is inferred| `NUMERIC`| Yes \\n`0.9`| `NUMERIC`| `Null`| No properties inferred| | Yes \\n`depth`| `NUMERIC`| `Null`| Error: data type of value does not match provided data type| | No \\n`0.9`| `NUMERIC`| `78545`| No properties inferred| | Conditional on config validation \\n`0.9`| `Null`| `78545`| Data type inferred| `NUMERIC`| Conditional on config validation \\n`depth`| `NUMERIC`| `78545`| Error: data type of value does not match provided data type| | No \\n \\nFor example, let\'s assume you\'d like to ingest a categorical score to measure **correctness**. We have included a table of possible score ingestion scenarios below.\\nValue| Data Type| Config Id| Description| Inferred Data Type| Inferred Value representation| Valid \\n---|---|---|---|---|---|--- \\n`correct`| `Null`| `Null`| Data type is inferred| `CATEGORICAL`| | Yes \\n`correct`| `CATEGORICAL`| `Null`| No properties inferred| | | Yes \\n`1`| `CATEGORICAL`| `Null`| Error: data type of value does not match provided data type| | | No \\n`correct`| `CATEGORICAL`| `12345`| Numeric value inferred| | `4` numeric config category mapping| Conditional on config validation \\n`correct`| `NULL`| `12345`| Data type inferred| `CATEGORICAL`| | Conditional on config validation \\n`1`| `CATEGORICAL`| `12345`| Error: data type of value does not match provided data type| | | No \\n "}, {"type": "text", "text": "For example, let\'s assume you\'d like to ingest a boolean score to measure **helpfulness**. We have included a table of possible score ingestion scenarios below.\\nValue| Data Type| Config Id| Description| Inferred Data Type| Inferred Value representation| Valid \\n---|---|---|---|---|---|--- \\n`1`| `BOOLEAN`| `Null`| Value\'s string equivalent inferred| | `True`| Yes \\n`true`| `BOOLEAN`| `Null`| Error: data type of value does not match provided data type| | | No \\n`3`| `BOOLEAN`| `Null`| Error: boolean data type expects `0` or `1` as input value| | | No \\n`0.9`| `Null`| `93547`| Data type and value\'s string equivalent inferred| `BOOLEAN`| `True`| Conditional on config validation \\n`depth`| `BOOLEAN`| `93547`| Error: data type of value does not match provided data type| | | No \\n \\nFor example, let\'s assume you\'d like to ingest a text score to capture **reviewer notes**. Text scores must be non-empty strings of at most 500 characters.\\nValue| Data Type| Config Id| Description| Inferred Data Type| Valid \\n---|---|---|---|---|--- \\n`\\"Good response\\"`| `Null`| `Null`| Data type is inferred| `TEXT`| Yes \\n`\\"Good response\\"`| `TEXT`| `Null`| No properties inferred| | Yes \\n`0.9`| `TEXT`| `Null`| Error: data type of value does not match provided data type| | No \\n`\\"Good response\\"`| `TEXT`| `24680`| No properties inferred| | Conditional on config validation \\n`\\"Good response\\"`| `Null`| `24680`| Data type inferred| `TEXT`| Conditional on config validation \\n`\\"\\"`| `TEXT`| `Null`| Error: text scores must be non-empty| | No \\n \\n\\n## Update Existing Scores via API/SDKs"}, {"type": "text", "text": "When creating a score, you can provide an optional `id` (JS/TS) / `score_id` (Python) parameter. A re-ingested score overwrites an existing one only when its `id`, `name`, and `timestamp` (at date granularity, `toDate(timestamp)`) all match — a matching `id` alone is not sufficient, and any difference creates a duplicate instead of an update.\\nTo overwrite a score without fetching existing scores first, set a stable `id` as an idempotency key when initially creating the score, and keep the `name` and `timestamp` unchanged on subsequent calls. See Preventing Duplicate Scores for details.\\n## Related guides\\nGuides\\n * [Collecting user feedback\\nCapture explicit and implicit user feedback as scores on your traces, including in-app ratings sent via our Browser SDK.\\n](/guides/user-feedback-loop)\\n * [Custom evaluation data pipeline\\nContinuously monitor quality by fetching traces, running custom evaluations, and ingesting scores back into Langfuse.\\n](/guides/cookbook/example_external_evaluation_pipelines)\\n * [Guardrails and security checks\\nCheck whether output contains a certain keyword, matches a required structure or format, or exceeds a length limit.\\n](/guides/cookbook/security-and-guardrails)\\n * [Custom internal workflow tooling\\nBuild internal tooling for human-in-the-loop workflows, ingesting scores back into Langfuse following your custom schema.\\n](/guides/human-in-the-loop-scoring)\\n * [Session-level quality tracking\\nScore full conversations, such as support chats or agent threads, by attaching scores via sessionId in the SDK or API.\\n](/guides/cookbook/example_evaluating_multi_turn_conversations)\\n* * *\\n* * *\\nLast edited 7/22/2026\\n"}], "type": "content"}}, {"type": "document", "record_type": "documentation", "url": "https://langfuse.com/docs/evaluation/scores/overview", "title": "Scores", "source": {"content": [{"type": "text", "text": "Overview - Langfuse\\n[Docs](/docs)\\n[Evaluation](/docs/evaluation/overview)\\n[Scores](/docs/evaluation/scores/overview)\\n[Overview](/docs/evaluation/scores/overview)\\n# Scores\\nScores are Langfuse\'s universal data object for storing evaluation results. Any time you want to assign a quality judgment to an LLM output, whether by a [human annotation](/docs/evaluation/evaluation-methods/scores-via-ui), an [LLM judge](/docs/evaluation/evaluation-methods/llm-as-a-judge), a [programmatic check](/docs/evaluation/evaluation-methods/scores-via-sdk), or end-user feedback, the result is stored as a score.\\nEvery score has a **name** (like `\\"correctness\\"` or `\\"helpfulness\\"`), a **value** , and a **data type**. Scores also support an optional **comment** for additional context.\\nScores can be attached to [traces](/docs/observability/data-model#observations-and-traces), [observations](/docs/observability/data-model#observations-and-traces), [sessions](/docs/observability/data-model#sessions), or [dataset runs](/docs/evaluation/experiments/data-model). Most commonly, scores are attached to traces to evaluate a single end-to-end interaction.\\nOnce you have scores, they show up in [score analytics](/docs/evaluation/scores/score-analytics), can be visualized in [custom dashboards](/docs/metrics/features/custom-dashboards), and can be queried via the [API](/docs/api).\\n## When to Use Scores\\nScores become useful when you want to go beyond observing what your application does and start measuring how well it does it. Common use cases:\\n * **Collecting user feedback** : Capture thumbs up/down or star ratings from your users and attach them to traces. See the [user feedback guide](/docs/observability/features/user-feedback)."}, {"type": "text", "text": "\\n * **Monitoring production quality** : Set up automated evaluators (like [LLM-as-a-Judge](/docs/evaluation/evaluation-methods/llm-as-a-judge)) to continuously score live traces for things like hallucination, relevance, or tone.\\n * **Running guardrails** : Score whether outputs pass safety checks like PII detection, format validation, or content policy compliance.\\n * **Comparing changes with experiments** : When you change a prompt, model, or pipeline, run an [experiment](/docs/evaluation/experiments) to score the new version against a dataset.\\n## Score Types\\nLangfuse supports four score data types:\\nType| Value| Use when \\n---|---|--- \\n`NUMERIC`| Float (e.g. `0.9`)| Continuous judgments like accuracy, relevance, or similarity scores \\n`CATEGORICAL`| String from predefined categories (e.g. `\\"correct\\"`, `\\"partially correct\\"`)| Discrete classifications where the set of possible values is known upfront \\n`BOOLEAN`| `0` or `1`| Pass/fail checks like hallucination detection or format validation \\n`TEXT`| Free-form string (1-500 characters)| Open-ended annotations like reviewer notes or qualitative feedback. Often used for [open coding](https://en.wikipedia.org/wiki/Open_coding) before formalizing into quantifiable scores via [axial coding](https://en.wikipedia.org/wiki/Axial_coding). \\n \\nText scores are designed for qualitative, open-ended scoring. Because free-form text cannot be meaningfully aggregated or compared, text scores are not supported in [experiments](/docs/evaluation/core-concepts#experiments), [LLM-as-a-Judge](/docs/evaluation/evaluation-methods/llm-as-a-judge), or [score analytics](/docs/evaluation/scores/score-analytics).\\n## How to Create Scores"}, {"type": "text", "text": "\\nThere are five ways to add scores:\\n * **LLM-as-a-Judge** : Set up [automated evaluators](/docs/evaluation/evaluation-methods/llm-as-a-judge) that score traces based on custom criteria (e.g. hallucination, tone, relevance). These can return numeric or categorical scores plus reasoning, and can run on live production traces or on experiment results.\\n * **Code evaluators** : Run [custom Python or TypeScript evaluators](/docs/evaluation/evaluation-methods/code-evaluators) in Langfuse for deterministic checks such as exact match, JSON validation, or custom business rules.\\n * **Scores via UI** : Team members [manually score](/docs/evaluation/evaluation-methods/scores-via-ui) traces, observations, or sessions directly in the Langfuse UI. Requires a [score config](/faq/all/manage-score-configs) to be set up first.\\n * **Annotation Queues** : Set up [structured review workflows](/docs/evaluation/evaluation-methods/annotation-queues) where reviewers work through batches of traces.\\n * **Scores via API/SDK** : [Programmatically add scores](/docs/evaluation/evaluation-methods/scores-via-sdk) from your application code. This is the way to go for user feedback (thumbs up/down, star ratings), guardrail results, or custom evaluation pipelines.\\n## Should I Use Scores or Tags?\\n| Scores| Tags \\n---|---|--- \\n **Purpose**| Measure _how good_ something is| Describe _what_ something is \\n **Data**| Numeric, categorical, boolean, or text value| Simple string label \\n **When added**| Can be added at any time, including long after the trace was created| Set during tracing and cannot be changed afterwards \\n **Used for**| Quality measurement, analytics, experiments| Filtering, segmentation, organizing \\n "}, {"type": "text", "text": "As a rule of thumb: if you already know the category at tracing time (e.g. which feature or API endpoint triggered the trace), use a [tag](/docs/observability/features/tags). If you need to classify or evaluate traces later, use a score.\\n## Score Comments\\nEvery score supports an optional **comment** field. Use it to capture reasoning (e.g. why an LLM judge assigned a particular score), reviewer notes, or context that helps others understand the score value. Comments are shown alongside scores in the Langfuse UI.\\nUse a `TEXT` score instead of comments to capture standalone qualitative feedback -- comments are best for additional reasoning on an existing score.\\n* * *\\n* * *\\nLast edited 7/23/2026\\n"}], "type": "content"}}, {"type": "document", "record_type": "github_discussion", "url": "https://github.com/orgs/langfuse/discussions/6016", "title": "Using scores in data sets from the SDK?", "source": {"content": [{"type": "text", "text": "Title: Using scores in data sets from the SDK?\\nCategory: Support\\nAuthor: @howinator\\nTimestamp: March 14, 2025\\nBody:\\nHere is a workflow that I want, but I can\'t figure out how to accomplish it without a lot of manual work.\\r\\n\\r\\n1. Collect traces\\r\\n2. Annotate traces with either manual annotation or programmatic feedback from users. For a simple classification, I would use a boolean score where True means the model returned the correct answer and False when it returned the incorrect answer.\\r\\n4. Create a \\"false positive\\" data set composed of all traces where the score was False. <-- I can\'t figure out how to do this without a lot of clicking.\\r\\n5. Run an eval from that data set and use the score to determine if the eval was correct, e.g., something like `(dataset.item.score && dataset.item.output === evalOutput.output) || (!dataset.item.score && dataset.item.output !== evalOutput.output)`. <-- I can\'t figure out how to do this programmatically at all.\\r\\n\\r\\nIs my workflow completely off here? Am I missing something? Or is this flow just not possible in Langfuse today?\\nComments:\\n\\n Comment #1 from @dosubot on March 14, 2025:\\n\\n <!-- Greeting -->\\nHey there, @howinator! I\'m here to help you out with any bugs, questions, or contributions you have in mind. Let\'s get to work!\\n\\n<!-- Answer -->\\nYour workflow is mostly feasible in Langfuse, and you can achieve it programmatically with some adjustments:\\n\\n1. **Collect Traces**: This step is straightforward and can be done using Langfuse\'s SDKs to capture and store traces.\\n\\n2. **Annotate Traces**: You can programmatically annotate traces with scores using the `langfuse_context.score_current_trace` function. This allows you to attach a boolean score to each trace based on user feedback or other criteria <sup>[[1]](https://langfuse.com/guides/cookbook/integration_langgraph)</sup>.\\n"}, {"type": "text", "text": "\\n3. **Create a \\"False Positive\\" Dataset**: While there isn\'t a direct method to filter dataset items based on scores, you can programmatically create a dataset by iterating over your traces and selecting those with a score of `False`. Use the SDK to create dataset items for these traces <sup>[[2]](https://langfuse.com/docs/datasets/get-started)</sup>.\\n\\n4. **Run an Evaluation**: You can automate the creation of evaluation jobs for your dataset using the `createEvalJobs` function. This function allows you to specify configurations and run evaluations on specific subsets of dataset items <sup>[[3]](https://github.com/langfuse/langfuse/blob/eecf0d680b13a4bde9fe8fed617acc328029307d/worker/src/__tests__/evalService.test.ts)</sup>.\\n\\nFor the evaluation logic, you can implement custom logic to compare the dataset item scores and outputs with the evaluation outputs. This might require some additional scripting to handle the specific logic you described.\\n\\nOverall, your workflow is possible with Langfuse, but it may require some custom scripting to fully automate the process of filtering and evaluating dataset items based on scores.\\n\\n\\n<!-- Dosu Comment Footer -->\\n*To continue talking to [Dosu](https://dosu.dev), mention @dosu.*\\n\\n---"}, {"type": "text", "text": "1. Create a \\"false positive\\" data set composed of all traces where the score was False -> use scores api to fetch all of these\\r\\n2. Run your own eval on them and add it to the same trace via the sdk\\r\\n3. Compare the evals by fetching all of them via the sdk again.\\r\\n\\r\\nWe currently plan to add more configurable dashboards which will allow for the comparison of these evals more easily in the UI.\\n"}], "type": "content"}}, {"type": "document", "record_type": "documentation", "url": "https://langfuse.com/docs/observability/troubleshooting-and-faq", "title": "Troubleshooting and FAQ", "source": {"content": [{"type": "text", "text": "\\n[LLM as a Session-Level Judge with Support for LangGraph Session](https://github.com/orgs/langfuse/discussions/8303 \\"Langfuse Ideas: LLM as a Session-Level Judge with Support for LangGraph Session\\")\\n[Score Configs: Allow editing the categories of a categorical score](https://github.com/orgs/langfuse/discussions/8259 \\"Langfuse Ideas: Score Configs: Allow editing the categories of a categorical score\\")\\n[feat(trace-detail-view): for each span, show the sum of nested observations\' token usage details](https://github.com/orgs/langfuse/discussions/8201 \\"Langfuse Ideas: feat\\\\(trace-detail-view\\\\): for each span, show the sum of nested observations\' token usage details\\")\\n[UI-LLM as a Jury](https://github.com/orgs/langfuse/discussions/8195 \\"Langfuse Ideas: UI-LLM as a Jury\\")\\n[Add Gemini 2.5 Pro model pricing](https://github.com/orgs/langfuse/discussions/8146 \\"Langfuse Ideas: Add Gemini 2.5 Pro model pricing\\")\\n[Deeplinking for Spans inside of a Trace](https://github.com/orgs/langfuse/discussions/8112 \\"Langfuse Ideas: Deeplinking for Spans inside of a Trace\\")\\n[feat(comments): allow attaching images](https://github.com/orgs/langfuse/discussions/8111 \\"Langfuse Ideas: feat\\\\(comments\\\\): allow attaching images\\")\\n[feat(sessions): support session-level tags](https://github.com/orgs/langfuse/discussions/8041 \\"Langfuse Ideas: feat\\\\(sessions\\\\): support session-level tags\\")\\n[Enable Immediate Score Management for User Feedback](https://github.com/orgs/langfuse/discussions/7686 \\"Langfuse Ideas: Enable Immediate Score Management for User Feedback\\")\\n[Allow for structured filtering on inputs / outputs](https://github.com/orgs/langfuse/discussions/7663 \\"Langfuse Ideas: Allow for structured filtering on inputs / outputs\\")"}, {"type": "text", "text": "\\n[Allow for lazy updating of traces in Python SDK (+ possible workaround)](https://github.com/orgs/langfuse/discussions/7655 \\"Langfuse Ideas: Allow for lazy updating of traces in Python SDK \\\\(+ possible workaround\\\\)\\")\\n[Filter by scores in session view](https://github.com/orgs/langfuse/discussions/7528 \\"Langfuse Ideas: Filter by scores in session view\\")\\n[Support break lines on evaluation run tooltip hint](https://github.com/orgs/langfuse/discussions/7452 \\"Langfuse Ideas: Support break lines on evaluation run tooltip hint\\")\\n[Enable sending Langfuse SDK OTEL spans to third party observability backend](https://github.com/orgs/langfuse/discussions/7365 \\"Langfuse Ideas: Enable sending Langfuse SDK OTEL spans to third party observability backend\\")\\n[Add Thinking config in playground for anthropic models](https://github.com/orgs/langfuse/discussions/7267 \\"Langfuse Ideas: Add Thinking config in playground for anthropic models\\")\\n[Better support for big int in metadata.](https://github.com/orgs/langfuse/discussions/7167 \\"Langfuse Ideas: Better support for big int in metadata.\\")\\n[Ability to filter/search comments on traces](https://github.com/orgs/langfuse/discussions/7109 \\"Langfuse Ideas: Ability to filter/search comments on traces\\")\\n[Image / File / Multimedia rendering in dataset items using mediaId](https://github.com/orgs/langfuse/discussions/6883 \\"Langfuse Ideas: Image / File / Multimedia rendering in dataset items using mediaId\\")\\n[Trace Comments support upload image](https://github.com/orgs/langfuse/discussions/6857 \\"Langfuse Ideas: Trace Comments support upload image\\")"}], "type": "content"}}, {"type": "document", "record_type": "github_issue", "url": "https://github.com/langfuse/langfuse/issues/3380", "title": "feat: add fetch_score(s) in the sdks", "source": {"content": [{"type": "text", "text": "Github Issue by @marcklingen created on September 17, 2024. The current state of the issue is: closed\\n\\n### Discussed in https://github.com/orgs/langfuse/discussions/3379\\r\\n\\r\\n<div type=\'discussions-op-text\'>\\r\\n\\r\\n<sup>Originally posted by **Preet1234-ux** September 17, 2024</sup>\\r\\nI want to fetch the score provided by the user from langfuse in my python code . Are there any functionality by which I can fetch the score for a trace ? </div>\\r\\n\\r\\n\\r\\nCurrently, we need to use either langfuse.client.*(potentially breaking) or the api.\\n---\\nComment #1 by @hassiebp:\\n\\nAlready shipped in Python SDK v3\\n\\n"}], "type": "content"}}, {"type": "document", "record_type": "github_discussion", "url": "https://github.com/orgs/langfuse/discussions/6210", "title": "Next.js + Vercel AI SDK: How to get `observationId` and attach it to scores?", "source": {"content": [{"type": "text", "text": "Title: Next.js + Vercel AI SDK: How to get `observationId` and attach it to scores?\\nCategory: Support\\nAuthor: @natterstefan\\nTimestamp: March 26, 2025\\nBody:\\nDear langfuse-Community,\\r\\n\\r\\nI need your help please, as I do not know how to obtain the `observationId` and attach it to a `score`.\\r\\n\\r\\nContext: this is how my `experimental_telemetry` looks like:\\r\\n\\r\\n```js\\r\\n// src: https://langfuse.com/docs/integrations/vercel-ai-sdk#group-multiple-executions-in-one-trace\\r\\n\\r\\nconst parentTraceId = getRandomId()\\r\\n\\r\\nexport async function POST(req: Request) {\\r\\n\\t// ... other code\\r\\n\\r\\n\\tconst trace = langfuse.trace({\\r\\n\\t id: parentTraceId,\\r\\n\\t name: \'cd-chat-messages\',\\r\\n\\t})\\r\\n\\r\\n\\tconsole.log(\'trace\', trace.observationId) // <<-- this returns `null`\\r\\n\\t\\r\\n\\tconst result = streamText({\\r\\n\\t\\t// ....\\r\\n\\t\\texperimental_telemetry: {\\r\\n\\t\\t isEnabled: true,\\r\\n\\t\\t functionId: \'cd-chat-message-\' + messages.length,\\r\\n\\t\\t metadata: {\\r\\n\\t\\t langfuseTraceId: parentTraceId,\\r\\n\\t\\t\\t // Do not update the parent trace with execution results\\r\\n\\t\\t langfuseUpdateParent: false,\\r\\n\\t\\t },\\r\\n\\t\\t },\\r\\n\\t})\\r\\n\\r\\n\\t// ... other code\\r\\n}\\r\\n```\\r\\n\\r\\nThe docs state\\r\\n\\r\\n> The id of the observation to which the score should be attached. Pass from backend trace. E.g. {generation, event, span}.id\\r\\n\\r\\nBut how and where do I get the observationId from, taking into account that I use `streamText` (<https://sdk.vercel.ai/docs/reference/ai-sdk-core/stream-text>)\\r\\n\\r\\n```js\\r\\n// source: https://langfuse.com/docs/sdk/typescript/guide-web#create-scores\\r\\n\\r\\n// pass traceId and observationId to front end\\r\\nawait langfuseWeb.score({\\r\\n traceId: message.traceId,\\r\\n observationId: message.observationId, <<<-- where do I get this?\\r\\n name: \\"user-feedback\\",\\r\\n value: 1,\\r\\n comment: \\"I like how personalized the response is\\",\\r\\n});\\r\\n```\\r\\n\\r"}, {"type": "text", "text": "Another question I could not answer myself is where (= which \\"layer\\". I guess generation, event, span is the correct wording) a score should be attached to. Is there any best practice recommendation or should I always go for the observation (`ai.streamText.doStream` in this example _if_ that\'s the observationId I can obtain)?\\r\\n\\r\\n\\r\\n\\r\\nThank you very much for your time and help!\\nComments:\\n\\n Comment #1 from @dosubot on March 26, 2025:\\n\\n <!-- Greeting -->\\nHey @natterstefan! I\'m here to help you with any bugs, questions, or even becoming a contributor. Let\'s squash those bugs together! 🤖\\n\\n<!-- Answer -->\\nTo obtain the `observationId` when using the `streamText` function in the Vercel AI SDK, you should look for it in the response from the `streamText` function. The SDK typically uses the ID from the provider response if available, or it generates one if not. Ensure that your telemetry setup is configured to pass the `observationId` from the backend trace, specifically from the context of the `streamText` execution.\\n\\nRegarding where to attach the score, it is generally recommended to attach it to the most relevant observation. In your case, if `ai.streamText.doStream` is the observation you can obtain, it would be appropriate to attach the score there. This aligns with best practices, as it ensures the score is associated with the specific operation or event you are evaluating.\\n"}, {"type": "text", "text": "\\nFor more detailed guidance, you might want to refer to the Langfuse documentation on creating scores and handling observations <sup>[[1]](https://langfuse.com/docs/sdk/typescript)</sup><sup>[[2]](https://langfuse.com/docs/sdk/typescript/guide)</sup>.\\n\\n\\n<!-- Dosu Comment Footer -->\\n*To continue talking to [Dosu](https://dosu.dev), mention @dosu.*\\n\\n---\\n<sup>Help Dosu learn! Give it feedback: [Great Response](https://app.dosu.dev/response-feedback/68b78af0-2c34-4867-b75c-008bcf449b81?feedback_type=great_response) | [Irrelevant Answer](https://app.dosu.dev/response-feedback/68b78af0-2c34-4867-b75c-008bcf449b81?feedback_type=irrelevant_answer) | [Incorrect Sources](https://app.dosu.dev/response-feedback/68b78af0-2c34-4867-b75c-008bcf449b81?feedback_type=incorrect_sources) | [Too Verbose](https://app.dosu.dev/response-feedback/68b78af0-2c34-4867-b75c-008bcf449b81?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/68b78af0-2c34-4867-b75c-008bcf449b81?feedback_type=hallucination) | [Bug Report](https://app.dosu.dev/response-feedback/68b78af0-2c34-4867-b75c-008bcf449b81?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/68b78af0-2c34-4867-b75c-008bcf449b81?feedback_type=other)</sup>\\n\\n\\n Comment #2 from @marcklingen on March 26, 2025:\\n\\n This seems like a feature request for the AI SDK as you\'d need the SDK to expose the span ids of each of the requests.\\n\\n Replies to comment #2:\\n\\n Reply #1 to comment #2 from marcklingen on March 27, 2025:\\n\\n Hi @marcklingen,\\r\\n\\r\\nthanks for your help. Alright, I [moved (aka copied) the discussion to their repo](https://github.com/vercel/ai/discussions/5415) and hope they can help me.\\r\\n\\r\\nIs @dosubot correct with \\"_(...) In your case, if ai.streamText.doStream is the observation you can obtain, it would be appropriate to attach the score there._\\"\\r\\n\\r"}, {"type": "text", "text": "\\n<sup>Help Dosu learn! Give it feedback: [Great Response](https://app.dosu.dev/response-feedback/d9fcd303-8526-48dc-85b4-1432b3d12429?feedback_type=great_response) | [Irrelevant Answer](https://app.dosu.dev/response-feedback/d9fcd303-8526-48dc-85b4-1432b3d12429?feedback_type=irrelevant_answer) | [Incorrect Sources](https://app.dosu.dev/response-feedback/d9fcd303-8526-48dc-85b4-1432b3d12429?feedback_type=incorrect_sources) | [Too Verbose](https://app.dosu.dev/response-feedback/d9fcd303-8526-48dc-85b4-1432b3d12429?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/d9fcd303-8526-48dc-85b4-1432b3d12429?feedback_type=hallucination) | [Bug Report](https://app.dosu.dev/response-feedback/d9fcd303-8526-48dc-85b4-1432b3d12429?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/d9fcd303-8526-48dc-85b4-1432b3d12429?feedback_type=other)</sup>\\n\\n\\n Reply #3 to comment #2 from marcklingen on March 27, 2025:\\n\\n Hi @marcklingen and @dosubot,\\r\\n\\r\\nFollow up question (once I get the `generation.id`/`response.id` whatever vercel/ai calls it): how do I attach it to the current trace to make sure the observation in langfuse has the same id as the score in my code uses?\\n\\n Reply #4 to comment #2 from marcklingen on March 27, 2025:\\n\\n <!-- Answer -->\\nTo attach the `generation.id` or `response.id` from Vercel AI to the current trace in Langfuse, use the `generation.id` as the `observationId` when logging user feedback. This ensures that the observation has the same ID as the score used in your code. Here\'s how you can do it:\\n\\n1. Add the `generation.id` to the streaming response as a custom header:\\n\\n ```javascript\\n return new StreamingTextResponse(stream, {\\n headers: {\\n \\"X-Message-Id\\": lfGeneration.id,"}], "type": "content"}}]}',},- ],+ ].map(({ text }) => ({+ type: "tool-result" as const,+ toolCallId: "call_OQNWWW4PjixkLIhkuHJRwiFV",+ toolName: "searchLangfuseDocs",+ output: { type: "text" as const, value: text },+ })),observationId: "3dbf50cbf2036387",startTime: new Date("2026-09-09T08:27:02.700Z"),endTime: new Date("2026-09-09T08:27:08.255Z"),diff --git a/packages/shared/src/server/transcript/generic-renderer.ts b/packages/shared/src/server/transcript/generic-renderer.tsindex 21fde15795..fd50acf158 100644--- a/packages/shared/src/server/transcript/generic-renderer.ts+++ b/packages/shared/src/server/transcript/generic-renderer.ts@@ -2,6 +2,7 @@ import type { Observation } from "../../domain";import type {NormalizedMessage,NormalizedMessagePart,+ ToolResultContentPart,} from "../../utils/normalized-io";import { normalizeIO } from "../normalized-io";import {@@ -10,14 +11,36 @@ import {} from "./topics-renderer-config";import type { Transcript } from "./types";+function json(value: unknown): string {+ return typeof value === "string" ? value : (JSON.stringify(value) ?? "");+}++function partContent(+ part: ToolResultContentPart,+ includeReasoning: boolean,+): string {+ switch (part.type) {+ case "text":+ return part.text;+ case "data":+ return json(part.value);+ case "custom":+ return json({ [part.kind]: part.value });+ case "file":+ return part.reasoning ? "" : `[${part.mediaType ?? "file"} omitted]`;+ case "reasoning":+ return includeReasoning && part.content.kind === "text"+ ? part.content.text+ : "";+ }+}+/** Preserve the original plain-text layout as a measurement baseline. */export function renderGenericTranscript(transcript: Transcript | null,observations: Observation[],): string {const config = transcriptRenderConfigSchema.parse(topicsTranscriptConfig);- const json = (value: unknown) =>- typeof value === "string" ? value : (JSON.stringify(value) ?? "");const labeled = (label: string, raw: string, maxChars: number) => {if (maxChars === 0) return `[${label}]`;let content = raw.replace(@@ -47,13 +70,17 @@ export function renderGenericTranscript(switch (part.type) {case "text":return role.include- ? labeled(roleLabel, part.text, role.maxChars)+ ? labeled(+ roleLabel,+ partContent(part, config.reasoning.include),+ role.maxChars,+ ): null;case "reasoning":return config.reasoning.include && part.content.kind === "text"? labeled(`${roleLabel} · reasoning`,- part.content.text,+ partContent(part, config.reasoning.include),config.reasoning.maxChars,): null;@@ -72,22 +99,27 @@ export function renderGenericTranscript(" "," ",),- json(part.output),+ part.output.type === "content"+ ? part.output.value+ .map((content) =>+ partContent(content, config.reasoning.include),+ )+ .filter(Boolean)+ .join("\n")+ : json(part.output.value),config.toolResults.maxChars,): null;case "file":return role.include && !part.reasoning- ? `[${roleLabel}] [${part.mediaType ?? "file"} omitted]`+ ? `[${roleLabel}] ${partContent(part, config.reasoning.include)}`: null;case "data":case "custom":return role.include? labeled(roleLabel,- json(- part.type === "data" ? part.value : { [part.kind]: part.value },- ),+ partContent(part, config.reasoning.include),role.maxChars,): null;diff --git a/packages/shared/src/server/transcript/tool-calls.ts b/packages/shared/src/server/transcript/tool-calls.tsindex 5c51c1b745..0cc84f07e5 100644--- a/packages/shared/src/server/transcript/tool-calls.ts+++ b/packages/shared/src/server/transcript/tool-calls.ts@@ -1,6 +1,8 @@+import { toolResultOutput } from "../../utils/normalized-io/core/normalize/message-parts/tool-results";import type {NormalizedMessage,ToolCallPart,+ ToolResultContentPart,} from "../../utils/normalized-io";import type { ThreadMessage } from "./types";import {@@ -12,6 +14,7 @@ import {} from "./threads";type Call = {+ part: ToolCallPart;thread: ThreadState;message: ThreadMessage;response?: ThreadMessage;@@ -39,7 +42,7 @@ export function createToolCallRegistry() {: undefined;if (id && calls.has(id)) return;- const call: Call = { thread, message };+ const call: Call = { part, thread, message };if (id) calls.set(id, call);if (part.toolCallId) {if (!callsByThread.has(thread)) callsByThread.set(thread, new Map());@@ -185,20 +188,45 @@ export function createToolCallRegistry() {let hasId = false;for (const part of parts) {if (part.type !== "tool-result" || !part.toolCallId) continue;-hasId = true;const call = calls.get(key(observation.traceId, part.toolCallId));if (call) setResponse(call, observation, [part]);}- if (hasId || !observation.name) return;+ if (hasId) return;+ if (!observation.name) return;const queue = pending.get(key(observation.traceId, observation.name));if (!queue) return;-while (queue.calls[queue.next]?.fromTool) queue.next++;+ // Without result IDs, assume execution order matches same-name call order.const call = queue.calls[queue.next];- if (call) {- queue.next++;+ if (!call) return;+ queue.next++;+ // Already-normalized results retain their output; ordinary content belongs+ // to the matched execution. Mixed call/result siblings remain separate parts.+ if (parts.length === 1 && parts[0]!.type === "tool-result") {+ setResponse(call, observation, [+ {+ ...parts[0]!,+ toolCallId: call.part.toolCallId,+ toolName: call.part.toolName,+ },+ ]);+ } else if (+ parts.every(+ (part): part is ToolResultContentPart =>+ part.type !== "tool-call" && part.type !== "tool-result",+ )+ ) {+ setResponse(call, observation, [+ {+ type: "tool-result",+ toolCallId: call.part.toolCallId,+ toolName: call.part.toolName,+ output: toolResultOutput(parts, parts),+ },+ ]);+ } else {setResponse(call, observation, parts);}}diff --git a/packages/shared/src/server/transcript/topics-renderer.test.ts b/packages/shared/src/server/transcript/topics-renderer.test.tsindex 6bca1aa99e..687d197319 100644--- a/packages/shared/src/server/transcript/topics-renderer.test.ts+++ b/packages/shared/src/server/transcript/topics-renderer.test.ts@@ -364,7 +364,7 @@ describe("Topics transcript renderer", () => {type: "tool-result",toolCallId: "call-1",toolName: "search",- output: "timeout",+ output: { type: "text", value: "timeout" },isError: true,},],@@ -576,7 +576,7 @@ describe("Topics transcript renderer", () => {type: "tool-result",toolCallId: "call-1",toolName: "lookup",- output: "Result",+ output: { type: "text", value: "Result" },},],observationId: tool.id,@@ -647,7 +647,7 @@ describe("Topics transcript renderer", () => {type: "tool-result",toolCallId: "same-id",toolName: "lookup",- output: "Found",+ output: { type: "text", value: "Found" },},],observationId: tool.id,diff --git a/packages/shared/src/server/transcript/topics-renderer.ts b/packages/shared/src/server/transcript/topics-renderer.tsindex ab16339530..f1ecd32642 100644--- a/packages/shared/src/server/transcript/topics-renderer.ts+++ b/packages/shared/src/server/transcript/topics-renderer.ts@@ -119,7 +119,9 @@ export function renderTranscript(case "tool-call":return `${part.toolName} ${json(part.input)}`;case "tool-result":- return json(part.output);+ return part.output.type === "content"+ ? toolResultContent(part.output.value)+ : json(part.output.value);case "file":return `[${part.mediaType ?? "file"} omitted]`;case "data":@@ -128,6 +130,15 @@ export function renderTranscript(return json({ [part.kind]: part.value });}};+ const toolResultContent = (parts: NormalizedMessagePart[]): string =>+ parts+ .map((part) => {+ if (part.type === "reasoning" && !config.reasoning.include) return "";+ if (part.type === "file" && part.reasoning) return "";+ return partContent(part);+ })+ .filter(Boolean)+ .join("\n");const rootContent = (observation: Observation,source: "input" | "output",@@ -379,7 +390,7 @@ export function renderTranscript(return config.toolResults.include? labeled(`${resultLabel}${part.isError ? " ERROR" : ""}`,- json(part.output),+ partContent(part),config.toolResults.maxChars,"tool_results",)diff --git a/packages/shared/src/utils/normalized-io/README.md b/packages/shared/src/utils/normalized-io/README.mdindex 286429d2dc..4245bdbcf4 100644--- a/packages/shared/src/utils/normalized-io/README.md+++ b/packages/shared/src/utils/normalized-io/README.md@@ -69,7 +69,7 @@ parts, while untyped structured values remain lossless `data` parts.| `text` | `text` | citations/annotations land in `providerMetadata.citations` || `reasoning` | `content` union: `{kind:"text", text, signature?}` \| `{kind:"redacted", data}` \| `{kind:"encrypted", data}` \| `{kind:"data", value}` | visible CoT/summaries; provider-withheld blobs; replayable encrypted blobs; structured payloads || `tool-call` | `toolCallId` (nullable), `toolName`, `input`, `toolType?`, `providerExecuted?` | `toolType` preserves the source kind (`function`, `custom`, provider-specific built-ins); `providerExecuted` marks server-side tools; parallel-call slot indexes are derived positionally by projections, raw streaming `index` fields stay in `providerMetadata` |-| `tool-result` | `toolCallId` (nullable), `toolName?`, `output`, `isError?` | AI-SDK `{type, value}` output wrappers are unwrapped |+| `tool-result` | `toolCallId` (nullable), `toolName?`, `output`, `isError?` | Output is tagged `text`, `json`, or `content`; content preserves typed parts without nested tool calls/results || `file` | `content` union: `{kind:"url"}` \| `{kind:"base64"}` \| `{kind:"reference", id}`, `mediaType?`, `filename?` | all media, incl. `@@@langfuseMedia:…@@@` tokens → references; `mediaType` is exact when declared, a modality wildcard (`image/*`) when only the part kind reveals it, absent for opaque ids || `data` | `value` | structured non-message payloads (function-span args/results, loose records) — JSON-passthrough parity with the trace view || `custom` | `kind`, `value` | recognized-but-unmapped typed blocks, verbatim (e.g. `source`, `document`) |@@ -90,6 +90,18 @@ variants) canonicalize to`stop | length | tool-calls | content-filter | error | other | unknown`,with the provider's verbatim value kept in `raw`.+### Tool result output++`ToolResultPart.output` is a tagged value: `{ type: "text", value: string }`,+`{ type: "json", value: JsonValue }`, or `{ type: "content", value: ToolResultContentPart[] }`.+Provider handlers use the existing part normalizer for tool payloads; explicit JSON+stays JSON, including arrays and null. The output helper only packages normalized+parts: a single bare text/data part becomes text/JSON, while multiple parts or parts+with metadata remain content. It does not recognize provider formats or normalize+parts again. Content can contain text, data, files, reasoning, and custom parts, but+not nested calls/results; unrepresentable output stays JSON. Display projections+such as the session tool preview belong to consumers.+## How parsing worksRecognition is **shape-based** — the parser never dispatches on a providerdiff --git a/packages/shared/src/utils/normalized-io/conventions/io-convention.ts b/packages/shared/src/utils/normalized-io/conventions/io-convention.tsindex b722a31211..a1dd78a3c6 100644--- a/packages/shared/src/utils/normalized-io/conventions/io-convention.ts+++ b/packages/shared/src/utils/normalized-io/conventions/io-convention.ts@@ -26,6 +26,8 @@ export type PartHandlerContext = {};export type MessageEnvelopeContext = {+ /** Normalize content extracted from a provider message envelope. */+ normalizePartList(values: unknown[]): NormalizedMessagePart[];/** The observation side being normalized — for implementations that* construct a message directly instead of recursing. */readonly source: "input" | "output";diff --git a/packages/shared/src/utils/normalized-io/conventions/providers/ai-sdk/fixtures.ts b/packages/shared/src/utils/normalized-io/conventions/providers/ai-sdk/fixtures.tsindex 89b8038b5e..540dc65f9e 100644--- a/packages/shared/src/utils/normalized-io/conventions/providers/ai-sdk/fixtures.ts+++ b/packages/shared/src/utils/normalized-io/conventions/providers/ai-sdk/fixtures.ts@@ -283,14 +283,10 @@ export const vercelAiSdkMixedToolMessagesFixture = {type: "tool-result",toolCallId: inputToolCallId,toolName: "getLangfuseOverview",- // AI SDK {type, value} output wrappers are unwrapped; the- // structured value is the result.- output: [- {- type: "text",- text: "[Langfuse documentation overview response]",- },- ],+ output: {+ type: "text",+ value: "[Langfuse documentation overview response]",+ },},],source: "input",@@ -542,12 +538,10 @@ export const vercelAiSdkOutputToolCallFixture = {{type: "tool-result",toolCallId: previousToolCallId,- output: [- {- type: "text",- text: "[Reduced documentation search response]",- },- ],+ output: {+ type: "text",+ value: "[Reduced documentation search response]",+ },},],source: "input",diff --git a/packages/shared/src/utils/normalized-io/conventions/providers/ai-sdk/index.ts b/packages/shared/src/utils/normalized-io/conventions/providers/ai-sdk/index.tsindex 79038c1e12..c988ebd2b0 100644--- a/packages/shared/src/utils/normalized-io/conventions/providers/ai-sdk/index.ts+++ b/packages/shared/src/utils/normalized-io/conventions/providers/ai-sdk/index.ts@@ -2,6 +2,8 @@ import { claimed, unmatched } from "../..";import {asRecord,compact,+ nullableString,+ parseIfString,optionalString,recordKeyAsParsed,toJsonValue,@@ -12,12 +14,17 @@ import {parseMediaReference,} from "../../../core/normalize/message-parts/media";import { toolCallPart } from "../../../core/normalize/message-parts/tool-calls";-import { toolResultPart } from "../../../core/normalize/message-parts/tool-results";+import { toolResultOutput } from "../../../core/normalize/message-parts/tool-results";import {toolDefinition,toolDefinitionProviderMetadata,} from "../../../core/normalize/tool-definitions";-import type { FilePart, FinishReason } from "../../../types";+import type {+ FilePart,+ FinishReason,+ ToolResultPart,+ ToolResultOutput,+} from "../../../types";import type {IOConvention,MessageSource,@@ -110,16 +117,21 @@ const normalizeAiSdkFile: PartHandler = (value) => {return part ? claimed(part) : unmatched;};-const normalizeAiSdkToolError: PartHandler = (value) =>- claimed({- // AI SDK tool execution error: the error is the result.- ...toolResultPart({- toolCallId: value.toolCallId,- toolName: value.toolName,- output: value.error ?? null,+const normalizeAiSdkToolError: PartHandler = (value) => {+ const raw = parseIfString(value.error ?? null);+ return claimed(+ compact<ToolResultPart>({+ type: "tool-result",+ toolCallId: nullableString(value.toolCallId),+ toolName: optionalString(value.toolName),+ output:+ typeof raw === "string"+ ? { type: "text", value: raw }+ : { type: "json", value: toJsonValue(raw) },+ isError: true,}),- isError: true,- });+ );+};const normalizeAiSdkReasoningFile: PartHandler = (value) => {// AI SDK reasoning-generated file (a FilePart nested under `file`; older@@ -155,17 +167,79 @@ const normalizeAiSdkToolCall: PartHandler = (value) =>);// AI SDK tool-result parts: { toolCallId, toolName, output } (v4 emissions// used `result`).-const normalizeAiSdkToolResult: PartHandler = (value) =>- claimed(- toolResultPart({- toolCallId: value.toolCallId,- toolName: value.toolName,- output: value.output ?? value.result,- isError: typeof value.isError === "boolean" ? value.isError : undefined,+const normalizeAiSdkToolResult: PartHandler = (value, context) => {+ const raw = value.output ?? value.result;+ const record = asRecord(raw);+ const wrapper =+ record && ("value" in record || record.type === "execution-denied")+ ? record+ : undefined;+ let output: ToolResultOutput;+ let isError = typeof value.isError === "boolean" ? value.isError : undefined;+ switch (wrapper?.type) {+ case "text":+ case "error-text":+ output =+ typeof wrapper.value === "string"+ ? { type: "text", value: wrapper.value }+ : { type: "json", value: toJsonValue(wrapper.value) };+ isError = isError ?? (wrapper.type === "error-text" ? true : undefined);+ break;+ case "json":+ case "error-json":+ output = { type: "json", value: toJsonValue(wrapper.value) };+ isError = isError ?? (wrapper.type === "error-json" ? true : undefined);+ break;+ case "content":+ output = toolResultOutput(+ Array.isArray(wrapper.value)+ ? context.normalizePartList(wrapper.value)+ : [],+ wrapper.value,+ );+ break;+ case "execution-denied":+ output = { type: "json", value: toJsonValue(raw) };+ break;+ default: {+ const parsed = parseIfString(raw ?? null);+ output =+ typeof parsed === "string"+ ? { type: "text", value: parsed }+ : { type: "json", value: toJsonValue(parsed) };+ }+ }+ return claimed(+ compact<ToolResultPart>({+ type: "tool-result",+ toolCallId: nullableString(value.toolCallId),+ toolName: optionalString(value.toolName),+ output,+ isError,}),);+};++// Model-facing tool outputs use explicit URL/data variants rather than the+// legacy image/file payloads used in ordinary messages.+const normalizeAiSdkToolMedia: PartHandler = (value) => {+ const type = String(value.type);+ const payload = type.endsWith("-url")+ ? { type: "url", url: value.url }+ : { type: "data", data: value.data };+ const part = aiSdkFilePart(payload, {+ mediaType: optionalString(value.mediaType),+ filename: optionalString(value.filename),+ fallbackMediaType: type.startsWith("image-") ? "image/*" : undefined,+ });+ return part ? claimed(part) : unmatched;+};const AI_SDK_PART_HANDLERS = {+ "image-data": normalizeAiSdkToolMedia,+ "image-url": normalizeAiSdkToolMedia,+ "file-data": normalizeAiSdkToolMedia,+ "file-url": normalizeAiSdkToolMedia,"tool-call": normalizeAiSdkToolCall,"tool-error": normalizeAiSdkToolError,"tool-result": normalizeAiSdkToolResult,diff --git a/packages/shared/src/utils/normalized-io/conventions/providers/anthropic/fixtures.ts b/packages/shared/src/utils/normalized-io/conventions/providers/anthropic/fixtures.tsindex 79cb549935..5acc5a12b2 100644--- a/packages/shared/src/utils/normalized-io/conventions/providers/anthropic/fixtures.ts+++ b/packages/shared/src/utils/normalized-io/conventions/providers/anthropic/fixtures.ts@@ -1,12 +1,27 @@import type { NormalizedIOFixture } from "../fixture-types";-import { toJsonValue } from "../../../core/utils/json";+import type { ToolResultOutput } from "../../../types";// Docs-derived tool-result variants; the image data is a sample placeholder.// https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-callsexport const documentedToolResultFixtures: NormalizedIOFixture[] = [- { label: "empty", content: undefined },+ {+ label: "empty",+ content: undefined,+ expectedOutput: { type: "json", value: null },+ },{label: "text and image",+ expectedOutput: {+ type: "content",+ value: [+ { type: "text", text: "15 degrees" },+ {+ type: "file",+ mediaType: "image/jpeg",+ content: { kind: "base64", data: "aGVsbG8=" },+ },+ ],+ },content: [{ type: "text", text: "15 degrees" },{@@ -17,6 +32,24 @@ export const documentedToolResultFixtures: NormalizedIOFixture[] = [},{label: "text and document",+ expectedOutput: {+ type: "content",+ value: [+ { type: "text", text: "The weather is" },+ {+ type: "custom",+ kind: "document",+ value: {+ type: "document",+ source: {+ type: "text",+ media_type: "text/plain",+ data: "15 degrees",+ },+ },+ },+ ],+ },content: [{ type: "text", text: "The weather is" },{@@ -26,7 +59,7 @@ export const documentedToolResultFixtures: NormalizedIOFixture[] = [],},].map(- ({ label, content }): NormalizedIOFixture => ({+ ({ label, content, expectedOutput }): NormalizedIOFixture => ({name: `Anthropic ${label} tool result with string system instruction`,spanIO: {input: {@@ -85,7 +118,7 @@ export const documentedToolResultFixtures: NormalizedIOFixture[] = [{type: "tool-result",toolCallId: "call_weather",- output: toJsonValue(content ?? null),+ output: expectedOutput as ToolResultOutput,},],},@@ -334,18 +367,18 @@ export const anthropicMessagesRawServerToolsAndMediaFixture = {{type: "tool-result",toolCallId: "server-call-1",- output: [{ type: "text", text: "Search result" }],+ output: { type: "text", value: "Search result" },},{type: "tool-result",toolCallId: "server-call-1",- output: "The report service timed out.",+ output: { type: "text", value: "The report service timed out." },isError: true,},{type: "tool-result",toolCallId: "mcp-call-1",- output: "Report metadata",+ output: { type: "text", value: "Report metadata" },isError: false,},],diff --git a/packages/shared/src/utils/normalized-io/conventions/providers/anthropic/index.ts b/packages/shared/src/utils/normalized-io/conventions/providers/anthropic/index.tsindex 6b0825b5c5..76b0db2ce4 100644--- a/packages/shared/src/utils/normalized-io/conventions/providers/anthropic/index.ts+++ b/packages/shared/src/utils/normalized-io/conventions/providers/anthropic/index.ts@@ -3,6 +3,8 @@ import { claimed, unmatched } from "../..";import {asRecord,compact,+ nullableString,+ parseIfString,optionalString,recordKeyAsParsed,toJsonValue,@@ -17,12 +19,12 @@ import {providerExecutedToolCall,toolCallPart,} from "../../../core/normalize/message-parts/tool-calls";-import { toolResultPart } from "../../../core/normalize/message-parts/tool-results";+import { toolResultOutput } from "../../../core/normalize/message-parts/tool-results";import {toolDefinition,toolDefinitionProviderMetadata,} from "../../../core/normalize/tool-definitions";-import type { FilePart, FinishReason } from "../../../types";+import type { FilePart, FinishReason, ToolResultPart } from "../../../types";import type {IOConvention,PartHandler,@@ -174,14 +176,24 @@ const normalizeAnthropicContainerUpload: PartHandler = (value) => {// Anthropic result blocks: { type: "tool_result" | "*_tool_result",// tool_use_id, content, is_error? }.-const normalizeAnthropicToolResult: PartHandler = (value) =>- claimed(- toolResultPart({- toolCallId: value.tool_use_id ?? value.id,- output: value.content,+const normalizeAnthropicToolResult: PartHandler = (value, context) => {+ const raw = parseIfString(value.content ?? null);+ let output: ToolResultPart["output"] =+ typeof raw === "string"+ ? { type: "text", value: raw }+ : { type: "json", value: toJsonValue(raw) };+ if (Array.isArray(value.content)) {+ output = toolResultOutput(context.normalizePartList(value.content), raw);+ }+ return claimed(+ compact<ToolResultPart>({+ type: "tool-result",+ toolCallId: nullableString(value.tool_use_id ?? value.id),+ output,isError: typeof value.is_error === "boolean" ? value.is_error : undefined,}),);+};const ANTHROPIC_PART_HANDLERS = {tool_use: (value) => claimed(anthropicToolCall(value, "tool_use")),diff --git a/packages/shared/src/utils/normalized-io/conventions/providers/gemini/fixtures.ts b/packages/shared/src/utils/normalized-io/conventions/providers/gemini/fixtures.tsindex 0f4f812626..c717b320c3 100644--- a/packages/shared/src/utils/normalized-io/conventions/providers/gemini/fixtures.ts+++ b/packages/shared/src/utils/normalized-io/conventions/providers/gemini/fixtures.ts@@ -84,7 +84,7 @@ export const documentedFunctionRoundTripFixtures: NormalizedIOFixture[] = [{type: "tool-result",toolCallId: "call_weather",- output: { temperature: 15 },+ output: { type: "json", value: { temperature: 15 } },},],},@@ -288,7 +288,10 @@ export const geminiMediaAndCodeExecutionFixture = {type: "tool-result",toolCallId: null,toolName: "code_execution",- output: { outcome: "OUTCOME_OK", output: "3" },+ output: {+ type: "json",+ value: { outcome: "OUTCOME_OK", output: "3" },+ },},{ type: "text", text: "The sum is 3." },],@@ -366,7 +369,10 @@ export const capturedTraceFixtures: NormalizedIOFixture[] = [type: "tool-result",toolCallId: "say_hello",output: {- greeting: "Hello Langfuse 👋",+ type: "json",+ value: {+ greeting: "Hello Langfuse 👋",+ },},},],diff --git a/packages/shared/src/utils/normalized-io/conventions/providers/gemini/index.ts b/packages/shared/src/utils/normalized-io/conventions/providers/gemini/index.tsindex 9130aa6d51..8369209f7c 100644--- a/packages/shared/src/utils/normalized-io/conventions/providers/gemini/index.ts+++ b/packages/shared/src/utils/normalized-io/conventions/providers/gemini/index.ts@@ -2,6 +2,7 @@ import { claimed, unmatched } from "../..";import {asRecord,compact,+ nullableString,optionalString,parseArray,recordKeyAsParsed,@@ -14,7 +15,6 @@ import {} from "../../../core/normalize/message-parts/media";import { reasoningPart } from "../../../core/normalize/message-parts/reasoning";import { toolCallPart } from "../../../core/normalize/message-parts/tool-calls";-import { toolResultPart } from "../../../core/normalize/message-parts/tool-results";import type {FilePart,FinishReason,@@ -81,9 +81,12 @@ function normalizeGeminiPart(// Gemini functionResponse: { name, response } — the name doubles as the// call id fallback, not the tool name (parity with the original join).return claimed(- toolResultPart({- toolCallId: functionResponse.id ?? functionResponse.name ?? value.id,- output: functionResponse.response,+ compact<ToolResultPart>({+ type: "tool-result",+ toolCallId: nullableString(+ functionResponse.id ?? functionResponse.name ?? value.id,+ ),+ output: { type: "json", value: toJsonValue(functionResponse.response) },}),);}@@ -147,7 +150,7 @@ function normalizeGeminiPart(type: "tool-result",toolCallId: null,toolName: "code_execution",- output: toJsonValue(codeExecutionResult),+ output: { type: "json", value: toJsonValue(codeExecutionResult) },isError: outcome && outcome !== "OUTCOME_OK" ? true : undefined,}),);diff --git a/packages/shared/src/utils/normalized-io/conventions/providers/langchain/fixtures.ts b/packages/shared/src/utils/normalized-io/conventions/providers/langchain/fixtures.tsindex 622658b408..f03abc0e27 100644--- a/packages/shared/src/utils/normalized-io/conventions/providers/langchain/fixtures.ts+++ b/packages/shared/src/utils/normalized-io/conventions/providers/langchain/fixtures.ts@@ -279,7 +279,7 @@ export const langchainSerializedEnvelopeFixture = {{type: "tool-result",toolCallId: "call_lc_1",- output: "Weather service unavailable.",+ output: { type: "text", value: "Weather service unavailable." },isError: true,// Side-band artifact data, preserved without becoming output.providerMetadata: { artifact: { attempts: 2 } },@@ -471,7 +471,7 @@ export const langchainDictToolMessageFixture = {type: "tool-result",toolCallId: "call_pNLR4DoZiptb5xGlb299QsoN",toolName: "search",- output: "It's 60 degrees and foggy.",+ output: { type: "text", value: "It's 60 degrees and foggy." },},],source: "input",@@ -794,7 +794,7 @@ export const langgraphProductionShapeFixture = {{type: "tool-result",toolCallId: "call_001",- output: "synthetic-value-016",+ output: { type: "text", value: "synthetic-value-016" },},],source: "input",@@ -805,7 +805,7 @@ export const langgraphProductionShapeFixture = {{type: "tool-result",toolCallId: "call_002",- output: "synthetic-value-017",+ output: { type: "text", value: "synthetic-value-017" },},],source: "input",diff --git a/packages/shared/src/utils/normalized-io/conventions/providers/mixed/fixtures/index.ts b/packages/shared/src/utils/normalized-io/conventions/providers/mixed/fixtures/index.tsindex 78113d0c65..ffc3a2fabb 100644--- a/packages/shared/src/utils/normalized-io/conventions/providers/mixed/fixtures/index.ts+++ b/packages/shared/src/utils/normalized-io/conventions/providers/mixed/fixtures/index.ts@@ -189,7 +189,7 @@ const capturedTraceFixtures: NormalizedIOFixture[] = [{type: "tool-result",toolCallId: null,- output: "Hello my darling Bob!",+ output: { type: "text", value: "Hello my darling Bob!" },},],source: "input",@@ -215,7 +215,7 @@ const capturedTraceFixtures: NormalizedIOFixture[] = [{type: "tool-result",toolCallId: null,- output: "Bye my dear Bob!",+ output: { type: "text", value: "Bye my dear Bob!" },},],source: "input",diff --git a/packages/shared/src/utils/normalized-io/conventions/providers/mixed/fixtures/loose-provider-message-shapes.ts b/packages/shared/src/utils/normalized-io/conventions/providers/mixed/fixtures/loose-provider-message-shapes.tsindex 6f422c6858..bbe06c1623 100644--- a/packages/shared/src/utils/normalized-io/conventions/providers/mixed/fixtures/loose-provider-message-shapes.ts+++ b/packages/shared/src/utils/normalized-io/conventions/providers/mixed/fixtures/loose-provider-message-shapes.ts@@ -80,7 +80,7 @@ export const looseProviderMessageShapesFixture = {{type: "tool-result",toolCallId: null,- output: "Sunny, 22 degrees",+ output: { type: "text", value: "Sunny, 22 degrees" },},],source: "input",diff --git a/packages/shared/src/utils/normalized-io/conventions/providers/openai/fixtures.ts b/packages/shared/src/utils/normalized-io/conventions/providers/openai/fixtures.tsindex eef217ea42..3f25673dcf 100644--- a/packages/shared/src/utils/normalized-io/conventions/providers/openai/fixtures.ts+++ b/packages/shared/src/utils/normalized-io/conventions/providers/openai/fixtures.ts@@ -1638,44 +1638,47 @@ export const customerFixtures: NormalizedIOFixture[] = [type: "tool-result",toolCallId: "sample_id_1",output: {- parts: {- org: {- country: "Sample country",- is_multi_entity: true,- name: "Sample name",- plan_label: "Sample plan_label",- plan_tier_internal: "Sample plan_tier_internal",- size_bucket: "Sample size_bucket",- },- products: {- enabled_entitlements_at_session_start_internal: [- "Sample enabled_entitlements_at_session_start_internal",- "Sample enabled_entitlements_at_session_start_internal",- "Sample enabled_entitlements_at_session_start_internal",- "Sample enabled_entitlements_at_session_start_internal",- "Sample enabled_entitlements_at_session_start_internal",- "Sample enabled_entitlements_at_session_start_internal",- "Sample enabled_entitlements_at_session_start_internal",- "Sample enabled_entitlements_at_session_start_internal",- "Sample enabled_entitlements_at_session_start_internal",- ],- },- session: {- session_started_at: "Sample session_started_at",- },- setup: {- erp_provider_internal: "Sample erp_provider_internal",- erp_provider_label: "Sample erp_provider_label",- },- user: {- department: "Sample department",- first_name: "Sample first_name",- is_manager: true,- role_internal: "Sample role_internal",- role_label: "Sample role_label",+ type: "json",+ value: {+ parts: {+ org: {+ country: "Sample country",+ is_multi_entity: true,+ name: "Sample name",+ plan_label: "Sample plan_label",+ plan_tier_internal: "Sample plan_tier_internal",+ size_bucket: "Sample size_bucket",+ },+ products: {+ enabled_entitlements_at_session_start_internal: [+ "Sample enabled_entitlements_at_session_start_internal",+ "Sample enabled_entitlements_at_session_start_internal",+ "Sample enabled_entitlements_at_session_start_internal",+ "Sample enabled_entitlements_at_session_start_internal",+ "Sample enabled_entitlements_at_session_start_internal",+ "Sample enabled_entitlements_at_session_start_internal",+ "Sample enabled_entitlements_at_session_start_internal",+ "Sample enabled_entitlements_at_session_start_internal",+ "Sample enabled_entitlements_at_session_start_internal",+ ],+ },+ session: {+ session_started_at: "Sample session_started_at",+ },+ setup: {+ erp_provider_internal: "Sample erp_provider_internal",+ erp_provider_label: "Sample erp_provider_label",+ },+ user: {+ department: "Sample department",+ first_name: "Sample first_name",+ is_manager: true,+ role_internal: "Sample role_internal",+ role_label: "Sample role_label",+ },},+ unavailable: [],},- unavailable: [],},},],@@ -1701,13 +1704,16 @@ export const customerFixtures: NormalizedIOFixture[] = [type: "tool-result",toolCallId: "sample_id_2",output: {- instructions: "Sample instructions",- skills: [- {- name: "Sample name",- description: "Sample description",- },- ],+ type: "json",+ value: {+ instructions: "Sample instructions",+ skills: [+ {+ name: "Sample name",+ description: "Sample description",+ },+ ],+ },},},],@@ -1734,7 +1740,7 @@ export const customerFixtures: NormalizedIOFixture[] = [{type: "tool-result",toolCallId: "sample_id_3",- output: "Sample tool result",+ output: { type: "text", value: "Sample tool result" },},],},@@ -1802,34 +1808,37 @@ export const customerFixtures: NormalizedIOFixture[] = [type: "tool-result",toolCallId: "sample_id_6",output: {- output_path: "Sample output_path",- output_bytes: 41556,- output_summary: {- format: "json",- shape: {- snippets: [- {- snippet: "Sample snippet",- title: "Sample title",- url: "Sample url",- links: [- {- label: "Sample label",- url: "Sample url",- },- "Sample links",- ],- similarity_score: "Sample similarity_score",- },- "Sample snippets",- ],- query: "Sample query",+ type: "json",+ value: {+ output_path: "Sample output_path",+ output_bytes: 41556,+ output_summary: {+ format: "json",+ shape: {+ snippets: [+ {+ snippet: "Sample snippet",+ title: "Sample title",+ url: "Sample url",+ links: [+ {+ label: "Sample label",+ url: "Sample url",+ },+ "Sample links",+ ],+ similarity_score: "Sample similarity_score",+ },+ "Sample snippets",+ ],+ query: "Sample query",+ },+ summary_truncated: true,},- summary_truncated: true,+ output_head: "Sample output_head",+ truncated: true,+ hint: "Sample hint",},- output_head: "Sample output_head",- truncated: true,- hint: "Sample hint",},},],@@ -3319,7 +3328,10 @@ export const openAiChatCompletionToolSequenceFixture = {{type: "tool-result",toolCallId,- output: { condition: "sunny", temperature: 24 },+ output: {+ type: "json",+ value: { condition: "sunny", temperature: 24 },+ },},],source: "input",@@ -3331,7 +3343,7 @@ export const openAiChatCompletionToolSequenceFixture = {type: "tool-result",toolCallId: null,toolName: "run_python",- output: 42,+ output: { type: "json", value: 42 },},],source: "input",@@ -3516,7 +3528,10 @@ export const openAiResponsesReasoningWithParallelCallsFixture = {{type: "tool-result",toolCallId: callId1,- output: "[Reduced refund policy doc excerpt]",+ output: {+ type: "text",+ value: "[Reduced refund policy doc excerpt]",+ },},],source: "input",@@ -3527,7 +3542,10 @@ export const openAiResponsesReasoningWithParallelCallsFixture = {{type: "tool-result",toolCallId: callId2,- output: "[Reduced annual plan terms excerpt]",+ output: {+ type: "text",+ value: "[Reduced annual plan terms excerpt]",+ },},],source: "input",@@ -3614,7 +3632,7 @@ export const openAiResponsesFunctionCallFixture = {{type: "tool-result",toolCallId: responsesToolCallId,- output: "The weather in Basel is cloudy.",+ output: { type: "text", value: "The weather in Basel is cloudy." },},],source: "input",@@ -4036,7 +4054,7 @@ export const openAiResponsesBuiltInToolsAndMediaFixture = {{type: "tool-result",toolCallId: "call_custom_100",- output: "ok",+ output: { type: "text", value: "ok" },},],source: "output",@@ -4369,7 +4387,7 @@ export const capturedTraceFixtures: NormalizedIOFixture[] = [{type: "tool-result",toolCallId: "call_Kud0j0DxWSmLzv9W5m6qVqXn",- output: "The weather in Tokyo is sunny.",+ output: { type: "text", value: "The weather in Tokyo is sunny." },},],source: "input",diff --git a/packages/shared/src/utils/normalized-io/conventions/providers/openai/index.ts b/packages/shared/src/utils/normalized-io/conventions/providers/openai/index.tsindex 943259f22a..b0dfddde2e 100644--- a/packages/shared/src/utils/normalized-io/conventions/providers/openai/index.ts+++ b/packages/shared/src/utils/normalized-io/conventions/providers/openai/index.ts@@ -22,7 +22,7 @@ import {providerExecutedToolCall,toolCallPart,} from "../../../core/normalize/message-parts/tool-calls";-import { toolResultPart } from "../../../core/normalize/message-parts/tool-results";+import { toolResultOutput } from "../../../core/normalize/message-parts/tool-results";import {toolDefinition,toolDefinitionProviderMetadata,@@ -33,6 +33,7 @@ import type {NormalizedMessage,NormalizedMessagePart,ToolCallPart,+ ToolResultPart,} from "../../../types";import type {ConventionResult,@@ -251,13 +252,19 @@ const normalizeOpenAiBuiltInCall: PartHandler = (value) =>claimed(normalizeBuiltInToolItem(value));// OpenAI Responses output items: { type: "*_output", call_id, output }.-const normalizeOpenAiToolResult: PartHandler = (value) =>- claimed(- toolResultPart({- toolCallId: value.call_id ?? value.id,- output: value.output,+const normalizeOpenAiToolResult: PartHandler = (value) => {+ const raw = parseIfString(value.output ?? null);+ return claimed(+ compact<ToolResultPart>({+ type: "tool-result",+ toolCallId: nullableString(value.call_id ?? value.id),+ output:+ typeof raw === "string"+ ? { type: "text", value: raw }+ : { type: "json", value: toJsonValue(raw) },}),);+};// OpenAI Responses custom (free-form input) tool call:// { type: "custom_tool_call", call_id, name, input }.@@ -580,6 +587,11 @@ const tryUnwrapLegacyFunctionMessage = (_fallbackRole: "user" | "assistant",ctx: MessageEnvelopeContext,): ConventionResult<NormalizedMessage> => {+ const content = parseIfString(value.content ?? null);+ let output: ToolResultPart["output"] =+ typeof content === "string"+ ? { type: "text", value: content }+ : { type: "json", value: toJsonValue(content) };if (// LangChain dict serializations carry `type: "tool"` instead of a role// key; the same tool-result shape (tool_call_id, artifact, status).@@ -587,6 +599,9 @@ const tryUnwrapLegacyFunctionMessage = ((typeof value.tool_call_id === "string" ||typeof value.tool_call_id === "number")) {+ if (Array.isArray(value.content)) {+ output = toolResultOutput(ctx.normalizePartList(value.content), content);+ }return claimed({...(optionalString(value.id) ? { id: String(value.id) } : {}),role: "tool",@@ -597,7 +612,7 @@ const tryUnwrapLegacyFunctionMessage = (// A `name` on a tool message is the tool's name, never a// participant name.toolName: optionalString(value.name),- output: toJsonValue(parseIfString(value.content ?? null)),+ output,isError: value.status === "error" ? true : undefined,providerMetadata:value.artifact !== undefined && value.artifact !== null@@ -620,10 +635,11 @@ const tryUnwrapLegacyFunctionMessage = (...(optionalString(value.id) ? { id: String(value.id) } : {}),role: "tool",parts: [- toolResultPart({- toolCallId: value.tool_call_id,- toolName: value.name,- output: value.content,+ compact<ToolResultPart>({+ type: "tool-result",+ toolCallId: nullableString(value.tool_call_id),+ toolName: optionalString(value.name),+ output,}),],source: ctx.source,diff --git a/packages/shared/src/utils/normalized-io/conventions/providers/otel-genai/index.ts b/packages/shared/src/utils/normalized-io/conventions/providers/otel-genai/index.tsindex 5fc374069c..deb064d553 100644--- a/packages/shared/src/utils/normalized-io/conventions/providers/otel-genai/index.ts+++ b/packages/shared/src/utils/normalized-io/conventions/providers/otel-genai/index.ts@@ -1,17 +1,17 @@import { claimed, dropped, unmatched } from "../..";import { asRecord, compact, optionalString } from "../../../core/utils/json";import { toolCallPart } from "../../../core/normalize/message-parts/tool-calls";-import { toolResultPart } from "../../../core/normalize/message-parts/tool-results";import type {FinishReason,NormalizedMessage,- ToolResultPart,+ NormalizedMessagePart,} from "../../../types";import type {ConventionResult,IOConvention,MessageEnvelopeContext,PartHandler,+ PartHandlerContext,ToolDefinitionCarrier,ToolDefinitionSource,} from "../../io-convention";@@ -25,9 +25,13 @@ import type {*/function normalizeOtelGenaiToolResult(value: Record<string, unknown>,-): ConventionResult<ToolResultPart> {+ context: PartHandlerContext,+): ConventionResult<NormalizedMessagePart[]> {+ // GenAI carriers can retain AI SDK output envelopes. Delegate their contents+ // to the existing tool-result handler after translating the carrier fields.return claimed(- toolResultPart({+ context.normalizePartValue({+ type: "tool-result",toolCallId:value.toolCallId /* ai sdk */ ??value.tool_use_id /* anthropic */ ??@@ -42,9 +46,7 @@ function normalizeOtelGenaiToolResult(isError: [value.is_error /* anthropic */,value.isError /* ai sdk */,- ].find((candidate) => typeof candidate === "boolean") as- | boolean- | undefined,+ ].find((candidate) => typeof candidate === "boolean"),}),);}@@ -69,8 +71,7 @@ const OTEL_GENAI_PART_HANDLERS = {toolType: optionalString(value.type),}),),- tool_call_response: (value: Record<string, unknown>) =>- normalizeOtelGenaiToolResult(value),+ tool_call_response: normalizeOtelGenaiToolResult,} satisfies Readonly<Record<string, PartHandler>>;/** GenAI choice events: `{index?, message, finish_reason?}`. */diff --git a/packages/shared/src/utils/normalized-io/conventions/providers/pydantic-ai/fixtures.ts b/packages/shared/src/utils/normalized-io/conventions/providers/pydantic-ai/fixtures.tsindex 035fd523c2..c8916a4990 100644--- a/packages/shared/src/utils/normalized-io/conventions/providers/pydantic-ai/fixtures.ts+++ b/packages/shared/src/utils/normalized-io/conventions/providers/pydantic-ai/fixtures.ts@@ -2820,20 +2820,29 @@ export const capturedTraceFixtures: NormalizedIOFixture[] = [{type: "tool-result",toolCallId: "call_X0OSgjUukT5inyEQvuZQnHrk",- output:- "Pun idea: Play on words related to 'programming' - think about homophones or double meanings",+ output: {+ type: "text",+ value:+ "Pun idea: Play on words related to 'programming' - think about homophones or double meanings",+ },},{type: "tool-result",toolCallId: "call_WxZcCvSDhGT4RJHlcU01k10x",- output:- "Dad joke idea: Use a classic setup-punchline format about 'programming' with a groan-worthy twist",+ output: {+ type: "text",+ value:+ "Dad joke idea: Use a classic setup-punchline format about 'programming' with a groan-worthy twist",+ },},{type: "tool-result",toolCallId: "call_aRaObiWKKt6GzgDkkUl3bu1Q",- output:- "One-liner idea: Make a quick, witty observation about 'programming' in a single sentence",+ output: {+ type: "text",+ value:+ "One-liner idea: Make a quick, witty observation about 'programming' in a single sentence",+ },},],source: "input",diff --git a/packages/shared/src/utils/normalized-io/core/normalize/message-parts/tool-results.ts b/packages/shared/src/utils/normalized-io/core/normalize/message-parts/tool-results.tsindex bd9d87d2d6..154cf7ae08 100644--- a/packages/shared/src/utils/normalized-io/core/normalize/message-parts/tool-results.ts+++ b/packages/shared/src/utils/normalized-io/core/normalize/message-parts/tool-results.ts@@ -1,61 +1,40 @@-import type { ToolResultPart } from "../../../types";-import {- asRecord,- optionalString,- compact,- nullableString,- toJsonValue,- parseIfString,-} from "../../utils/json";+import type {+ NormalizedMessagePart,+ ToolResultContentPart,+ ToolResultOutput,+} from "../../../types";+import { toJsonValue } from "../../utils/json";-// {type, value} output wrappers originate in the AI SDK but echo through-// loose conversions of every dialect, so unwrapping them is canonical-// builder mechanics — the one deliberate residual in this file. error-*-// marks a failed execution.-const OUTPUT_WRAPPER_TYPES = new Set([- "text",- "json",- "content",- "error-text",- "error-json",- "execution-denied",-]);+/** Package normalized parts without interpreting or normalizing their contents. */+export function toolResultOutput(+ parts: NormalizedMessagePart[],+ fallback: unknown,+): ToolResultOutput {+ if (+ parts.length === 0 ||+ !parts.every(+ (part): part is ToolResultContentPart =>+ part.type !== "tool-call" && part.type !== "tool-result",+ )+ ) {+ return { type: "json", value: toJsonValue(fallback) };+ }-type ToolResultFields = {- /** Raw id value; coerced via nullableString. */- toolCallId?: unknown;- /** Raw name value; coerced via optionalString. */- toolName?: unknown;- /** Raw payload; the builder unwraps output wrappers, parses one- * JSON-string boundary, and converts to JsonValue. */- output?: unknown;- isError?: boolean;-};--/**- * Canonical tool-result constructor. Takes already-extracted fields — the- * caller (a provider handler, or `toolResultPartFromLooseShape` for- * dialect-less shapes) owns the field vocabulary; this owns only the- * mechanics every dialect shares.- */-export function toolResultPart(fields: ToolResultFields): ToolResultPart {- const wrapper = asRecord(fields.output);- const wrapperType = optionalString(wrapper?.type);- const isWrapped =- wrapper !== undefined &&- wrapperType !== undefined &&- "value" in wrapper &&- OUTPUT_WRAPPER_TYPES.has(wrapperType);- const wrapperError =- isWrapped && wrapperType.startsWith("error") ? true : undefined;-- return compact<ToolResultPart>({- type: "tool-result",- toolCallId: nullableString(fields.toolCallId),- toolName: optionalString(fields.toolName),- output: toJsonValue(- parseIfString(isWrapped ? wrapper.value : (fields.output ?? null)),- ),- isError: fields.isError ?? wrapperError,- });+ const [part] = parts;+ // Only unwrap bare scalar parts; annotations and metadata stay on the part.+ if (parts.length === 1) {+ if (+ part.type === "text" &&+ Object.keys(part).every((key) => key === "type" || key === "text")+ ) {+ return { type: "text", value: part.text };+ }+ if (+ part.type === "data" &&+ Object.keys(part).every((key) => key === "type" || key === "value")+ ) {+ return { type: "json", value: part.value };+ }+ }+ return { type: "content", value: parts };}diff --git a/packages/shared/src/utils/normalized-io/core/normalize/message.ts b/packages/shared/src/utils/normalized-io/core/normalize/message.tsindex a2ef555810..624b221f21 100644--- a/packages/shared/src/utils/normalized-io/core/normalize/message.ts+++ b/packages/shared/src/utils/normalized-io/core/normalize/message.ts@@ -178,6 +178,7 @@ export function normalizeMessage(const envelopeContext: MessageEnvelopeContext = {source,+ normalizePartList: (parts) => normalizePartList(parts, parserContext),normalizeMessage: (nestedValue, nestedFallbackRole) =>normalizeMessage(nestedValue, nestedFallbackRole, parserContext),isMessageLike,diff --git a/packages/shared/src/utils/normalized-io/core/normalize/role.ts b/packages/shared/src/utils/normalized-io/core/normalize/role.tsindex 9053ec00e9..0663acc1f7 100644--- a/packages/shared/src/utils/normalized-io/core/normalize/role.ts+++ b/packages/shared/src/utils/normalized-io/core/normalize/role.ts@@ -1,3 +1,4 @@+import { toolResultOutput } from "./message-parts/tool-results";import { registeredProviders } from "../../conventions";import type { NormalizedMessagePart, NormalizedMessageRole } from "../../types";import { ownLookup } from "../utils/json";@@ -54,9 +55,7 @@ export function coerceRole(return "assistant";}if (parts.every((part): boolean => part.type === "text")) {- const output = parts- .map((part) => (part.type === "text" ? part.text : ""))- .join("\n");+ const output = toolResultOutput(parts.slice(), parts);parts.splice(0, parts.length, {type: "tool-result",toolCallId: null,diff --git a/packages/shared/src/utils/normalized-io/types.ts b/packages/shared/src/utils/normalized-io/types.tsindex 1ec41a2f38..ded2325bb1 100644--- a/packages/shared/src/utils/normalized-io/types.ts+++ b/packages/shared/src/utils/normalized-io/types.ts@@ -74,11 +74,24 @@ export type ToolCallPart = NormalizedPartBase & {invalid?: true;};+/** Content belonging to one execution; nested calls/results are not content. */+export type ToolResultContentPart =+ | TextPart+ | DataPart+ | FilePart+ | ReasoningPart+ | CustomPart;++export type ToolResultOutput =+ | { type: "text"; value: string }+ | { type: "json"; value: JsonValue }+ | { type: "content"; value: ToolResultContentPart[] };+export type ToolResultPart = NormalizedPartBase & {type: "tool-result";toolCallId: string | null;toolName?: string;- output: JsonValue;+ output: ToolResultOutput;isError?: boolean;};diff --git a/web/src/__tests__/server/unit/loadTraceTranscript.servertest.ts b/web/src/__tests__/server/unit/loadTraceTranscript.servertest.tsindex 8e4a70ab68..fa9e417fa5 100644--- a/web/src/__tests__/server/unit/loadTraceTranscript.servertest.ts+++ b/web/src/__tests__/server/unit/loadTraceTranscript.servertest.ts@@ -236,7 +236,7 @@ it.each(["ERROR", "WARNING"] as const)({type: "tool-result",toolCallId: "call-1",- output: null,+ output: { type: "json", value: null },isError: level === "ERROR",},],@@ -392,7 +392,7 @@ it.each(["missing", "idless"])({ toolCallId: "call-1" },]);expect(parts.filter((part) => part.type === "tool-result")).toMatchObject([- { toolCallId: "call-1", output: { answer: 42 } },+ { toolCallId: "call-1", output: { type: "json", value: { answer: 42 } } },]);expect(observations).toEqual(snapshot);},@@ -905,7 +905,7 @@ it("preserves explicit results that conflict with TOOL metadata", async () => {(message) => message.parts,);expect(parts.filter((part) => part.type === "tool-result")).toMatchObject([- { toolCallId: "explicit", output: "result" },+ { toolCallId: "explicit", output: { type: "text", value: "result" } },]);expect(parts.some(@@ -1007,7 +1007,7 @@ it.each([type: "tool-result",toolCallId: "call-1",toolName: "execute",- output,+ output: { type: "json", value: output },},],});@@ -1082,7 +1082,7 @@ it("opts into provenance-based reverse multi-call responses without mutating asstype: "tool-result",toolCallId: "call-1",toolName: "weather",- output: "weather",+ output: { type: "content", value: [{ type: "text", text: "weather" }] },},],[@@ -1090,7 +1090,7 @@ it("opts into provenance-based reverse multi-call responses without mutating asstype: "tool-result",toolCallId: "call-0",toolName: "search",- output: "search",+ output: { type: "content", value: [{ type: "text", text: "search" }] },},],]);@@ -1127,14 +1127,19 @@ it.each([expect(result.transcript?.threads[0]?.currentTurn.messages[1]?.parts,).toEqual([- { type: "tool-result", toolCallId: "call-0", toolName: "search", output },+ {+ type: "tool-result",+ toolCallId: "call-0",+ toolName: "search",+ output: { type: "content", value: [{ type: "data", value: output }] },+ },]);expect(original).toEqual(snapshot);expect((await loadTraceTranscript(trace)).transcript).toBe(original);},);-it("preserves multiple JSON parts as an output array", async () => {+it("preserves multiple JSON parts as typed content", async () => {const original = fixture(["search"], ["search"]);original.threads[0]!.currentTurn.messages[1]!.parts = [{ type: "data", value: { answer: 42 } },@@ -1150,7 +1155,13 @@ it("preserves multiple JSON parts as an output array", async () => {type: "tool-result",toolCallId: "call-0",toolName: "search",- output: [{ answer: 42 }, { confidence: 0.9 }],+ output: {+ type: "content",+ value: [+ { type: "data", value: { answer: 42 } },+ { type: "data", value: { confidence: 0.9 } },+ ],+ },},],);@@ -1192,7 +1203,11 @@ it.each([messages.push({...messages[1]!,parts: [- { type: "tool-result", toolCallId: "call-0", output: "explicit" },+ {+ type: "tool-result",+ toolCallId: "call-0",+ output: { type: "text", value: "explicit" },+ },],});}@@ -1221,7 +1236,13 @@ it("preserves explicit result precedence", async () => {const original = fixture(["search"], ["search"]);original.threads[0]!.currentTurn.messages.push({...original.threads[0]!.currentTurn.messages[1]!,- parts: [{ type: "tool-result", toolCallId: "call-0", output: "explicit" }],+ parts: [+ {+ type: "tool-result",+ toolCallId: "call-0",+ output: { type: "text", value: "explicit" },+ },+ ],});expect((await loadTraceTranscript({ ...trace, recoverToolResponses: true }))diff --git a/web/src/features/events/server/loadTraceTranscript.ts b/web/src/features/events/server/loadTraceTranscript.tsindex fb68b5bbfe..f15280c928 100644--- a/web/src/features/events/server/loadTraceTranscript.ts+++ b/web/src/features/events/server/loadTraceTranscript.ts@@ -251,7 +251,13 @@ function assembleSessionTraceTranscript(const marker: NormalizedMessage = {role: "tool",source: "output",- parts: [{ type: "tool-result", toolCallId: callId, output: null }],+ parts: [+ {+ type: "tool-result",+ toolCallId: callId,+ output: { type: "json", value: null },+ },+ ],};// Let the registry resolve identity and placement, then retain the// original media parts instead of exposing a JSON-only result marker.@@ -404,7 +410,7 @@ function recoverToolCalls(observations: Observation[]) {type: "tool-result",toolCallId: callId,toolName: observation.name ?? "Tool",- output: null,+ output: { type: "json", value: null },isError: observation.level === "ERROR",},],@@ -412,8 +418,8 @@ function recoverToolCalls(observations: Observation[]) {];}const parts = messages.flatMap((message) => message.parts);- // Tool-result payloads are JSON; wrapping media would discard the file- // parts the session renderer needs for previews.+ // Keep the session media rendering path when metadata recovers a call+ // whose response contains media or other individually rendered parts.if (!parts.length) return messages;if (!parts.every((part) => part.type === "text") &&@@ -598,15 +604,12 @@ function pairToolResponses(const call = candidates.get(index);if (!call?.toolCallId) return message;if (candidateCounts.get(call.toolCallId) !== 1) return message;- const output = (() => {- if (message.parts.every((part) => part.type === "text")) {- return message.parts.map((part) => part.text).join("\n");- }- const values = message.parts.flatMap((part) =>- part.type === "data" ? [part.value] : [],- );- return values.length === 1 ? values[0] : values;- })();+ const output = {+ type: "content" as const,+ value: message.parts.filter(+ (part) => part.type === "text" || part.type === "data",+ ),+ };return {...message,parts: [diff --git a/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/components/SessionConversationTimeline/components/SessionConversationTimelineTrace/SessionConversationTimelineTrace.stories.tsx b/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/components/SessionConversationTimeline/components/SessionConversationTimelineTrace/SessionConversationTimelineTrace.stories.tsxindex e9ee5f060a..f8e7de7a1f 100644--- a/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/components/SessionConversationTimeline/components/SessionConversationTimelineTrace/SessionConversationTimelineTrace.stories.tsx+++ b/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/components/SessionConversationTimeline/components/SessionConversationTimelineTrace/SessionConversationTimelineTrace.stories.tsx@@ -1,3 +1,4 @@+import type { JsonValue } from "@langfuse/shared/src/utils/normalized-io";import preview from "@/.storybook/preview";import { type ComponentProps } from "react";import { expect, fn, userEvent, waitFor, within } from "storybook/test";@@ -75,7 +76,10 @@ const result: Extract<Props["state"], { type: "transcript" }>["result"] = {type: "tool-result",toolCallId: "weather-1",toolName: "weather",- output: { temperature: 12, conditions: "Sunny" },+ output: {+ type: "json",+ value: { temperature: 12, conditions: "Sunny" },+ },},],},@@ -158,10 +162,7 @@ function toolPreviewState(Thread["currentTurn"]["messages"][number]["parts"][number],{ type: "tool-call" }>["input"];- output: Extract<- Thread["currentTurn"]["messages"][number]["parts"][number],- { type: "tool-result" }- >["output"];+ output: JsonValue;}[],): TranscriptState {return transcriptState({@@ -192,7 +193,10 @@ function toolPreviewState(type: "tool-result",toolCallId: name,toolName: name,- output,+ output:+ typeof output === "string"+ ? { type: "text", value: output }+ : { type: "json", value: output },isError,},],@@ -674,7 +678,7 @@ export const ToolResultOnly = meta.story({type: "tool-result",toolCallId: "result-only",toolName: "get_subscription_details",- output: { plan: "annual_pro" },+ output: { type: "json", value: { plan: "annual_pro" } },},],},@@ -738,13 +742,13 @@ export const KeepDifferentToolData = meta.story({type: "tool-result",toolCallId: "docs",toolName: "search_documentation",- output: { found: true },+ output: { type: "json", value: { found: true } },},{type: "tool-result",toolCallId: "profile",toolName: "get_customer_profile",- output: { plan: "annual_pro" },+ output: { type: "json", value: { plan: "annual_pro" } },},],},@@ -864,7 +868,7 @@ export const ToolFailure = meta.story({type: "tool-result",toolCallId: "timeout",toolName: "get_order",- output: { code: "TOOL_TIMEOUT" },+ output: { type: "json", value: { code: "TOOL_TIMEOUT" } },isError: true,},],diff --git a/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/components/SessionConversationTimeline/components/SessionConversationTimelineTrace/components/SessionTranscriptContent/SessionTranscriptContent.tsx b/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/components/SessionConversationTimeline/components/SessionConversationTimelineTrace/components/SessionTranscriptContent/SessionTranscriptContent.tsxindex a5fc1ac207..993719e5be 100644--- a/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/components/SessionConversationTimeline/components/SessionConversationTimelineTrace/components/SessionTranscriptContent/SessionTranscriptContent.tsx+++ b/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/components/SessionConversationTimeline/components/SessionConversationTimelineTrace/components/SessionTranscriptContent/SessionTranscriptContent.tsx@@ -1,9 +1,11 @@+import { SessionTimelinePart } from "./components/SessionTimelinePart/SessionTimelinePart";import { useState, type ComponentProps, type ReactNode } from "react";import { type TranscriptMessageGroup } from "@/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/fns/groupTranscriptMessages";import { getSessionTranscriptRows } from "@/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/fns/getSessionTranscriptRows";import { getSessionTranscriptThreads } from "@/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/fns/getSessionTranscriptThreads";import { SessionTimelineToolRow } from "@/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/components/SessionConversationTimeline/components/SessionConversationTimelineTrace/components/SessionTranscriptContent/components/SessionTimelineToolRow/SessionTimelineToolRow";import { Wrench } from "lucide-react";+import { getSessionToolOutputPreview } from "./components/SessionTimelineToolRow/getSessionToolOutputPreview";import { type NormalizedMessage } from "@langfuse/shared/src/utils/normalized-io";import { type SessionTraceTranscriptState } from "@/src/features/sessions/hooks/useSessionTraceTranscripts";import { SessionTimelineContentMessage } from "@/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/components/SessionConversationTimeline/components/SessionConversationTimelineTrace/components/SessionTranscriptContent/components/SessionTimelineContentMessage/SessionTimelineContentMessage";@@ -338,6 +340,9 @@ function SessionTranscriptTool({trailingContent: ReactNode;}) {const [isExpanded, setIsExpanded] = useState(false);+ const preview = row.result+ ? getSessionToolOutputPreview(row.result.output)+ : undefined;const status = getSessionToolStatus({level: row.message.level,statusMessage: row.message.statusMessage,@@ -347,7 +352,15 @@ function SessionTranscriptTool({<SessionTimelineToolRowname={row.call?.toolName ?? row.result?.toolName ?? "Tool"}input={row.call?.input}- output={row.result?.output}+ output={preview?.value}+ outputContent={+ row.result?.output.type === "content" &&+ row.result.output.value.length > 0+ ? row.result.output.value.map((part, index) => (+ <SessionTimelinePart key={index} part={part} />+ ))+ : undefined+ }{...status}isExpanded={isExpanded}onExpandedChange={setIsExpanded}diff --git a/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/components/SessionConversationTimeline/components/SessionConversationTimelineTrace/components/SessionTranscriptContent/components/SessionTimelineToolRow/SessionTimelineToolRow.tsx b/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/components/SessionConversationTimeline/components/SessionConversationTimelineTrace/components/SessionTranscriptContent/components/SessionTimelineToolRow/SessionTimelineToolRow.tsxindex 29662b4cde..037f740791 100644--- a/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/components/SessionConversationTimeline/components/SessionConversationTimelineTrace/components/SessionTranscriptContent/components/SessionTimelineToolRow/SessionTimelineToolRow.tsx+++ b/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/components/SessionConversationTimeline/components/SessionConversationTimelineTrace/components/SessionTranscriptContent/components/SessionTimelineToolRow/SessionTimelineToolRow.tsx@@ -14,6 +14,7 @@ export function SessionTimelineToolRow({name,input,output,+ outputContent,isExpanded,onExpandedChange,level,@@ -23,6 +24,7 @@ export function SessionTimelineToolRow({name: string;input: unknown;output: unknown;+ outputContent?: ReactNode;isExpanded: boolean;onExpandedChange: (isExpanded: boolean) => void;level?: Observation["level"];@@ -99,17 +101,21 @@ export function SessionTimelineToolRow({</div></div>) : null}- {hasPreviewValue(output) ? (+ {outputContent || hasPreviewValue(output) ? (<div className="flex min-w-0 flex-col gap-1"><span className="text-muted-foreground font-mono text-[10px] font-bold uppercase">Output</span>- <div className="grid max-h-96 min-w-0">- <Codeblock label="Tool output" value={output} allowFormatting />- </div>+ {outputContent ?? (+ <div className="grid max-h-96 min-w-0">+ <Codeblock label="Tool output" value={output} allowFormatting />+ </div>+ )}</div>) : null}- {!hasPreviewValue(input) && !hasPreviewValue(output) ? (+ {!hasPreviewValue(input) &&+ !hasPreviewValue(output) &&+ !outputContent ? (<div className="relative"><span className="text-muted-foreground text-xs">No input or outputdiff --git a/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/components/SessionConversationTimeline/components/SessionConversationTimelineTrace/components/SessionTranscriptContent/components/SessionTimelineToolRow/getSessionToolOutputPreview.ts b/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/components/SessionConversationTimeline/components/SessionConversationTimelineTrace/components/SessionTranscriptContent/components/SessionTimelineToolRow/getSessionToolOutputPreview.tsnew file mode 100644index 0000000000..aa2bd0792d--- /dev/null+++ b/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/components/SessionConversationalView/components/SessionConversationTimeline/components/SessionConversationTimelineTrace/components/SessionTranscriptContent/components/SessionTimelineToolRow/getSessionToolOutputPreview.ts@@ -0,0 +1,46 @@+import type {+ JsonValue,+ ToolResultPart,+} from "@langfuse/shared/src/utils/normalized-io";++/** Projects tool content for the session code block without changing the transcript. */+export function getSessionToolOutputPreview(output: ToolResultPart["output"]): {+ value: JsonValue;+ omittedContent: Array<{ kind: "media" | "unsupported"; count: number }>;+} {+ if (output.type !== "content") {+ return { value: output.value, omittedContent: [] };+ }++ const values: JsonValue[] = [];+ let onlyText = true;+ let media = 0;+ let unsupported = 0;+ for (const part of output.value) {+ if (part.type === "text") {+ values.push(part.text);+ } else if (part.type === "data") {+ values.push(part.value);+ onlyText = false;+ } else if (part.type === "file") {+ media++;+ } else {+ unsupported++;+ }+ }++ let value: JsonValue = null;+ if (values.length > 0) {+ if (onlyText) value = values.join("\n");+ else value = values.length === 1 ? values[0]! : values;+ }+ return {+ value,+ omittedContent: [+ ...(media ? [{ kind: "media" as const, count: media }] : []),+ ...(unsupported+ ? [{ kind: "unsupported" as const, count: unsupported }]+ : []),+ ],+ };+}diff --git a/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/fns/getSessionTranscriptRows.clienttest.ts b/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/fns/getSessionTranscriptRows.clienttest.tsindex c5b8821641..64bcda075f 100644--- a/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/fns/getSessionTranscriptRows.clienttest.ts+++ b/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/fns/getSessionTranscriptRows.clienttest.ts@@ -40,7 +40,11 @@ const transcript = {role: "tool",source: "output",parts: [- { type: "tool-result", toolCallId: "call", output: "Found" },+ {+ type: "tool-result",+ toolCallId: "call",+ output: { type: "text", value: "Found" },+ },],},],@@ -302,7 +306,7 @@ describe("getSessionTranscriptRows", () => {]);expect(rows[1]?.row).toMatchObject({call: { toolName: "search" },- result: { output: "Found" },+ result: { output: { type: "text", value: "Found" } },});});diff --git a/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/fns/groupTranscriptMessages.clienttest.ts b/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/fns/groupTranscriptMessages.clienttest.tsindex 17c3f03579..5c02121455 100644--- a/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/fns/groupTranscriptMessages.clienttest.ts+++ b/web/src/features/sessions/components/ConnectedModernSessionBodyTimeline/components/ConnectedSessionConversationTimeline/fns/groupTranscriptMessages.clienttest.ts@@ -18,7 +18,7 @@ const call = (id: string | null): ToolCallPart => ({const result = (id: string | null): ToolResultPart => ({type: "tool-result",toolCallId: id,- output: "found",+ output: { type: "text", value: "found" },});const text = (value: string): NormalizedMessagePart => ({type: "text",@@ -84,7 +84,7 @@ describe("groupTranscriptMessages", () => {});it("pairs a server-produced identified tool response", () => {- const output = "found";+ const output = { type: "text", value: "found" } as const;const parts = [{ ...result("a"), toolName: "search", output }];const toolCall = call("a");const response = {diff --git a/web/src/features/traces/components/IOPreview/components/ChatMessage.tsx b/web/src/features/traces/components/IOPreview/components/ChatMessage.tsxindex 050b4eb0e9..0af50f4b8f 100644--- a/web/src/features/traces/components/IOPreview/components/ChatMessage.tsx+++ b/web/src/features/traces/components/IOPreview/components/ChatMessage.tsx@@ -58,6 +58,15 @@ export function ChatMessage({}: ChatMessageProps) {const [showTableView, setShowTableView] = useState(false);+ const renderToolResponse = (response: ChatMlMessage) => (+ <ChatMessage+ message={response}+ shouldRenderMarkdown={shouldRenderMarkdown}+ currentView={currentView}+ contentMode={contentMode}+ />+ );+const title = getMessageTitle(message);const toolCalls = parseToolCallsFromMessage(message);const hasContent = hasRenderableContent(message);@@ -158,6 +167,7 @@ export function ChatMessage({<ToolCallInvocationsViewmessage={message}toolCallNumbers={toolCallNumbers}+ renderResponse={renderToolResponse}/></div>);@@ -204,6 +214,7 @@ export function ChatMessage({<ToolCallInvocationsViewmessage={message}toolCallNumbers={toolCallNumbers}+ renderResponse={renderToolResponse}/></div>)}@@ -224,6 +235,7 @@ export function ChatMessage({<ToolCallInvocationsViewmessage={message}toolCallNumbers={toolCallNumbers}+ renderResponse={renderToolResponse}/></div>)}diff --git a/web/src/features/traces/components/ToolCallInvocationsView.tsx b/web/src/features/traces/components/ToolCallInvocationsView.tsxindex 9432155d94..0142a08f3d 100644--- a/web/src/features/traces/components/ToolCallInvocationsView.tsx+++ b/web/src/features/traces/components/ToolCallInvocationsView.tsx@@ -1,4 +1,6 @@/* eslint-disable @repo/no-style-props, @repo/no-null-render */+import type { ReactNode } from "react";+import type { ChatMlMessage } from "../hooks/useChatMLParser";import { Wrench } from "lucide-react";import { cn } from "@/src/utils/tailwind";import { PrettyJsonView } from "@/src/components/ui/PrettyJsonView";@@ -9,6 +11,7 @@ interface ToolCallInvocationsViewProps {message: z.infer<typeof ChatMlMessageSchema>;toolCallNumbers?: number[];className?: string;+ renderResponse: (message: ChatMlMessage) => ReactNode;}/**@@ -22,7 +25,11 @@ type ToolCallEntry = NonNullable<z.infer<typeof ChatMlMessageSchema>["tool_calls"]>[number] & {arguments: unknown;- response?: { output: unknown; isError?: boolean } | null;+ response?: {+ output: unknown;+ isError?: boolean;+ message?: ChatMlMessage;+ } | null;};/** Tool outputs are frequently JSON serialized as a string; show the@@ -40,6 +47,7 @@ export function ToolCallInvocationsView({message,toolCallNumbers,className,+ renderResponse,}: ToolCallInvocationsViewProps) {const toolCalls = message.tool_calls as ToolCallEntry[] | undefined;@@ -123,11 +131,14 @@ export function ToolCallInvocationsView({<span className="text-dark-red ml-1">(error)</span>)}</div>- <PrettyJsonView- json={parseIfJsonString(response.output)}- currentView="pretty"- codeClassName="text-xs"- />+ {response.message && renderResponse(response.message)}+ {!response.message && (+ <PrettyJsonView+ json={parseIfJsonString(response.output)}+ currentView="pretty"+ codeClassName="text-xs"+ />+ )}</div>)}</div>diff --git a/web/src/features/traces/parsers/toIOPreview.clienttest.ts b/web/src/features/traces/parsers/toIOPreview.clienttest.tsindex e68126e818..bad497b110 100644--- a/web/src/features/traces/parsers/toIOPreview.clienttest.ts+++ b/web/src/features/traces/parsers/toIOPreview.clienttest.ts@@ -62,7 +62,7 @@ describe("toIOPreview", () => {type: "tool-result",toolCallId: "call-1",toolName: "search",- output: { matches: 1 },+ output: { type: "json", value: { matches: 1 } },},],},@@ -122,13 +122,13 @@ describe("toIOPreview", () => {{type: "tool-result",toolCallId: "call-a",- output: "boom",+ output: { type: "text", value: "boom" },isError: true,},{type: "tool-result",toolCallId: "call-unknown",- output: "orphaned",+ output: { type: "text", value: "orphaned" },},],},diff --git a/web/src/features/traces/parsers/toIOPreview.ts b/web/src/features/traces/parsers/toIOPreview.tsindex c09b97183e..b89852bcfa 100644--- a/web/src/features/traces/parsers/toIOPreview.ts+++ b/web/src/features/traces/parsers/toIOPreview.ts@@ -1,10 +1,10 @@/* eslint-disable no-nested-ternary */import type {FilePart,- JsonValue,NormalizedIO,NormalizedMessage,NormalizedMessagePart,+ ToolResultPart,ToolDefinition as NormalizedToolDefinition,} from "@langfuse/shared/src/utils/normalized-io";import {@@ -76,7 +76,11 @@ function toToolDefinition(definition: NormalizedToolDefinition): {};}-type ToolCallResponse = { output: JsonValue; isError?: boolean } | null;+type ToolCallResponse = {+ output: ToolResultPart["output"]["value"];+ isError?: boolean;+ message?: ChatMlMessage;+} | null;function toToolCallPart(part: Extract<NormalizedMessagePart, { type: "tool-call" }>,@@ -97,10 +101,18 @@ function toToolResultMessage(// Deliberately no `name`: the renderer titles messages name-over-role, and// a tool result must render as a tool turn, not as a participant named// after the tool. The tool name stays on the paired tool-call part.+ const content =+ part.output.type === "content"+ ? toChatMessages({+ role: "tool",+ source: "output",+ parts: part.output.value,+ }).main+ : { content: part.output.value };return {+ ...content,role: "tool",...(part.toolCallId ? { tool_call_id: part.toolCallId } : {}),- content: part.output,} as ChatMlMessage;}@@ -260,7 +272,10 @@ export function toIOPreview(io: NormalizedIO): ChatMLParserResult {: undefined;if (!entry || entry.response !== null) return true;entry.response = {- output: part.output,+ output: part.output.value,+ ...(part.output.type === "content"+ ? { message: toToolResultMessage(part) }+ : {}),...(part.isError !== undefined ? { isError: part.isError } : {}),};return false;diff --git a/worker/src/features/topics/README.md b/worker/src/features/topics/README.mdindex 09b27886f8..37bff1ba7f 100644--- a/worker/src/features/topics/README.md+++ b/worker/src/features/topics/README.md@@ -295,7 +295,7 @@ and limitations.If transcript plus instructions/schema exceeds the execution's input allowance,the worker fails before calling the provider; it does notsilently change the evidence for that facet. Stored summaries record-`transcript_id` (`poc`) and `transcript_version` (`shared-transcript-v2`), plus the+`transcript_id` (`poc`) and `transcript_version` (`shared-transcript-v3`), plus themodels used. Historical summaries from other producer versions are regenerated.Accepted Redis payloads retain their recorded version when the same executionresumes. Transcripts are regenerated from current observations; original sourcediff --git a/worker/src/features/topics/assembledTranscript.test.ts b/worker/src/features/topics/assembledTranscript.test.tsindex 93901e4b7e..319055d9fa 100644--- a/worker/src/features/topics/assembledTranscript.test.ts+++ b/worker/src/features/topics/assembledTranscript.test.ts@@ -52,9 +52,12 @@ it("keeps canonical conversation evidence without provenance or opaque payloads"toolCallId: "private-call",toolName: "search",output: {- result: "Refunds allowed",- thinking: "private-thinking",- image: "data:image/png;base64,SElEREVO",+ type: "json",+ value: {+ result: "Refunds allowed",+ thinking: "private-thinking",+ image: "data:image/png;base64,SElEREVO",+ },},},{ type: "data", value: { count: 2 } },diff --git a/worker/src/features/topics/assembledTranscript.ts b/worker/src/features/topics/assembledTranscript.tsindex 2372332e36..1d494c12c8 100644--- a/worker/src/features/topics/assembledTranscript.ts+++ b/worker/src/features/topics/assembledTranscript.ts@@ -85,7 +85,10 @@ function modelPart(part: NormalizedMessagePart): unknown[] {{type: part.type,toolName: part.toolName,- output: modelData(part.output),+ output:+ part.output.type === "content"+ ? part.output.value.flatMap(modelPart)+ : modelData(part.output.value),isError: part.isError,},];diff --git a/worker/src/features/topics/summarizeAssembledTrace.test.ts b/worker/src/features/topics/summarizeAssembledTrace.test.tsindex 956f47ece6..b4f8328c1b 100644--- a/worker/src/features/topics/summarizeAssembledTrace.test.ts+++ b/worker/src/features/topics/summarizeAssembledTrace.test.ts@@ -25,7 +25,7 @@ vi.mock("@langfuse/shared/topics/server", () => ({ensureDefaultTopicFacets: (...args: unknown[]) => state.facets(...args),listTopicSummaries: (...args: unknown[]) => state.stored(...args),writeTopicSummaries: (...args: unknown[]) => state.write(...args),- TOPICS_TRANSCRIPT_VERSION: "shared-transcript-v2",+ TOPICS_TRANSCRIPT_VERSION: "shared-transcript-v3",}));vi.mock("@langfuse/shared/src/server", () => ({recordDistribution: vi.fn(),diff --git a/worker/src/queues/__tests__/traceBatchQueue.test.ts b/worker/src/queues/__tests__/traceBatchQueue.test.tsindex a52c880cb8..2e9ca3720c 100644--- a/worker/src/queues/__tests__/traceBatchQueue.test.ts+++ b/worker/src/queues/__tests__/traceBatchQueue.test.ts@@ -325,8 +325,10 @@ describe("trace batch queue", () => {tokenCount(estimates[0])! + tokenCount(estimates[1])!,});const toolCharacters = JSON.stringify({- type: "text",- text: "tool payload",+ type: "tool-result",+ toolCallId: "call",+ toolName: "lookup",+ output: { type: "text", value: "tool payload" },}).length;expect(span.attributes[@@ -378,7 +380,7 @@ describe("trace batch queue", () => {const toolCharacters = JSON.stringify({type: "tool-result",toolCallId: "unmatched",- output: "tool payload",+ output: { type: "text", value: "tool payload" },}).length;const totalCharacters =toolCharacters +