---

name: OpenAI Agents description: Workflow patterns and gotchas for OpenAI Agents SDK. Directs to RAG for implementation.

OpenAI Agents Workflow

When to Choose OpenAI Agents

• Already using OpenAI API and models
• Need handoff patterns between specialized agents
• Want function calling with type safety
• Building conversational assistants

Decision Framework

Architecture Patterns

Query RAG: mcp__agentic-rag__query_sdk("pattern name", sdk="openai", mode="build")

Critical Gotchas

These cause silent failures or confusion:

1. Use @tool decorator - Functions without it won't be recognized
2. Type hints are required - Parameters need type annotations for schema generation
3. Docstrings define the schema - LLM uses docstring for understanding, not just comments
4. OPENAI_API_KEY env var - Must be set; SDK doesn't prompt for it
5. Model names are specific - gpt-5.2, gpt-5.2-codex (not gpt5 or GPT-5.2)
6. Handoff descriptions drive routing - Vague = poor decisions

Workflow: Creating an OpenAI Agent

Step 1: Environment Setup

RAG Query: mcp__agentic-rag__query_sdk("openai agents installation", sdk="openai", mode="explain")

Step 2: Basic Agent

RAG Query: mcp__agentic-rag__query_sdk("Agent class definition", sdk="openai", mode="build")

Step 3: Tool Definition

RAG Query: mcp__agentic-rag__query_sdk("@tool decorator example", sdk="openai", mode="build")

Type hints + docstring = working tool.

Step 4: Running the Agent

RAG Query: mcp__agentic-rag__query_sdk("Runner execution", sdk="openai", mode="build")

Step 5: Handoffs (if multi-agent)

RAG Query: mcp__agentic-rag__query_sdk("handoff between agents", sdk="openai", mode="build")

Step 6: Memory (if conversational)

RAG Query: mcp__agentic-rag__query_sdk("agent memory persistence", sdk="openai", mode="build")

Common Error Patterns

Advanced Features

Query RAG when you need:

• Streaming responses: "streaming agent output"
• Parallel tool calls: "parallel tool execution"
• Custom runners: "custom Runner implementation"
• Guardrails: "agent guardrails safety"
• Tracing: "agent tracing debugging"