Mmcp.market

openai-agents-sdk skill

by laguagu·laguagu/claude-code-nextjs-skills·67 stars·MIT

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 via 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.

A100/100content scan

Is the openai-agents-sdk skill safe?

Clean: nothing in its files matched our rules. We read 10 files in the folder on 2026-09-28.

No findings.

Install the openai-agents-sdk skill

A skill is a folder. Copy it into your agent's skills folder and the agent loads it when the task matches its description.

git clone --depth 1 https://github.com/laguagu/claude-code-nextjs-skills.git /tmp/claude-code-nextjs-skills
mkdir -p ~/.claude/skills
cp -r /tmp/claude-code-nextjs-skills/skills/openai-agents-sdk ~/.claude/skills/openai-agents-sdk
available in every project

In the Claude apps, zip the folder and upload it from the Skills settings. The folder on GitHub

The instructions your agent would load

SKILL.md as published, without the frontmatter. Read it on GitHub

OpenAI Agents SDK (Python)

Use this skill when developing AI agents using OpenAI Agents SDK (openai-agents package).

Quick Reference

Installation

uv add openai-agents        # or `pip install openai-agents` outside a uv project

Environment Variables

Set both in the process environment before running the example; replace the placeholders:

export OPENAI_API_KEY="sk-..."
export OPENAI_MODEL="your-verified-model-id"  # this example's own variable; the SDK itself reads OPENAI_DEFAULT_MODEL

Using Azure or another provider instead? See agents.md — don't hardcode provider env vars here, they vary and go stale.

Basic Agent

import os
from agents import Agent, Runner

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
    model=os.environ["OPENAI_MODEL"],  # configure a verified model ID
)

# Synchronous
result = Runner.run_sync(agent, "Tell me a joke")
print(result.final_output)

# Asynchronous
result = await Runner.run(agent, "Tell me a joke")

Omitting model= uses the installed SDK's default. Configure it explicitly in production and verify available IDs against the provider's model catalog.

Key Patterns

The SDK has no separate Subagent class: express delegation with handoffs or agent.as_tool(). For model-written tool orchestration, use ProgrammaticToolCallingTool and verify its Responses-only constraints.

Preferred: Live Docs via MCP

Model names and API details change frequently. When available, consult the OpenAI Developer Docs MCP server (openaiDeveloperDocs) before relying on the static references below.

Setup (Codex CLI):

codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp

Setup (Claude Code):

claude mcp add --transport http openaiDeveloperDocs https://developers.openai.com/mcp

Or in Codex ~/.codex/config.toml (VS Code and Cursor use different JSON schemas):

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

Key tools: mcpopenaiDeveloperDocssearchopenaidocs, fetchopenaidoc, listapiendpoints, getopenapispec.

Rules: Cite fetched docs. Never speculate on field names, defaults, or current model IDs — fetch first. Keep quotes under 125 chars.

Fallback when MCP is unavailable: https://developers.openai.com/api/docs/llms.txt (plain-text index of all API docs; each entry has a .md twin at /api/docs/.md).

Reference Documentation

Offline/quick-lookup snippets. Verify model names and API signatures against the MCP or docs when accuracy matters.

  • agents.md - read when choosing or wiring a model: default-model caveat, LiteLLM, native Azure client
  • tools.md - read when adding function tools, hosted tools, or agents-as-tools
  • structured-output.md - read when the output must be a Pydantic/dataclass shape (AgentOutputSchema, strict vs non-strict)
  • streaming.md - read when streaming to a UI (event types, SSE with FastAPI)
  • handoffs.md - read when one agent delegates to another (handoff vs as_tool, input filters)
  • guardrails.md - read when validating input/output or gating tool calls
  • sessions.md - read when conversation history must persist across requests (SQLite, SQLAlchemy, Redis, OpenAI Conversations)
  • patterns.md - read for multi-agent pipelines, LLM-as-judge loops, tracing controls, max_turns, parallelization
  • sandbox.md - read when the agent must edit files or run commands in an isolated workspace (SandboxAgent, beta)

Official Documentation

  • Docs: https://openai.github.io/openai-agents-python/
  • Examples: https://github.com/openai/openai-agents-python/tree/main/examples
  • Major update: https://openai.com/index/the-next-evolution-of-the-agents-sdk/
  • Docs MCP setup: https://developers.openai.com/learn/docs-mcp
  • Docs index (llms.txt): https://developers.openai.com/api/docs/llms.txt
  • Current model IDs: https://platform.openai.com/docs/models

