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

[alexander-alderman-webb]

Description

Add on_agent_start(), on_agent_end() and on_handoff() 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 the span stored on the RunHooks instance 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]

Codecov Results 📊

✅ 97214 passed | ⏭️ 6239 skipped | Total: 103453 | Pass Rate: 93.97% | Execution Time: 358m 25s

📊 Comparison with Base Branch

Metric	Change
Total Tests	📈 +550
Passed Tests	📈 +502
Failed Tests	—
Skipped Tests	📈 +48

All tests are passing successfully.

✅ Patch coverage is 89.32%. Project has 2494 uncovered lines.
✅ Project coverage is 90%. Comparing base (base) to head (head).

Files with missing lines (3)

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

Coverage diff

@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
+ Coverage    89.90%    90.00%     +0.1%
==========================================
  Files          193       193         —
  Lines        24822     24936      +114
  Branches      8924      8974       +50
==========================================
+ Hits         22315     22442      +127
- Misses        2507      2494       -13
- Partials      1417      1423        +6

---

Generated by Codecov Action

[cursor]

Cursor Bugbot has reviewed your changes and found 2 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 8343310. Configure here.}