Agent UI

Multi-agent inbox UI built with Next.js 16 (App Router) that communicates with AI agents via the AG-UI protocol through CopilotKit.

Prerequisites

• Bun (package manager and runtime)

Setup

1. Install dependencies:

bun install

2. Copy the environment file:

cp .env.example .env.local

Local dev uses a file-based SQLite database (file:local.db) by default -- no external services needed. For production, set TURSO_DATABASE_URL and TURSO_AUTH_TOKEN for Turso cloud.

3. Start the dev server:

bun dev

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

Agent Configuration

Agents are defined in agents.config.json at the project root. Each entry has an id, name, endpoint_url (AG-UI protocol endpoint), optional api_docs URL, and description. To add a new agent, add an entry to this file.

Scripts

Command	Description
bun dev	Start Next.js dev server
bun run build	Production build
bun start	Start production server (runs migrations first)
bun run lint	ESLint
bun run format	Format all files with Prettier
bun run format:check	Check formatting (CI)
bun run typecheck	Type-check without emitting
bun run test	Run unit tests (Vitest)
bun run test:watch	Run unit tests in watch mode
bun run test:coverage	Run unit tests with coverage
bun run db:migrate	Run database migrations manually
bun run opencode:append-thread [pr-number] [session-id]	Post session transcript to a PR as a marked comment
bunx playwright test	Run end-to-end tests (Playwright)

Architecture

Core Flow

1. Agent Configuration -- Agents defined in agents.config.json are loaded at startup.
2. AG-UI Protocol Bridge -- The /api/copilotkit route creates a CopilotRuntime that instantiates HttpAgent instances for each configured agent, bridging CopilotKit to remote AG-UI endpoints.
3. Chat Interface -- ChatThread wraps CopilotKit's useCopilotChat() hook for streaming messages, loading states, and stop-generation.
4. Data Persistence -- Turso (libSQL/SQLite) stores agents, threads, and messages. Local dev uses a file-based SQLite database; production uses Turso cloud.

Key Directories

src/
  components/
    inbox/       -- Inbox list, filtering, thread previews
    thread/      -- Chat UI (MessageList, MessageBubble, ChatInput)
    sidebar/     -- Agent list sidebar, new thread dialog
    providers/   -- AppLayout root client component
    ui/          -- shadcn/ui primitives
  lib/
    agents/      -- Agent config loading and types
    hooks/       -- Data hooks (useInbox, useMessages)
  types/         -- Database types
db/              -- Turso/libSQL client, schema, and migrations

Routes

• / -- redirects to /inbox
• /inbox -- Thread list (all or filtered by agent)
• /thread/[id] -- Individual thread chat view
• /api/copilotkit -- AG-UI protocol endpoint (POST)
• /api/mock-agent -- Test agent endpoint

Tech Stack

• Framework: Next.js 16 (App Router)
• Language: TypeScript
• UI: shadcn/ui (Radix UI + Tailwind CSS 4)
• Database: Turso (libSQL/SQLite); local dev uses file:local.db
• Networking: Tailscale (private access to agent endpoints)
• Hosting: Railway
• Agent Protocol: AG-UI via CopilotKit
• Testing: Vitest (unit), Playwright (e2e)
• Package Manager: Bun