Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/temporalio/edu-ai-workshop-openai-agents-sdk/llms.txt

Use this file to discover all available pages before exploring further.

This page maps out the full layout of the temporal-openai-agents-sdk repository so you know exactly where to find workshop materials, starter code, helper scripts, and configuration files. Whether you’re running the Temporal + OpenAI Agents SDK workshop or doing homework exercises afterwards, understanding the project structure will save you time.

​
Directory Tree

temporal-openai-agents-sdk/
├── solutions/                          # Complete workshop implementations
│   ├── 01_agent_hello_world/           # Exercise 1 (solution.ipynb)
│   ├── 02_temporal_hello_world/        # Exercise 2 (solution.ipynb)
│   ├── 03_durable_agent/               # Exercise 3 (solution.ipynb)
│   └── 04_agent_routing/               # Exercise 4 (.py files)
├── exercises/                          # Homework starter code
│   ├── 01_agent_hello_world/           # Exercise 1 starter (exercise.ipynb)
│   ├── 02_temporal_hello_world/        # Exercise 2 starter (exercise.ipynb)
│   ├── 03_durable_agent/               # Exercise 3 starter (exercise.ipynb)
│   └── 04_agent_routing/               # Exercise 4 starter (.py files)
├── scripts/                            # Helper scripts
│   ├── bootstrap.sh                    # Dev container post-create hook
│   ├── run_temporal.sh                 # Idempotent Temporal server starter
│   ├── check_env.py                    # API key validation
│   └── apply_notebook_metadata.py      # Notebook metadata helper
├── .devcontainer/
│   └── devcontainer.json               # GitHub Codespaces configuration
├── .github/
│   └── workflows/
│       └── ci.yml                      # CI pipeline
├── temporal_installation.ipynb         # Temporal CLI install notebook
├── pyproject.toml                      # Python project + dependencies
├── Makefile                            # Common commands
├── .env.sample                         # Environment variable template
├── README.md                           # Project overview and quickstart
├── WORKSHOP_SPEC.md                    # Workshop specification
└── CLAUDE.md                           # Claude AI assistant context

​
solutions/ vs exercises/

The repository contains two parallel directory trees — solutions/ and exercises/ — that mirror each other exercise-for-exercise. During the workshop you work inside solutions/. Every notebook and Python file there is a fully working, production-quality implementation. Run the code, read the output, and understand how everything fits together before writing a line yourself. After the workshop you practice independently inside exercises/. Each exercise provides starter code with # TODO markers to guide you. When you get stuck or want to verify your work, look at the matching file in solutions/.
The solutions/ directory is the source of truth for the workshop. Never delete or overwrite files there — keep them as your reference implementation.

​
Exercise Format: Notebooks vs Python Files

Exercises 1–3 use Jupyter notebooks (.ipynb) opened directly in VS Code. Notebooks let you run individual cells interactively, which is ideal for learning Temporal concepts step by step. Exercise 4 deliberately uses separate Python files (workflow.py, worker.py, starter.py) instead of a notebook. This mirrors how real production Temporal applications are structured — the worker process runs continuously in one terminal while the starter script submits workflow executions from another. The separation enables independent deployment and horizontal scaling of workers, patterns that don’t translate naturally to a notebook environment. 
exercises/04_agent_routing/
├── workflow.py      # Workflow definition and agent configurations
├── worker.py        # Worker process that polls the task queue
├── starter.py       # Script that submits workflow executions
├── requirements.txt # Dependencies
└── README.md        # Exercise instructions

​
scripts/ — Helper Scripts

​
bootstrap.sh

bootstrap.sh is the postCreateCommand for the GitHub Codespaces dev container. It runs automatically when the Codespace finishes provisioning and performs three steps:
  1. Installs all Python dependencies in editable mode: pip install -e ".[dev]" --quiet
  2. Installs the Temporal CLI if it isn’t already present, downloads it via the official install script, and adds $HOME/.temporalio/bin to PATH in ~/.bashrc
  3. Copies .env.sample to .env (only if .env doesn’t already exist) and prints a reminder to add your OPENAI_API_KEY
After bootstrap completes, the environment check script runs automatically to validate the key.

​
run_temporal.sh

This script starts the Temporal development server idempotently. It first checks whether a temporal server start-dev process is already running via pgrep; if so it exits immediately rather than spawning a duplicate. Otherwise it starts the server with a persistent database file at ~/.temporal/default.db, waits three seconds to confirm the process is alive, then blocks the terminal while the server runs. Press Ctrl+C to stop it.
  • gRPC endpoint: localhost:7233
  • Web UI: localhost:8233
The recommended way to install and start Temporal is via the temporal_installation.ipynb notebook. Open it in VS Code, run each cell, then verify the server is up by checking the Ports tab for port 8233.

​
check_env.py

A standalone validation script that loads .env via python-dotenv, checks that OPENAI_API_KEY is present and non-empty, and exits with a non-zero status code if anything is wrong. Run it manually with python scripts/check_env.py or via make env. The output shows the first eight and last four characters of the key so you can confirm you’ve set the right one without exposing the full secret.

​
.devcontainer/ — GitHub Codespaces Configuration

The devcontainer.json file configures a Python 3.11 container image (mcr.microsoft.com/devcontainers/python:3.11) with the following VS Code extensions pre-installed:
  • ms-python.python — Python language support
  • ms-python.vscode-pylance — fast type-checking and IntelliSense
  • charliermarsh.ruff — linting and formatting (configured as the default formatter with format-on-save)
  • ms-toolsai.jupyter — Jupyter notebook support
Two ports are forwarded automatically:
PortLabelBehavior
7233Temporal ServerForwarded silently (ignore)
8233Temporal UIForwarded with a notification (notify)
The postCreateCommand is set to bash scripts/bootstrap.sh, so the entire environment — dependencies, Temporal CLI, and .env file — is ready without any manual steps after the Codespace starts.

​
Python Project (pyproject.toml)

The project is packaged as temporal-ai-agents-workshop (version 1.0.0) and requires Python ≥ 3.11. Core runtime dependencies include:
  • openai>=1.54.0 and openai-agents>=0.3.3 — OpenAI client and Agents SDK
  • temporalio>=1.7.0 — Temporal Python SDK
  • jupyter>=1.0.0, ipykernel>=6.29.0, notebook>=7.0.0 — notebook runtime
  • nest-asyncio>=1.6.0 — allows nested event loops inside Jupyter
  • python-dotenv>=1.0.0 — .env file loading
  • rich>=13.7.0 — formatted terminal output
The [dev] optional group adds pytest>=8.0.0, pytest-asyncio>=0.23.0, ruff>=0.6.0, and mypy>=1.11.0.

​
Workshop Exercise Pages

Exercise 1: Agent Hello World

Build your first OpenAI agent with tool calling and real weather data from the National Weather Service.

Exercise 2: Temporal Hello World

Create your first Temporal workflow, explore the UI, and experience automatic retries firsthand.

Exercise 3: Durable Agent

Wrap LLM calls in Temporal activities to get automatic retries, state persistence, and full observability.

Exercise 4: Routing Workflow

Build a multi-agent routing system with French, Spanish, and English specialist agents using production Python files.

Build docs developers (and LLMs) love

Get started for freeTalk to us