GAIA Playbooks

Source Code: src/gaia/chat/sdk.py | src/gaia/rag/sdk.py | src/gaia/agents/emr/ | examples/hardware_advisor_agent.py

These playbooks provide step-by-step tutorials for building AI agents on AMD AI PCs. Each explains implementation details and architectural decisions.

Built for AI PCs: All agents run locally on Ryzen AI hardware (NPU/iGPU acceleration) for private, fast AI processing.

What makes playbooks different?Unlike reference documentation, playbooks are journey-based tutorials that:

Start with a working example in 5 minutes
Build complexity incrementally
Explain what happens “under the hood”
Include production deployment patterns
Provide reusable code you can extend

Available Playbooks

Hardware Advisor Agent

Build an agent that analyzes your system hardware and recommends which LLMs you can run locally.

Building a Hardware Advisor

15-20 minutesBuild an agent that advises on LLM capabilities based on hardware.

Quick start (5 min working example)
LemonadeClient SDK integration
GPU/NPU detection (Windows & Linux)
Memory-based recommendations

Image Generation Agent

Build an agent that generates images from text descriptions using Stable Diffusion running on Ryzen AI.

Building an Image Generation Agent

20-30 minutesBuild an agent that generates images using SDToolsMixin.

Quick start (5 min working example)
SDToolsMixin pattern
Tool registration and orchestration
Prompt enhancement strategies
Multiple model support (SD-Turbo, SDXL)

Document Q&A Agent with RAG

Build an agent that searches, indexes, and answers questions about documents. Split into 3 progressive parts for easier learning.

Part 1: Getting Started

15-20 minutesBuild your first agent with RAG capability.

Quick start (5 min working example)
Understanding components
Steps 1-3: Basic → RAG → File Discovery

Part 2: Advanced Features

15-20 minutesAdd monitoring, sessions, and customization.

Tool mixins pattern
File monitoring & auto-indexing
Session persistence
Custom tools & specialization
Real-world examples

Part 3: Deployment & Optimization

15-20 minutesDeploy and optimize your agent.

Agent intelligence & reasoning
Advanced patterns
Web API & CLI deployment
Performance tuning
Troubleshooting

Medical Intake Agent (EMR)

Build an automated patient intake processor with VLM extraction, database storage, and a real-time web dashboard. Perfect for learning FileWatcherMixin and DatabaseMixin.

Part 1: Getting Started

20-25 minutesBuild an automated intake form processor.

FileWatcherMixin for auto-detection
VLM extraction from images/PDFs
DatabaseMixin for patient storage
Natural language patient queries

Part 2: Dashboard & API

20-25 minutesCreate a real-time monitoring dashboard.

FastAPI server setup
Server-Sent Events (SSE)
React frontend components
REST API endpoints

Part 3: Architecture

15-20 minutesDeep dive into system design.

Database schema design
Processing pipeline steps
Time savings calculation
Production considerations

Code Generation Agent

Build an AI-powered agent that generates complete Next.js applications from natural language descriptions. Split into 3 progressive parts.

Part 1: Introduction & Architecture

20-25 minutesUnderstanding GAIA Code Agent architecture.

What is GAIA Code?
System architecture
MVP approach
Technology stack
Quick start example

Part 2: App Creation & Components

20-25 minutesSchema, API, and React component generation.

Database schema generation
API route creation with validation
React component creation
Tailwind CSS styling
Working examples

Part 3: Validation & Building

15-20 minutesTypeScript validation and error iteration.

TypeScript validation process
Next.js build pipeline
Error iteration loop
Auto-fix process
Testing final applications

More Guides

Voice Interaction

Integrate Whisper (ASR) and Kokoro (TTS) for voice interaction.

Routing Agent

Intelligent request analysis and agent selection through conversational disambiguation.

How to Use Playbooks

Choose your playbook

Pick a use case that matches your needs. Each playbook is self-contained.

Follow the journey

Start from Step 1 and work through sequentially. Each step builds on the previous one.

Understand the implementation

Read the “Under the Hood” sections to understand the technical details and design decisions.

Extend and customize

Use the “Making It Your Own” sections to adapt the agent for your specific use case.

Deploy to production

Review deployment patterns for packaging and distribution.

Playbook Structure

Each playbook follows this format:

1. Why Build This? (Context)

Sets the stage - what problem does this solve? What will you build?

2. Quick Start (5 min)

