LLM Agents Workshop

A hands-on workshop demonstrating LLM agent patterns using OpenAI's Responses API.

Demos

Demo	Description	Tools
Demo 1	Structured JSON Output	Schema validation
Demo 2	Web Search	web_search (OpenAI built-in)
Demo 3	Multi-Tool Agent	web_search + calculator + write_html_report

Quick Start

# Clone and setup
git clone https://github.com/omarzanji/llm-agents-workshop.git
cd llm-agents-workshop
pyenv local 3.11.0
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Configure API key
cp .env.example .env
# Edit .env with your OPENAI_API_KEY

# Run demos
just demo1
just demo2
just demo3

Prerequisites

• pyenv for Python version management
• OpenAI API key
• Just command runner (optional)

Running Demos

# Using Just (recommended)
just demo1          # Structured JSON output
just demo2          # Web search tool
just demo3          # Multiple tools

# Using Python directly
python main.py 1
python main.py 2
python main.py 3
python main.py --list   # List all demos

Example Output

Demo 3: Multi-Tool Agent

USER → Look up Tokyo's population. Calculate 15% of it. 
       Write results to an HTML report.

▶ LLM requests 2 tool(s)
  ↳ web_search(query='current population of Tokyo')
  ↳ calculator(operation='multiply', operand1=14094034, operand2=0.15)
  ✓ {"success": true, "result": 2114105.1}
▶ LLM requests 1 tool(s)
  ↳ write_html_report(title='Population Report', ...)
  ✓ {"success": true, "filepath": "outputs/html_reports/..."}
▶ LLM responds

LLM → Tokyo's population is ~14 million. 15% is 2,114,105.
      I've saved the results to an HTML report.

Project Structure

llm-agents-workshop/
├── main.py                 # Entry point
├── demos/
│   ├── demo1.py           # Structured JSON
│   ├── demo2.py           # Web search
│   └── demo3.py           # Multi-tool agent
├── modules/
│   ├── llm.py             # LLM client (Responses API)
│   ├── tools.py           # Tool schemas
│   ├── handlers.py        # Tool implementations
│   ├── colors.py          # Terminal colors
│   └── demo_logger.py     # Output logging
├── docs/                   # Documentation
│   ├── README.md
│   ├── demo1.md
│   ├── demo2.md
│   ├── demo3.md
│   └── architecture.md
├── slideshow/              # Workshop presentation
│   ├── slideshow.md
│   └── README.md
├── outputs/                # Generated files (gitignored)
├── requirements.txt
├── .env.example
├── Justfile
└── README.md

Documentation

Full documentation is in the docs/ folder:

• Overview
• Demo 1: Structured JSON
• Demo 2: Web Search
• Demo 3: Multi-Tool Agent
• Architecture

Workshop Slideshow

A presentation for running this workshop is in slideshow/:

# View slides (requires marp-cli)
npm install -g @marp-team/marp-cli
just slides

# Or export to PDF
just slides-pdf

Adding Custom Tools

1. Define schema (modules/tools.py)

MY_TOOL = {
    "type": "function",
    "name": "my_tool",
    "description": "What this tool does",
    "parameters": {
        "type": "object",
        "properties": {
            "param1": {"type": "string"}
        },
        "required": ["param1"],
        "additionalProperties": False
    },
    "strict": True
}

2. Implement handler (modules/handlers.py)

def my_tool(param1: str) -> str:
    result = do_something(param1)
    return json.dumps({"success": True, "result": result})

3. Register in your demo

tools = [MY_TOOL]
tool_functions = {"my_tool": my_tool}

Troubleshooting

Python version: pyenv local 3.11.0

API key not found: Check .env file exists with OPENAI_API_KEY=sk-...

Import errors: pip install -r requirements.txt

Resources

• OpenAI Responses API
• OpenAI Function Calling
• pyenv
• Just