Skip to main content
hc
Submit
toolsSource-backedReview first Safety ✓ Privacy ✓

OpenAI Agents Python SDK

Official Python framework for building multi-agent workflows with agents, tools, handoffs, guardrails, sessions, tracing, realtime voice agents, MCP tools, hosted tools, human-in-the-loop flows, and sandbox agents.

by OpenAI·added 2026-06-18·
CLI
HarnessCLI
Review first — review before installing

Open the source and read safety notes before installing.

Safety notes

  • Agents can call function tools, hosted tools, MCP tools, realtime tools, and sandbox agents; treat every tool as an API endpoint with explicit authorization, input validation, rate limits, and side-effect controls.
  • Sandbox agents can inspect files, run commands, apply patches, and carry workspace state across longer tasks; restrict workspace scope and require human approval before destructive or high-impact actions.
  • Guardrails are useful runtime checks, but they do not replace permission checks, least-privilege credentials, audit logs, or human review for risky operations.
  • Handoffs and agents-as-tools can delegate work across agents; document which agent owns each tool, decision, retry, rollback, and escalation path.
  • Realtime voice agents and human-in-the-loop flows need clear consent, interruption, recording, and operator takeover behavior.

Privacy notes

  • Prompts, instructions, tool arguments, tool outputs, session history, traces, realtime audio events, sandbox files, logs, provider responses, and errors may contain user or workspace data.
  • Do not expose secrets, tokens, private file paths, customer records, credentials, internal identifiers, or raw exceptions through traces, logs, prompts, tool schemas, or examples.
  • When using MCP servers, hosted tools, Redis sessions, SQL-backed sessions, or observability systems, review each service's retention, access control, and third-party data handling separately.
  • If sandbox agents operate on repositories or user files, define which files can be mounted, modified, committed, uploaded, logged, or returned to the model.

Prerequisites

  • Python 3.10 or newer and a project environment managed with uv, pip, or another Python package manager.
  • OpenAI API credentials or another configured model provider supported through the SDK's provider-agnostic routes.
  • A reviewed tool boundary for function tools, hosted tools, MCP tools, handoffs, sandbox agents, and any external systems the agent can call.
  • A tracing, logging, and retention policy for prompts, tool calls, sessions, provider responses, and run metadata.
  • Optional voice, Redis, SQLAlchemy, realtime, sandbox, or deployment dependencies only when those runtime capabilities are actually needed.

Schema details

Install type
cli
Troubleshooting
No
Source repository stats
Scope
Source repo
Collection metadata
Estimated setup
20 minutes
Difficulty
intermediate
Tool listing metadata
Pricing
free
Disclosure
editorial
Application category
DeveloperApplication
Operating system
Cross-platform
Full copyable content
uv add openai-agents

About this resource

Overview

OpenAI Agents Python SDK is OpenAI's official Python framework for building agentic applications and multi-agent workflows. The SDK centers on agents with instructions, tools, guardrails, handoffs, sessions, tracing, realtime voice agents, and sandbox agents, while also supporting OpenAI APIs and other model providers.

Use it when a Python project needs a code-first agent runtime rather than a single prompt wrapper. It is especially relevant for teams building production agent workflows that need inspectable traces, delegated agents, tool execution, MCP integration, session storage, human review, or voice interaction.

Install

For uv-managed projects:

uv add openai-agents

For pip-managed projects:

pip install openai-agents

Optional extras cover voice, Redis sessions, SQLAlchemy sessions, realtime, MCP-related runtime dependencies, sandbox providers, deployment integrations, and other advanced capabilities. Install only the extras required by the workflow you are actually running.

Agent Capabilities

Area Python SDK Coverage
Agents Instructions, model configuration, tools, guardrails, handoffs, and run behavior
Tools Function tools, hosted tools, MCP tools, agents-as-tools, and sandbox agents
Workflow Control Handoffs, human-in-the-loop review, sessions, retries, and run configuration
Observability Built-in tracing for debugging and optimizing agent runs
Realtime Voice agent support through realtime agent APIs and optional voice dependencies
Sandboxes Agents that can work against controlled filesystem or container-like workspaces
Provider Routing OpenAI Responses and Chat Completions APIs plus provider-agnostic support for other LLM routes

