Environment setup

Before we can build the FAQ bot, we need a small Python project where the notebook can call the OpenAI API.

This workshop runs in Jupyter. We create a fresh Python project, install the packages, add the API key, and check that the OpenAI client works.

Prerequisites

Make sure you have these prerequisites:

• Python 3.10 or newer.
• An OpenAI API key, or an OpenAI-compatible provider.
• Basic command-line familiarity.

Create the project

You can run the workshop locally or in GitHub Codespaces. Codespaces is useful when you want a clean Linux environment with Python already installed.

To use Codespaces, create an empty GitHub repository for the workshop. Open the green Code menu and create a new codespace, then wait until the browser editor starts. You can keep working in the browser editor, or open the codespace in VS Code desktop for a more native editing experience.

In the terminal, check Python:

python --version

Codespaces usually ships a recent Python, and 3.12 works for this workshop.

If the terminal prompt takes too much horizontal space, shorten it:

PS1='> '

Now install uv if you don't have it yet:

pip install uv

Create a fresh project folder:

mkdir agent-with-guardrails
cd agent-with-guardrails
uv init

This creates pyproject.toml and the basic project files.

Install the packages we use in the notebook:

uv add requests minsearch openai jupyter python-dotenv pydantic

The packages have these roles:

• requests fetches the FAQ JSON.
• minsearch builds a small in-memory search index.
• openai calls the model through the Responses API.
• jupyter gives us the notebook environment.
• python-dotenv loads the API key from .env.
• pydantic defines structured guardrail decisions.

Set up the API key

Create an OpenAI API key for this workshop. A separate key is easier to delete after the workshop if it's exposed by mistake. If you use OpenAI projects, create the key inside a workshop project so usage is easy to track later.

Create a .env file in the project folder:

OPENAI_API_KEY=sk-YOUR_KEY_HERE

Now add .env to .gitignore:

.env

Never commit .env to git, and never share your API key.

Start Jupyter

Start Jupyter from the project folder:

uv run jupyter notebook

Create a new notebook file named agent-with-guardrails.ipynb.

If you use VS Code or Codespaces, VS Code may ask to install the Jupyter extension. Install it before continuing.

The first cell we'll create enables autoreload:

%load_ext autoreload
%autoreload 2

Later in the workshop, we'll create helper files such as agent.py and guardrails.py. When we change them, autoreload reloads them after each edit. You don't need to restart the kernel after editing these scripts.

Now load .env:

from dotenv import load_dotenv
load_dotenv()

If the notebook finds and loads .env, this cell returns True.

Now create the async OpenAI client:

from openai import AsyncOpenAI
openai_client = AsyncOpenAI()

We use the async client because later we'll have more than one model call waiting on the network. For example, a topic guardrail can check the question while the FAQ agent prepares an answer.

If the guardrail blocks the question, we can cancel the agent work. If it passes, we don't lose time waiting for the guardrail first. Jupyter lets us use await directly in notebook cells, so the async version stays simple.

Exercise

Check that the OpenAI client works. Ask the model for a short response with await openai_client.responses.create(...), then look at response.output_text.

Use these example prompts:

• Answer with exactly: ready.
• Reply with one short sentence about Docker.
• Reply with one short sentence about Data Engineering Zoomcamp.

response = await openai_client.responses.create(
    model="gpt-4o-mini",
    input="Answer with exactly: ready",
)

response.output_text

If response.output_text returns a short answer, the environment is ready. Continue with Load the FAQ and build search to load the FAQ data and build the search function.