| .. | ||
| patches | ||
| rmcp-patches | ||
| rust | ||
| scripts | ||
| src/_agents_codex | ||
| tests | ||
| .gitignore | ||
| AGENTS.md | ||
| Cargo.lock | ||
| Cargo.toml | ||
| CODEX_REVISION | ||
| MAINTAINING.md | ||
| NATIVE_AGENTS.md | ||
| README.md | ||
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.