Add the Python OpenAI Agents SDK integration guide - #5138
Draft
brianstrauch wants to merge 1 commit into
Draft
Conversation
Python was the only Temporal OpenAI Agents integration with no page on docs.temporal.io: both the SDK index and the integrations grid sent readers to the contrib README on GitHub, which is reference prose for SDK developers rather than a guide. Mirrors the structure of the TypeScript page, adapted where the Python plugin genuinely differs: - The plugin goes on the Client, and Workers inherit it. There is no Temporal-specific runner — Runner.run is redirected in place. - Python has no WorkflowSafeMemorySession, so conversation history is Workflow state rebuilt from result.to_input_list(), and SQLiteSession is unsupported. Long sessions get a continue-as-new section instead. - Agent.as_tool() works as-is, so there is no agentAsTool equivalent. - Two sections have no TypeScript counterpart: Sandbox, and the temporal_worker_env_ref() secrets flow for hosted tools. Both are marked pre-release/experimental inline. The page carries no ReleaseNoteHeader: the contrib README marks individual features as pre-release or experimental but the integration as a whole is not, so those warnings live on the sections they apply to. The feature-support matrix stays in the README rather than being mirrored here, where it would go stale. Depends on the matching sample PR in temporalio/samples-python. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📖 Docs PR preview links
|
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a Python guide for the Temporal OpenAI Agents SDK integration and connects it to documentation navigation.
Changes:
- Adds setup, tools, MCP, sandbox, streaming, and tracing guidance.
- Links the guide from Python navigation and the SDK index.
- Updates the integrations grid to use the internal guide.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
docs/develop/python/integrations/openai-agents.mdx |
Adds the integration guide. |
docs/develop/python/index.mdx |
Links the guide from the Python SDK index. |
sidebars.js |
Adds sidebar navigation. |
src/components/IntegrationsGrid/integrations-data.json |
Updates the integration card URL. |
💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+102
to
+103
| `ModelActivityParameters` controls how the model Activity is scheduled. Alongside `start_to_close_timeout`, which | ||
| defaults to 60 seconds, it takes `retry_policy`, `task_queue`, `priority`, `summary_override`, and `use_local_activity`. |
|
|
||
| ```python | ||
| from agents import HostedMCPTool | ||
| from temporalio.contrib.openai_agents import temporal_worker_env_ref |
Comment on lines
+676
to
+679
| The sample above uses `UnixLocalSandboxClient`, which runs commands on the Worker host—convenient locally, but it means | ||
| the agent gets a shell on that machine. In production, register a remote client such as `DaytonaSandboxClient` or | ||
| `E2BSandboxClient` from `agents.extensions.sandbox` instead. Only the Worker changes; the Workflow still just names a | ||
| provider. |
Comment on lines
+824
to
+827
| ### OpenTelemetry | ||
|
|
||
| If you already collect traces with OpenTelemetry, the integration can emit the agent's spans through your pipeline, so | ||
| model calls, tools, and orchestration land in the same backend as the rest of your traces. |
Comment on lines
+863
to
+864
| from agents import custom_span | ||
| from temporalio.worker.workflow_sandbox import SandboxedWorkflowRunner, SandboxRestrictions |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this PR do?
Adds
docs/develop/python/integrations/openai-agents.mdx, plus the sidebar entry, the SDK index link, and the integrations-gridhref.Python is currently the only Temporal OpenAI Agents integration with no page on docs.temporal.io — both the SDK index and the grid send readers to the contrib README on GitHub, which is reference prose for SDK developers rather than a guide.
Blocked on temporalio/samples-python#351, which adds the sandbox sample and the snipsync markers. Draft until that merges —
yarn snipsynccan't resolve the new IDs before then.Notes to reviewers
Mirrors the TypeScript page's structure, adapted where the Python plugin genuinely differs:
Runner.runis redirected in place.WorkflowSafeMemorySession, so conversation history is Workflow state rebuilt fromresult.to_input_list(), andSQLiteSessionis unsupported. Long sessions get a Continue-as-New section instead.Agent.as_tool()works as-is, so there is noagentAsToolequivalent.temporal_worker_env_ref()secrets flow for hosted tools. Both are marked pre-release/experimental inline.Three decisions worth a look:
ReleaseNoteHeader. The contrib README marks individual features as pre-release or experimental, but not the integration as a whole, so those warnings live on the sections they apply to rather than at the top of the page.keywordsfrontmatter, per AGENTS.md, even though the sibling integration pages still carry one.Verification
Snippet resolution was checked by temporarily pointing
snipsync.config.yamlat a local clone of the samples branch and runningyarn snipsync: all 18 IDs resolve and every excerpt dedents to column 0. That config change is not part of this PR. Re-runyarn snipsynconce #351 merges; the committed content should be unchanged.yarn buildpasses.vale --config .vale-ci.ini— 0 errors, 0 warnings, 0 suggestions.yarn check:orphans— no orphaned pages, so the sidebar entry is wired correctly.yarn check-links— the 4 failures touching this page are all expected: theog:urland GitHub edit-URL checks fail because the page isn't onmainyet, and the two/glossary#activityfragment-redirects are a systemic class with ~3000 hits site-wide that the TypeScript page shares.Known follow-up
The Sandbox section's warning about
UnixLocalSandboxClientundersells the exposure and I plan to tighten it. The local backend doesos.environ.copy(), so the agent can read the worker's whole environment; anything it prints becomes a tool result, which is carried into the nextinvoke_model_activityinput and therefore recorded in event history and visible in the Web UI without a payload codec. Reproduced with a sentinel key. This is upstream behavior inopenai-agents, not something the plugin introduces, and it is a different flow from the one temporalio/sdk-python#1745 addresses.🤖 Generated with Claude Code
┆Attachments: EDU-6985 Add the Python OpenAI Agents SDK integration guide