docs: Document openai-agents control-flow

[alexander-alderman-webb]

Description

Issues

Reminders

• Please add tests to validate your changes, and lint your code using tox -e linters.
• 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]

Semver Impact of This PR

🟢 Patch (bug fixes)

📋 Changelog Preview

This is how your changes will appear in the changelog.
Entries from this PR are highlighted with a left border (blockquote style).

---

Bug Fixes 🐛

• fix(celery): Close the connection we're reading driver_type from by sentrivana in #5427

Documentation 📚

• docs: Document openai-agents control-flow by alexander-alderman-webb in #5447

Internal Changes 🔧

• test(openai-agents): Avoid calling SDK-internal functions by alexander-alderman-webb in #5437
• ref: Remove references to unsupported attribute types by alexander-alderman-webb in #5425
• ci: Pin setuptools for linting and chalice tests by alexander-alderman-webb in #5438

---

_{🤖 This preview updates automatically when you update the PR.}

[github-actions]

Codecov Results 📊

✅ 13 passed | Total: 13 | Pass Rate: 100% | Execution Time: 6.79s

All tests are passing successfully.

✅ Patch coverage is 100.00%. Project has 13656 uncovered lines.

Files with missing lines (180)

File	Patch %	Lines
langchain.py	3.28%	⚠️ 590 Missing
utils.py	52.63%	⚠️ 432 Missing and 79 partials
openai.py	5.57%	⚠️ 492 Missing
utils.py	0.00%	⚠️ 479 Missing
__init__.py	5.08%	⚠️ 374 Missing
tracing_utils.py	45.27%	⚠️ 324 Missing and 28 partials
starlette.py	5.34%	⚠️ 337 Missing
scope.py	70.52%	⚠️ 242 Missing and 66 partials
transport.py	23.54%	⚠️ 302 Missing and 2 partials
client.py	55.98%	⚠️ 221 Missing and 56 partials
mcp.py	5.24%	⚠️ 253 Missing
anthropic.py	9.16%	⚠️ 248 Missing
transaction_profiler.py	35.52%	⚠️ 216 Missing and 10 partials
langgraph.py	5.29%	⚠️ 215 Missing
utils.py	16.08%	⚠️ 214 Missing
span_processor.py	0.00%	⚠️ 205 Missing
__init__.py	5.14%	⚠️ 203 Missing
continuous_profiler.py	43.45%	⚠️ 177 Missing and 17 partials
strawberry.py	8.54%	⚠️ 182 Missing
tracing.py	71.37%	⚠️ 136 Missing and 38 partials
aws_lambda.py	16.50%	⚠️ 167 Missing
huggingface_hub.py	8.89%	⚠️ 164 Missing
sanic.py	9.60%	⚠️ 160 Missing
aiohttp.py	10.84%	⚠️ 148 Missing
cloud_resource_context.py	0.00%	⚠️ 145 Missing
ai_client.py	0.00%	⚠️ 145 Missing
rust_tracing.py	0.00%	⚠️ 143 Missing
litellm.py	0.00%	⚠️ 138 Missing
litestar.py	9.59%	⚠️ 132 Missing
starlite.py	8.33%	⚠️ 132 Missing
falcon.py	8.94%	⚠️ 112 Missing
flask.py	12.50%	⚠️ 112 Missing
spotlight.py	28.47%	⚠️ 103 Missing and 8 partials
asgi.py	20.71%	⚠️ 111 Missing
cohere.py	12.70%	⚠️ 110 Missing
agent_run.py	0.00%	⚠️ 110 Missing
asgi.py	0.00%	⚠️ 109 Missing
hub.py	45.60%	⚠️ 105 Missing and 3 partials
envelope.py	54.59%	⚠️ 89 Missing and 17 partials
pymongo.py	10.17%	⚠️ 106 Missing
caching.py	0.00%	⚠️ 106 Missing
utils.py	0.00%	⚠️ 103 Missing
templates.py	0.00%	⚠️ 100 Missing
asyncpg.py	11.61%	⚠️ 99 Missing
quart.py	16.10%	⚠️ 99 Missing
wsgi.py	22.66%	⚠️ 99 Missing
models.py	4.81%	⚠️ 99 Missing
gcp.py	0.00%	⚠️ 98 Missing
otlp.py	0.00%	⚠️ 97 Missing
utils.py	13.39%	⚠️ 97 Missing
sessions.py	27.82%	⚠️ 96 Missing
pyramid.py	13.76%	⚠️ 94 Missing
tornado.py	14.55%	⚠️ 94 Missing
__init__.py	0.00%	⚠️ 93 Missing
bottle.py	11.65%	⚠️ 91 Missing
middleware.py	0.00%	⚠️ 90 Missing
agent_run.py	0.00%	⚠️ 90 Missing
_wsgi_common.py	30.71%	⚠️ 88 Missing and 1 partials
runner.py	0.00%	⚠️ 87 Missing
loguru.py	11.58%	⚠️ 84 Missing
asyncio.py	0.00%	⚠️ 80 Missing
invoke_agent.py	0.00%	⚠️ 79 Missing
session.py	15.56%	⚠️ 76 Missing
clickhouse_driver.py	17.58%	⚠️ 75 Missing
pure_eval.py	0.00%	⚠️ 73 Missing
worker.py	22.58%	⚠️ 72 Missing
ariadne.py	14.46%	⚠️ 71 Missing
gql.py	10.13%	⚠️ 71 Missing
sqlalchemy.py	10.26%	⚠️ 70 Missing
fastapi.py	15.85%	⚠️ 69 Missing
monitoring.py	17.07%	⚠️ 68 Missing
graphene.py	12.82%	⚠️ 68 Missing
transactions.py	0.00%	⚠️ 67 Missing
_queue.py	26.67%	⚠️ 66 Missing
logging.py	66.67%	⚠️ 51 Missing and 15 partials
stdlib.py	60.45%	⚠️ 53 Missing and 11 partials
boto3.py	14.86%	⚠️ 63 Missing
streaming.py	0.00%	⚠️ 62 Missing
httpx.py	16.44%	⚠️ 61 Missing
chalice.py	16.18%	⚠️ 57 Missing
propagator.py	0.00%	⚠️ 57 Missing
server.py	0.00%	⚠️ 56 Missing
spark_driver.py	67.47%	⚠️ 54 Missing and 2 partials
api.py	64.43%	⚠️ 53 Missing
graph_nodes.py	0.00%	⚠️ 52 Missing
gnu_backtrace.py	0.00%	⚠️ 51 Missing
socket.py	0.00%	⚠️ 50 Missing
views.py	0.00%	⚠️ 50 Missing
tools.py	0.00%	⚠️ 49 Missing
_batcher.py	41.25%	⚠️ 47 Missing
invoke_agent.py	0.00%	⚠️ 46 Missing
traces.py	47.06%	⚠️ 45 Missing
_asgi_common.py	16.67%	⚠️ 45 Missing
signals_handlers.py	0.00%	⚠️ 44 Missing
utils.py	22.22%	⚠️ 42 Missing and 1 partials
threading.py	63.16%	⚠️ 35 Missing and 5 partials
client.py	0.00%	⚠️ 40 Missing
serializer.py	84.95%	⚠️ 28 Missing and 10 partials
executing.py	0.00%	⚠️ 38 Missing
client.py	0.00%	⚠️ 38 Missing
_span_batcher.py	35.71%	⚠️ 36 Missing
serverless.py	0.00%	⚠️ 36 Missing
server.py	0.00%	⚠️ 35 Missing
sys_exit.py	0.00%	⚠️ 32 Missing
caches.py	49.15%	⚠️ 30 Missing and 2 partials
launchdarkly.py	0.00%	⚠️ 31 Missing
trytond.py	0.00%	⚠️ 30 Missing
tools.py	0.00%	⚠️ 30 Missing
integration.py	0.00%	⚠️ 30 Missing
error_tracing.py	0.00%	⚠️ 29 Missing
ai_client.py	13.33%	⚠️ 26 Missing
execute_tool.py	0.00%	⚠️ 26 Missing
utils.py	74.67%	⚠️ 19 Missing and 7 partials
scrubber.py	76.81%	⚠️ 16 Missing and 9 partials
_openai_completions_api.py	19.35%	⚠️ 25 Missing
ray.py	70.24%	⚠️ 25 Missing
_werkzeug.py	11.11%	⚠️ 24 Missing
typer.py	0.00%	⚠️ 24 Missing
__init__.py	93.91%	⚠️ 14 Missing and 10 partials
tasks.py	0.00%	⚠️ 24 Missing
_compat.py	41.03%	⚠️ 23 Missing
statsig.py	0.00%	⚠️ 23 Missing
logger.py	43.59%	⚠️ 22 Missing
decorator.py	37.14%	⚠️ 22 Missing
__init__.py	84.78%	⚠️ 14 Missing and 8 partials
_log_batcher.py	0.00%	⚠️ 21 Missing
attachments.py	27.59%	⚠️ 21 Missing
unraisablehook.py	0.00%	⚠️ 21 Missing
__init__.py	8.70%	⚠️ 21 Missing
openfeature.py	0.00%	⚠️ 20 Missing
execute_tool.py	0.00%	⚠️ 20 Missing
dramatiq.py	90.91%	⚠️ 10 Missing and 9 partials
unleash.py	0.00%	⚠️ 19 Missing
_lru_cache.py	43.33%	⚠️ 17 Missing and 1 partials
model_request.py	0.00%	⚠️ 18 Missing
monitor.py	81.97%	⚠️ 11 Missing and 5 partials
beat.py	92.24%	⚠️ 9 Missing and 7 partials
utils.py	0.00%	⚠️ 16 Missing
redis_cluster.py	52.94%	⚠️ 16 Missing
atexit.py	56.25%	⚠️ 14 Missing and 1 partials
excepthook.py	56.25%	⚠️ 14 Missing and 1 partials
feature_flags.py	56.25%	⚠️ 14 Missing
__init__.py	27.78%	⚠️ 13 Missing
types.py	0.00%	⚠️ 12 Missing
_async_common.py	86.27%	⚠️ 7 Missing and 5 partials
_types.py	66.67%	⚠️ 10 Missing
handoff.py	0.00%	⚠️ 10 Missing
_sync_common.py	88.00%	⚠️ 6 Missing and 4 partials
spark_worker.py	89.29%	⚠️ 6 Missing and 4 partials
metrics.py	47.06%	⚠️ 9 Missing
beam.py	94.05%	⚠️ 5 Missing and 3 partials
dedupe.py	85.00%	⚠️ 6 Missing and 2 partials
rq.py	97.44%	⚠️ 2 Missing and 6 partials
_metrics_batcher.py	65.00%	⚠️ 7 Missing
consts.py	0.00%	⚠️ 7 Missing
redis_py_cluster_legacy.py	53.33%	⚠️ 7 Missing
_init_implementation.py	75.00%	⚠️ 6 Missing
_openai_responses_api.py	33.33%	⚠️ 6 Missing
arq.py	97.52%	⚠️ 3 Missing and 3 partials
queries.py	90.32%	⚠️ 3 Missing and 2 partials
debug.py	91.30%	⚠️ 2 Missing and 2 partials
consts.py	0.00%	⚠️ 4 Missing
__init__.py	20.00%	⚠️ 4 Missing
__init__.py	0.00%	⚠️ 4 Missing
__init__.py	89.66%	⚠️ 3 Missing and 1 partials
__init__.py	0.00%	⚠️ 3 Missing
__init__.py	40.00%	⚠️ 3 Missing
__init__.py	0.00%	⚠️ 3 Missing
__init__.py	0.00%	⚠️ 3 Missing
rb.py	70.00%	⚠️ 3 Missing
redis.py	85.00%	⚠️ 3 Missing
consts.py	99.43%	⚠️ 2 Missing
argv.py	100.00%	⚠️ 2 partials
huey.py	100.00%	⚠️ 2 partials
modules.py	94.12%	⚠️ 1 Missing and 1 partials
utils.py	88.24%	⚠️ 2 Missing
agent_workflow.py	71.43%	⚠️ 2 Missing
api.py	100.00%	⚠️ 1 partials
consts.py	0.00%	⚠️ 1 Missing
consts.py	0.00%	⚠️ 1 Missing

---

Generated by Codecov Action

[sl0thentr0py]

this is good but please move them to the relevant functions that we patch or explicitly mention the function names here. I'd like to know what each function is responsible for when I read this integration.

[alexander-alderman-webb]

I've added explicit references to the functions we patch in the library and added lists for the responsibilities of each patch in our integration.