OpenAI Agents SDK for Python Skill

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. Model availability/live responses were not tested by the offline SDK check.

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: beta 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.

Agent Skills: OpenAI Agents SDK for Python

Install this agent skill to your local

Skill Files