AI Agent Workshop

Welcome to the AI Agent Workshop! This repository is designed to help students learn agentic LLM development through hands-on examples using the Agno framework.

🎓 What You'll Learn

By completing this workshop, students will understand:

Part 1: Atomic Agent Fundamentals (Module 1)

• Single Responsibility Principle - One agent, one job
• Modular Design - Independent agents working together
• Schema Design - Flat structures for reliability
• Sequential Coordination - Manual result combination
• Why atomic agents are more reliable than monolithic ones

Part 2: Workflow Orchestration (Module 2)

• Parallel Execution - Running agents simultaneously
• Workflow Patterns - Sequential + parallel coordination
• Automatic Orchestration - Framework-managed agent coordination
• Production Patterns - Scaling from atomic to workflow
• Building on atomic agents with structured workflows

Complete Learning Path:

Module 1: Atomic Agents (Foundation)
    ↓
Module 2: Workflows (Orchestration)
    ↓
Real-World Applications

📋 Prerequisites

• Python 3.11 or higher
• Basic understanding of Python programming
• Familiarity with terminal/command line

🚀 Setup from a bare environment

These steps work on Windows, macOS, and Linux.

1. Install Python 3.11+

Windows (PowerShell):

winget install Python.Python.3.11

Or download the installer from python.org/downloads.

macOS:

brew install python@3.11

Or download the installer from python.org/downloads.

Linux (examples):

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install -y python3.11 python3.11-venv

# Fedora
sudo dnf install -y python3.11

Verify:

python --version

2. Install UV Package Manager

UV is a fast Python package installer and resolver. Choose your operating system:

Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

After installation, restart your terminal or run:

source $HOME/.cargo/env  # macOS/Linux

3. Install Ollama

Ollama allows you to run LLMs locally on your machine.

Windows:

1. Download the installer from ollama.com/download
2. Run the installer and follow the prompts
3. Open a new terminal after installation

macOS:

brew install ollama

Or download from ollama.com/download

Linux:

curl -fsSL https://ollama.com/install.sh | sh

4. Clone and set up this repository

git clone https://github.com/researchTestingAnd/ai_workshop.git
cd ai_workshop

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync --frozen

5. Pull the Granite model and start Ollama

After installing Ollama, download the model we'll use:

ollama pull granite4:3b

Why Granite 4 (3B)?

• ✅ Better Quality - Improved over smaller 2B models
• ✅ Still Fast - 3B parameters is lightweight for most laptops
• ✅ Structured Output - Excellent at following schemas and instructions
• ✅ Recent Release - Latest from IBM's Granite family
• ✅ Free & Local - No API costs, complete privacy
• ✅ Workshop Optimized - Good balance for learning atomic agents

Model Size: ~2.1GB download, ~3-4GB RAM required

Start the Ollama server (if not already running):

ollama serve

6. Launch Jupyter

jupyter lab

Open 01_document_summarizer.ipynb to begin!

📚 Workshop Modules

Module 1: Atomic Agents - Document Analysis Pipeline

File: 01_document_summarizer.ipynb
Duration: 60-90 minutes
Level: Beginner → Foundation

The Atomic Agent Pattern:

Learn the foundational pattern of building atomic agents - single-purpose, focused agents that do one thing well. You'll build a document analysis pipeline using three independent agents:

Document 
   ↓
Summary Agent  → BasicSummary (title, summary, key_points)
   ↓
Entity Agent   → EntityList (people, organizations, dates)
   ↓  
Action Agent   → ActionItemList (tasks, owners, deadlines)
   ↓
Manual Combination → Complete Analysis

What You'll Build:

• 🎯 Summary Agent - Generates core summary and key points
• 👥 Entity Agent - Extracts people, organizations, dates
• ✅ Action Agent - Identifies tasks and assignments
• 🔧 Pipeline Function - Manual coordination of all three agents

Why Atomic Agents?

• ✅ More Reliable - Simple, flat schemas work better with small models
• ✅ Easier to Debug - See exactly which agent succeeds/fails
• ✅ Maintainable - Update one agent without affecting others
• ✅ Composable - Combine agents in different ways
• ✅ No Magic - Pure agent outputs, NO fallback parsing!
• ✅ Foundation - Prepares you for workflow orchestration (Module 2)

Key Concepts:

• Modular agent design (one agent = one job)
• Simple, flat schemas for reliability
• Sequential execution pattern
• Manual result combination
• Tool integration (file reading)

What Makes This "Atomic"? Each agent is independent and focused:

• Can run separately
• Has one clear responsibility
• Returns simple, flat data structure
• No dependencies on other agents

Important Learning: In this module, you manually coordinate agents - you explicitly call each one and combine results yourself. This teaches you HOW agents work before learning workflow automation in Module 2!

---

Module 2: Workflow Orchestration - Parallel Research System

File: 02_research_workflow.ipynb
Duration: 60-90 minutes
Level: Intermediate → Building on Module 1

From Atomic to Orchestrated:

Building on Module 1's atomic agents, learn workflow orchestration - using the Agno framework to automatically coordinate multiple agents with parallel execution.

User Query
    ↓
[Workflow Framework Takes Over]
    ↓
Parallel Execution:
  Web Agent + Tech Agent + Market Agent (run simultaneously!)
    ↓
Automatic Consolidation (framework-managed)
    ↓
Writer Agent (synthesis)
    ↓
Final Report

Progression from Module 1:

Aspect	Module 1 (Atomic)	Module 2 (Workflow)
Execution	Sequential (one by one)	Parallel (simultaneous)
Coordination	Manual (you code it)	Automatic (framework)
Pattern	Call each agent yourself	Define workflow steps
Scaling	Hard to add more agents	Easy workflow definition
Production	Prototype/learning	Production-ready