MCP Fit

The SDK is relevant to MCP searches because its tool layer can use MCP tools alongside function tools and hosted tools. That makes it useful for Python agent apps that want to call existing MCP servers without writing every integration as a custom Python adapter.

Keep the trust boundary explicit: an MCP server can expose local files, SaaS accounts, databases, browser automation, cloud infrastructure, or internal APIs. The agent framework wires those capabilities into a workflow, but the application still owns authorization, least privilege, logging, approval gates, and rollback behavior.

Use Cases

  • Build Python assistants that coordinate several specialized agents.
  • Route work between agents with handoffs or agents-as-tools.
  • Add MCP tools to an OpenAI Agents workflow.
  • Use guardrails and human review around higher-risk tool calls.
  • Trace agent runs for debugging, evaluation, and release review.
  • Add session memory backed by local, Redis, SQL, or custom stores.
  • Build realtime voice agents with the optional voice and realtime paths.
  • Run sandbox agents against controlled workspaces for longer coding or repository tasks.

Source Review

Verified on 2026-06-18:

  • The upstream README describes the OpenAI Agents SDK as a lightweight framework for multi-agent workflows and says it supports OpenAI APIs plus other LLMs.
  • The README lists agents, sandbox agents, agents-as-tools, handoffs, tools, guardrails, human-in-the-loop flows, sessions, tracing, and realtime agents as core concepts.
  • The README documents pip install openai-agents and uv add openai-agents install paths, with optional voice and Redis extras.
  • pyproject.toml declares the openai-agents package, Python >=3.10, MIT licensing, the OpenAI author, OpenAI docs, repository URL, MCP package dependency, and optional extras for voice, realtime, Redis, SQLAlchemy, sandbox providers, deployment providers, and Temporal.
  • PyPI resolves package metadata for openai-agents version 0.17.5.

Safety and Privacy

The SDK's risk profile depends on the tools and systems attached to each agent. Treat function tools, MCP tools, hosted tools, realtime actions, sandbox agents, and delegated agents as separate trust boundaries with their own permissions, audit trail, and failure mode.

Tracing, session storage, voice events, sandbox files, tool results, provider responses, and logs can contain sensitive user or workspace data. Review what is stored, who can read it, how long it is retained, and whether data crosses OpenAI, other model providers, MCP servers, databases, observability systems, or deployment platforms.

Duplicate Check

Checked current content/agents/, content/guides/, content/mcp/, content/tools/, content/skills/, open pull requests, and repository-wide content for openai/openai-agents-python, OpenAI Agents Python SDK, OpenAI Agents SDK, openai-agents, OpenAI Agents MCP tools, OpenAI Agents tracing, and OpenAI sandbox agents. Existing entries include an OpenAI Agents SDK production specialist agent and a trace-to-eval guide, but no dedicated installable Python SDK tools entry, exact source URL duplicate, target file, or open duplicate PR was found.

#openai#agents#python#agent-framework#mcp#tracing#voice

Source citations

Add this badge to your README

Show that OpenAI Agents Python SDK is listed on HeyClaude. Paste this Markdown into your README — it renders the badge and links back to this page.

