CopilotKit & Generative UI Hooks
Relevant source files
The following files were used as context for generating this wiki page:
The mdeai platform implements an AI-first architecture using CopilotKit v1.55.2 as the primary orchestration layer for chat-based interactions and Generative UI. This system bridges the frontend Next.js application with AI agents (built on Mastra) and the Google Gemini 3.5 Flash model. The integration enables "Generative UI," where the AI can programmatically update frontend state, render interactive components (like approval panels or search cards), and respond to real-time user input via specialized hooks.
Sources: README.md:3-13, package.json:115-117
System Architecture
The architecture consists of a frontend chat shell that communicates with a backend CopilotRuntime. The runtime acts as a bridge to Mastra agents, which execute tools and logic.
This diagram shows the flow from a user message in the UI to the backend runtime and the subsequent Generative UI render loop.
Sources: README.md:15-32, src/app/api/copilotkit/[[...path]]/route.ts:51-64
Core Hooks and Integration
The project utilizes several key hooks from @copilotkit/react-core to manage AI state and actions.
useCoAgent
Used to synchronize shared state between the frontend and a specific AI agent. For example, in the host event wizard, useCoAgent keeps the EventDraftState in sync between the React component and the hostEventAgent.
- Source of Truth: React state remains the source of truth, but the agent can suggest or apply updates.
- State Merging: Updates from the agent are merged into the existing draft state using specialized utility functions.
Sources: src/components/host/host-event-copilot-bridge.tsx:29-45
useCopilotAction
Enables the AI to execute specific frontend functions. Actions are defined with names, descriptions, and parameters that the LLM understands.
| Action Name | Purpose | Key Parameters |
|---|---|---|
set_event_basics | Updates title, neighborhood, and date. | title, neighborhood, dateIso |
set_venue | Updates venue details. | venue, capacity |
set_pricing | Manages pricing and ticket tiers. | priceMinCop, ticketTiers |
preview_and_publish | Triggers a Generative UI approval panel. | draft (Object) |
Sources: src/components/host/host-event-copilot-bridge.tsx:55-110
renderAndWaitForResponse
A critical feature of Generative UI where the agent pauses execution to display a React component and waits for a user decision (HITL - Human In The Loop).
// Example from HostEventCopilotBridge
useCopilotAction({
name: "preview_and_publish",
available: "remote",
renderAndWaitForResponse: ({ args, respond, status }) => (
<EventPublishApprovalPanel
draft={args.draft}
status={status}
respond={(decision) => respond?.(decision)}
/>
),
});
Sources: src/components/host/host-event-copilot-bridge.tsx:93-125
Backend Runtime & API Route
The CopilotKit backend is hosted at /api/copilotkit. It initializes a CopilotRuntime with agents retrieved via getLocalAgentsWithLogging.
Request Context and Logging
The system injects Supabase user IDs into the Mastra RequestContext to ensure tool calls are audited and RLS-compliant. It also uses a persistTurnLog function wrapped in Next.js after() to log AI runs without delaying the SSE (Server-Sent Events) response.
Sources: src/app/api/copilotkit/[[...path]]/route.ts:20-49, src/app/api/copilotkit/[[...path]]/route.ts:74-85
Mobile UI Optimizations
To maintain a professional "app-like" feel, the system overrides default CopilotKit styles in globals.css for mobile devices.
- Input Sizing: Textarea font-size is set to
1rem(16px) to prevent iOS Safari auto-zoom. - Touch Targets: Control buttons have a minimum size of
44x44pxto meet WCAG 2.5.5 standards. - Overscroll Behavior: The message list uses
overscroll-behavior-y: containto prevent pull-to-refresh triggers during chat scrolling. - Safe Areas: Padding is adjusted to respect the iOS home indicator using
env(safe-area-inset-bottom).
Sources: src/app/globals.css:128-150
Provider Hierarchy
The GeoChatShell demonstrates the complex provider nesting required for a map-first generative UI.
This diagram shows the nesting of the CopilotKit provider and the specific UI search renders within the map shell.
Conclusion
The integration of CopilotKit and Mastra within mdeai creates a robust framework for Medellín discovery. By combining shared state (useCoAgent), actionable tools (useCopilotAction), and interactive UI components (renderAndWaitForResponse), the platform allows users to transition seamlessly from natural language queries to structured data entry and ticketing workflows.