Note START by importing this repo into v0

AI Ship 2025 Workshop - v0 Template Starter

Learn to build modern AI-powered applications with the latest Vercel AI SDK and v0

Overview

This is a hands-on workshop template for AI Ship 2025 that teaches you how to refactor AI applications from traditional patterns to modern, secure, and scalable approaches using the latest Vercel AI SDK v5 features. The workshop focuses on migrating to best practices including agents, workflows, structured outputs, and AI Elements.

Tech Stack

• Next.js - React framework for production
• AI SDK 5 - Vercel's AI SDK with modern agent patterns
• shadcn/ui - Beautiful, accessible component library
• AI Gateway - All AI providers in one place
• AI Elements - Pre-built UI components for AI interactions
• Upstash KV - Redis-compatible storage for workflows
• Workflows SDK - Long-running async operations
• Vercel Sandbox - Secure code execution environment

Prerequisites

Before starting the workshop, ensure you have:

• ✅ React knowledge
• ✅ Next.js experience
• ✅ v0 Account
• ✅ Vercel Account
• ✅ Vercel AI Gateway API key
• ✅ GitHub Account
• ✅ Node.js and pnpm installed

Development (after you have cloned the template!!)

Run the development server:

pnpm install
vercel link
vercel env pull
pnpm dev

Open http://localhost:3000 to see your application.

Test the application with "iPhone" in the brand input field.

Workshop Tasks

Phase 1: Initial Setup

• Clone workshop template from v0.dev into your personal workspace
• Connect your v0 project to GitHub and create new repository
• Deploy project from v0 to Vercel and verify deployment
• Clone GitHub repository to your local machine
• Run pnpm install to install dependencies
• Run vercel link to link your local project to vercel project
• Set up environment variables with vercel env pull
• Test the application locally with pnpm dev

Phase 2: Refactor to AI SDK v5

• Import Experimental_Agent as Agent and Output from ai package
• Refactor create-brand-context API route to use Agent class with experimental_output: Output.object()
• Add system prompt to create-brand-context Agent
• Create Zod schema for brand context structured output
• Ensure contextData matches BrandContext type from upstash.ts
• Refactor generate-questions API route to use Agent class with structured output
• Add system prompt to generate-questions Agent with brand name restrictions
• Create validation tool that checks for brand mentions in questions
• Configure Agent with stopWhen: stepCountIs(3) for max 3 steps
• Update Agent system prompt to instruct calling validateQuestions tool
• Remove manual validation check and trust Agent tool validation
• Ensure questions match Question[] type from upstash.ts
• Refactor check-visibility API route to use Agent class
• Add system prompt to check-visibility Agent for brand detection
• Create Zod schema for brand detection with isVisible and position fields
• Ensure answerData matches VisibilityAnswer type from upstash.ts
• Test all three API routes with brand name input

Stretch Goals

Phase 3: CLI Agent Flow (Streach Goal)

• Install @next/env package for environment variable loading
• Create lib/envConfig.ts with loadEnvConfig from @next/env
• Create scripts/full-agent-flow.ts to import envConfig at the top
• Use types from lib/upstash.ts and lib/constants.ts
• Create checkVisibility function with Promise.allSettled for parallel execution
• Test CLI script locally with pnpm full-agent-flow iphone run222
• Verify all 27 checks run in parallel
• Confirm results are stored in Redis with the correct runId

Phase 4: Vercel Sandbox Integration (Streach Goal)

• Install @vercel/sandbox, ms, and @types/ms packages
• Create app/api/full-flow-agent/route.ts endpoint
• Configure Sandbox to clone from GitHub repository
• Set Sandbox resources to 4 vCPUs and 10 minute timeout
• Pass all required environment variables to runCommand (not Sandbox.create)
• Run pnpm install in Sandbox with environment variables
• Execute pnpm full-agent-flow <brand> <runId> in detached mode
• Do not use sandbox.stop() to keep sandbox running until completion
• Update app/page.tsx to call /api/full-flow-agent instead of 3 separate routes
• Remove unused MODELS import from page.tsx
• Update button text to indicate Sandbox execution
• Test locally with vercel env pull for OIDC token
• Test endpoint with curl -X POST http://localhost:3000/api/full-flow-agent -H "Content-Type: application/json" -d '{"brand": "iphone"}'
• Verify frontend polling displays results in real-time

Phase 5: Sync and Deploy

• Push changes to GitHub main branch
• Sync v0 with GitHub to pull latest changes
• Verify deployment on Vercel production
• Test production Sandbox endpoint
• Monitor sandboxes in Vercel Dashboard Observability tab
• Test production application end-to-end

Once you've completed Phase 1-5, try these advanced challenges:

UI enhancements

• Integrate AI Elements into results display
• Use v0 to generate chart components for visualization
• Add interactive data visualizations to results

Advanced: Security & Performance

• Implement BotID for bot detection and prevention
• Add rate limiting middleware to API routes
• Configure Vercel Firewall or Upstash rate limiting
• Monitor and log API usage patterns

Advanced: SaaS Features

• Add Stripe for payment processing
• Claim Stripe Sandbox account
• test Stripe payment processing in Stripe dashboard

Troubleshooting

• Make sure you have AI_GATEWAY_API_KEY environment variable set in .env.local
• Make sure youhave REDIS connected in v0 and then do vercel env pull to pull the environment variables into your local environment.

Resources

• AI SDK v5 Documentation
• Agent Building Guide
• Vercel Sandbox Documentation
• v0 Documentation
• Next.js Documentation
• Next.js Environment Variables

---

Happy Building! 🚀