Overview and setup

In this workshop, you build a coding agent for a real project. It can 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. The base prompt stays small, while capabilities are added 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

Prepare these accounts and keys:

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

Install or confirm these 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 from the project folder:

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.