OpenAI Agents SDK — From Zero to Multi-Agent Systems

A hands-on learning repo with 7 real-world projects that progressively teach every concept in the OpenAI Agents SDK. Each project solves a practical problem using multi-agent AI workflows.

Prerequisites

• Python 3.10+ (this repo uses 3.12)
• OpenAI API Key

Quick Start

# 1. Clone the repo
git clone <repo-url> && cd openai-agents-sdk

# 2. Create & activate virtual environment
python3.12 -m venv .venv
source .venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Add your API keys
cp .env.example .env   # or edit .env directly
# Set OPENAI_API_KEY in .env

# 5. Open any project notebook
jupyter notebook

Project Overview

#	Project	Key Concepts	Difficulty
1	Customer Support Triage	Agents, Runner, function_tool, handoffs	Beginner
2	Research & Report Generator	Agents as tools (manager pattern), WebSearchTool	Beginner
3	Multi-Language Content Pipeline	output_type (Pydantic), context, chained agents	Intermediate
4	Guardrailed Support Bot	Input/output guardrails, tripwires, guardrail agents	Intermediate
5	Session-Powered Study Buddy	SQLiteSession, memory across turns, multi-turn	Intermediate
6	Code Review Assistant	CodeInterpreterTool, dynamic instructions, hooks	Advanced
7	Full-Stack AI Agency	All concepts combined (capstone)	Advanced

Learning Path

The projects are designed to be followed in order. Each one introduces new concepts while reinforcing previous ones:

Project 1 → Agents, Runner, Function Tools, Handoffs (Triage Pattern)
    ↓
Project 2 → Agents as Tools (Manager Pattern), WebSearchTool
    ↓
Project 3 → Structured Output (output_type), Context Injection
    ↓
Project 4 → Input & Output Guardrails, Tripwires
    ↓
Project 5 → Sessions (SQLiteSession), Persistent Memory
    ↓
Project 6 → CodeInterpreterTool, Dynamic Instructions, Hooks
    ↓
Project 7 → Everything Combined (Capstone)

Concepts Reference

The Core Primitives

Primitive	What It Is	Real-Life Analogy
Agent	An LLM with a name, instructions, and tools	A specialist on the team
Runner	The engine that runs the agent loop	The shift manager
Tool	A function or hosted service the agent can call	A stethoscope, calculator
Handoff	Passing control to another agent	"Let me transfer you to billing"
Guardrail	Input/output safety check	The security guard at the door
Session	Memory that persists across turns	The patient's medical file

Multi-Agent Patterns

Pattern	How It Works	When to Use
Triage + Handoffs	Router agent delegates to specialist agents	User intent determines the handler
Manager + as_tool()	Orchestrator invokes sub-agents as tools	Coordinating multiple sub-tasks
Pipeline	Sequential handoffs through stages	Research → Analyze → Report

Key Parameters

Parameter	What It Does
model="gpt-4o"	Which LLM model to use
tools=[...]	List of tools the agent can call
handoffs=[...]	List of agents to hand off to
output_type=Model	Forces structured Pydantic output
input_guardrails=[...]	Safety checks on input
output_guardrails=[...]	Safety checks on output
model_settings=ModelSettings(...)	Temperature, tool_choice, etc.
handoff_description="..."	Hint for when other agents should hand off here

Runner Methods

Method	Use Case
await Runner.run(agent, input)	Async execution (production)
Runner.run_sync(agent, input)	Synchronous execution (notebooks/scripts)
Runner.run_streamed(agent, input)	Token-by-token streaming

Project Structure

openai-agents-sdk/
├── README.md                              ← You are here
├── .env                                   ← Your API keys (git-ignored)
├── .gitignore
├── requirements.txt
├── openai-agents-concepts-guide.md        ← Complete concepts reference
│
├── project-1-customer-support-triage/
│   ├── README.md                          ← What you'll learn
│   └── customer_support_triage.ipynb      ← Jupyter notebook
│
├── project-2-research-report-generator/
│   ├── README.md
│   └── research_report_generator.ipynb
│
├── project-3-content-pipeline/
│   ├── README.md
│   └── content_pipeline.ipynb
│
├── project-4-guardrailed-bot/
│   ├── README.md
│   └── guardrailed_bot.ipynb
│
├── project-5-study-buddy/
│   ├── README.md
│   └── study_buddy.ipynb
│
├── project-6-code-review-assistant/
│   ├── README.md
│   └── code_review_assistant.ipynb
│
└── project-7-full-agency/
    ├── README.md
    └── full_agency.ipynb

Environment Variables

All projects load API keys from a shared .env file in the root directory:

OPENAI_API_KEY=sk-your-openai-key-here

No API keys are hardcoded in any notebook.

Common Pitfalls

Problem	Cause	Fix
Agent loops forever	No max_turns set	Pass max_turns to Runner.run()
Handoff not triggered	Unclear instructions	Be explicit about when to hand off
Tool not called	Vague docstring	Write clear descriptions with arg docs
Guardrail not firing	Wrong agent	Input guardrails only run on first agent
Session not persisting	Mixing memory strategies	Pick ONE: sessions OR previous_response_id
Import error	Wrong package	Install openai-agents not openai

Additional Resources

• OpenAI Agents SDK Documentation
• OpenAI Agents SDK GitHub
• A Practical Guide to Building Agents (OpenAI)
• See openai-agents-concepts-guide.md for a complete concepts deep-dive