fix(openai-agents): handle MCP list tools spans by Ayush-Gupta100 · Pull Request #4508 · open-telemetry/opentelemetry-python-contrib

Ayush-Gupta100 · 2026-04-30T09:15:14Z

Description

This change teaches the OpenAI Agents v2 span processor to recognize MCPListToolsSpanData and name the span list_tools instead of falling back to unknown. It also adds test coverage for the MCP list-tools span-data path so the behavior stays covered.

Motivation and context

When an agent uses an MCP server, the SDK emits MCPListToolsSpanData while fetching the available tools. Before this change, that span was not handled by the processor, so the resulting telemetry had an unknown operation name and no useful MCP-specific behavior. This fix makes the emitted span consistent with the rest of the GenAI operation naming.

Dependencies

No new dependencies are required for this change.

Type of change

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
This change requires a documentation update

How Has This Been Tested?

python -m pytest instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/tests/test_z_span_processor_unit.py::test_operation_and_span_naming -v
python -m pytest instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/tests/test_z_span_processor_unit.py -v

These tests verify the new MCP operation mapping and confirm the full unit test file still passes.

Does This PR Require a Core Repo Change?

Yes. - Link to PR:
No.

Checklist:

Followed the style guidelines of this project
Changelogs have been updated
Unit tests have been added
Documentation has been updated

linux-foundation-easycla · 2026-04-30T09:15:22Z

The committers listed above are authorized under a signed CLA.

✅ login: Ayush-Gupta100 / name: assassins (7b8d5c8, c28bb1a, c8a9115, d75e313)
✅ login: Ayush-Gupta100 / name: Ayush Gupta (75594b1, 804db2a, c636de4)
✅ login: lzchen / name: Leighton Chen (66fcfbf)

