Openai Agents Sdk

OpenAI Agents SDK (Python)

Overview

The OpenAI Agents SDK is a lightweight, Python-first package for building agentic AI apps with very few abstractions: Agents (LLMs with instructions and tools), Agents as tools / Handoffs (delegation), Guardrails (input/output validation), Sessions (memory across turns), and Tracing (observability). Runner executes agents with a built-in loop that manages turns, tool calls, handoffs, guardrails, and sessions.

Ground all code in the official docs. This skill's reference files reproduce the documented API — never invent imports or parameters.

Core workflow (hello world)

from agents import Agent, Runner

agent = Agent(name="Assistant", instructions="You are a helpful assistant")

result = Runner.run_sync(agent, "Write a haiku about recursion in programming.")
print(result.final_output)

Setup: pip install openai-agents, then set OPENAI_API_KEY. The SDK is async-first: use await Runner.run(...) inside an async def main() (or asyncio.run(main())); Runner.run_sync() for scripts.

How to use this skill

1. Identify what the user is building (single agent → tools → multi-agent → production).
2. Read the matching reference file(s) below before writing agent code.
3. Use the example scripts in assets/examples/ as starting points; adapt them to the user's needs.
4. For anything beyond these guides, consult the official docs (https://openai.github.io/openai-agents-python/); model IDs change and docs examples lag — prefer configurable model selection.

Before implementing

Gather context before writing agent code:

Clarify when ambiguous

Ask only what the code cannot tell you — never ask the user to recall SDK API details (this skill embeds them). Limit to 1–2 questions up front.

• Required (ask before building if unknown)
  • What does the agent do end-to-end, and who/what invokes it (CLI, web endpoint, background job)?
  • Is the interaction multi-turn (needs sessions/memory) or single-turn?
• Optional (only if relevant)
  • Custom model/provider vs the default, and is an API key already configured?
  • Streaming UX (run_streamed) vs a full RunResult?
  • Is a persistence backend already available (Postgres/Redis/SQLite) for sessions?

Learning path: hello world → production

Decision guide (jump straight to the right file)

• "Hello world" / first run / how does Runner work? → getting-started.md
• Agent configuration (name, instructions, output_type, hooks, context types, tool_use_behavior) → agents.md
• Tools (@tool, schemas, hosted tools, timeouts, error handling) → tools.md
• Agent orchestration (handoffs vs agents-as-tools, which to pick) → orchestration.md
• Validate input/output/tool calls → guardrails.md
• Conversation memory / sessions / backends → state-and-sessions.md
• Which model / provider / temperature → models-and-config.md
• Traces, group_id, disabling tracing, custom processors → observability.md
• Connect an MCP server (stdio, HTTP, hosted) → mcp.md
• Robustness, evals, deployment, human-in-the-loop → production.md

Key rules (verified against official docs)

• Import @tool from agents.decorators — the documented decorator. The legacy function_tool is still exported from agents and behaves identically.
• Guardrail decorators live in agents.decorators: input_guardrail, output_guardrail, tool_input_guardrail, tool_output_guardrail.
• Agent + Runner = the SDK manages turns, tools, guardrails, handoffs, sessions for you. Use the Responses API directly only when you want to own the loop yourself.
• name is required on every Agent; instructions is strongly recommended.
• Final output rule: an agent's output is final only when it produces text with the desired type and there are no tool calls.
• Sessions cannot combine with conversation_id, previous_response_id, or auto_previous_response_id in the same run.
• Input guardrails run only on the first agent; output guardrails only on the final agent; tool guardrails wrap every custom @tool call.
• tool_choice auto-resets to auto after a tool call (reset_tool_choice=True) to prevent infinite loops.
• Hosted tools (WebSearchTool, FileSearchTool, ToolSearchTool, etc.) require OpenAIResponsesModel.
• Tracing is on by default. Disable via OPENAI_AGENTS_DISABLE_TRACING=1, set_tracing_disabled(True), or RunConfig(tracing_disabled=True).
• Default model is gpt-5.4-mini (overridable via OPENAI_DEFAULT_MODEL or RunConfig(model=...)). Model IDs in docs examples lag reality — configure via env/config, don't hardcode.

Example scripts (assets/examples/)

Copy and adapt these runnable scripts rather than writing from scratch:

• hello_world.py — minimal sync agent (hello world)
• function_tools.py — agents with @tool functions (async + context)
• structured_output.py — Pydantic output_type extraction
• handoffs.py — triage agent routing to specialists
• multi_agent.py — orchestrator calling specialists via as_tool()
• guardrails.py — input + output guardrail with tripwires
• sessions.py — multi-turn conversation with SQLiteSession

References

• references/getting-started.md — install, hello world, Runner API, agent loop, RunResult, streaming, exceptions
• references/agents.md — Agent constructor, structured output, context types, dynamic instructions, hooks
• references/tools.md — @tool, hosted tools, timeouts, errors, agents-as-tools, tool search
• references/orchestration.md — handoffs, handoff customization, manager pattern, code-driven patterns
• references/guardrails.md — input/output/tool guardrails, tripwires
• references/state-and-sessions.md — memory strategies, session backends, session operations
• references/models-and-config.md — model selection, providers, ModelSettings, env vars, RunConfig
• references/observability.md — tracing, group_id, sensitive data, custom processors
• references/mcp.md — HostedMCPTool, MCPServerStdio/StreamableHttp/Sse, server manager, filtering
• references/production.md — error handlers, approvals, RunConfig hardening, durable execution, checklist