More skills from laguagu/claude-code-nextjs-skills

  • Aai-appFull-stack AI application generator with Next.js, AI SDK, and ai-elements. Use when creating chatbots, agent dashboards, or custom AI applications.
  • Aai-elementsBuild AI chat interfaces with pre-built shadcn-style components (Message, Conversation, PromptInput, Reasoning, Sources, Tool, Artifact, CodeBlock, Suggestion, Task, Image, ChainOfThought, InlineCitation, WebPreview, Checkpoint, Plan, Queue, ModelSelector, and more). Use when adding AI chat UI to a Next.js + AI SDK app, installing AI Elements components via the CLI (`bun x ai-elements@latest add message` or `npx shadcn@latest add @ai-elements/message`), composing message displays with markdown, building prompt inputs with attachments, or rendering streaming reasoning and tool output.
  • Aai-sdkAnswer questions about the AI SDK and help build AI-powered features. Use when developers ask about Vercel AI SDK, generateText, streamText, ToolLoopAgent, useChat, providers, tools, structured output, embeddings, streaming, or adding AI to an app. First identify the installed major version and route version-specific work: use ai-sdk-7 for AI SDK 7 features/migrations such as WorkflowAgent, HarnessAgent, reasoning, runtime/tools context, toolApproval, telemetry, realtime, or v6-to-v7 upgrades; use ai-sdk-6 for v6 code.
  • Aai-sdk-6Vercel AI SDK v6 development, for projects already on ai@6. Use when building or maintaining AI agents, chatbots, tool integrations, streaming apps, or structured output in a v6 codebase. New projects and ai@7 code use ai-sdk-7; an unknown version goes through ai-sdk. Covers ToolLoopAgent, useChat, generateText, streamText, tool approval, smoothStream, provider tools, MCP integration, and Output patterns.
  • Aai-sdk-7Vercel AI SDK v7 development and migration. Use when building or upgrading AI SDK 7 apps, especially ToolLoopAgent, WorkflowAgent, HarnessAgent, Claude Code/Codex/Pi harnesses, runtimeContext, toolsContext, toolApproval, telemetry, reasoning, file or skill uploads, realtime, video generation, or v6-to-v7 breaking changes. For AI SDK v6 code use ai-sdk-6; for version discovery and general doc lookup use ai-sdk.
  • Acache-componentsExpert guidance for Next.js Cache Components and Partial Prerendering (PPR). Use when implementing 'use cache' directive, configuring cache lifetimes with cacheLife(), tagging cached data with cacheTag(), invalidating caches with updateTag()/revalidateTag(), optimizing static vs dynamic content boundaries, instant navigation validation, 'use cache: private', pass-through/interleaving patterns, GET Route Handler caching, debugging cache issues, and reviewing Cache Component implementations.
  • Achrome-devtoolsTests in real browsers via Chrome DevTools MCP. Use when building or debugging anything that runs in a browser. Use when you need to inspect the DOM, capture console errors, analyze network requests, profile performance (LCP/CLS/INP), or verify visual output with real runtime data. Complements Playwright — use this for live debugging and performance work, Playwright for stable E2E test suites.
  • Afrontend-designGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.
  • AgoOpens the running app in a browser and verifies that recent UI changes actually work. Use for any quick smoke test of recent work — "go", "test in browser", "check in browser", "make sure it works", "verify it works", "did it work", "works on mobile" — including when the user appends "...and make sure it works" to a UI request. For design critique, use go-ui or web-design-guidelines.
  • AhandoffWrite or update a HANDOFF.md so a fresh agent can continue this work. Use when the user says "handoff", "compact this", "context is full", or "/clear and continue".
  • Chetzner-cloudManage Hetzner Cloud infrastructure with the `hcloud` CLI — servers, networks, firewalls, load balancers, volumes, DNS zones, SSH keys, primary/floating IPs, snapshots, certificates, placement groups, storage boxes. Use whenever the user mentions Hetzner, hcloud, VPS provisioning, or Hetzner location codes (fsn1, hel1, nbg1, ash, hil, sin) — even if they don't say "hcloud". CLI-only; does NOT cover Hetzner Robot (dedicated servers, separate product and API).
  • AiconsFind, fetch, and install the right icon or logo from the right source — brand marks, country flags, file-type icons (PDF, DOCX, ZIP), and UI glyphs — and keep them visually consistent with the app. Use when the project's icon library has no match, when svgl comes up empty, or when the user asks for a flag, a file-type badge, a brand logo, or just "an icon for X". Covers the Iconify search API (200k+ icons across flags, file types, logos and UI sets), the svgl shadcn registry for full-colour brand logos, family and stroke-weight matching so a borrowed icon does not look pasted in, and fallback sources when neither Iconify nor svgl has the mark. Triggers on "add an icon", "country flag", "flag icon", "PDF icon", "file type icon", "brand logo", "sign in with Google/GitHub", "language switcher", "svgl", "iconify", "find an icon". For overall visual direction rather than sourcing one specific mark, use frontend-design; for installing shadcn components generally, use shadcn.

All agent skills → · MCP servers