feat(openai-agents): GenAI semconv compliance

[max-deygin-traceloop]

Migrate openai-agents instrumentation to OTel GenAI semconv

Aligns the OpenAI Agents SDK instrumentation with the upstream OpenTelemetry GenAI semantic conventions.

Changes:

• Replace all SpanAttributes.LLM_* constants with upstream GenAIAttributes.GEN_AI_* equivalents
• Migrate flat gen_ai.prompt.{i}.* / gen_ai.completion.{i}.* attributes to gen_ai.input.messages / gen_ai.output.messages JSON arrays
• Migrate flat gen_ai.tool.definitions.{i}.* attributes to gen_ai.tool.definitions JSON array
• Fix 5 duplicate gen_ai.operation.name dict keys in _hooks.py
• Fix duplicate gen_ai.system key in _realtime_wrappers.py
• Update all tests to use new attribute names and JSON array format

---

Note: This is a recreation of #3823, which was auto-closed when its target branch was merged into main. No code changes were made.

Summary by CodeRabbit

• Refactor

  • Telemetry now records conversation inputs/outputs as JSON arrays (gen_ai.input.messages, gen_ai.output.messages) instead of many per-message attributes.
  • Tool definitions and usage totals are consolidated into single JSON attributes and updated semantic names (gen_ai.tool_definitions, gen_ai.usage.*, gen_ai.operation.name).

• Tests

  • Tests updated to validate the new JSON-encoded attributes and revised semantic convention names.

• Chores

  • Bumped semantic conventions dependency to v0.5.0+.

[coderabbitai]

📝 Walkthrough

Walkthrough

Prompt and response attributes were consolidated: per-message indexed attributes (e.g., gen_ai.prompt.0.*, gen_ai.completion.0.*) are replaced by JSON-encoded message arrays stored in gen_ai.input.messages and gen_ai.output.messages. Span attribute names were updated to newer GenAI semconv fields; tests and dependency constraints adjusted accordingly.

Changes

Cohort / File(s)	Summary
Core Implementation packages/opentelemetry-instrumentation-openai-agents/opentelemetry/instrumentation/openai_agents/_hooks.py, packages/opentelemetry-instrumentation-openai-agents/opentelemetry/instrumentation/openai_agents/_realtime_wrappers.py	Reworked prompt/response extraction to emit single JSON-encoded arrays (gen_ai.input.messages, gen_ai.output.messages) instead of per-message indexed attributes; removed some tool metadata attributes and legacy fallbacks; switched request-type/usage attribute names to GenAI semconv; added json usage for serialization.
Dependencies packages/opentelemetry-instrumentation-openai-agents/pyproject.toml	Bumped opentelemetry-semantic-conventions-ai constraint from >=0.4.13,<0.5.0 to >=0.5.0,<0.6.0.
Tests packages/opentelemetry-instrumentation-openai-agents/tests/test_openai_agents.py, .../tests/test_realtime.py, .../tests/test_realtime_session.py, .../tests/test_recipe_agents_hierarchy.py	Updated tests to parse and assert JSON-encoded gen_ai.input.messages / gen_ai.output.messages instead of indexed prompt/completion attributes; removed assertions for SpanAttributes.LLM_REQUEST_TYPE; added json imports and tightened usage attribute checks to gen_ai.usage.*.
New Compliance Test packages/opentelemetry-instrumentation-openai-agents/tests/test_semconv_compliance.py	Added test module that imports semantic-convention test symbols from opentelemetry.semconv_ai._testing to validate installed semconv constants.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 Hop, hop, messages bundled tight,

JSON arrays gleam in telemetry light,
No more indices scattered wide,
One tidy stream where prompts reside,
A rabbit cheers the cleaner stride! 🎉

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	Docstring coverage is 93.75% which is sufficient. The required threshold is 80.00%.
Title check	✅ Passed	The title accurately describes the main change: migrating OpenAI Agents instrumentation to comply with upstream OpenTelemetry GenAI semantic conventions.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch max/tlp-1928-openai-agents-insturmentation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

