Improve OpenAI Agents conformance and metrics

[alfozan]

Description

Updates the OpenAI Agents instrumentation to better handle current Agents SDK tracing data and the GenAI semantic-convention issues reported in #86.

High-level changes:

• Handles current response and generation span payload shapes, including string response input, response IDs/models, token usage, tool definitions, and system instructions.
• Uses the current Agents SDK span-data module layout directly instead of carrying a legacy import fallback.
• Avoids emitting gen_ai.operation.name = unknown for non-GenAI Agents SDK spans such as task, turn, MCP list-tools, speech group, and custom spans.
• Removes gen_ai.system from OpenAI Agents spans and leaves successful spans with unset status.
• Emits required response/content fields when the SDK omits them, including gen_ai.response.finish_reasons and output-message finish_reason fallback values.
• Removes undocumented handoff GenAI operation/attributes from handoff spans.
• Emits gen_ai.tool.call.id for tool spans, falling back to the SDK span ID when no call ID is available.
• Stops labeling the root workflow span as invoke_agent, so arbitrary workflow trace names are not validated as invoke-agent span names.
• Enables metrics support with the shared GenAI duration/token histogram helpers and the configured meter_provider.
• Preserves custom/sandbox span attributes from CustomSpanData.data (for example sandbox.* and process exit attributes) without assigning them a GenAI operation.
• Refreshes the examples and supported openai-agents test range for the current Agents SDK.

This addresses the OpenAI Agents instrumentation failures called out in #86 without marking that issue closed here, since this PR still does not add a live weaver scenario for the package.

Type of change

• Bug fix (non-breaking change which fixes an issue)

How has this been tested?

Latest checks on the final pushed diff:

• uvx --with tox-uv tox -e py310-test-instrumentation-genai-openai_agents-oldest,py310-test-instrumentation-genai-openai_agents-latest,py311-test-instrumentation-genai-openai_agents-oldest,py311-test-instrumentation-genai-openai_agents-latest,py312-test-instrumentation-genai-openai_agents-oldest,py312-test-instrumentation-genai-openai_agents-latest,py313-test-instrumentation-genai-openai_agents-oldest,py313-test-instrumentation-genai-openai_agents-latest,py314-test-instrumentation-genai-openai_agents-oldest,py314-test-instrumentation-genai-openai_agents-latest,lint-instrumentation-genai-openai_agents -- -q
• uvx --with tox-uv tox -e precommit
• git diff --check

Earlier validation for this PR:

• uvx --with tox-uv tox -e lint-license-header-check
• uvx ruff format --check instrumentation/opentelemetry-instrumentation-genai-openai-agents
• uvx --from towncrier==25.8.0 towncrier build --draft --version Unreleased
• Real SDK smoke checks with openai-agents==0.17.0 and openai-agents==0.17.2
• Example dependency install checks for the manual and zero-code examples using local editable packages.
• Example smoke checks for content capture, manual instrumentation, and zero-code instrumentation.
• Healthcare OTEL e2e smoke with local Collector/Jaeger using prior_auth_confusion_ct; verified service name, GenAI attrs, no unknown operation names, and sandbox attrs in Jaeger trace dea30d9909ec5238e7347130f25dc4c2.

Checklist

See CONTRIBUTING.md for the style guide, changelog guidance, and more.

• Followed the style guidelines of this project
• Changelog updated if the change requires an entry
• Unit tests added
• Documentation updated

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: alfozan / name: Abdulrahman Alfozan (3b2fd00, 420a319, 5dbf2b2, 6deae89)

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Updates the OpenAI Agents v2 instrumentation to better support current Agents SDK tracing payload shapes, while updating the supported openai-agents version range and expanding test coverage for newer span types.

Changes:

• Add support for additional Agents SDK span data types (task/turn/custom/MCP tools/speech group) in the span processor.
• Improve message normalization to handle string input payloads (e.g., response spans).
• Update compatibility range to openai-agents >= 0.17.0 and expand tests accordingly.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
instrumentation/opentelemetry-instrumentation-openai-agents-v2/tests/test_z_span_processor_unit.py	Updates unit test expectation for unknown span operation handling (now None).
instrumentation/opentelemetry-instrumentation-openai-agents-v2/tests/test_tracer.py	Adds new tracer tests for string inputs and current Agents SDK span types.
instrumentation/opentelemetry-instrumentation-openai-agents-v2/tests/stubs/agents/tracing/init.py	Extends tracing stubs with additional span types used in tests.
instrumentation/opentelemetry-instrumentation-openai-agents-v2/tests/requirements.oldest.txt	Bumps oldest tested openai-agents to 0.17.0.
instrumentation/opentelemetry-instrumentation-openai-agents-v2/tests/requirements.latest.txt	Bumps latest tested openai-agents to 0.17.2.
instrumentation/opentelemetry-instrumentation-openai-agents-v2/src/opentelemetry/instrumentation/openai_agents/span_processor.py	Adds new span-type handling, safer naming, usage extraction, and string message normalization.
instrumentation/opentelemetry-instrumentation-openai-agents-v2/src/opentelemetry/instrumentation/openai_agents/package.py	Updates declared instrumented package minimum version.
instrumentation/opentelemetry-instrumentation-openai-agents-v2/pyproject.toml	Updates optional dependency range for instruments extra.
instrumentation/opentelemetry-instrumentation-openai-agents-v2/.changelog/49.fixed	Adds changelog entry for the fix.

[alfozan]

Hi @lzchen, PR is updated. Could you please take another look when you have a chance?

[lmolkova]

I think it would be best to fix existing issues in OpenAI Agents instrumentation before adding more features to it - #86

[alfozan]

I think it would be best to fix existing issues in OpenAI Agents instrumentation before adding more features to it - #86

Hi @lmolkova, agreed. I updated this PR to address the conformance failures from #86.

[alfozan]

Hi @lzchen, @lmolkova. Could you please take a look when you have a chance?

[alfozan]

Hi @nagkumar91, @hectorhdzg, @rads-1996, could one of you take a look at this PR when you have a chance?

[rads-1996]

Would it make more sense to move all of these constants to a constant.py file instead of adding it in this one?

[alfozan]

I kept them here because they are only used in span_processor.py, and this package does not currently have a constants module. I’d prefer to avoid the extra refactor in this PR, but we can do it in a follow-up PR once this is merged.

[lzchen]

Do we need a default if gen_ai.response.finish_reasons is recommended and not mandatory?

[alfozan]

Updated, this now only emits gen_ai.response.finish_reasons when the SDK provides a finish reason.

[lzchen]

This is kind of problematic as [gen_ai.operation.name](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/registry/attributes/gen-ai.md) is a required field. I understand that the root workflow span shouldn't be marked as invoke_agent however. @lmolkova any thoughts?

[lzchen]

A lot of this behavior is undefined. Should we mark root spans as OK status if the end properly? @lmolkova @aabmass wdyt?