scaffolding-openai-agents_skill

Overview

This skill demonstrates how to build production AI agents using the OpenAI Agents SDK with async/await patterns and multi-agent orchestration. It provides patterns for creating Agent classes, Runner execution (sync, async, streaming), tool functions, guardrails, and agent handoffs for specialist routing. The examples emphasize Python idioms, structured outputs, and integrating agents into services like FastAPI.

How this skill works

You define Agent objects with instructions, model settings, tools, and optional handoffs or guardrails. The Runner executes agents asynchronously (or synchronously for simple scripts), supports streamed output events, and can continue conversations by feeding prior turn outputs back into input. Tools can be synchronous or async function_tools, agents can act as tools, and guardrails validate inputs/outputs or trigger tripwires.

When to use it

• Building tutoring or instructional agents that must ask clarifying questions and track progress
• Orchestrating multiple specialist agents with automatic handoffs (triage → specialist)
• Implementing tool-calling agents that run code, call external APIs, or query docs
• Streaming responses to clients or integrating agents into FastAPI endpoints
• Enforcing input/output guardrails to prevent unsafe or out-of-scope responses

Best practices

• Prefer async Runner.run for production; use run_sync for simple scripts only
• Encapsulate external calls in async function_tools and validate inputs with pydantic
• Use structured output types (Pydantic models) when deterministic JSON output is required
• Combine handoffs and agents-as-tools for clear separation of concerns and easier testing
• Implement input and output guardrails to detect policy or domain violations early
• Stream responses to UX clients for lower latency and progressive rendering

Example use cases

• A Python tutoring system that routes student queries to concept, debug, or exercise agents
• A content pipeline where a manager agent uses researcher and writer agents as tools
• A FastAPI-based Q&A service that streams agent responses to clients
• A documentation search tool using async function_tools returning typed results
• A monitored tutoring session that logs topics via a shared RunContext and traces