What You'll Build:

• Multi-agent research system with 3+ specialized agents
• Parallel execution patterns (agents run at same time)
• Automatic result consolidation
• Custom step functions
• Production-grade workflows

Key Concepts:

• Workflow design patterns
• Parallel vs sequential execution
• Step definitions and executors
• Agent coordination and data flow
• Scaling from prototype to production

Why Workflows?

• ⚡ Faster - Parallel execution saves time
• 🔄 Automatic - Framework handles coordination
• 📈 Scalable - Easy to add more agents
• 🏗️ Structured - Clear execution flow
• 🛡️ Reliable - Built-in error handling

Building on Module 1: Module 1 taught you atomic agents and manual coordination. Now you'll see how to scale that pattern using workflow orchestration for production systems!

• Multi-agent research system with parallel execution
• Automatic result consolidation
• Complex workflow patterns (sequential + parallel)

Progression from Module 1:

• Module 1: Atomic agents (sequential, manual coordination)
• Module 2: Workflows (parallel execution, automatic orchestration)

Key Concepts:

• Workflow design patterns
• Parallel vs sequential execution
• Agent coordination and data flow
• Production-grade multi-agent systems

🔧 Configuration

Switching Model Providers

The notebooks are pre-configured to use Ollama with granite4:3b for local, cost-free execution. However, you can easily switch to cloud providers:

Option 1: Ollama (Local - Default)

Advantages:

• ✅ Free to use
• ✅ Complete privacy (runs locally)
• ✅ No API keys needed
• ✅ Works offline
• ⚠️ Limited to available models

from agno.models.ollama import Ollama

model = Ollama(id="granite4:3b")

Available Models: Run ollama list or visit ollama.com/library

Option 2: OpenAI

Advantages:

• ✅ Most powerful models (GPT-4, etc.)
• ✅ Fast response times
• ✅ No local resource usage
• ⚠️ Requires API key and costs money

from agno.models.openai import OpenAIChat
import os

os.environ["OPENAI_API_KEY"] = "your-api-key-here"
model = OpenAIChat(id="gpt-4")

Get API Key: platform.openai.com/api-keys

Option 3: Anthropic Claude

Advantages:

• ✅ Excellent reasoning capabilities
• ✅ Long context windows
• ✅ Strong at following instructions
• ⚠️ Requires API key and costs money

from agno.models.anthropic import Claude
import os

os.environ["ANTHROPIC_API_KEY"] = "your-api-key-here"
model = Claude(id="claude-3-5-sonnet-20241022")

Get API Key: console.anthropic.com

Option 4: Other Ollama Models

Try different local models for different use cases:

# Faster, smaller models
ollama pull phi3:mini              # 3.8GB - Very fast
ollama pull gemma2:2b              # 1.6GB - Efficient

# More capable models
ollama pull llama3.2:latest        # 2.0GB - Good balance
ollama pull mistral:latest         # 4.1GB - Strong performance
ollama pull qwen2.5:7b             # 4.7GB - Multilingual

# Specialized models
ollama pull codellama:7b           # 3.8GB - Code generation
ollama pull llama3.2-vision:latest # Multimodal (images + text)

Model Configuration in Notebooks

To change models in the notebooks, simply modify the model parameter when creating agents:

# Find this line in the notebook:
model = Ollama(id="granite4:3b")

# Replace with your preferred model:
model = Ollama(id="llama3.2:latest")
# OR
model = OpenAIChat(id="gpt-4")
# OR
model = Claude(id="claude-3-5-sonnet-20241022")

Model Selection Guide

Use Case	Recommended Model	Why
Workshop/Learning	granite4:3b	Balanced quality, good with structured outputs
Better Quality (Local)	llama3.2:3b or qwen2.5:7b	More capable, larger models
Fastest (Local)	phi3:mini or gemma2:2b	Smaller, faster responses
Production (Cloud)	gpt-4 or claude-3-5-sonnet	Highest quality
Code Generation	codellama:7b	Optimized for code
Privacy-Critical	Any Ollama model	Runs completely local
Cost-Sensitive	granite4:3b or phi3:mini	Free, efficient

Granite 4 (3B) is the default because:

• Good balance of quality and speed
• Excellent at following structured output schemas
• Works well for atomic agent patterns
• Reliable with modular designs
• Free and runs locally

Using Different Model Providers

The notebooks are pre-configured to use Ollama with granite4:3b by default. To switch providers:

Ollama (Local - Default):

from agno.models.ollama import Ollama

model = Ollama(id="granite4:3b")

OpenAI:

from agno.models.openai import OpenAIChat
import os

os.environ["OPENAI_API_KEY"] = "your-api-key"
model = OpenAIChat(id="gpt-4")

Anthropic:

from agno.models.anthropic import Claude
import os

os.environ["ANTHROPIC_API_KEY"] = "your-api-key"
model = Claude(id="claude-3-5-sonnet-20241022")

📖 Additional Resources

• Agno Documentation
• Ollama Documentation
• UV Documentation

🐛 Troubleshooting

Ollama not responding:

• Make sure the Ollama service is running: ollama serve
• Check if the model is downloaded: ollama list

UV command not found:

• Restart your terminal after installation
• Check if cargo bin is in PATH: echo $PATH | grep cargo

Module import errors:

• Ensure virtual environment is activated
• Reinstall dependencies: uv sync --reinstall

🤝 Contributing

Found an issue or want to improve the workshop? Please open an issue or submit a pull request!

📄 License

This workshop is provided for educational purposes.