Alem Tuzlak
79ce60c580
Replace eslint and prettier with oxlint and oxfmt for faster linting and formatting across the monorepo. Remove all eslint and prettier configs, dependencies, and related packages. Add .oxlintrc.json and .oxfmtrc.json for the new tooling. Update CI workflows and lefthook hooks accordingly. Reformat codebase with oxfmt. https://claude.ai/code/session_01GMkSf29p78HuMR1mbXn8He
AG-UI Mastra Workshop
A comprehensive workshop demonstrating AG-UI (Agent User Interaction) protocol with Mastra integration. This workshop shows how to build sophisticated AI applications with shared state, multiple client interfaces, and rich user interactions.
What is AG-UI?
AG-UI is a protocol for communicating between AI Agents and Users, enabling:
- Shared-State: Real-time synchronization between agents and UI components
- Multiple Clients: Build web apps, CLI tools, mobile apps - all connected to the same agent
- Generative UI: Agents can render dynamic interface components
- Tool Integration: Seamless integration of agent tools with user interfaces
Learn more: @ag-ui/mastra on npm
Workshop Structure
This workshop is organized into 3 progressive steps, each building on the previous to demonstrate different aspects of AG-UI:
🎯 Step 1: Basic AG-UI Integration
Branch: git checkout step-1
Link: https://github.com/CopilotKit/CopilotKit/tree/main/examples/canvas/mastra-pm
Focus: Core concepts and simple state management
- Simple agent state (proverbs array)
- Basic CopilotKit integration with Mastra
- Frontend actions and generative UI
- CLI and Web clients with same agent
🎯 Step 2: Complex State & Agent Behavior
Branch: git checkout step-2
Link: https://github.com/CopilotKit/CopilotKit/tree/main/examples/canvas/mastra-pm
Focus: Structured data and agent personas
- Complex state schemas with Zod validation
- Product manager agent with specific instructions
- Working memory with structured data types
- Enhanced CLI debugging with state snapshots
🎯 Step 3: Production-Ready Application
Branch: git checkout step-3
Link: https://github.com/CopilotKit/CopilotKit/tree/main/examples/canvas/mastra-pm
Focus: Full-featured project management interface
- Complete kanban board and team management UI
- Rich React component architecture
- Professional project management interface
- Multiple interaction patterns (modals, drag-drop, etc.)
Key Learning Outcomes
By completing this workshop, you'll understand:
- ✅ Multi-Client Architecture: How to build CLI and web interfaces for the same agent
- ✅ Shared-State Management: How state synchronizes between agents and multiple UI clients
- ✅ Agent Design: Creating agents with personas, tools, and memory
- ✅ UI Integration: Building rich interfaces that react to agent state
- ✅ Production Patterns: Scalable architecture for real-world applications
Quick Start
Prerequisites
- Node.js 18+
- OpenAI API key
- Package manager (pnpm recommended)
Setup
- Clone and install dependencies:
git clone <repository-url>
cd mastra-pm-canvas
pnpm install
- Add your OpenAI API key:
echo "OPENAI_API_KEY=your-key-here" >> .env
- Choose your starting point:
# Start from the beginning
git checkout step-1
# Or jump to a specific step
git checkout step-2
git checkout step-3
Running the Workshop
Each step provides two different client interfaces for the same agent:
🌐 Web Interface (CopilotKit + React)
pnpm dev
# Opens http://localhost:3000
💻 CLI Interface (Terminal-based)
pnpm cli
# Interactive chat in your terminal
Key Point: Both interfaces connect to the same agent and share the same state. This demonstrates AG-UI's power in enabling multiple client types.
Workshop Navigation
Step-by-Step Progression
git checkout step-1 # Basic concepts
# Work through step-1, then:
git checkout step-2 # Enhanced state management
# Work through step-2, then:
git checkout step-3 # Full application
Compare Between Steps
# See what changed between steps
git diff step-1 step-2 --name-only
git diff step-2 step-3 --name-only
Architecture Overview
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Web Client │ │ Mastra Agent │ │ CLI Client │
│ (CopilotKit) │◄──►│ + AG-UI │◄──►│ (Terminal) │
│ │ │ │ │ │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │ │
└────────────────────────┼────────────────────────┘
│
┌──────────────┐
│ Shared-State │
│ + Memory │
└──────────────┘
Technologies Used
- Mastra: AI agent framework
- AG-UI: Agent User Interaction protocol
- CopilotKit: React AI interface components
- Next.js: React framework
- Zod: Schema validation
- LibSQL: SQLite-compatible database
Support & Resources
Next Steps
After completing this workshop:
- Experiment with custom tools and agent instructions
- Try building additional client interfaces (mobile, desktop)
- Explore more complex agent behaviors and state schemas
- Build your own production AG-UI application
Happy Building! 🚀