SKILL.md
OpenAI Agents SDK (Python)
Use this skill when developing AI agents using OpenAI Agents SDK (openai-agents package).
Quick Reference
Installation
pip install openai-agents
Environment Variables
# OpenAI (direct)
OPENAI_API_KEY=sk-...
LLM_PROVIDER=openai
Azure OpenAI (via LiteLLM)
LLM_PROVIDER=azure
AZURE_API_KEY=...
AZURE_API_BASE=https://your-resource.openai.azure.com
AZURE_API_VERSION=2024-12-01-preview
### Basic Agent
from agents import Agent, Runner
agent = Agent(
name="Assistant",
instructions="You are a helpful assistant.",
model="gpt-5.4", # or "gpt-5.4-mini", "gpt-5.4-nano"
)
Synchronous
result = Runner.run_sync(agent, "Tell me a joke")
print(result.final_output)
Asynchronous
result = await Runner.run(agent, "Tell me a joke")
### Key Patterns
Pattern
Purpose
Basic Agent
Simple Q&A with instructions
Azure/LiteLLM
Azure OpenAI integration
AgentOutputSchema
Strict JSON validation with Pydantic
Function Tools
External actions (@function_tool)
Streaming
Real-time UI (Runner.run_streamed)
Handoffs
Specialized agents, delegation
Agents as Tools
Orchestration (agent.as_tool)
LLM as Judge
Iterative improvement loop
Guardrails
Input/output validation
Sessions
Automatic conversation history
Multi-Agent Pipeline
Multi-step workflows
Sandboxing
Isolated execution environment for agents
Subagents
Spawn specialized subordinate agents (Python + TS)
Observability
Built-in execution graph recording
## Preferred: Live Docs via MCP
Model names and API details change frequently. When available, consult the **OpenAI Developer Docs MCP server** (`openaiDeveloperDocs`) before relying on the static references below.
Setup (Codex CLI):
codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp
Or config (`~/.codex/config.toml`, VS Code `.vscode/mcp.json`, Cursor `~/.cursor/mcp.json`):
[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"