OpenAI Agents SDK (analysis mirror)
Find a file
2026-11-15 19:49:41 -08:00
.agents fix: validate MCP results, retain Cloudflare auth, and clarify docs (#5656) 2026-11-09 10:34:51 -08:00
.github Allow qualification of unpublished SDK previews (#6027) 2026-11-15 16:49:14 -08:00
.vscode [8/n] Make realtime more like the rest of agents sdk (#1076) 2025-07-11 20:50:06 -04:00
benchmarks/native-sdk docs: Clarify Python SDK setup, tool names, and output limits (#6014) 2026-11-14 21:47:20 -08:00
docs docs: Describe supported CustomStorage checkpoint workflows (#6018) 2026-11-15 17:17:21 -08:00
examples docs: Describe supported CustomStorage checkpoint workflows (#6018) 2026-11-15 17:17:21 -08:00
packages/codex Fix rollback for ordinary Python SDK sessions (#6033) 2026-11-15 19:49:41 -08:00
src Preserve Classic compaction history limits (#6028) 2026-11-15 17:41:43 -08:00
.gitattributes fix: keep checkout line endings LF 2026-08-20 12:04:27 +09:00
.gitignore Import the native Agents SDK into feat/codex-harness (#5489) 2026-11-02 22:21:22 -08:00
.prettierrc Initial commit 2025-03-11 09:42:28 -07:00
.release-please-manifest.json Prepare Agents SDK v0.24.0-alpha.8 2026-11-11 09:36:56 -08:00
AGENTS.md chore: prepare 0.24.0-alpha.7 release 2026-11-08 06:02:46 +00:00
CHANGELOG-alpha.md Fix rollback for ordinary Python SDK sessions (#6033) 2026-11-15 19:49:41 -08:00
CHANGELOG.md fix: close documentation gaps and validate SDK examples (#5546) 2026-11-05 22:11:17 -08:00
CLASSIC.md Clarify Python SDK APIs for alpha.8 (#6029) 2026-11-15 16:18:53 -08:00
CONTRIBUTING.md docs: add focused v0-to-v1 migration walkthroughs (#5609) 2026-11-07 23:39:21 -08:00
LICENSE Initial commit 2025-03-11 09:42:28 -07:00
Makefile refactor: consolidate Codex runtime ownership (#5548) 2026-11-05 18:53:47 -08:00
MIGRATION.md docs: Clarify Python SDK setup, tool names, and output limits (#6014) 2026-11-14 21:47:20 -08:00
mkdocs.yml docs: organize SDK guides around developer tasks (#5920) 2026-11-12 21:00:58 -08:00
PLANS.md docs: add ExecPlan guidance and template (#2298) 2026-01-12 18:37:49 +09:00
pyproject.toml Precompile SDK dataclass methods for cold startup (#5993) 2026-11-14 04:42:02 -08:00
pyrightconfig.json Native v1 model callbacks, tools, storage and tracing (#5685) 2026-11-09 22:31:48 -08:00
README.md Fix strict tool recovery and Python preview compatibility (#6026) 2026-11-15 11:34:48 -08:00
release-please-config.json Import the native Agents SDK into feat/codex-harness (#5489) 2026-11-02 22:21:22 -08:00
SECURITY.md docs: clarify retry-delay security threat model (#5215) 2026-09-28 08:57:39 -07:00
uv.lock Prepare Agents SDK v0.24.0-alpha.8 2026-11-11 09:36:56 -08:00

OpenAI Agents SDK

Build Python agents that call your functions, use MCP tools, and keep a conversation across messages. Define the agent's instructions and tools; the SDK uses Codex to coordinate model requests and tool calls. It validates tool arguments, calls your functions, and parses typed results.

Your application runs the agent and owns its workers, storage, and credentials. See how the SDK and hosted Agents API run agents.

Install

Install a prebuilt preview wheel from GitHub Releases. Follow the installation guide to set up a Python environment and find the command for your platform.

Run your first agent

With your Python environment active, save this script as agent.py in your project directory. It needs an OpenAI API key and makes live model requests that can incur charges.

import asyncio

from agents import Agent, function_tool


@function_tool
async def greeting(name: str) -> str:
    return f"Hello, {name}!"


async def main() -> None:
    agent = Agent(
        name="Assistant",
        instructions=(
            "Use greeting to greet the user. "
            "After the tool returns, repeat its greeting in your final answer."
        ),
        tools=[greeting],
    )
    result = await agent.run("Greet Ada.")
    print(result.final_output)


asyncio.run(main())

Set OPENAI_API_KEY in your environment, then run python agent.py in the same shell. See how to create and export an API key.

The script prints a greeting for Ada. The wording can vary. The @function_tool decorator tells the model which arguments greeting takes. The SDK calls the function when the model requests it.

Guides and examples

Find the guides and examples for your installed version, including a test you can run without an API key.

Existing v0 applications

You can stay on v0. When you choose to upgrade, we recommend migrating directly to native v1, including your tools, execution, and state handling. The guide includes an API mapping, validation steps, and instructions for using a coding agent to help with the port.

If a workflow needs the new package before you can port it, this branch provides agents.classic as an intermediate step. It retains the Python runner while the root agents API uses Codex. See classic setup for imports, dependencies, and compatibility limits.

Get help

Use GitHub issues for questions, bug reports, and feedback.

Contributing

To build or test the SDK from source, follow the contributor guide. Use the development guides and examples from the same commit as your build.