| .agents | ||
| .github | ||
| .vscode | ||
| benchmarks/native-sdk | ||
| docs | ||
| examples | ||
| packages/codex | ||
| src | ||
| .gitattributes | ||
| .gitignore | ||
| .prettierrc | ||
| .release-please-manifest.json | ||
| AGENTS.md | ||
| CHANGELOG-alpha.md | ||
| CHANGELOG.md | ||
| CLASSIC.md | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| Makefile | ||
| MIGRATION.md | ||
| mkdocs.yml | ||
| PLANS.md | ||
| pyproject.toml | ||
| pyrightconfig.json | ||
| README.md | ||
| release-please-config.json | ||
| SECURITY.md | ||
| uv.lock | ||
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.