Overview and setup

This workshop is a notebook build. We are not deploying a web app here, and we are not turning the notebook into modules. We are using a small FAQ assistant because it gives us a concrete agent with tools, useful answers, and failure modes we can see in a few cells.

Guardrails in this workshop

A guardrail is a check around an agent run. The input version runs before the agent sees the user message. The output version runs after the agent answers, but before the response is shown to the user.

Input guardrail:  User -> check -> agent
Output guardrail: Agent -> check -> user

A helpful agent will often try to answer even when it should stop. A user can ask for cooking recipes instead of course questions. A user can ask the assistant to promise refunds or deadline extensions. A user can ask the assistant to write homework for them.

The guardrails in this workshop catch those cases in different places:

• Input guardrails block irrelevant or harmful input before the agent sees it.
• Output guardrails catch unsafe responses before the user sees them.
• Tool-based guardrails use a normal tool call when the framework does not have a first-class guardrail API.
• DIY async guardrails run alongside the agent and cancel it when a check fails.

The DIY async version is close to how framework guardrails work internally. The user does not need to wait for a topic check and then wait again for the agent. Both can run at the same time, and the agent can be cancelled if the check fails first.

Prerequisites

You can run the workshop on a laptop. You need:

• Python 3.10 or newer.
• An OpenAI API key.
• uv for the Python environment.
• Jupyter Notebook.
• Internet access, because docs.py downloads FAQ markdown from GitHub.

The workshop code runs with Python 3.13.5. The workshop asks for Python 3.10 or newer, so use any current Python version in that range.

We use the OpenAI Agents SDK because it already has input and output guardrail hooks. My usual preference is PydanticAI, but the OpenAI Agents SDK gives us the built-in guardrail API we need for the first half of this workshop. The second half rebuilds the idea with plain tools and asyncio.

The examples use gpt-4o-mini, and a full notebook run should cost below one cent. You still need an API key. If you want to use another OpenAI-compatible provider, configure the SDK base URL and API key for that provider.

Project setup

Install uv if you do not have it already:

pip install uv

Create a fresh folder and initialize the project:

mkdir guardrails-for-ai-agents
cd guardrails-for-ai-agents
uv init

Install the packages used in the notebook:

uv add jupyter openai openai-agents minsearch requests python-frontmatter

Add your OpenAI key to .env:

OPENAI_API_KEY='your-key'

Keep the key out of git:

echo .env >> .gitignore

This setup uses dirdotenv so the .env file becomes part of the terminal environment before Jupyter starts:

pip install dirdotenv
echo 'eval "$(dirdotenv hook bash)"' >> ~/.bashrc

Open a new terminal after changing .bashrc, then start Jupyter:

uv run jupyter notebook

Create notebook.ipynb. The cells use top-level await, so run them in Jupyter or another notebook environment that supports async cells.

Note: this notebook does not call python-dotenv. It expects the environment variable to be present before Jupyter starts. If you do not use dirdotenv, export OPENAI_API_KEY in your shell before running uv run jupyter notebook.

Continue with Part 1: Load FAQ documents to load the FAQ data and look at the helper that does it.