Skip to content

laguagu/claude-code-nextjs-skills / skills/openai-agents-sdk

openai-agents-sdk

Verified

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.run_sync`/`Runner.run_streamed`, `@function_tool`, `AgentOutputSchema`, `SQLiteSession`, or questions about the openai-agents-python SDK. Python only — not the TypeScript `@openai/agents` SDK.

FileKindSize
SKILL.mdskill md5.9 KB
references/guardrails.mdmarkdown1.8 KB
references/handoffs.mdmarkdown1.4 KB
references/patterns.mdmarkdown1.5 KB
references/providers.mdmarkdown2.8 KB
references/sandbox.mdmarkdown1.5 KB
references/sessions.mdmarkdown1.6 KB
references/streaming.mdmarkdown1.5 KB
references/structured-output.mdmarkdown838 B
references/tools.mdmarkdown3.0 KB
---
name: openai-agents-sdk
description: 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.run_sync`/`Runner.run_streamed`, `@function_tool`, `AgentOutputSchema`, `SQLiteSession`, or questions about the openai-agents-python SDK. Python only — not the TypeScript `@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](https://openai.github.io/openai-agents-python/)
and a matching source tag take precedence over static examples.

Choose a model from the current [OpenAI model catalog](https://developers.openai.com/api/docs/models)
and [model-selection guide](https://developers.openai.com/api/docs/guides/model-selection).
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.24.0; confirm names in the installed source for
another version:

```python
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](https://developers.openai.com/api/docs/models/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](references/providers.md): model defaults, Azure and adapters.
- [Tools](references/tools.md): local/hosted execution, delegation and approval/resume.
- [Structured output](references/structured-output.md): schema and capability constraints.
- [Streaming](references/streaming.md): event types, failures and guardrails.
- [Handoffs](references/handoffs.md): control transfer and filtering.
- [Guardrails](references/guardrails.md): execution timing and coverage.
- [Sessions](references/sessions.md): history ownership and persistence.
- [Orchestration/tracing](references/patterns.md): run limits and observability.
- [Sandbox](references/sandbox.md): 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](https://github.com/openai/openai-agents-python/tree/main/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.24.0) 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.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall