openai-agents-python/examples/codex/README.md
Mark Stuart ba3fbbf400
docs: organize SDK guides around developer tasks (#5920)
* docs: organize SDK guides and clarify examples

* fix: correct native SDK type declarations

* test: update native SDK contract fixtures

* fix: normalize persisted agent profile transport settings

* test: reconcile inherited model settings API snapshot

* test: preserve executor coverage on Windows

---------

Co-authored-by: markstuart-oai <323302876+markstuart-oai@users.noreply.github.com>
2026-11-12 21:00:58 -08:00

13 KiB

Run an SDK example

Use these examples with the SDK preview wheel and source files from the same release. Start with one Python tool, then choose an example for your task. Scripted examples run the native engine against local synthetic responses; live examples send model requests.

Set up your environment

Follow the installation guide, activate your Python environment, and open the root of the matching release's source archive. Install any extra dependencies listed in the example's README.

Entries marked Development require a matching source build and example files from that checkout.

Run all commands from the source archive or checkout root, using the Python environment where you installed the matching SDK. For scripted examples, allow direct access to 127.0.0.1 or add it to your proxy bypass list.

For a live model example, supply OPENAI_API_KEY through your usual credential setup. These examples make model requests and can incur charges. The scripted recipes identify when no API key is needed.

Run a Python tool

With OPENAI_API_KEY configured, run the greeting example:

python -m examples.codex.basic

The example asks the agent to greet Ada with the Python greeting tool and prints the final answer. Live wording can vary. The source shows the tool declaration and Agent.run() call.

Run without model credentials

The typed-tools recipe runs a local scripted response through a Python tool and validates its result:

python -m examples.codex.recipes.typed_tools

Expect a JSON receipt for SKU synthetic with accepted equal to 2. The script checks the recorded order line before printing the receipt. It tests tool execution and validation; the peer supplies the model's decisions. Choose another scripted recipe to test application behavior.

Choose an agent task

Choose a task below, then follow its guide or the script's opening instructions. Alpha.7 means the example files are in that release archive; use that archive with its matching wheel. Development means a source build and examples from the same current checkout. Execution mode and setup version are separate requirements.

Python tools and agent behavior

Task Example Setup and execution
Call a Python function basic.py Alpha.7; live. One answer through Agent and function_tool.
Supply application context typed_context.py Alpha.7; live. Context for a tool and a validated Pydantic answer.
Make typed decisions Decisions guide Development; live typed decisions or scripted routing.
Continue and restore a conversation conversation.py Alpha.7; live. Multiple turns, streamed observations, and saved state.
Preserve task state during compaction compaction.py Alpha.7; live. A before_compact callback supplies the summary.
Retain selected original context during compaction retained_compaction.py Alpha.7; live. An application summary and selected message survive restore.
Require a saved report before completion completion.py Alpha.7; live. Completion checks within a five-request budget.
Refresh reference text for each request model_context.py Alpha.7; live. An existing UTF-8 file and a question.
Handle a callback timeout tool_timeout.py Alpha.7; live. A timeout returned as a tool error.
Limit Python callbacks callback_quota.py Alpha.7; live. An application quota per run.
Test a focused application behavior Task recipe chooser Scripted and live recipes with individual release and dependency requirements.

Documents, memory, and output

Task Guide Setup and execution
Read or revise selected text files Selected documents Alpha.7; live. Bounded reads, search, and authorized edits to decoded text.
Discover selected collection sources Selective collection Alpha.7; live workflow and scripted benchmark over 10,000 local files.
Store facts across Sessions Packaged memory Development; scripted. Scoped SQLite facts, recall, and deletion.
Validate XML before writing validated_artifact.py Alpha.7; live. A callback returns validation errors for repair.
Validate JSON before writing Packaged artifact Development; scripted. json_artifact_tool with a selected destination and schema.
Publish an accepted answer Accepted output Development; scripted. Private drafts, application checks, and in-memory publication.
Bound a large function result Oversized output Development; scripted. Bounded request content and retained full evidence.
Edit the next sampling request prepared_request.py Alpha.7; scripted. Request edits after a tool result under the existing policies.

Approvals, state, and recovery

Task Guide Setup and execution
Approve a Python callback Managed approvals Development; scripted. Decisions before callback execution and pending approval restore.
Own native Session storage Application-owned storage Alpha.7; live. Local POSIX adapter, writer ownership, and tool-result recovery.
Pause or restore a budgeted run Budgeted recovery Development; API combinations and synthetic contributor tests.
Resume an external job External jobs Alpha.7; scripted. A separate worker, private POSIX journal, and bundled model endpoint.

Build an application or service

A runnable demo supplies its own local service. An integration helper requires the host application described in its guide.

Task Guide Setup and execution
Build a browser application Service and browser starter Alpha.7; scripted or live runnable service. Node 22+, pinned browser dependencies, and private POSIX storage.
Stream Vercel UI frames vercel_stream.py Development; integration helper for your HTTP service and worker. No CLI entrypoint.
Render an MCP App and send an action MCP App browser Development; scripted runnable service with Node 22+ and pinned browser dependencies.
Stream AG-UI events AG-UI guide Development helper for your worker, HTTP endpoint, and browser; alpha.7 variant linked in the guide. Pinned AG-UI dependency.
Record voice or run a speech pipeline Native voice Development; live recording, WAV pipeline, and transport integration recipes.
Call an A2A peer or expose an Agent A2A adapter Development integration guide; alpha.7 variant linked inside. Client requires an existing authenticated peer; server factory requires host identity and task storage.
Supervise local coding workers Supervised workers Development; live. Matching native helpers and separate Linux/macOS job workspaces.
Use registered ChatGPT plan access Sign in with ChatGPT Development; registered integration and user consent. Separate from experimental Codex login.

Inspect runs and compare configurations

Task Guide Setup and execution
Debug tool and provider failures Trace walkthrough Alpha.7; scripted collector and viewer. Development build for retry/send-count extensions.
Continue a trace across workers Explicit trace context Alpha.7; scripted. Explicit parent headers and a second Agent.
Trace a business workflow across services Business workflow tracing Development; scripted. Two processes and a local telemetry sink.
Compare model configurations Evaluation runner Alpha.7; scripted runner check or live baseline/candidate comparison.

Hosted tools, storage, and executors

Task Example Setup and execution
Search the web hosted_web_search.py Alpha.7; live. Compatible Responses model with web search.
Search files, run hosted Python, or generate images Provider-hosted tools Alpha.7; live. API-key Responses and any pre-existing provider resources listed by the recipe.
Search project paths and text project_search.py Alpha.7; live. Linux/macOS project directory.
Read an additional local directory Storage mounts Alpha.7; live. Linux native sandbox and existing trusted directories.
Connect provider storage Provider storage Application integration; prepared resource provider, storage driver, and an application-owned executor connector. Current source for managed-workspace extensions.
Run commands on an existing executor remote_executor.py Alpha.7; live. Pre-provisioned authenticated WSS executor and assigned workspace.
Push a reviewed Git commit from macOS Host Git Development; scripted model. Real Git push with a trusted checkout and existing scratch-repository credentials.
Use Unix sockets inside an offline job offline_unix_sockets.py Alpha.7; existing isolated Linux/macOS executor, gateway credentials, and local synthetic Responses peer.
Permit public hosts with explicit exceptions Network policy Development; configure managed executor network access and separate socket permissions.
Provision an offline Docker job offline_docker.py Alpha.7; integration helper. Docker, prepared image, and application-owned gateway configuration.

Use ChatGPT plan usage with a registered integration

Follow the registered integration recipe for verified identity, credential refresh, supported tools, and usage-limit recovery. It requires a matching source build and an existing Sign in with ChatGPT registration.

Migrate a v0 workflow

Follow the migration guide to move directly from v0 to native v1. It maps the APIs, explains conversation cutover, and includes a brief for a coding agent. Start with the read-only invoice walkthrough: one agent, one tool, typed context, and typed output. It includes matching-source installation and an optional classic import change.

If a staged package upgrade is necessary, the classic example demonstrates the retained Python runner without model credentials. Read classic setup for its source-build and dependency requirements. Moving a workflow to classic is optional and does not move its execution to Codex.

Push a reviewed Git commit from macOS

Follow the host Git recipe for trusted-checkout setup, the complete command, remote-branch verification, and uncertain-push recovery. This scripted-model example performs a real push to your selected scratch repository.

Allow public hosts with exceptions

Use NetworkPolicy.allow_all() with explicit denials to permit public hosts through the managed executor proxy. This factory requires a matching development build. The network policy guide gives the declaration and platform-specific socket requirements.

Use the SDK guide for API behavior and the tool guide for Python functions and native MCP tools.