Agents Workshop

GitNation React Summit US Workshop Learn to build production-ready AI agents with Next.js and the AI SDK

About This Workshop

This workshop teaches you how to build intelligent chatbot applications with real-time streaming, document artifacts, and multimodal capabilities. You'll learn hands-on by extending and customizing a production-ready AI chatbot built with modern web technologies.

What You'll Learn

• Building streaming chat interfaces with the AI SDK
• Creating interactive artifacts (documents, code editors, spreadsheets)
• Implementing multimodal AI (text, images, file uploads)
• Managing conversation history and user sessions
• Integrating authentication and rate limiting
• Working with AI model providers through gateway patterns

Tech Stack

• Next.js 16 - App Router with React Server Components
• AI SDK - Unified interface for LLM interactions
• AI Gateway - Multiple AI providers (Anthropic Claude, OpenAI)
• MongoDB - Database for chat history and artifacts
• NextAuth.js v5 - Authentication
• shadcn/ui - UI components with Tailwind CSS

Getting Started

Prerequisites

• Node.js 18+ (npm comes bundled with Node.js)
• Docker and Docker Compose (for MongoDB)
• AI Gateway API key (provided during workshop)

Installation

1. Clone and install dependencies:

npm install

2. Set up environment variables:

Copy .env.example to .env.local and fill in the required values:

cp .env.example .env.local

Required variables:

• AUTH_SECRET - Generate with: openssl rand -base64 32
• AI_GATEWAY_API_KEY - Your AI Gateway API key
• MONGODB_URI - MongoDB connection string (use Docker default)
• BLOB_READ_WRITE_TOKEN - For file storage

3. Start MongoDB and services:

npm run docker:up

4. Run the development server:

npm run dev

5. Open http://localhost:3000 in your browser

MongoDB Access

• MongoDB Port: 27018
• Mongo Express UI:http://localhost:8082
• Database:gitnation

Project Structure

app/
├── (auth)/ # Authentication routes (login, register)
├── (chat)/ # Chat interface and API routes
│ ├── api/chat/ # Main streaming endpoint
│ └── chat/[id]/ # Individual chat sessions
components/ # React components
├── artifact.tsx # Artifact modal and rendering
├── chat.tsx # Main chat interface
└── ui/ # shadcn/ui components
lib/
├── ai/ # AI SDK configuration
│ ├── providers.ts # Model and gateway setup
│ └── prompts.ts # System prompts
├── db/ # Database utilities
│ ├── mongodb.ts # Connection helper
│ ├── queries.ts # Database operations
│ └── types.ts # TypeScript types
└── artifacts/ # Artifact system
└── server.ts # Artifact orchestration
artifacts/ # Artifact implementations
├── text/ # Text document artifacts
├── code/ # Python code artifacts
└── sheet/ # Spreadsheet artifacts

Key Features

1. Streaming Chat Interface

Real-time AI responses with support for:

• Text streaming
• Tool calling
• Multimodal input (text, images, files)
• Message history and context

2. Document Artifacts

Interactive documents that appear alongside chat:

• Text Documents - Rich text editing with ProseMirror
• Code Artifacts - Python execution with Pyodide in-browser
• Spreadsheets - Excel-like interface with data visualization

3. Multimodal Capabilities

• Image uploads and analysis
• File attachments (PDF, text, etc.)
• Vision model support with Claude 3.5 Haiku

4. Authentication System

• Email/password authentication
• Guest user support for demos
• Session management with NextAuth.js v5

5. Rate Limiting

• Guest users: 20 messages/day
• Registered users: 100 messages/day
• Customizable entitlements

Workshop Exercises

Throughout the workshop, you'll complete hands-on exercises to:

1. Customize the AI behavior - Modify system prompts and model parameters
2. Create a new artifact type - Build a custom interactive component
3. Add a custom tool - Extend the AI with new capabilities
4. Implement rate limiting - Add usage tracking and limits
5. Style customization - Brand the interface with your own design

Development Commands

# Development
npm run dev # Start dev server
npm run build # Build for production
npm run start # Start production server# Database
npm run docker:up # Start MongoDB and services
npm run docker:down # Stop all services
npm run docker:logs # View service logs# Code Quality
npm run lint # Check for issues (Biome via Ultracite)
npm run format # Auto-fix formatting issues

AI Models

This project uses multiple AI providers through the AI Gateway:

• Claude 3.5 Haiku (anthropic/claude-3-5-haiku-latest) - Main chat model with multimodal support
• GPT-4o Mini (openai/gpt-4o-mini) - For artifact generation and title creation

Switching Model Providers

The AI SDK makes it easy to switch providers. See lib/ai/providers.ts for configuration. Supported providers include:

• Anthropic (Claude models)
• OpenAI (GPT models)
• Google (Gemini models)
• xAI (Grok models)
• Many more...

Resources

• AI SDK Documentation:ai-sdk.dev/docs
• Next.js Documentation:nextjs.org/docs
• Anthropic Documentation:docs.anthropic.com
• OpenAI Documentation:platform.openai.com/docs

Troubleshooting

MongoDB Connection Issues

# Check if MongoDB is running
npm run docker:logs
# Restart services
npm run docker:down && npm run docker:up

AI Gateway Errors

• Verify AI_GATEWAY_API_KEY is set in .env.local
• Check you're within rate limits
• Review error messages in the browser console

Build Errors

# Clear Next.js cache
rm -rf .next
# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

Contributing

This is a workshop project! Feel free to experiment, break things, and learn. Your instructor will help you through any issues.

License

Based on open-source templates and modified for educational purposes. See original projects for licensing details.

---

Happy coding! 🚀

Workshop by Niall Maher for GitNation React Summit US