feat: add agent span support in langchain instrumentation by yiyuan-he · Pull Request #3788 · open-telemetry/opentelemetry-python-contrib

yiyuan-he · 2025-09-25T16:05:00Z

Description

This PR adds agent span support to the LangChain instrumentation following the OpenTelemetry Semantic Conventions for GenAI agent spans. It enables tracing of LangChain agent invocations, chain executions, and agent actions/decisions.

invoke_agent operation for agent invocations
Proper span naming: invoke_agent {agent_name} and chain {chain_name}
Agent-specific attributes: gen_ai.agent.name, gen_ai.operation.name

A follow-up PR will add tool execution spans (execute_tool operation).

Sidenote: Previous PR from our team can be closed.

Type of change

Please delete options that are not relevant.

New feature (non-breaking change which adds functionality)

How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration

Added unit tests for agent span creation and lifecycle
Added unit tests for chain span creation with proper parent-child
relationships
Added unit tests for agent action and finish callbacks
All existing tests continue to pass
Tests verify proper span attributes according to semantic conventions

Does This PR Require a Core Repo Change?

Yes. - Link to PR:
No.

Checklist:

See contributing.md for styleguide, changelog guidelines, and more.

Followed the style guidelines of this project
Changelogs have been updated
Unit tests have been added
[] Documentation has been updated (README update may be needed in follow-up)

rads-1996 · 2025-10-02T17:44:19Z

+        )
+        span.set_attribute(
+            GenAI.GEN_AI_OPERATION_NAME,
+            "invoke_agent",


Is it possible that the operation name might be changed in the future, if so, declaring it a constant for it might be better.

Good point - I'm not sure if this semantic convention will change but agree that this should be moved to a constant since it's currently hardcoded in a few places.

rads-1996 · 2025-10-02T17:49:59Z

+            GenAI.GEN_AI_OPERATION_NAME,
+            "invoke_agent",
+        )
+        if agent_name:


If agent_name is None, in that case, should a default value be passed?

Yeah makes sense, i'll default it to "unknown" for now. Open to suggestions on the naming though.

rads-1996 · 2025-10-02T17:52:31Z

+    span = spans[0]
+    assert span.name == "chain TestAgent"
+    assert span.kind == SpanKind.INTERNAL
+    assert span.attributes.get(GenAI.GEN_AI_AGENT_NAME) == "TestAgent"


In the above comment you mentioned that chain spans are internal operations and will not have an operation name but there you are adding assert statements for it, did I miss something?

Thanks for your review! Let me try to clarify.

Regular chains don't have gen_ai.operation.name since they're just internal operations. However, Agent chains are different. In LangChain's architecture, agents are implemented as chains so we:

create them using create_agent_span() (which creates an internal span)

detect if it's actually an agent by checking for agent_name in metadata

if it is an agent, we add the agent-specific attributes:

gen_ai.agent.name

gen_ai.operation.name = "invoke_agent"

I'll update the docstrings to make this distinction clearer.

Awesome. Thanks for the clarification.

lmolkova · 2025-12-04T17:24:38Z

+__all__ = ["_SpanManager", "_OPERATION_INVOKE_AGENT"]
+
+# Operation name constants
+_OPERATION_INVOKE_AGENT = "invoke_agent"


there is a constant in semconv for it - https://github.com/open-telemetry/opentelemetry-python/blob/83ee962595b04d0b43ed1a04a87cf1ce03795521/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/gen_ai_attributes.py#L416

lmolkova · 2025-12-04T17:28:03Z

+        if span:
+            tool = getattr(action, "tool", None)  # type: ignore[arg-type]
+            if tool:
+                span.set_attribute("langchain.agent.action.tool", tool)


could this be expressed as one of a standard tool attributes?

https://github.com/open-telemetry/opentelemetry-python/blob/83ee962595b04d0b43ed1a04a87cf1ce03795521/opentelemetry-semantic-conventions/src/opentelemetry/semconv/_incubating/attributes/gen_ai_attributes.py#L347