Minimal working example to verify setup and understand basic usage.

3. Architecture Overview

Visual diagram showing how components fit together.

4. Understanding Components

Deep dive into each piece with “under the hood” explanations.

5. Step-by-Step Build

Incremental construction - each step adds one feature and explains it.

6. Making It Your Own

Customization patterns, extensions, and advanced use cases.

7. Production Deployment

API servers, CLI tools, and distribution patterns.

8. Real-World Examples

Complete, copy-paste ready examples for common scenarios.

Prerequisites

All playbooks assume you have:

Python Environment
GAIA Installed
Lemonade Server
Basic Python Knowledge

Python 3.10 or higher
uv package manager (recommended)
A project folder for your agent code

Create a project folder and install GAIA:

mkdir my-gaia-project
cd my-gaia-project
uv venv .venv
source .venv/bin/activate  # On Windows: .\.venv\Scripts\Activate.ps1
uv pip install amd-gaia

Each playbook specifies additional extras you may need (e.g., amd-gaia[rag] for document processing).

Lemonade Server is installed automatically with GAIA:

# Start with NPU/iGPU acceleration
lemonade-server serve

Lemonade Server provides AMD-optimized inference for AI PCs, utilizing NPU and iGPU acceleration. GAIA will auto-start it if not running.

Learning Path

Start here

Begin with Document Q&A Agent - it covers foundational concepts used in all other playbooks.

Add capabilities

Once comfortable, add voice with the Talk Guide or code generation with the Code Agent.

Go advanced

Build complex systems with Routing Agent and custom tool mixins.

Ship it

Package and distribute with UI Documentation guides.

Playbook Principles

Our playbooks follow these principles:

Fast Start

Working example in 5 minutes to verify setup.

Teachable

Technical explanations of implementation details and design trade-offs.

Extensible

Code is designed for extension via inheritance and composition.

Progressive

Incremental build process, adding one feature per step.

Practical

Production-oriented examples with real-world use cases.

Reusable

Code samples you can adapt for your specific requirements.

Contributing Playbooks

If you’ve built an agent that demonstrates useful patterns, consider contributing a playbook.

Playbook template coming soonWe’re creating a template to make it easy for the community to contribute playbooks. Check the GitHub repo for updates.

Feedback

Help us improve these playbooks!

Found a bug? Report it
Have a suggestion? Open an issue
Built something useful? Share it in Discord

Getting Started

C++ Framework

Python Framework

Available Playbooks

Hardware Advisor Agent

Building a Hardware Advisor

Image Generation Agent

Building an Image Generation Agent

Document Q&A Agent with RAG

Part 1: Getting Started

Part 2: Advanced Features

Part 3: Deployment & Optimization

Medical Intake Agent (EMR)

Part 1: Getting Started

Part 2: Dashboard & API

Part 3: Architecture

Code Generation Agent

Part 1: Introduction & Architecture

Part 2: App Creation & Components

Part 3: Validation & Building

More Guides

Voice Interaction

Routing Agent

How to Use Playbooks

Playbook Structure

Prerequisites

Learning Path

Playbook Principles

Fast Start

Teachable

Extensible

Progressive

Practical

Reusable

Contributing Playbooks

Feedback

Getting Started

C++ Framework

Python Framework

​Available Playbooks

​Hardware Advisor Agent

Building a Hardware Advisor

​Image Generation Agent

Building an Image Generation Agent

​Document Q&A Agent with RAG

Part 1: Getting Started

Part 2: Advanced Features

Part 3: Deployment & Optimization

​Medical Intake Agent (EMR)

Part 1: Getting Started

Part 2: Dashboard & API

Part 3: Architecture

​Code Generation Agent

Part 1: Introduction & Architecture

Part 2: App Creation & Components

Part 3: Validation & Building

​More Guides

Voice Interaction

Routing Agent

​How to Use Playbooks

​Playbook Structure

​Prerequisites

​Learning Path

​Playbook Principles

Fast Start

Teachable

Extensible

Progressive

Practical

Reusable

​Contributing Playbooks

​Feedback

Available Playbooks

Hardware Advisor Agent

Image Generation Agent

Document Q&A Agent with RAG

Medical Intake Agent (EMR)

Code Generation Agent

More Guides

How to Use Playbooks

Playbook Structure

Prerequisites

Learning Path

Playbook Principles

Contributing Playbooks

Feedback