openai-agents-python/packages/codex
2026-11-15 19:49:41 -08:00
..
patches Fix rollback for ordinary Python SDK sessions (#6033) 2026-11-15 19:49:41 -08:00
rmcp-patches feat: expose native MCP resource pages and reads (#5597) 2026-11-07 15:48:08 -08:00
rust fix: Confirm remote command exit and expose native tool events (#6015) 2026-11-15 15:05:00 -08:00
scripts Speed up Python harness CI and preserve native artifact reuse (#6010) 2026-11-15 15:10:51 -08:00
src/_agents_codex Fix rollback for ordinary Python SDK sessions (#6033) 2026-11-15 19:49:41 -08:00
tests Fix rollback for ordinary Python SDK sessions (#6033) 2026-11-15 19:49:41 -08:00
.gitignore Import the native Agents SDK into feat/codex-harness (#5489) 2026-11-02 22:21:22 -08:00
AGENTS.md chore: restore classic examples and organize example collections (#5566) 2026-11-06 11:43:21 -08:00
Cargo.lock Native HTTP/2 streaming with buffered HTTP/1.1 (#5982) 2026-11-13 23:05:56 -08:00
Cargo.toml Native HTTP/2 streaming with buffered HTTP/1.1 (#5982) 2026-11-13 23:05:56 -08:00
CODEX_REVISION Import the native Agents SDK into feat/codex-harness (#5489) 2026-11-02 22:21:22 -08:00
MAINTAINING.md Speed up Python harness CI and preserve native artifact reuse (#6010) 2026-11-15 15:10:51 -08:00
NATIVE_AGENTS.md Import the native Agents SDK into feat/codex-harness (#5489) 2026-11-02 22:21:22 -08:00
README.md Fix strict tool recovery and Python preview compatibility (#6026) 2026-11-15 11:34:48 -08:00

OpenAI Agents SDK

Build Python agents that call your functions, use MCP tools, and keep a conversation across messages. Your application defines the agent's instructions and tools. The SDK uses Codex to coordinate model requests and tool calls.

Install

Follow the installation guide to install a preview wheel from GitHub Releases. Find the guides and examples for your installed version.

For an existing v0 application, prefer a direct migration to native v1 when you choose to upgrade. You can stay on v0. The SDK also retains classic for workflows that need a staged package upgrade.

Development guides

If you build the SDK from source, use the guides and examples from the same commit as your build. Start with the development quickstart.

Guide Use it to
Agent configuration Choose a model, provider and typed output.
Sessions Continue turns and stream observations.
State and recovery Compact, save, and restore conversations.
Tools Declare Python functions and select tools.
MCP servers Connect servers and configure approval and result policies.
Execution Run commands and edit workspace files.
Delegation Configure and control native children.
Approvals and manual results Answer live requests and recover external jobs.
Usage and tracing Read usage and diagnose work with telemetry and history.
API reference Find supported calls and defaults.

For current-branch native voice APIs, read the native voice guide. It covers Session-owned Realtime, credentials, custom adapters, and speech pipelines. Use it with the matching build; published wheels may not include these APIs.

Hosted prompts

Native Agents have been using hosted_prompt to select a stored Responses prompt. A static reference has been supplying fixed variables. A factory has been deriving variables from each request's application context.

Prerequisites: the matching native v1 build, OPENAI_API_KEY, and OPENAI_PROMPT_ID for a project prompt with a topic variable.

import asyncio
import os

from agents import Agent, NativeProvider


async def main() -> None:
    prompt_id = os.environ["OPENAI_PROMPT_ID"]
    async with NativeProvider() as provider:
        fixed = Agent(
            hosted_prompt={"id": prompt_id, "variables": {"topic": "native"}},
            provider=provider,
        )
        fixed_result = await fixed.run("Give one example.")
        print(fixed_result.final_output)

        contextual = Agent[dict[str, str], str](
            hosted_prompt=lambda request: {
                "id": prompt_id,
                "variables": {"topic": request.context["topic"]},
            },
            provider=provider,
        )
        contextual_result = await contextual.run("Give one example.", context={"topic": "history"})
        print(contextual_result.final_output)


asyncio.run(main())

An optional version string in the reference has been selecting a specific prompt version. An asynchronous factory has been working through the same callback path.

Omitted settings have been inheriting prompt values. Explicit settings have been overriding them:

Setting Omitted Explicit
model Stored prompt's model The supplied model
instructions Stored prompt's instructions The supplied text, including ""
tools Stored prompt's tools The declared native tools, including []

Native tool selections and policies have also been overriding inherited prompt tools, including explicit empty selections. Combining hosted_prompt with a prompt entry in model_settings["extra_body"] has been raising a configuration error.

After restoration, the current Agent declaration has been supplying the prompt reference or factory. Before dispatch, the SDK has been rejecting new explicit settings for fields previously inherited from the prompt.

This component owns the Codex Python implementation in src/_agents_codex, native inputs, tests, and examples. The root project builds one openai-agents wheel; application code continues to import agents.

For SDK development and source builds, see CONTRIBUTING.md. See the maintenance guide for native builds and artifact checks.