lzchen · 2026-04-30T18:36:44Z

 - Populate instructions and tool definitions from Response obj.
  ([#4196](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4196))

+### Fixed


No need to add these headers.

lzchen · 2026-04-30T18:38:02Z

@@ -34,6 +34,7 @@
        GenerationSpanData,


Is there any additional attributes we need to handle from these types of operations in _extract_genai_attributes?

lzchen · 2026-04-30T18:53:06Z

Also this pr seems to be a duplicate of this? #4387

Copilot

Pull request overview

Updates the OpenAI Agents v2 span processor to recognize MCP “list tools” spans so they no longer fall back to an unknown GenAI operation name, and adds unit-test coverage plus changelog notes for the new mapping.

Changes:

Add MCPListToolsSpanData detection to _get_operation_name, mapping it to list_tools.
Extend test stubs and unit tests to cover the MCP list-tools span-data path.
Add a changelog entry documenting the fix.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/src/opentelemetry/instrumentation/openai_agents/span_processor.py	Imports and recognizes `MCPListToolsSpanData` to map its operation name to `list_tools`.
instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/tests/test_z_span_processor_unit.py	Adds a unit assertion for MCP list-tools operation-name mapping.
instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/tests/stubs/agents/tracing/init.py	Adds a stub `MCPListToolsSpanData` to support unit tests.
instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/CHANGELOG.md	Notes the MCP list-tools span handling fix in Unreleased.

Comments suppressed due to low confidence (1)

instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/src/opentelemetry/instrumentation/openai_agents/span_processor.py:41

The new MCPListToolsSpanData import is inside a try that only catches ModuleNotFoundError. If the agents.tracing module exists but that symbol is not present (e.g., older openai-agents versions within the supported range), this will raise ImportError at import time and break instrumentation. Please make the import resilient to missing span-data classes (e.g., catch ImportError as well and/or import the module then getattr(..., Any) for optional classes).

try:
    from agents.tracing import Span, Trace, TracingProcessor
    from agents.tracing.span_data import (
        AgentSpanData,
        FunctionSpanData,
        GenerationSpanData,
        GuardrailSpanData,
        HandoffSpanData,
        MCPListToolsSpanData,
        ResponseSpanData,
        SpeechSpanData,
        TranscriptionSpanData,
    )

Copilot · 2026-05-01T01:40:54Z

            return GenAIOperationName.HANDOFF
+        if _is_instance_of(span_data, MCPListToolsSpanData):
+            return "list_tools"
        return "unknown"


_get_operation_name now recognizes MCPListToolsSpanData, but _extract_genai_attributes has no corresponding branch for this span type. As a result, metrics (and any later logic relying on the extracted attribute dict) will see no gen_ai.operation.name for MCP list-tools spans, even though it was set at span start. Add MCP list-tools handling in the attribute extraction path (at minimum emitting gen_ai.operation.name, and ideally any relevant MCP/tool-definition attributes) so end-of-span enrichment and metrics are consistent.

Copilot · 2026-05-01T01:40:55Z

+    mcp_data = MCPListToolsSpanData()
+    assert processor._get_operation_name(mcp_data) == "list_tools"
+


This unit test only asserts _get_operation_name returns "list_tools". Given the span processor enriches spans at start/end and records metrics based on the extracted attribute dict, it would be good to add a regression assertion that a processed MCPListToolsSpanData span actually ends up with the expected gen_ai.operation.name attribute (and correct span name, if applicable) after on_span_start/on_span_end.

Copilot · 2026-05-01T01:40:55Z


+### Fixed
+
+- `opentelemetry-instrumentation-openai-agents`: Handle MCP list tools spans correctly.


The changelog entry names the package as opentelemetry-instrumentation-openai-agents, but this changelog is for opentelemetry-instrumentation-openai-agents-v2 (see pyproject.toml). Please update the package name in this entry to match the actual distribution so users can find the fix in the right package.

Suggested change

- `opentelemetry-instrumentation-openai-agents`: Handle MCP list tools spans correctly.

- `opentelemetry-instrumentation-openai-agents-v2`: Handle MCP list tools spans correctly.

Copilot · 2026-05-01T01:40:55Z

+### Fixed
+
+- `opentelemetry-instrumentation-openai-agents`: Handle MCP list tools spans correctly.
+  ([#4508](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4508))


The PR description’s change-type checklist marks this as a breaking change and says a documentation update is required, but the code changes look like a non-breaking bug fix and the only doc-facing update here is the changelog entry. Please reconcile the PR description with the actual scope/impact of the change.

Ayush-Gupta100 · 2026-05-01T08:01:56Z

Also this pr seems to be a duplicate of this? #4387

the bug is same but my pr is different as PR #4387 implements MCP semantics: sets mcp.method.name, uses MCP-style span name tools/list {target}, and marks the span SpanKind.CLIENT and it implements GenAI semantics: emits gen_ai.operation.name (list_tools), captures gen_ai.tool.definitions/gen_ai.output.type, and relies on the processor's GenAI span naming/kind.

- Add GenAIOperationName.LIST_TOOLS constant - Implement _get_attributes_from_mcp_list_tools_span_data to extract operation name, tool definitions, and output type - Update _extract_genai_attributes dispatch for MCPListToolsSpanData - Add test coverage for MCP list tools attribute extraction - Update CHANGELOG Fixes open-telemetry#4197

lzchen · 2026-05-02T19:14:10Z

@Ayush-Gupta100 It seems like this pr is a subset of #4387. Seeing as they opened the PR first, it would make sense to work with that other one. Perhaps you can review it and leave comments if it addresses your concerns?

fix(openai-agents): handle MCP list tools spans

c28bb1a

Ayush-Gupta100 requested a review from a team as a code owner April 30, 2026 09:15

github-project-automation Bot added this to Python PR digest Apr 30, 2026

Merge branch 'main' into fix-mcp-list-tools

66fcfbf

lzchen added the gen-ai Related to generative AI label Apr 30, 2026

docs: add CHANGELOG entry for MCP list tools spans fix

7b8d5c8

lzchen reviewed Apr 30, 2026

View reviewed changes

Comment thread ...mentation-openai-agents-v2/src/opentelemetry/instrumentation/openai_agents/span_processor.py Outdated

lzchen reviewed Apr 30, 2026

View reviewed changes

lzchen requested changes Apr 30, 2026

View reviewed changes

github-project-automation Bot moved this to Reviewed PRs that need fixes in Python PR digest Apr 30, 2026

Merge branch 'main' into fix-mcp-list-tools

75594b1

lmolkova requested a review from Copilot May 1, 2026 01:36

Copilot started reviewing on behalf of lmolkova May 1, 2026 01:37 View session

Copilot AI reviewed May 1, 2026

View reviewed changes

Ayush-Gupta100 and others added 2 commits May 1, 2026 13:32

Merge branch 'main' into fix-mcp-list-tools

804db2a

Ayush-Gupta100 requested a review from lzchen May 1, 2026 08:22

Ayush-Gupta100 and others added 2 commits May 2, 2026 22:02

fix: apply ruff format

c8a9115

Merge branch 'main' into fix-mcp-list-tools

c636de4

		mcp_data = MCPListToolsSpanData()
		assert processor._get_operation_name(mcp_data) == "list_tools"


		### Fixed

		- `opentelemetry-instrumentation-openai-agents`: Handle MCP list tools spans correctly.

Conversation

Ayush-Gupta100 commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation and context

Dependencies

Type of change

How Has This Been Tested?

Does This PR Require a Core Repo Change?

Checklist:

Uh oh!

linux-foundation-easycla Bot commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

lzchen Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Ayush-Gupta100 May 1, 2026

Choose a reason for hiding this comment

Uh oh!

lzchen Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

lzchen commented Apr 30, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI May 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI May 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 1, 2026

Choose a reason for hiding this comment

Uh oh!

Ayush-Gupta100 commented May 1, 2026

Uh oh!

lzchen commented May 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Ayush-Gupta100 commented Apr 30, 2026 •

edited

Loading

linux-foundation-easycla Bot commented Apr 30, 2026 •

edited

Loading