OpenAI Agents integration breaks parent-child span relationships due to isolation_scope usage

[Afstkla]

(Full disclosure, the issue text & root cause analysis were done by Claude. The problem is very much a problem we're running into atm tho)

Problem

The OpenAI Agents integration in Sentry SDK creates separate traces instead of proper parent-child span relationships when agents are called from within existing trace contexts. This results in:

1. Trace fragmentation: Long "holes" appear in traces when agents are executing
2. Lost context: Agent spans don't appear as children of the calling span
3. Poor observability: Agent-to-agent (through agent.as_tool() create completely separate traces instead of nested spans

Root Cause

The issue is in sentry_sdk/integrations/openai_agents/patches/runner.py:28 where sentry_sdk.isolation_scope() is used:

# Isolate each workflow so that when agents are run in asyncio tasks they
# don't touch each other's scopes
with sentry_sdk.isolation_scope():
    agent = args[0]
    with agent_workflow_span(agent):
        # ... agent execution

The isolation_scope() creates a completely separate tracing context that breaks the connection to any existing parent span, even when that parent-child relationship is desired.

Proposed Solution

Replace sentry_sdk.isolation_scope() with sentry_sdk.new_scope() on line 28:

# Create new scope for local span management while preserving parent context
with sentry_sdk.new_scope():
    agent = args[0]
    with agent_workflow_span(agent):
        # ... agent execution

This change would:

✅ Preserve parent-child relationships: Agent spans would properly nest under calling spans
✅ Maintain concurrent isolation: Different concurrent agent executions would still be isolated from each other
✅ Keep existing functionality: All current tests should continue to pass
✅ Improve observability: Traces would show the complete flow including agent work

Impact

• Current behavior: Agent execution creates separate traces
• Expected behavior: Agent execution creates child spans within the existing trace
• Backward compatibility: This change should not break existing functionality

The concurrent agent execution test (line 673 in tests) should still pass because new_scope() provides sufficient isolation between parallel executions while allowing proper parent-child relationships.

Files Affected

• sentry_sdk/integrations/openai_agents/patches/runner.py (line 28)

[linear]

PY-1838 OpenAI Agents integration breaks parent-child span relationships due to isolation_scope usage

[sentrivana]

Hey @Afstkla, can you share some code to reproduce or an example with what the traces look like vs what they should look like?

Since this is fundamentally also a specification problem about how this stuff should be instrumented, I have a more general question for you as someone who has worked with agents a lot: How would you expect agent traces to look in order to get the most value out of them? I.e., what would you expect to be the root span/transaction? What should sub-agent workflows when one agent calls another look like?

[Afstkla]

Good questions!

For me / us, the preferred way would be if it mimics OpenAI's tracing solution

In the image above, we have

• 1 'main' agent ("Skills Agent"),
• that uses another agent ("Skill Executor: Weekly Return Percentage Report")
• which uses yet another agent ("Skill Executor: return_rate_reporting")
• which uses 3 other agents ("Shopify Agent", "Returnless Agent" and "Slack Agent")

In Sentry, this looks like (not 100% the same data, as a few agents were executing at the same time, and it's actual data from our Sentry):

and

While that does give all the information, I have a hard time linking those together other than based on timing, which makes it hard to track over-all costs, and debug anything in the grander scheme of things. And, probably most difficult of all, traces show a big black "No Instrumentation" hole (the 57.59s gap below)

Hope that helps @sentrivana, lmk if you need any more insights