openai-agents-sdk

Q: How do I install openai-agents-sdk?

Run npx skills add https://github.com/laguagu/claude-code-nextjs-skills --skill openai-agents-sdk in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/openai-agents-sdk/ (personal) or .claude/skills/openai-agents-sdk/ (project).

by laguaguAI & Agents

OpenAI Agents SDK (Python) development. Use when building AI agents, multi-agent handoffs, function tools, guardrails, sessions, streaming, or tracing with the openai-agents / agents Python package — including Azure OpenAI through its native client or LiteLLM. Triggers on imports from agents, uses of Runner.runsync/Runner.runstreamed, @functiontool, AgentOutputSchema, SQLiteSession, or questions about the openai-agents-python SDK. Python only — not the TypeScript @openai/agents SDK.

Installs: 2.2K
Last 24h: +8
Trending rank: #9545
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/laguagu/claude-code-nextjs-skills --skill openai-agents-sdk

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads openai-agents-sdk automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

OpenAI Agents SDK for Python

Use this skill for openai-agents / agents, not the TypeScript SDK. Resolve the installed package and its provider integrations before implementing an API. Current SDK documentation and a matching source tag take precedence over static examples.

Choose a model from the current OpenAI model catalog and model-selection guide. Check the selected model's tools, reasoning settings and provider availability; an SDK fallback or a demo ID is not a permanent recommendation.

The wheel ships no docs. Offline, read the installed source: the version from importlib.metadata.version("openai-agents"), public exports in agents/__init__.py, docstrings and types in the package directory (python -c "import agents; print(agents.__file__)"). The documentation source is docs/ at repository tag v<version>.

Core shape

Runner.run_sync raises inside a running event loop (async handlers and notebooks); use await Runner.run(...). Runner.run_streamed(...) itself is not awaited; consume its stream_events() async iterator to completion.

Checked with openai-agents 0.22.3; confirm names in the installed source for another version:

import asyncio
from pydantic import BaseModel
from agents import Agent, ModelSettings, Runner, SQLiteSession, function_tool
from openai.types.shared import Reasoning

class OrderAnswer(BaseModel):
    order_id: str
    status: str
    reply: str

@function_tool
def get_order_status(order_id: str) -> str:
    """Return an order's shipping status.

    Args:
        order_id: Order ID given by the customer.
    """
    return f"{order_id}: shipped"  # authorize and read the app's data here

support = Agent(
    name="Support",
    instructions="Answer order questions. Use get_order_status for order data.",
    model="gpt-6.1-sol",  # example API ID; use the project's configured model
    model_settings=ModelSettings(reasoning=Reasoning(effort="medium")),
    tools=[get_order_status],
    output_type=OrderAnswer,
)
# A manager keeps control with tools=[order_tool]; handoffs=[support] transfers it.
order_tool = support.as_tool("order_support", "Answer an order question.")

async def main() -> None:
    session = SQLiteSession("user-123", "conversations.db")  # ID owned by the signed-in user
    result = await Runner.run(support, "Where is order A-17?", session=session)
    answer: OrderAnswer = result.final_output  # validated OrderAnswer instance
    print(answer.status, answer.reply)

asyncio.run(main())

The example uses Responses (the SDK's default API). GPT-6.1 Sol requires Responses for tool calling and does not support none or minimal reasoning effort.

Integration decisions

Keep the project's provider, model and storage unless the task requires a change. Verify model IDs/capabilities in provider configuration or live docs. SDK model/settings defaults may change; configure product-critical choices explicitly.
Use native provider/client support when it fits. LiteLLM/Any-LLM are optional integrations with their own compatibility and settings behavior.
Choose handoffs when a specialist takes over, or agent.as_tool() when the manager should continue after delegated work. A fixed pipeline does not need extra agents merely to implement ordinary control flow.
Authorize side effects in tools. Agent instructions, output schemas and guardrails do not replace authorization or idempotency.
Decide history ownership, approval/resume and tracing data policy before exposing a multi-turn agent to untrusted clients.

Read for the feature

Agents/providers: model defaults, Azure and adapters.
Tools: local/hosted execution, delegation and approval/resume.
Structured output: schema and capability constraints.
Streaming: event types, failures and guardrails.
Handoffs: control transfer and filtering.
Guardrails: execution timing and coverage.
Sessions: history ownership and persistence.
Orchestration/tracing: run limits and observability.
Sandbox: workspace execution and resume state.

Use the OpenAI Developer Docs MCP (https://developers.openai.com/mcp) if available for current OpenAI API/provider behavior, or its plain-text index https://developers.openai.com/api/docs/llms.txt; use the Python SDK's own reference for SDK signatures. Read selected official examples from a compatible tag, not a copied catalog of demos.

Verification

Verify changed tools, multi-turn history, approval/denial and failure recovery. Use installed agents.testing (verified in 0.22.3) for offline orchestration: ScriptedModel, ModelStep, assistant_message, function_call and model.assert_complete(), with RunConfig(tracing_disabled=True); assigning agent.model = ScriptedModel([...]) runs the core shape offline. Run the project's checks; report missing provider access separately from verified SDK behavior.

FAQ

What does the openai-agents-sdk skill do?

How do I install openai-agents-sdk?

Run npx skills add https://github.com/laguagu/claude-code-nextjs-skills --skill openai-agents-sdk in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/openai-agents-sdk/ (personal) or .claude/skills/openai-agents-sdk/ (project).

Which AI agents can use openai-agents-sdk?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is openai-agents-sdk safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains openai-agents-sdk?

It is published by laguagu in laguagu/claude-code-nextjs-skills. It has 2,227 recorded installs.