ref(openai-agents): Use first class agent hooks when available by alexander-alderman-webb · Pull Request #7029 · getsentry/sentry-python

alexander-alderman-webb · 2026-08-04T10:31:33Z

Description

Add on_agent_start() and on_agent_end() hooks.

Unlike tool hooks, the Invoke Agent span is stored on the RunHooks instance.

If the hooks are active, start and finish Invoke Agent spans in the hooks in successful executions. If an exception bubbles up, on_agent_end() does not run. Modify monkey-patches so that RunHooks span is finished if the hooks are present.

Make the signatures of invoke_agent_span(), update_invoke_agent_span() and _maybe_start_agent_span() more minimal so that they can be re-used in the on_agent_start() and on_agent_end() hooks.

Issues

Closes #6989

Reminders

Please add tests to validate your changes, and lint your code using uv run ruff.
Add GH Issue ID & Linear ID (if applicable)
PR title should use conventional commit style (feat:, fix:, ref:, meta:)
For external contributors: CONTRIBUTING.md, Sentry SDK development docs, Discord community

github-actions · 2026-08-04T11:52:35Z

Codecov Results 📊

✅ 95803 passed | ⏭️ 6239 skipped | Total: 102042 | Pass Rate: 93.89% | Execution Time: 350m 33s

📊 Comparison with Base Branch

Metric	Change
Total Tests	📈 +189
Passed Tests	📈 +189
Failed Tests	—
Skipped Tests	—

All tests are passing successfully.

✅ Patch coverage is 94.12%. Project has 2486 uncovered lines.
✅ Project coverage is 90.02%. Comparing base (base) to head (head).

Files with missing lines (3)

File	Patch %	Lines
sentry_sdk/integrations/openai_agents/patches/agent_run.py	95.35%	⚠️ 2 Missing and 9 partials
sentry_sdk/integrations/openai_agents/patches/runner.py	92.11%	⚠️ 3 Missing and 3 partials
sentry_sdk/integrations/openai_agents/spans/invoke_agent.py	100.00%	⚠️ 1 partials

Coverage diff

@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
+ Coverage    89.90%    90.02%    +0.12%
==========================================
  Files          193       193         —
  Lines        24825     24919       +94
  Branches      8922      8954       +32
==========================================
+ Hits         22319     22433      +114
- Misses        2506      2486       -20
- Partials      1415      1421        +6

Generated by Codecov Action

…agent-hooks-2

cursor

Cursor Bugbot has reviewed your changes and found 4 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 01fd3b1. Configure here.}

cursor · 2026-08-04T15:15:49Z

+        context: "AgentHookContext[TContext]",
+        agent: "Agent[TContext]",
+    ) -> "None":
+        self._sentry_invoke_agent_span = invoke_agent_span(agent, context.turn_input)


Handoffs leak invoke agent spans

High Severity

With use_run_hooks, invoke agent spans live on the hooks instance and are finished in on_agent_end, which only runs on final output. Handoffs never close the prior span: on_agent_start overwrites _sentry_invoke_agent_span, and _execute_handoffs still looks for context_wrapper._sentry_agent_span, which is never set on this path. Each handoff therefore leaves an unfinished invoke agent span.

Additional Locations (1)

sentry_sdk/integrations/openai_agents/patches/agent_run.py#L284-L315

^{Reviewed by Cursor Bugbot for commit 01fd3b1. Configure here.}

sentry-warden · 2026-08-04T16:05:25Z

+                    if span is not None:
+                        update_invoke_agent_span(
+                            span=span, usage=context_wrapper.usage, agent=agent
+                        )
+                        del run_hooks._sentry_invoke_agent_span
+                        span.__exit__(*exc_info)
+            else:
+                span = getattr(context_wrapper, "_sentry_agent_span", None)
+                if span:


Invoke agent span leaks on exception when user-provided hooks are used

The exception handler retrieves _sentry_invoke_agent_span from run_hooks, but when the user provides a RunHooks instance _patch_run_hooks stores the span on a separate internal _SentryRunHooks object, so the span is never finished and leaks on every exception.

Evidence

run_hooks is retrieved from args[2] / kwargs.get("hooks"), which is the user-provided RunHooks instance.

_patch_run_hooks in runner.py:129 creates a separate _SentryRunHooks() instance (sentry_hooks) whose on_agent_start stores _sentry_invoke_agent_span on that private object.

The patched on_agent_start delegates to sentry_hooks.on_agent_start, but the user's hooks object never receives the _sentry_invoke_agent_span attribute.

getattr(run_hooks, "_sentry_invoke_agent_span", None) therefore always resolves to None on patched user hooks.

Because the span is never updated or exited, it leaks on every exception path when custom hooks are present.

