Same agent Smaller bill. The tools and infrastructure to get more work from your AI. Fewer tokens. Less compute. Lower cost.
TypeScript agent-harnessagent-harness-engineeringai-engineeringai-observabilityamd-gpuclaude-codeclickhousecodexcoding-agentcoding-agentscursorgenaigpu-monitoringllm-observabilityllmopsnvidia-smiobservabilityopen-sourceopenaiopentelemetry
fix(langgraph): map message roles to OTel convention and filter output to assistant only (#1291)
citizen2043eb106840a37
diff --git a/sdk/python/src/openlit/__helpers.py b/sdk/python/src/openlit/__helpers.pyindex f6558693..df4add2c 100644--- a/sdk/python/src/openlit/__helpers.py+++ b/sdk/python/src/openlit/__helpers.py@@ -25,6 +25,17 @@ from opentelemetry._logs import LogRecordfrom openlit.semcov import SemanticConventionfrom openlit._config import OpenlitConfig+# Shared LangChain/LangGraph message-type → OTel GenAI semantic convention role mapping.+# Both the LangChain and LangGraph instrumentations use these types; centralising here+# prevents the two copies from drifting apart.+LANGCHAIN_ROLE_MAPPING: Dict[str, str] = {+ "human": "user",+ "ai": "assistant",+ "tool": "tool",+ "function": "tool",+ "system": "system",+}+# ContextVar for propagating agent name from agent frameworks to LLM instrumentors.# Set by framework instrumentors (CrewAI, PydanticAI, etc.) or via the public# openlit.set_agent_name() API so that downstream LLM call metrics are taggeddiff --git a/sdk/python/src/openlit/instrumentation/langchain/utils.py b/sdk/python/src/openlit/instrumentation/langchain/utils.pyindex 302850ae..d5a37db9 100644--- a/sdk/python/src/openlit/instrumentation/langchain/utils.py+++ b/sdk/python/src/openlit/instrumentation/langchain/utils.py@@ -11,6 +11,7 @@ from opentelemetry.trace import Status, StatusCodefrom openlit._config import OpenlitConfigfrom openlit.__helpers import (+ LANGCHAIN_ROLE_MAPPING,common_span_attributes,get_chat_model_cost,record_completion_metrics,@@ -88,18 +89,11 @@ def build_input_messages_from_langchain(messages: List) -> List[dict]:"""try:structured = []- role_mapping = {- "system": "system",- "human": "user",- "ai": "assistant",- "tool": "tool",- "function": "tool",- }for msg_list in messages:for msg in msg_list:role = getattr(msg, "type", "user")content = getattr(msg, "content", str(msg))- otel_role = role_mapping.get(role, "user")+ otel_role = LANGCHAIN_ROLE_MAPPING.get(role, "user")structured.append({"role": otel_role,diff --git a/sdk/python/src/openlit/instrumentation/langgraph/utils.py b/sdk/python/src/openlit/instrumentation/langgraph/utils.pyindex 9a32b6d3..13d0ccab 100644--- a/sdk/python/src/openlit/instrumentation/langgraph/utils.py+++ b/sdk/python/src/openlit/instrumentation/langgraph/utils.py@@ -9,9 +9,12 @@ from openlit.__helpers import (common_framework_span_attributes,truncate_content,get_server_address_for_provider,+ LANGCHAIN_ROLE_MAPPING,)from openlit.semcov import SemanticConvention+_ROLE_MAPPING = LANGCHAIN_ROLE_MAPPING+_ROLE_ASSISTANT = "assistant"# === OPERATION MAPPING - Framework Guide Compliant ===OPERATION_MAP = {@@ -147,14 +150,42 @@ def get_message_role(message):str: Role string"""if hasattr(message, "role"):- return message.role+ raw = message.roleelif hasattr(message, "type"):- return message.type+ raw = message.typeelif hasattr(message, "__class__"):# Extract role from class name (e.g., HumanMessage -> human)class_name = message.__class__.__name__- return class_name.replace("Message", "").lower()- return "unknown"+ raw = class_name.replace("Message", "").lower()+ else:+ raw = "unknown"+ return _ROLE_MAPPING.get(raw, raw)+++def build_assistant_output_messages(messages):+ """+ Build OTel ``gen_ai.output.messages`` entries for assistant messages only.++ Per the GenAI semantic convention, output spans must not contain user/human+ or tool messages — only assistant responses belong in ``gen_ai.output.messages``.+ """+ otel_msgs = []+ for msg in messages:+ content = get_message_content(msg)+ role = get_message_role(msg)+ if content and role == _ROLE_ASSISTANT:+ otel_msgs.append(+ {+ "role": role,+ "parts": [+ {+ "type": "text",+ "content": truncate_content(content),+ }+ ],+ }+ )+ return otel_msgsdef set_graph_attributes(span, nodes=None, edges=None):@@ -193,7 +224,7 @@ def set_graph_attributes(span, nodes=None, edges=None):span.set_attribute(f"gen_ai.graph.edge.{i}.target", parts[1])-def extract_llm_info_from_result(span, state, result):+def extract_llm_info_from_result(span, state, result, set_output_messages=True):"""Extract LLM token usage, model info from node result.@@ -201,6 +232,8 @@ def extract_llm_info_from_result(span, state, result):span: OpenTelemetry spanstate: Input state dictresult: Result from node execution+ set_output_messages: When False, skip writing ``gen_ai.output.messages``+ (e.g. graph invoke already wrote assistant-only output)."""try:# Extract messages from state as OTel-compliant gen_ai.input.messages@@ -285,16 +318,12 @@ def extract_llm_info_from_result(span, state, result):SemanticConvention.GEN_AI_RESPONSE_ID, metadata["id"])- if hasattr(last_msg, "content"):- content = get_message_content(last_msg)- role = get_message_role(last_msg)- if content:- otel_msg = [- {"role": role, "content": truncate_content(content)}- ]+ if set_output_messages:+ otel_msgs = build_assistant_output_messages([last_msg])+ if otel_msgs:span.set_attribute(SemanticConvention.GEN_AI_OUTPUT_MESSAGES,- json.dumps(otel_msg),+ json.dumps(otel_msgs),)# Extract usage_metadata (alternative location)@@ -596,21 +625,19 @@ def _process_invoke_response(span, response, capture_message_content):)if capture_message_content:- otel_msgs = []- for msg in messages:- content = get_message_content(msg)- role = get_message_role(msg)- entry = {"role": role}- if content:- entry["content"] = truncate_content(content)- otel_msgs.append(entry)+ otel_msgs = build_assistant_output_messages(messages)if otel_msgs:span.set_attribute(SemanticConvention.GEN_AI_OUTPUT_MESSAGES,json.dumps(otel_msgs),)- extract_llm_info_from_result(span, {}, response)+ extract_llm_info_from_result(+ span,+ {},+ response,+ set_output_messages=not capture_message_content,+ )except Exception:passdiff --git a/sdk/python/tests/test_langgraph.py b/sdk/python/tests/test_langgraph.pyindex c6854c4c..6f02c1c8 100644--- a/sdk/python/tests/test_langgraph.py+++ b/sdk/python/tests/test_langgraph.py@@ -279,7 +279,49 @@ class TestLangGraphInstrumentorUnit:type = "human"result = get_message_role(MockMessageWithType())- assert result == "human"+ assert result == "user"++ class MockAiMessage:+ type = "ai"++ assert get_message_role(MockAiMessage()) == "assistant"++ def test_build_assistant_output_messages_filters_non_assistant(self):+ """Only assistant messages belong in gen_ai.output.messages."""+ from openlit.instrumentation.langgraph.utils import build_assistant_output_messages++ class HumanMsg:+ type = "human"+ content = "user turn"++ class AiMsg:+ type = "ai"+ content = "assistant reply"++ result = build_assistant_output_messages([HumanMsg(), AiMsg()])+ assert len(result) == 1+ assert result[0]["role"] == "assistant"+ assert result[0]["parts"][0]["content"] == "assistant reply"++ def test_extract_llm_info_skips_human_output_message(self):+ """Node results ending in HumanMessage must not write gen_ai.output.messages."""+ from openlit.instrumentation.langgraph.utils import extract_llm_info_from_result++ class HumanMsg:+ type = "human"+ content = "follow-up question"++ class MockSpan:+ def __init__(self):+ self.attributes = {}++ def set_attribute(self, key, value):+ """Record span attributes for assertions."""+ self.attributes[key] = value++ span = MockSpan()+ extract_llm_info_from_result(span, {}, {"messages": [HumanMsg()]})+ assert "gen_ai.output.messages" not in span.attributesdef test_generate_span_name(self):"""Tests span name generation."""diff --git a/sdk/typescript/src/helpers.ts b/sdk/typescript/src/helpers.tsindex b976d26b..6f6577ac 100644--- a/sdk/typescript/src/helpers.ts+++ b/sdk/typescript/src/helpers.ts@@ -226,6 +226,25 @@ export function getServerAddressForProvider(provider: string): [string, number]return PROVIDER_DEFAULT_ENDPOINTS[provider] || ['', 0];}+/** LangChain/LangGraph message type → OTel GenAI role (mirrors Python LANGCHAIN_ROLE_MAPPING). */+export const LANGCHAIN_ROLE_MAP: Record<string, string> = {+ system: 'system',+ human: 'user',+ ai: 'assistant',+ tool: 'tool',+ function: 'tool',+};++export const OTEL_ASSISTANT_ROLE = LANGCHAIN_ROLE_MAP.ai;++/** Map a raw LangChain message type/role to the OTel GenAI convention value. */+export function mapLangChainRole(rawRole: string | undefined | null): string {+ if (!rawRole) {+ return OTEL_ASSISTANT_ROLE;+ }+ return LANGCHAIN_ROLE_MAP[rawRole] ?? rawRole;+}+/*** Apply global (from init) and context-scoped (from usingAttributes /* injectAdditionalAttributes) custom attributes to a span.diff --git a/sdk/typescript/src/instrumentation/__tests__/langchain-role-map.test.ts b/sdk/typescript/src/instrumentation/__tests__/langchain-role-map.test.tsnew file mode 100644index 00000000..18e576c6--- /dev/null+++ b/sdk/typescript/src/instrumentation/__tests__/langchain-role-map.test.ts@@ -0,0 +1,23 @@+import {+ LANGCHAIN_ROLE_MAP,+ OTEL_ASSISTANT_ROLE,+ mapLangChainRole,+} from '../../helpers';++describe('LangChain role mapping', () => {+ it('maps LangChain internal types to OTel GenAI roles', () => {+ expect(LANGCHAIN_ROLE_MAP.human).toBe('user');+ expect(LANGCHAIN_ROLE_MAP.ai).toBe('assistant');+ expect(OTEL_ASSISTANT_ROLE).toBe('assistant');+ });++ it('mapLangChainRole passes through already-normalised roles', () => {+ expect(mapLangChainRole('user')).toBe('user');+ expect(mapLangChainRole('assistant')).toBe('assistant');+ });++ it('mapLangChainRole defaults empty raw roles to assistant', () => {+ expect(mapLangChainRole('')).toBe('assistant');+ expect(mapLangChainRole(null)).toBe('assistant');+ });+});diff --git a/sdk/typescript/src/instrumentation/langchain/wrapper.ts b/sdk/typescript/src/instrumentation/langchain/wrapper.tsindex 112f6fc1..9c12abdf 100644--- a/sdk/typescript/src/instrumentation/langchain/wrapper.ts+++ b/sdk/typescript/src/instrumentation/langchain/wrapper.ts@@ -10,6 +10,7 @@ import OpenLitHelper, {setFrameworkParentContext,clearFrameworkParentContext,getServerAddressForProvider,+ LANGCHAIN_ROLE_MAP,} from '../../helpers';import { SDK_NAME, SDK_VERSION } from '../../constant';import SemanticConvention from '../../semantic-convention';@@ -260,13 +261,7 @@ function detectObservationType(serialized: any, callbackType: string, name: stri// Message formatting helpers (mirrors Python utils.py)// ----------------------------------------------------------------------------const ROLE_MAP: Record<string, string> = {- system: 'system',- human: 'user',- ai: 'assistant',- tool: 'tool',- function: 'tool',-};+const ROLE_MAP = LANGCHAIN_ROLE_MAP;function buildInputMessagesFromLangChain(messages: any[][]): any[] {try {diff --git a/sdk/typescript/src/instrumentation/langgraph/wrapper.ts b/sdk/typescript/src/instrumentation/langgraph/wrapper.tsindex a52a8e1e..5400ce3b 100644--- a/sdk/typescript/src/instrumentation/langgraph/wrapper.ts+++ b/sdk/typescript/src/instrumentation/langgraph/wrapper.ts@@ -10,8 +10,10 @@ import {import { ATTR_SERVICE_NAME, ATTR_TELEMETRY_SDK_NAME } from '@opentelemetry/semantic-conventions';import SemanticConvention from '../../semantic-convention';import OpenlitConfig from '../../config';-import OpenLitHelper, { applyCustomSpanAttributes } from '../../helpers';-import {+import OpenLitHelper, {+ applyCustomSpanAttributes,+ mapLangChainRole,+ OTEL_ASSISTANT_ROLE,runWithLangGraph,runWithCreateAgent,isCreateAgentActive,@@ -630,11 +632,14 @@ function extractLlmInfoFromResult(span: any, _state: any, result: any): void {? lastMsg.content: JSON.stringify(lastMsg.content);if (content && OpenlitConfig.captureMessageContent) {- const role = lastMsg.role || lastMsg._getType?.() || lastMsg.type || 'assistant';- span.setAttribute(- SemanticConvention.GEN_AI_OUTPUT_MESSAGES,- JSON.stringify([{ role, parts: [{ type: 'text', content }] }])- );+ const rawRole = lastMsg.role || lastMsg._getType?.() || lastMsg.type || '';+ const role = mapLangChainRole(rawRole);+ if (role === OTEL_ASSISTANT_ROLE) {+ span.setAttribute(+ SemanticConvention.GEN_AI_OUTPUT_MESSAGES,+ JSON.stringify([{ role, parts: [{ type: 'text', content }] }])+ );+ }}}} catch { /* don't fail the span */ }