---

name: openai-agents-python description: "Route tasks for using, debugging, and maintaining the OpenAI Agents Python SDK across agents, tools, sessions, models, MCP, realtime, sandbox, tracing, and repo-development workflows." disable-model-invocation: true metadata: disco-role: operating license: MIT

OpenAI Agents Python

Use this repo skill when a task involves the Python openai-agents package, the agents import module, or this repository's SDK code, examples, tests, docs, and maintainer workflow.

The root is a router. Read only the nearest sub-skill and references needed for the current task.

Start Here

1. Install the package with Python 3.10+:

   pip install openai-agents
   

2. Use extras only for the workflow that needs them:

   pip install "openai-agents[voice]"       # VoicePipeline, STT/TTS helpers
   pip install "openai-agents[redis]"       # RedisSession
   pip install "openai-agents[sqlalchemy]"  # SQLAlchemySession
   pip install "openai-agents[docker]"      # Docker sandbox client
   pip install "openai-agents[litellm]"     # LiteLLM adapter
   

3. Run the bundled install diagnostic when import, extras, or version facts are unclear:

   python openai-agents-python/scripts/check_openai_agents_install.py --json
   

4. Read references/repo-provenance.md before deciding whether this skill is current for a checkout. If commit, dirty source state, version, or major evidence paths changed, refresh the skill.

Route By Task

User task or signal	Read
Define Agent, run Runner.run, stream events, inspect RunResult, resume RunState, use RunConfig core settings	sub-skills/core-runtime/SKILL.md
Add function tools, hosted tools, local shell/computer/apply-patch tools, agents-as-tools, handoffs, approvals, guardrails	sub-skills/tools-handoffs-guardrails/SKILL.md
Add persistent memory, choose SQLiteSession or optional session backends, use OpenAI conversation continuation, compact history	sub-skills/sessions-memory/SKILL.md
Configure OpenAI model providers, Responses vs Chat Completions, websocket transport, third-party adapters, retries, ModelSettings	sub-skills/models-providers/SKILL.md
Integrate local MCP servers, hosted MCP tools, filtering, approvals, structured content, retries, auth/session issues	sub-skills/mcp-and-hosted-tools/SKILL.md
Build realtime sessions, audio/text event loops, telephony attach flows, interruption playback, optional voice pipelines	sub-skills/realtime-voice/SKILL.md
Configure SandboxAgent, Manifest, entries, capabilities, sandbox clients, snapshots, mounts, sandbox memory, workspace safety	sub-skills/sandbox-agents/SKILL.md
Configure tracing, processors, spans, sensitive-data controls, usage tracking, logging/debug, visualization	sub-skills/tracing-observability/SKILL.md
Modify this repository, choose focused tests, follow API compatibility rules, update docs/snapshots, prepare PR handoff	sub-skills/repo-development/SKILL.md

Cross-Cutting References

• Read references/capability-map.md when a request spans several SDK surfaces and the owning sub-skill is not obvious.
• Read references/troubleshooting.md for install/import, API key, optional extra, package-version, and source-vs-installed-package confusion.
• Read references/repo-routing-metadata.json only when importing or updating the managed repo-skills-router entry.

Bundled Scripts

• Run scripts/check_openai_agents_install.py to inspect package version, importability, public surfaces, and optional extras without API calls.
• Run scripts/list_example_families.py to see the distilled example families this skill covers without depending on the original checkout.
• Each sub-skill also owns focused helpers for safe schema, config, manifest, tracing, or test-target checks.

Important Boundaries

• This skill is self-contained. Do not require future agents to open original repository docs, examples, tests, or scripts at runtime.
• Original examples and tests are evidence. Credentialed, networked, audio-device, Docker, hosted-provider, or long-running examples are distilled into bundled references or marked as verification candidates, not runtime dependencies.
• Most SDK examples require OPENAI_API_KEY or another provider credential before real model calls. The bundled helpers avoid model/API calls by default.
• agents.voice requires the voice extra. Optional session, provider, sandbox, and visualization backends require their matching extras.
• When editing this repository, follow sub-skills/repo-development/SKILL.md before changing runtime code, tests, examples, build/test config, or behavior-impacting docs.