(all tool attributes are in the semconv - https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-spans.md#execute-tool-span)

lmolkova · 2025-12-04T17:28:43Z

+            tool_input = getattr(action, "tool_input", None)  # type: ignore[arg-type]
+            if tool_input:
+                span.set_attribute(
+                    "langchain.agent.action.tool_input", str(tool_input)


should this be gen_ai.tool.call.arguments ?

lmolkova · 2025-12-04T17:30:18Z

+            return_values = getattr(finish, "return_values", None)  # type: ignore[arg-type]
+            if return_values and "output" in return_values:
+                span.set_attribute(
+                    "langchain.agent.finish.output",


should this be either [gen_ai.tool.call.result](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/registry/attributes/gen-ai.md) or gen_ai.output.messages ?

lmolkova · 2025-12-04T17:34:02Z

+        if agent_name:
+            span.set_attribute(GenAI.GEN_AI_AGENT_NAME, agent_name)
+
+        return span


Invoke agent span must have gen_ai.provider.name attribute with a name of genai system used under (e.g. openai, vertex_ai, etc). Is it possible to populate them here?

there are more recommended/opt-in attributes documented in https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-agent-spans.md#invoke-agent-span

lmolkova

Left some comments around following semconv more closely and reusing constants from the semconv lib.

lmolkova · 2025-12-04T17:49:15Z

@zhirafovod @wrisa could you please review?

wrisa · 2025-12-08T20:50:13Z

+        if span:
+            tool = getattr(action, "tool", None)  # type: ignore[arg-type]
+            if tool:
+                span.set_attribute("langchain.agent.action.tool", tool)


I guess your intention is to use gen_ai.tool.name, gen_ai.tool.call.result and gen_ai.tool.call.arguments which are on execute_tool. Please use these gen-ai attributes. Also another PR updating invoke_agent with the above attributes would also be required.

github-actions · 2026-03-11T03:55:52Z

This PR has been automatically marked as stale because it has not had any activity for 14 days. It will be closed if no further activity occurs within 14 days of this comment.
If you're still working on this, please add a comment or push new commits.

github-actions · 2026-03-25T04:03:24Z

This PR has been closed due to inactivity. Please reopen if you would like to continue working on it.

feat: add agent span support in langchain instrumentation

529ebd7

yiyuan-he requested a review from a team as a code owner September 25, 2025 16:05

Merge branch 'main' into langchain-agent-spans

b1fe20f

github-actions Bot assigned codefromthecrypt, karthikscale3, lzchen and nirga Sep 25, 2025

yiyuan-he and others added 5 commits September 25, 2025 16:25

fix precommit and typechecks

d030990

Merge branch 'main' into langchain-agent-spans

87b6b05

update changelog with PR number

f1d1cee

Merge branch 'main' into langchain-agent-spans

207c54d

Merge branch 'main' into langchain-agent-spans

fdacebd

lmolkova reviewed Sep 30, 2025

View reviewed changes

Comment thread ...ry-instrumentation-langchain/src/opentelemetry/instrumentation/langchain/callback_handler.py

yiyuan-he added 2 commits October 1, 2025 15:32

Merge branch 'main' into langchain-agent-spans

d3b2528

Merge branch 'main' into langchain-agent-spans

1b98f9f

rads-1996 reviewed Oct 2, 2025

View reviewed changes

yiyuan-he and others added 7 commits October 3, 2025 09:47

Merge branch 'main' into langchain-agent-spans

ae6bf62

address pr comments

744ddb6

Merge branch 'main' into langchain-agent-spans

82bfb84

Merge branch 'main' into langchain-agent-spans

6fb9f9f

apply ruff format

7807450

Merge branch 'main' into langchain-agent-spans

9058d97

Merge branch 'main' into langchain-agent-spans

e95d658

github-actions Bot assigned lmolkova Oct 15, 2025

yiyuan-he added 2 commits October 16, 2025 08:30

Merge branch 'main' into langchain-agent-spans

86033c3

Merge branch 'main' into langchain-agent-spans

4de0f08

lmolkova reviewed Oct 28, 2025

View reviewed changes

Merge branch 'main' into langchain-agent-spans

c33571b

yiyuanh and others added 4 commits November 25, 2025 09:47

address pr comments for agent span creation

370d930

Merge branch 'main' into langchain-agent-spans

f97424c

Merge branch 'main' into langchain-agent-spans

ca54118

Merge branch 'main' into langchain-agent-spans

e0881b9

lmolkova reviewed Dec 4, 2025

View reviewed changes

lmolkova requested changes Dec 4, 2025

View reviewed changes

lmolkova unassigned codefromthecrypt, lmolkova, nirga, lzchen and karthikscale3 Dec 4, 2025

wrisa reviewed Dec 8, 2025

View reviewed changes

yiyuan-he mentioned this pull request Jan 20, 2026

langchain instrumentor PR aws-observability/aws-otel-python-instrumentation#448

Closed

github-actions Bot added the Stale label Mar 11, 2026

github-actions Bot closed this Mar 25, 2026

Conversation

yiyuan-he commented Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

How Has This Been Tested?

Does This PR Require a Core Repo Change?

Checklist:

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lmolkova left a comment

Choose a reason for hiding this comment

Uh oh!

lmolkova commented Dec 4, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Mar 11, 2026

Uh oh!

github-actions Bot commented Mar 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

yiyuan-he commented Sep 25, 2025 •

edited

Loading