packages/opentelemetry-instrumentation-openai-agents/tests/test_semconv_compliance.py (1)

1-8: Consider extending _testing.py to cover new message/tool attributes.

The shared compliance tests in opentelemetry.semconv_ai._testing (per the context snippet at packages/opentelemetry-semantic-conventions-ai/opentelemetry/semconv_ai/_testing.py:1-56) currently validate renamed GEN_AI_* constants but do not include tests for:

• GenAIAttributes.GEN_AI_INPUT_MESSAGES
• GenAIAttributes.GEN_AI_OUTPUT_MESSAGES
• GenAIAttributes.GEN_AI_TOOL_DEFINITIONS

These constants are imported from the upstream opentelemetry.semconv._incubating.attributes.gen_ai_attributes module and used heavily throughout _hooks.py and _realtime_wrappers.py. While the import will fail if the constants don't exist, explicit compliance tests would provide better validation and documentation.

Would you like me to draft compliance tests for these new upstream constants in _testing.py?

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@packages/opentelemetry-instrumentation-openai-agents/tests/test_semconv_compliance.py`
around lines 1 - 8, Add explicit compliance assertions in the shared test module
_testing.py to verify the presence and expected values of the three new GenAI
constants: GenAIAttributes.GEN_AI_INPUT_MESSAGES,
GenAIAttributes.GEN_AI_OUTPUT_MESSAGES, and
GenAIAttributes.GEN_AI_TOOL_DEFINITIONS; import these from
opentelemetry.semconv._incubating.attributes.gen_ai_attributes (same source used
by _hooks.py and _realtime_wrappers.py) and add simple equality/assertion checks
that the exported constants in opentelemetry.semconv_ai match the upstream
constants so the tests will fail if those names or values are missing or
renamed.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In
`@packages/opentelemetry-instrumentation-openai-agents/tests/test_semconv_compliance.py`:
- Around line 1-8: Add explicit compliance assertions in the shared test module
_testing.py to verify the presence and expected values of the three new GenAI
constants: GenAIAttributes.GEN_AI_INPUT_MESSAGES,
GenAIAttributes.GEN_AI_OUTPUT_MESSAGES, and
GenAIAttributes.GEN_AI_TOOL_DEFINITIONS; import these from
opentelemetry.semconv._incubating.attributes.gen_ai_attributes (same source used
by _hooks.py and _realtime_wrappers.py) and add simple equality/assertion checks
that the exported constants in opentelemetry.semconv_ai match the upstream
constants so the tests will fail if those names or values are missing or
renamed.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 55f0bea4-7b6a-434a-89a3-58e2c26ee263

📥 Commits

Reviewing files that changed from the base of the PR and between 3f2418b and af07493.

⛔ Files ignored due to path filters (1)

• packages/opentelemetry-instrumentation-openai-agents/uv.lock is excluded by !**/*.lock

📒 Files selected for processing (8)

• packages/opentelemetry-instrumentation-openai-agents/opentelemetry/instrumentation/openai_agents/_hooks.py
• packages/opentelemetry-instrumentation-openai-agents/opentelemetry/instrumentation/openai_agents/_realtime_wrappers.py
• packages/opentelemetry-instrumentation-openai-agents/pyproject.toml
• packages/opentelemetry-instrumentation-openai-agents/tests/test_openai_agents.py
• packages/opentelemetry-instrumentation-openai-agents/tests/test_realtime.py
• packages/opentelemetry-instrumentation-openai-agents/tests/test_realtime_session.py
• packages/opentelemetry-instrumentation-openai-agents/tests/test_recipe_agents_hierarchy.py
• packages/opentelemetry-instrumentation-openai-agents/tests/test_semconv_compliance.py

💤 Files with no reviewable changes (1)

• packages/opentelemetry-instrumentation-openai-agents/tests/test_realtime.py

[doronkopit5]

recalling @avivhalfon comments, shouldn't this be provider?

[doronkopit5]

did you succeed testing sending traces with this instrumentation using a sample-app?