A hands-on, teaching-by-doing path to mastering the OpenAI Agents SDK.
This repository documents my comprehensive learning journey through the OpenAI Agents SDK, following a hands-on, teaching-by-doing approach. As I master each concept, I create my own explanations, examples, and projects to solidify understanding and help fellow learners.
"The best way to learn is to teach." — Richard Feynman
I believe in learning through active creation and explanation. This repo captures not just what I've learned, but how I learned it — including challenges, breakthroughs, and real applications.
This journey is inspired by @mjunaidca's agents-sdk-decoded — a brilliant expert-level educational resource.
- 📝 Personal explanations in my own words
- 🎯 Focused on practical understanding
- 🚀 Live examples built step-by-step
- 📊 Documenting the learning process
- 💡 Beginner-friendly + real-world mindset
By the end of this journey, I aim to:
- ✅ Master the OpenAI Agents SDK from fundamentals to advanced patterns
- ✅ Build production-ready agentic applications
- ✅ Understand the DACA framework for scalable systems
- ✅ Create developer-friendly documentation
- ✅ Help others learn agentic AI — one concept at a time
.
├── 📁 modules/
│ ├── 📁 01_agents/
│ ├── 📁 02_runner/
│ ├── 📁 03_results/
│ ├── 📁 04_stream/
│ ├── 📁 05_tools/
│ ├── 📁 06_handoffs/ # NEW: Advanced handoff, input filtering, callbacks, prompt engineering
│ ├── 📁 07_lifecycle/ # NEW: Agent lifecycle hooks, monitoring, analytics
│ ├── 📁 08_exceptions/ # In Progress: Exception handling, error flows
│ ├── 📁 09_guardrails/ # In Progress: Guardrails, input validation, safety
│ ├── 📁 10_multiple_agents.py/ # NEW: Multi-agent orchestration, hybrid orchestration
│ ├── 📁 11_configuration_visualizations/ # NEW: Configuration visualization
│ └── 📁 projects/
│ ├── 📁 01_fantasy_world_generator/
│ ├── 📁 02_university_helpdesk_orchestration/ # NEW: Advanced multi-agent orchestration project
│ └── 📄 README.md
├── 🚫 .gitignore
├── 📄 .python-version
├── 🐍 main.py
├── 📋 pyproject.toml
├── 📖 README.md
├── 🔒 uv.lock
├── 📄 .env.example
├── 📄 LICENSE
Note: Each module and project contains its own README for detailed explanations, code summaries, and learning notes.
| Module/Section | Status |
|---|---|
| 🚀 01_agents | ✅ Completed Core agent patterns, context, instructions, structured outputs, advanced orchestration, tool behavior control, agent handoffs |
| ⚡ 02_runner | ✅ Completed Agent execution, RunResult exploration, execution lifecycle, synchronous execution, streaming patterns, real-time event processing, advanced context, handoffs, chat, exceptions |
| 📊 03_results | ✅ Completed RunResult basics, results handling, and multi-turn conversation management |
| 📡 04_stream | ✅ Completed Advanced streaming patterns, real-time events, token-by-token streaming, run item events, and streaming with agent handoffs |
| 🔧 05_tools | ✅ Completed Function tools, custom configurations, agents as tools, error handling, context-aware tools, advanced tool choice patterns |
| 🤝 06_handoffs | ✅ Completed Advanced handoff orchestration, input filtering, callbacks, structured handoff data, prompt engineering |
| 🔄 07_lifecycle | ✅ Completed Agent lifecycle hooks, monitoring, analytics, session management, performance tracking |
| 🚨 08_exceptions | 🚧 In Progress Exception handling, error flows, advanced error management |
| 🛡️ 09_guardrails | 🚧 In Progress Guardrails, input validation, safety, compliance |
| 🤖 10_multiple_agents.py | 🚀 Started Multi-agent orchestration, LLM/code/hybrid orchestration |
| 📊 11_configuration_visualizations | 🚀 Started Configuration visualization |
| 🧩 Projects | 🚀 Started: Real-world agentic applications and showcases |
| ... | ... |
The modules/projects/ folder contains real-world, showcase projects that demonstrate advanced agentic workflows, tool integrations, and creative applications using the OpenAI Agents SDK.
- Fantasy World Generator: An interactive multi-agent system that builds a fantasy world, including magic systems, maps, lore, and magical creatures. Demonstrates agent orchestration, agents-as-tools, streaming, and creative AI workflows.
- University Smart Helpdesk Orchestrator: A real-world multi-agent system simulating a university helpdesk. Features advanced orchestration, context-aware routing, escalation handling, streaming UX, and smart agent handoffs. Demonstrates context models, escalation logic, and real-time agent transitions.
See each project's README for setup and usage instructions.
- Agent Handoffs & Input Filtering: See
modules/06_handoffs/for advanced handoff orchestration, input filtering, callbacks, and prompt engineering. - Agent Lifecycle Hooks & Monitoring: See
modules/07_lifecycle/for RunHooks, AgentHooks, session management, and analytics. - Guardrails & Exception Handling: See
modules/08_exceptions/andmodules/09_guardrails/for in-progress work on error management and safety. - University Helpdesk Orchestration Project: See
modules/projects/02_university_helpdesk_orchestration/for advanced multi-agent orchestration, escalation, and context-aware routing. - All previous advanced streaming, tool integration, and orchestration features remain available in their respective modules.
- Multi-Agent Orchestration: See
modules/10_multiple_agents.py/for LLM-orchestrated, code-orchestrated, and hybrid agent orchestration patterns. - Configuration Visualization: See
modules/11_configuration_visualizations/for configuration visualization tools and examples.
- Python (version specified in
.python-version) - uv package manager installed
.envfile with OpenAI/Gemini/OpenRouter API keys
# Clone the repository
git clone https://github.com/ZohaibCodez/agents-sdk-from-zero.git
cd agents-sdk-from-zero
# Initialize environment
uv venv
.venv\Scripts\activate # For Windows
# or
source .venv/bin/activate # For macOS/Linux
# Install dependencies
uv sync
# Copy environment variables
cp .env.example .env # Then add your API key inside- Python version: Managed by
.python-version - Dependency manager:
uv(uv add,uv sync) - Virtual environment:
.venv/ - API secrets: Stored in
.envfile
- Understand – Study SDK internals and examples
- Apply – Build simplified working demos
- Explain – Write markdown explanations and insights
- Extend – Build real tools and integrations
- Repeat – Keep iterating and improving
This is a personal learning repo, but:
- 💬 Ask questions via GitHub Issues
- ✍️ Suggest improvements if you spot unclear parts
- 🌟 Star the repo if it helps — it motivates me to keep going!
🎯 Final Goal:
Master the OpenAI Agents SDK from foundation to production-ready apps.
📚 Philosophy:
Learn deeply. Build consistently. Teach simply.
- 📢 Follow this repo for updates
- 🤝 Let's build the Agentic future, one concept at a time
📚 Learning Never Stops – This repository is a living record of my OpenAI Agents SDK mastery. Join me on the journey!
Last Updated: 2025-07-28