Overview and setup

This workshop builds a coding agent that can inspect a real project, read and write files, run shell commands, and load reusable skill instructions. We start from plain OpenAI tool calls and end with the same agent running on PydanticAI.

The app you will build

The agent has five core tools:

• read_file - read a file's contents
• write_file - write or create a file
• see_file_tree - list the project directory tree
• execute_bash_command - run a shell command inside the project
• search_in_files - grep across project files

Plus a skills system that lets the agent load SKILL.md instruction files on demand, keeping the base prompt small while adding capabilities when needed.

The workshop has four parts:

• Part 1 - Tool calls intro. Understand the tool-call loop with the OpenAI Responses API.
• Part 2 - The coding agent. Use the ToyAIKit framework, group tools into a class, and run the agent against a Django project template.
• Part 3 - Skills. Add a skill loader that reads SKILL.md files and exposes them as a tool the agent can call.
• Part 4 - PydanticAI. Port the same agent to PydanticAI with message history and usage tracking.

Prerequisites

Accounts and keys:

• OpenAI API key
• Groq API key (optional - the workshop uses OpenAI, but Groq works with the same SDK)
• GitHub account

Local tools:

• Python 3.10+
• uv for package management

Environment setup

You can use GitHub Codespaces or a local environment. For Codespaces, create an empty repo, open a codespace on it, and add your OPENAI_API_KEY as a Codespaces secret. The rest of the workshop works the same either way.

Initialize the project and install dependencies:

pip install uv
uv init
uv add jupyter openai

Start Jupyter:

uv run jupyter notebook

All Python snippets in this workshop are meant to run inside the notebook. If you prefer the terminal, use uv run python instead.

OpenAI client setup

We use these two variables throughout the workshop:

from openai import OpenAI

openai_client = OpenAI()
model = 'gpt-5.4-mini'

Optional: Groq with the OpenAI SDK

If you want to use Groq instead, keep the same variable names and swap the client:

from openai import OpenAI
import os

openai_client = OpenAI(
    api_key=os.getenv('GROQ_API_KEY'),
    base_url='https://api.groq.com/openai/v1'
)
model = 'openai/gpt-oss-120b'

Use OpenAI if you want to reproduce the full workshop exactly as shown.

Continue with Part 1: Tool calls intro to start building the tool-call loop.