Learn to build durable AI agents using OpenAI Agents SDK + Temporal in this hands-on 90-minute workshop. Everything runs in GitHub Codespaces with zero local setup required.
By the end of this workshop, you'll understand how to:
- Create AI agents with tool calling using OpenAI's Agents SDK
- Build durable workflows with Temporal for reliability and retries
- Combine both to create production-ready AI agents that survive failures
- Implement multi-agent systems with handoff patterns
- Observe and debug agent execution using Temporal UI
Pro Tip: These aren't just toy examples—you'll learn production patterns used by real companies!
What You Need to Bring
- Basic Python knowledge - If you can write a function, you're ready!
- OpenAI API key - Get one here (free tier works!)
- GitHub account - For Codespaces
Cost Note: The workshop uses ~$0.50-$1.00 of OpenAI API credits. Free tier is plenty!
| 1. | Open in GitHub Codespaces |
| 2. | Wait 2-3 minutes for the environment to set up |
| 3. | Add your OpenAI API key to .env:
# The .env file is already created during setup # Edit .env and add your OPENAI_API_KEY |
| 4. | Install and start Temporal server using the notebook:
|
| 5. | You're ready to start the workshop!
Workshop Flow: During the session, you'll explore and run the complete implementations in solutions/. After the workshop, practice building everything yourself using exercises/ as homework! Make your changes to the code in the exercises/ subdirectories. If you need a hint or want to verify your changes, look at the complete version in the corresponding solutions/ subdirectory.
|
Note: All workshop instructions use the
temporal_installation.ipynbnotebook for Temporal setup. This ensures a consistent, reliable experience across all environments!
30 min instruction + 4×15 min hands-on exercises
Progress Bar: [░░░░░░░░░░] 0% → [██████████] 100%
Exercises 1-3 are Jupyter notebooks for interactive learning.
Exercise 4 uses separate Python files to demonstrate production-ready Temporal applications!
During the workshop: You'll explore and run the complete implementations in the solutions/ directory. These are fully working examples that demonstrate production patterns. Learn by running the code, seeing the output, and understanding how everything works together.
After the workshop: Practice building everything from scratch using the exercises/ directory as optional homework! The exercises provide starter code with TODO markers to guide you.
temporal-openai-agents-sdk/
├── solutions/ # Work here during the workshop
│ ├── 01_agent_hello_world/ # Workshop Exercise 1 - OpenAI agent basics (.ipynb)
│ ├── 02_temporal_hello_world/ # Workshop Exercise 2 - Temporal fundamentals (.ipynb)
│ ├── 03_durable_agent/ # Workshop Exercise 3 - Combine both! (.ipynb)
│ └── 04_agent_routing/ # Workshop Exercise 4 - Routing workflow (.py files)
│
├── exercises/ # Extra homework exercises (optional)
│ ├── 01_agent_hello_world/ # Homework: Build your own agent (.ipynb)
│ ├── 02_temporal_hello_world/ # Homework: Practice workflows (.ipynb)
│ ├── 03_durable_agent/ # Homework: Create durable agent (.ipynb)
│ └── 04_agent_routing/ # Homework: Implement routing (.py files)
│
├── scripts/ # Helper scripts (bootstrap, env checks)
├── Makefile # Common commands (setup, lint, test)
├── WORKSHOP_SPEC.md # Workshop design specification
└── README.md # You are here!
During the workshop, you'll explore and run the complete implementations in the solutions/ directory. These are fully working examples that you'll execute, observe, and learn from—see how production-ready AI agents work in practice.
After the workshop, you can practice building them yourself using the exercises/ directory as homework! Make your changes to the code in the exercises/ subdirectories. If you need a hint or want to verify your changes, look at the complete version in the corresponding solutions/ subdirectory.
Your First AI Agent
Build it, run it, watch it think!
Goal: Create a simple AI agent with tool calling using real weather data
What you'll learn:
- Build your first OpenAI agent with a weather tool
- Understand the agent → tool → response flow
- See how LLMs decide when to use tools
- Call real APIs (National Weather Service)
Time: 15 minutes
Workshop Notebook | Homework: Build Your Own
Challenge: Can your agent handle weather queries for multiple cities at once?
Meet Your Reliability Superhero
Workflows that never give up!
Goal: Understand Temporal workflows and activities
What you'll learn:
- Create your first Temporal workflow
- Learn about activities as units of work
- Observe execution in the Temporal UI
- Experience automatic retries
Time: 15 minutes
Workshop Notebook | Homework: Build Your Own
Pro Tip: The Temporal UI is your best friend for debugging—explore it thoroughly!
THE KEY ACTIVITY
Where AI meets unbreakable reliability!
Goal: Combine agents + Temporal for production durability
What you'll learn:
- Wrap LLM calls in Temporal activities
- Get automatic retries on failures
- Persist agent state across crashes
- Add observability with trace IDs
- Build production-ready AI agents
🎯 This is the KEY exercise! Everything comes together here!
Time: 15 minutes
Workshop Notebook | Homework: Build Your Own
Mind Blown Moment: Your agent code doesn't change—Temporal just wraps it with superpowers!
Build a Polyglot Agent Team
French, Spanish, English—your agents speak them all!
Goal: Build a routing workflow with language-specific agents using production-ready file structure
What you'll learn:
- Implement agent routing/triage patterns with OpenAI Agents SDK
- Create specialized language agents (French, Spanish, English)
- Use handoff patterns for agent-to-agent transitions
- Structure real Temporal applications (workflow, worker, starter files)
- Run production-style workflows with separate worker processes
Time: 15 minutes
Workshop Files | Homework: Build Your Own
Next Level: This is how real production systems are structured!
# Setup and validation
make setup # Install all dependencies
make env # Check environment variables (OPENAI_API_KEY)
# Code quality
make lint # Run code linters (ruff, mypy)
make test # Run test suite (mocked - no API key needed!)
# Temporal server
# Use temporal_installation.ipynb notebook to install and start Temporal:
# 1. Open temporal_installation.ipynb in VS Code
# 2. Run each cell to install Temporal CLI and start dev server
# 3. Verify In Codespaces: Go to the **Ports** tab → Find port **8233** → Click the **Globe icon**
# Working with the workshop
# During the workshop, work through solutions/ notebooks:
# solutions/01_agent_hello_world/solution.ipynb
# solutions/02_temporal_hello_world/solution.ipynb
# solutions/03_durable_agent/solution.ipynb
#
# Exercise 4 uses separate Python files (production pattern):
# cd solutions/04_agent_routing
# python worker.py # Terminal 1
# python starter.py # Terminal 2
#
# After the workshop, practice building your own in exercises/:
# exercises/01_agent_hello_world/exercise.ipynb
# exercises/02_temporal_hello_world/exercise.ipynb
# exercises/03_durable_agent/exercise.ipynb
# exercises/04_agent_routing/ # Python files (workflow.py, worker.py, starter.py)Pro Tip: Run
make setupfirst thing, every time!
|
The Problem |
AI agents in production face several challenges:
|
|
The Solution |
Temporal solves these by providing:
|
Think of Temporal as: A time machine + a guardian angel for your code!
User Query
↓
┌───────────────────────────┐
│ Temporal Workflow │ Orchestration Layer
│ (orchestration layer) │ (Your AI's brain)
└───────────────────────────┘
↓
┌───────────────────────────┐
│ Activity: Call LLM │ AI Decision Making
│ with tools │
└───────────────────────────┘
↓
[If tool needed]
↓
┌───────────────────────────┐
│ Activity: Execute tool │ Take Action
└───────────────────────────┘
↓
┌───────────────────────────┐
│ Activity: Get final │ Final Response
│ LLM response │
└───────────────────────────┘
↓
Return to user
The Magic: Each activity can retry independently, and the entire flow is durable!
Key Insight: Your AI agent becomes unstoppable—it will complete its task even if the server crashes!
Problem: OPENAI_API_KEY not found
# Check your .env file exists
ls -la .env
# Verify the key is set
python scripts/check_env.py
# Or run: make envFix: If .env doesn't exist, create it from .env.sample (cp .env.sample .env), then add your API key
Tip: Don't commit your
.envfile! It's in.gitignorefor a reason.
Problem: Temporal server not running
# Check if it's running
pgrep -f temporalFix: Use the temporal_installation.ipynb notebook to install and start Temporal:
- Open
temporal_installation.ipynbin VS Code - Run each cell to install Temporal CLI and start the dev server
- Verify In Codespaces: Go to the Ports tab → Find port 8233 → Click the Globe icon
Problem: Import errors when running exercises
# Reinstall dependencies
make setup
# Or: pip install -e ".[dev]"Tip: Run
make setupwhenever you pull new changes!
Problem: Notebook kernel not found
# Install ipykernel
pip install ipykernel
python -m ipykernel install --user --name temporal-workshopThen select the temporal-workshop kernel in your notebook!
Problem: Can't access Temporal UI at localhost:8233
In Codespaces: The port should be automatically forwarded. To access it:
- Go to the Ports tab at the bottom of VS Code
- Find port 8233
- Click the Globe icon to open the Temporal Web UI in your browser
- Make sure the port visibility is set to Public if you need to share it
✅ Solution: Make sure Temporal server is running using temporal_installation.ipynb and follow the Codespaces instructions above.
Problem: Tests fail with "module not found"
# Make sure you're in the project root and have installed in editable mode
cd /path/to/temporal-openai-agents-sdk
pip install -e ".[dev]"Still stuck? Open an issue on GitHub! We're here to help!
| Temporal Documentation - Your complete guide to Temporal | |
| OpenAI API Reference - Everything OpenAI | |
| OpenAI Agents SDK - Deep dive into function calling | |
| Temporal Python SDK - Python-specific docs | |
| Workshop Slides - Slide deck from the workshop |
Recommended Next Steps:
- Explore the Temporal Samples repository
- Join the Temporal Slack community
- Build something awesome and share it!
| 00:00-05:00 | Introduction & Setup verification |
| 05:00-15:00 | OpenAI Agents SDK Introduction (slides) |
| 15:00-30:00 | Walk through Exercise 1 solution notebook together + Q&A |
| 30:00-35:00 | Discussion & key takeaways from Exercise 1 |
| 35:00-40:00 | Intro to Temporal (slides) |
| 40:00-55:00 | Walk through Exercise 2 solution notebook together + Q&A |
| 55:00-60:00 | Discussion & key takeaways from Exercise 2 |
| 60:00-65:00 | OpenAI Agents SDK + Temporal (slides) |
| 65:00-80:00 | Walk through Exercise 3 solution notebook (THE KEY EXERCISE!) |
| 80:00-90:00 | 🎉 Demo Exercise 4 (production patterns) + Wrap-up |
1. Students skip checking .env
- Do environment check before starting (
make env) - Emphasize that exercises 1, 3, 4 need API key
- Have backup keys ready for those who forget
2. Temporal not running
- Remind students to use
temporal_installation.ipynbnotebook to install and start Temporal - Walk through opening the notebook and running each cell
- Show them how to verify In Codespaces: Go to the Ports tab → Find port 8233 → Click the Globe icon
- Verify EARLY before Exercise 2!
3. Confusion between workshop and homework
- Clearly explain: work through
solutions/during the workshop, practice building your own inexercises/afterward - Solution notebooks are complete implementations to learn from during the workshop
- Exercises are for independent practice after the workshop (optional homework)
4. Temporal Activity timeouts
- Explain
start_to_close_timeoutdefaults - Show how to adjust for longer-running operations
- Common when students use GPT-4 vs GPT-4-mini
5. Notebook vs Python files
- Exercises 1-3 are Jupyter notebooks (
.ipynb) - work throughsolutions/during workshop - Exercise 4 uses separate Python files (workflow.py, worker.py, starter.py)
- Emphasize Exercise 4 demonstrates production application structure
- After workshop, students can practice building their own using
exercises/directory
Exercise 1: Agent Foundations 🤖
- Walk through the complete solution notebook together
- Emphasize tool calling as the foundation of agentic behavior
- Show how the agent decides to use tools
- Highlight the real API integration (National Weather Service)
- Demo tip: Try queries that do and don't need tools
Exercise 2: Temporal Magic 🌊
- Walk through the solution notebook as a group
- Show the Temporal UI extensively - it's powerful for debugging
- Walk through execution history
- Demonstrate the retry mechanism
- Demo tip: Kill the worker mid-execution and restart it!
Exercise 3: THE KEY MOMENT
- Guide students through the solution notebook
- Show how activities make LLM calls durable
- The agent code doesn't change - Temporal wraps it!
- Emphasize: production-ready with zero agent modifications
- Demo tip: Show the Temporal UI and OpenAI trace correlation
Exercise 4: Production Patterns 🔀
- Walk through the production file structure together
- Language-based routing pattern (French/Spanish/English agents)
- Handoff pattern enables agent-to-agent transitions
- Demonstrates real Temporal application structure (separate worker/starter)
- Show how to run with two terminals (worker + starter)
- Demo tip: Show language detection in real-time
Golden Rule: Keep energy high! These concepts are powerful and fun—your enthusiasm is contagious.
MIT License - feel free to use this workshop material for educational purposes!
Found a bug or have a suggestion? Please open an issue or submit a pull request! We welcome contributions to make this workshop even better!
Build amazing durable AI agents!
Made with love by the Temporal Community
Star us on GitHub | Follow Temporal | Join Slack