Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/temporalio/edu-ai-workshop-openai-agents-sdk


https://github.com/temporalio/edu-ai-workshop-openai-agents-sdk

Last synced: about 2 months ago
JSON representation

Awesome Lists containing this project

README 

          



![Workshop Hero Banner](images/hero-banner.svg)






---



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.



## What You'll Build






### Master Durable AI Agents






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!



## Prerequisites






**What You Need to Bring**






- **Basic Python knowledge** - If you can write a function, you're ready!

- **OpenAI API key** - [Get one here](https://platform.openai.com/api-keys) (free tier works!)

- **GitHub account** - For Codespaces 



> **Cost Note**: The workshop uses ~$0.50-$1.00 of OpenAI API credits. Free tier is plenty!



## Quick Start






### Ready, Set, Code!



*Get started in minutes!*






### GitHub Codespaces (Recommended)



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:

   
    

       
  • Open temporal_installation.ipynb in VS Code
    • 

       
  • Run each cell to:

         
      

             
    • Install the Temporal CLI
      • 

             
    • Start the Temporal dev server
      • 

           
    

       
    • 

       
  • 

    Verify In Codespaces: Go to the Ports tab at the bottom of VS Code → Find port 8233 → Click the Globe icon to open the Temporal Web UI
    • 

       



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.ipynb` notebook for Temporal setup. This ensures a consistent, reliable experience across all environments!



## Workshop Structure






### 90 Minutes to Mastery



*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.



### Repository Navigation



```

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!

```



## Workshop Exercises






### Your Learning Journey



*From zero to hero in four exercises!*






**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.



---



### Exercise 1: Agent Hello World






**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](solutions/01_agent_hello_world/solution.ipynb)** | **[Homework: Build Your Own](exercises/01_agent_hello_world/exercise.ipynb)**



> **Challenge**: Can your agent handle weather queries for multiple cities at once?



---



### Exercise 2: Temporal Hello World






**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](solutions/02_temporal_hello_world/solution.ipynb)** | **[Homework: Build Your Own](exercises/02_temporal_hello_world/exercise.ipynb)**



> **Pro Tip**: The Temporal UI is your best friend for debugging—explore it thoroughly!



---



### Exercise 3: Durable Agent






**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](solutions/03_durable_agent/solution.ipynb)** | **[Homework: Build Your Own](exercises/03_durable_agent/exercise.ipynb)**



> **Mind Blown Moment**: Your agent code doesn't change—Temporal just wraps it with superpowers!



---



### Exercise 4: Routing Workflow






**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](solutions/04_agent_routing/)** | **[Homework: Build Your Own](exercises/04_agent_routing/)**



> **Next Level**: This is how real production systems are structured!



## Common Commands






### Your Command Toolbox



*Everything you need, one command away!*






```bash

# 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 setup` first thing, every time!



## Key Concepts






### The "Aha!" Moments



*Understanding the magic behind durable agents*






### Why Temporal for AI Agents?



**The Problem**



AI agents in production face several challenges:



1. **API Failures**: LLM APIs can be rate-limited or temporarily unavailable

2. **Crashes**: Your agent process might crash mid-execution

3. **Long-Running Ops**: Multi-step agent flows need to resume from checkpoints

4. **Observability**: You need to debug what your agent actually did



**The Solution**



Temporal solves these by providing:



- **Automatic retries** with configurable policies

- **State persistence** across failures and restarts

- **Execution history** for debugging and auditing

- **Durable execution** that survives crashes



> **Think of Temporal as**: A time machine + a guardian angel for your code!



### Architecture Pattern



```

       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!



## Troubleshooting






### Common Issues & Quick Fixes



*Don't panic—we've got you covered!*






---



### Environment Issues



Problem: OPENAI_API_KEY not found



```bash

# Check your .env file exists

ls -la .env



# Verify the key is set

python scripts/check_env.py

# Or run: make env

```



**Fix:** If `.env` doesn't exist, create it from `.env.sample` (`cp .env.sample .env`), then add your API key



> **Tip**: Don't commit your `.env` file! It's in `.gitignore` for a reason.



---



Problem: Temporal server not running



```bash

# Check if it's running

pgrep -f temporal

```



**Fix:** Use the `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 the dev server

3. **Verify In Codespaces:** Go to the **Ports** tab → Find port **8233** → Click the **Globe icon**



⚠️ The Temporal dev server must be running for exercises 2, 3, and 4! ⚡



---



### Exercise Issues



Problem: Import errors when running exercises



```bash

# Reinstall dependencies

make setup

# Or: pip install -e ".[dev]"

```



> **Tip**: Run `make setup` whenever you pull new changes!



---



Problem: Notebook kernel not found



```bash

# Install ipykernel

pip install ipykernel

python -m ipykernel install --user --name temporal-workshop

```



Then 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:

1. Go to the **Ports** tab at the bottom of VS Code

2. Find port **8233** 

3. Click the **Globe icon** to open the Temporal Web UI in your browser

4. 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"



```bash

# 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!



## Additional Resources






### Continue Your Learning Journey



*Bookmark these for later!*






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**: 

> 1. Explore the [Temporal Samples repository](https://github.com/temporalio/samples-python)

> 2. Join the [Temporal Slack community](https://temporal.io/slack)

> 3. Build something awesome and share it!



## Instructor Notes






### For Workshop Leaders



*Tips from the trenches!*






### Timing Breakdown



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



### Common Pitfalls



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.ipynb` notebook 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 in `exercises/` 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_timeout` defaults

- 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 through `solutions/` 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



### Key Teaching Points



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.



## License



MIT License - feel free to use this workshop material for educational purposes!



## Contributing



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!



---






### **Happy Coding!**



**Build amazing durable AI agents!**



---



Made with love by the Temporal Community



[Star us on GitHub](https://github.com/temporal-community/edu-ai-workshop-openai-agents-sdk) | [Follow Temporal](https://twitter.com/temporalio) | [Join Slack](https://temporal.io/slack)



---



### Ready to get started? Scroll back to [Quick Start](#-quick-start)!