feat(mappers): add OpenAI Agents OTel session mapper

[liramon2]

Description

Add support for OpenAI Agent SDK + OpenLLMetry Traceloop instrumentation to GenericGenAISessionMapper. This combination supports GenAI conventions with some deviations. The PR handles both Cloudwatch ADOT and in-memory exporter formats. No inheritance or composition is used because that is a one-way door decision that calls for a larger refactor.

This PR also fixes parent span ids in GenericGenAISessionMapper so that they point to converted spans. This preserves the agent-tool scopes when converting from OpenAI Agent traces (or other GenAI traces) to evaluator inputs.

Related Issues

#319

Documentation PR

Type of Change

New feature

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce new warnings.

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have reviewed and understand every line of code in this PR, including any generated by AI tools, and I can explain why it works
• My change is focused and reasonably small; I have split unrelated work into separate PRs
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[liramon2]

@strandly-the-agent Review this PR. Consolidate findings into 1 comment.

[liramon2]

@strandly-the-agent Review this PR. Consolidate findings into 1 comment. Accepting the risk of finding 3 because it is difficult to reach.

[liramon2]

@strandly-the-agent Review this PR. Consolidate any findings into a single comment.

[liramon2]

@strandly-the-agent Review this PR. Consolidate any findings into a single comment. The 3 findings found in the last round are theoretical, not realistic.

[liramon2]

@strandly-the-agent Review this PR. Consolidate any findings into a single comment.

[liramon2]

@strandly-the-agent Review this PR. Consolidate any findings into a single comment. A vendor special-case is acceptable for now and the docstring specifies that the scope name is unrecognized by the other mappers.

[liramon2]

@strandly-the-agent Review this PR. Consolidate any findings into a single comment.

[liramon2]

@strandly-the-agent Review this PR. Consolidate any findings into a single comment.

[strandly-the-agent]

Suite is green again — the round-7 🔴 is fixed, and nothing of mine remains open. The amended head applies the five assertion updates (delta is tests-only: +27/-14, source and fixtures untouched) and adds the test_research_specialist_tools case pinning the best property of the new definitions path — get_weather listed as available despite never being called. No new findings.

✅ 916ece7 · mapper suite 379 passed · mappers+extractors+types 511 passed · ruff check + format --check clean · verified the delta touches only the test file.

Full ledger across the PR: findings 1/2/4 fixed at 5b1142b · finding 5 fixed at 9fb48f5 · finding 3 risk-accepted · findings 6–8 withdrawn as theoretical · vendor special-case accepted · round-5 backfill-coverage 🟡 fixed at 6971865 · round-7 stale-tests 🔴 fixed here. From my side this is merge-ready pending a human maintainer's approval.

What I ran

head 916ece7dd848ca5b95e0677dfc3c81520081dd3f (amend of 086d053; delta tests-only, +27/-14)

pytest tests/strands_evals/mappers/ -q                       -> 379 passed (was 5 failed, 373 passed)
pytest mappers/ extractors/ types/ -q                        -> 511 passed
ruff check / ruff format --check (changed file)              -> clean
git diff 086d053..HEAD -- src/ fixtures/                     -> empty (no source or fixture change)

Self-run follow-up — the delta only repairs my round-7 finding. Automated review — solid work for a human to approve, not a gate.

[liramon2]

@strandly-the-agent Review this PR. Consolidate any findings into a single comment. I removed the handoff reparenting because handoffs are semantically sibling agents.

[strandly-the-agent]

No blocking findings. Reviewed the 916ece7..2210c15 delta — the handoff-reparenting removal is clean and complete, the sibling-agents semantic call makes sense to me, and the suite is green. One ⚪: the rewritten test's docstring describes the root-selection rule incorrectly (suggestion below). From my side the PR remains merge-ready pending human approval.

✅ 2210c15 · mapper suite 379 passed · mappers+extractors+types 511 passed · ruff check + format --check clean · no dangling reparenting references left in src/ (remaining "handoff" hits are the unrelated, pre-existing swarm_extractor.py).

The reversal, for the ledger

Accepting the semantics: OpenAI Agents handoffs transfer control between peers rather than nesting one agent under another, so parent/child was the wrong encoding — siblings it is. Two knock-on effects worth recording:

• Finding 5's resolution changes shape but stays resolved. My original ask (round 1) was that dropping agent_handoff shouldn't be silent. It's now a deliberate, stated design decision with a test pinning the flat shape — that's exactly the "decision rather than an accident" outcome I was after, even though the mechanism (reparenting) went away.
• Findings 6–8 go from withdrawn to moot — the code they lived in no longer exists.

⚪ The new test's docstring teaches the wrong root-selection rule

test_handoff_agents_are_flat_with_coordinator_as_root says "root is the earliest-start agent". The actual rule in _find_root_agent_span (types/trace.py:135-149) is: first parentless-with-content agent in span-list order; start_time is only the final fallback when no agent is parentless. In this fixture both rules pick the coordinator, so the assertion is correct and stable (span order is deterministic from the fixture) — but I probed it: reversing the agent-list order flips the result to c2828d53371818f0, which start-time ordering never would. A maintainer who trusts the docstring will mispredict behaviour on the first trace where list order and start order diverge.

        """Handoff sub-agents are left independent (parentless); the root resolves to the
        coordinator as the first parentless agent with content (span-list order —
        start_time only breaks ties when no agent is parentless)."""

What I ran

head 2210c15fce1e7c50e713412d07dfcb79b01da84b (delta from 916ece7: -41 src / ~17 test lines)

pytest tests/strands_evals/mappers/ -q                 -> 379 passed
pytest mappers/ extractors/ types/ -q                  -> 511 passed
ruff check / ruff format --check (changed files)       -> clean
grep for dangling reparent/handoff refs in src/        -> only pre-existing swarm_extractor.py
root-selection probe on the ADOT fixture               -> both agents parentless; root = first-in-list
                                                          (reversed list -> different root; start_time not the rule)

Self-run follow-up — the delta is a scoped reversal with its test updated in the same commit. Full ledger: findings 1/2/4 fixed · 5 resolved (now via documented sibling semantics) · 3 risk-accepted · 6–8 moot (code deleted) · vendor special-case accepted · round-5 🟡 and round-7 🔴 fixed.

Automated review — solid work for a human to approve, not a gate.