Openai Agents Sdk

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 asynciofrom pydantic import BaseModelfrom agents import Agent, ModelSettings, Runner, SQLiteSession, function_toolfrom openai.types.shared import Reasoning
class OrderAnswer(BaseModel):    order_id: str    status: str    reply: str
@function_tooldef 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 [blocked]: model defaults, Azure and adapters.
• Tools [blocked]: local/hosted execution, delegation and approval/resume.
• Structured output [blocked]: schema and capability constraints.
• Streaming [blocked]: event types, failures and guardrails.
• Handoffs [blocked]: control transfer and filtering.
• Guardrails [blocked]: execution timing and coverage.
• Sessions [blocked]: history ownership and persistence.
• Orchestration/tracing [blocked]: run limits and observability.
• Sandbox [blocked]: 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.