Skip to content

Same agent Smaller bill. The tools and infrastructure to get more work from your AI. Fewer tokens. Less compute. Lower cost.

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.py
index 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 LogRecord
from openlit.semcov import SemanticConvention
from 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 tagged
diff --git a/sdk/python/src/openlit/instrumentation/langchain/utils.py b/sdk/python/src/openlit/instrumentation/langchain/utils.py
index 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, StatusCode
from openlit._config import OpenlitConfig
from 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.py
index 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.role
elif hasattr(message, "type"):
- return message.type
+ raw = message.type
elif 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_msgs
def 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 span
state: Input state dict
result: 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:
pass
diff --git a/sdk/python/tests/test_langgraph.py b/sdk/python/tests/test_langgraph.py
index 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.attributes
def test_generate_span_name(self):
"""Tests span name generation."""
diff --git a/sdk/typescript/src/helpers.ts b/sdk/typescript/src/helpers.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 */ }