Listed on HeyClaude
[![Listed on HeyClaude](https://heyclau.de/badge/tools/openai-agents-python-sdk.svg)](https://heyclau.de/entry/tools/openai-agents-python-sdk)

How it compares

OpenAI Agents Python SDK side by side with 3 alternatives on trust, install, platform support, and disclosed safety notes — all from reviewed registry metadata.

FieldOpenAI Agents Python SDK

Official Python framework for building multi-agent workflows with agents, tools, handoffs, guardrails, sessions, tracing, realtime voice agents, MCP tools, hosted tools, human-in-the-loop flows, and sandbox agents.

Open dossier 		OpenAI Agents JavaScript SDK

Official JavaScript and TypeScript framework for building multi-agent workflows with agents, tools, handoffs, guardrails, sessions, tracing, realtime voice agents, MCP tools, hosted tools, and sandbox agents.

Open dossier 		AG2 Agent Framework

Open-source Python AgentOS and multi-agent framework, evolved from AutoGen, for building conversable agents, group chats, swarms, human-in-the-loop workflows, tool use, RAG, code execution, and provider-backed agent systems.

Open dossier 		Microsoft Agent Framework

Microsoft framework for building, orchestrating, and deploying production AI agents and multi-agent workflows across Python and .NET, with workflows, middleware, OpenTelemetry, Foundry hosting, A2A, MCP, and Semantic Kernel migration support.

Open dossier
Trust
Install riskReview firstReview firstReview firstReview first
Notes Safety ✓ Privacy ✓ Safety ✓ Privacy ✓ Safety ✓ Privacy ✓ Safety ✓ Privacy ✓
Categorytoolstoolstoolstools
Sourcesource-backedsource-backedsource-backedsource-backed
AuthorOpenAIOpenAIAG2Microsoft
Added2026-06-182026-06-182026-06-182026-06-18
Platforms
CLI
CLI
CLI
CLI
Source repo————
Safety notes✓Agents can call function tools, hosted tools, MCP tools, realtime tools, and sandbox agents; treat every tool as an API endpoint with explicit authorization, input validation, rate limits, and side-effect controls. Sandbox agents can inspect files, run commands, apply patches, and carry workspace state across longer tasks; restrict workspace scope and require human approval before destructive or high-impact actions. Guardrails are useful runtime checks, but they do not replace permission checks, least-privilege credentials, audit logs, or human review for risky operations. Handoffs and agents-as-tools can delegate work across agents; document which agent owns each tool, decision, retry, rollback, and escalation path. Realtime voice agents and human-in-the-loop flows need clear consent, interruption, recording, and operator takeover behavior.✓Agents can call function tools, hosted tools, MCP tools, realtime tools, and sandbox agents; treat every tool as an API endpoint with explicit authorization, input validation, rate limits, and side-effect controls. Sandbox agents can inspect files, run commands, apply patches, and carry workspace state across longer tasks; restrict workspace scope and require human approval before destructive or high-impact actions. Cloudflare Workers support is described upstream as experimental; review runtime compatibility, secrets, outbound network access, logging, request limits, and `nodejs_compat` behavior before production use. Guardrails help validate inputs and outputs, but they do not replace permission checks, least-privilege credentials, audit logs, or human review for risky operations. Handoffs and agents-as-tools can delegate work across agents; document which agent owns each tool, decision, retry, rollback, and escalation path.✓AG2 agents can converse, call tools, execute code, use retrieval systems, run browser workflows, and coordinate group chats; require explicit permissions and approval gates for high-impact actions. The upstream install docs and examples commonly involve provider credentials; keep API keys, config files, notebooks, and `.env` files out of commits and support tickets. Code execution, Docker, Jupyter, browser-use, and RAG extras can touch local files, network services, notebooks, databases, and external websites; scope them tightly before granting agent access. Multi-agent conversations can continue through nested chats, swarms, group chats, and custom reply handlers; define termination, escalation, retry, and human takeover behavior. Track the release roadmap before upgrading because deprecations and the v1.0 transition can change which APIs should be used for new work.✓Microsoft Agent Framework can orchestrate agents, tools, workflows, middleware, hosting, A2A, MCP, and third-party providers; review each external system before granting access. Production agents need explicit approval gates, retries, cancellation, idempotency, rollback behavior, tool authorization, and human-in-the-loop boundaries. DefaultAzureCredential is convenient for development but can probe multiple credential sources; choose explicit production credentials and managed identity patterns where appropriate. Foundry-hosted agents, cloud workflows, Durable Task, Azure Functions, and A2A/MCP endpoints need authentication, least privilege, network controls, logging policy, and abuse protection. Migration from Semantic Kernel or AutoGen should include behavior parity tests, trace comparison, provider compatibility review, and safety regression checks.
Privacy notes✓Prompts, instructions, tool arguments, tool outputs, session history, traces, realtime audio events, sandbox files, logs, provider responses, and errors may contain user or workspace data. Do not expose secrets, tokens, private file paths, customer records, credentials, internal identifiers, or raw exceptions through traces, logs, prompts, tool schemas, or examples. When using MCP servers, hosted tools, Redis sessions, SQL-backed sessions, or observability systems, review each service's retention, access control, and third-party data handling separately. If sandbox agents operate on repositories or user files, define which files can be mounted, modified, committed, uploaded, logged, or returned to the model.✓Prompts, instructions, tool arguments, tool outputs, session history, traces, realtime audio events, sandbox files, logs, provider responses, and errors may contain user or workspace data. Do not expose secrets, tokens, private file paths, customer records, credentials, internal identifiers, raw exceptions, or voice transcripts through traces, logs, prompts, tool schemas, or examples. When using MCP servers, hosted tools, session stores, worker logs, observability systems, or deployment platforms, review each service's retention, access control, and third-party data handling separately. If sandbox agents operate on repositories or user files, define which files can be mounted, modified, committed, uploaded, logged, or returned to the model.✓Prompts, messages, tool arguments, tool outputs, code snippets, notebook state, retrieved documents, vector-store contents, provider responses, traces, and execution logs may contain sensitive user or workspace data. Do not expose secrets, API keys, private file paths, customer records, internal documents, database rows, or raw exceptions through agent messages, logs, notebooks, screenshots, or public examples. Provider extras and retrieval integrations can route data through OpenAI, Anthropic, Google, AWS, local model servers, databases, vector stores, browser automation, or other third-party services. If AG2 is used for code execution or browser automation, define which files, domains, credentials, downloads, screenshots, and logs can be read or retained.✓Prompts, instructions, tool arguments, tool outputs, workflow state, middleware data, traces, provider responses, logs, credentials, and hosted-agent metadata may contain sensitive user or business data. Do not expose Azure credentials, Foundry project endpoints, model deployment names, API keys, private file paths, customer records, internal documents, or raw exceptions through examples, traces, logs, or support issues. When using third-party providers, A2A agents, MCP servers, observability systems, or cloud hosting, review where data is sent, stored, retained, and governed. If workflows are durable or restartable, define retention and access controls for checkpoints, state stores, trace spans, and replayable execution history.
Prerequisites
  • Python 3.10 or newer and a project environment managed with uv, pip, or another Python package manager.
  • OpenAI API credentials or another configured model provider supported through the SDK's provider-agnostic routes.
  • A reviewed tool boundary for function tools, hosted tools, MCP tools, handoffs, sandbox agents, and any external systems the agent can call.
  • A tracing, logging, and retention policy for prompts, tool calls, sessions, provider responses, and run metadata.
  • Node.js 22 or later, Deno, Bun, or an explicitly reviewed Cloudflare Workers runtime with `nodejs_compat` enabled.
  • OpenAI API credentials or another configured model provider supported through the SDK's provider-agnostic routes.
  • A reviewed tool boundary for function tools, hosted tools, MCP tools, handoffs, sandbox agents, and any external systems the agent can call.
  • A TypeScript schema strategy for `zod`, tool inputs, tool outputs, guardrails, and runtime validation.
  • Python 3.10 or newer and a Python environment managed with pip, uv, or another package manager.
  • Model provider credentials for the selected provider extra, such as OpenAI, Anthropic, Gemini, Bedrock, Mistral, Ollama, Groq, xAI, or another supported route.
  • A secrets strategy for provider keys, AG2 config files, `.env` files, notebooks, and example `OAI_CONFIG_LIST`-style credentials.
  • A reviewed execution boundary for code execution, Docker, Jupyter, browser-use, RAG, retrieval, database, and external tool extras.
  • Python 3.10 or newer for the Python SDK, or a supported .NET runtime for the `Microsoft.Agents.AI` package.
  • A selected model/provider route, such as Microsoft Foundry, Azure OpenAI, OpenAI, GitHub Copilot SDK, or another supported provider.
  • Azure identity, Foundry project, endpoint, model deployment, or API-key configuration appropriate for the chosen provider and runtime.
  • A deployment plan for workflows, hosting, A2A, MCP, Durable Task, Azure Functions, local development, or cloud execution.
Install
uv add openai-agents
npm install @openai/agents zod
pip install 'ag2[openai]'
pip install agent-framework
Config————
Citations
ClaimUnclaimedUnclaimedUnclaimedUnclaimed

Signals

Loading live community signals…

More like this, weekly

A short, calm digest of reviewed Claude resources. Unsubscribe any time.