Also found at 2 additional locations

sentry_sdk/integrations/openai_agents/patches/agent_run.py:139

sentry_sdk/integrations/openai_agents/patches/runner.py:131-131

_{Identified by Warden · find-bugs · XD7-X2Q}

sentry-warden · 2026-08-04T16:05:25Z


 def update_invoke_agent_span(
    span: "Union[sentry_sdk.tracing.Span, StreamedSpan]",
-    context: "agents.RunContextWrapper",
+    usage: "Optional[Usage]",
    agent: "agents.Agent",
    output: "Any" = None,
 ) -> None:
-    # Add aggregated usage data from context_wrapper
-    if hasattr(context, "usage"):
-        _set_usage_data(span, context.usage)
+    if usage is not None:
+        _set_usage_data(span, usage)



update_invoke_agent_span lost defensive usage guard, callers crash on missing usage attribute

The update_invoke_agent_span signature changed from taking context (with a hasattr(context, "usage") guard) to taking usage directly. Callers now pass context_wrapper.usage or context.usage without defensive guards. If the context object lacks a usage attribute, callers raise AttributeError inside capture_internal_exceptions(), which suppresses the error but skips span cleanup—leaving spans unfinished.

Evidence

update_invoke_agent_span previously checked hasattr(context, "usage") before accessing .usage; the new signature only checks if usage is not None.

Callers in patches/agent_run.py and patches/runner.py pass context_wrapper.usage or context.usage directly without getattr or hasattr guards (e.g., agent_run.py:71, agent_run.py:141, runner.py:68).

Exception handlers in _run_single_turn (agent_run.py:136-146) and _run_single_turn_streamed (agent_run.py:238-248) wrap these calls inside capture_internal_exceptions(), whose __exit__ returns True, swallowing any AttributeError and blocking the del / span.__exit__ cleanup that follows.

The same pattern exists in _SentryRunHooks.on_agent_end (runner.py:66-70), which is executed through a _patch_run_hooks wrapper that also uses capture_internal_exceptions(), so a missing .usage there silently leaks the invoke-agent span on the hooks instance.

_{Identified by Warden · find-bugs · JK8-BDR}

alexander-alderman-webb added 10 commits August 4, 2026 12:31

ref(openai-agents): Use first class agent hooks when available

3cef85d

merge

eb9bd68

delattr before span is closed

f60881e

make context_wrapper available again

0e7155a

pass usage instead of context to update_invoke_agent_span

b273a1d

update all use_agent_hooks references to use_run_hooks

b5ae6b3

simplify

9c8074d

.

573480b

make mypy happy

9210726

add missing argument

d555e9c

alexander-alderman-webb added 2 commits August 4, 2026 14:39

.

517d837

merge

002ec0a

alexander-alderman-webb changed the base branch from webb/use-agent-hooks to webb/fix-run_single_turn_streamed-patch August 4, 2026 13:09

alexander-alderman-webb added 2 commits August 4, 2026 15:11

Merge branch 'webb/fix-run_single_turn_streamed-patch' into webb/use-…

9fe9910

…agent-hooks-2

.

01fd3b1

alexander-alderman-webb marked this pull request as ready for review August 4, 2026 15:09

alexander-alderman-webb requested a review from a team as a code owner August 4, 2026 15:09

cursor Bot reviewed Aug 4, 2026

View reviewed changes

close streaming workflow span in all cases

0759b8b

alexander-alderman-webb marked this pull request as draft August 4, 2026 15:33

sentry Bot reviewed Aug 4, 2026

View reviewed changes

Comment thread sentry_sdk/integrations/openai_agents/patches/agent_run.py

sentry-warden Bot reviewed Aug 4, 2026

View reviewed changes

Navigation Menu

Uh oh!

ref(openai-agents): Use first class agent hooks when available - #7029

ref(openai-agents): Use first class agent hooks when available#7029
alexander-alderman-webb wants to merge 15 commits into
webb/fix-run_single_turn_streamed-patchfrom
webb/use-agent-hooks-2

alexander-alderman-webb commented Aug 4, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 4, 2026 •

edited

Loading

Uh oh!

cursor Bot left a comment

Uh oh!

cursor Bot Aug 4, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sentry-warden Bot Aug 4, 2026

Uh oh!

sentry-warden Bot Aug 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

alexander-alderman-webb commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Issues

Reminders

Uh oh!

github-actions Bot commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Results 📊

📊 Comparison with Base Branch

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 4, 2026

Choose a reason for hiding this comment

Handoffs leak invoke agent spans

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sentry-warden Bot Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

sentry-warden Bot Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

alexander-alderman-webb commented Aug 4, 2026 •

edited

Loading

github-actions Bot commented Aug 4, 2026 •

edited

Loading