AI integration

Multi-provider chat, agents, and user-scoped API keys in the Zero To Shipped boilerplate.

Zero To Shipped ships an AI chat feature built on the Vercel AI SDK (v6). Users bring their own provider API keys; the app stores them in user preferences, not in server .env files.

Stack at a glance

Layer	Package / path	Role
Core AI	`@zts/ai` (`packages/ai`)	Language models, `ToolLoopAgent`, built-in tools
Provider catalog	`@zts/shared`	Provider list, model catalog, preference keys
Chat API	`apps/web/src/app/api/chat/route.ts`	Streaming agent responses, persistence
Chat UI	`apps/web/src/components/ai/*`	`useChat`, provider picker, workspace
Settings	Settings → AI tab	Enable providers, paste keys per user
Mobile demo	`apps/mobile/src/features/chat/ChatPanel.tsx`	Minimal `useChat` example

Enable chat

Set in root .env:

NEXT_PUBLIC_ENABLE_CHAT_PAGE=true

The /chat route and nav entry are gated on this flag. Users still need to configure at least one provider in Settings → AI before sending messages.

How it fits together

flowchart TB
  UI[Chat UI useChat]
  API["POST /api/chat"]
  Agent[ToolLoopAgent @zts/ai]
  Prefs[User preferences aiProviderKey*]
  LLM[createLanguageModel]
  Tools[Built-in + tRPC tools]
  UI --> API
  API --> Prefs
  API --> LLM
  API --> Agent
  Agent --> Tools
  LLM --> Provider[OpenAI / Anthropic / Gemini / ...]

User selects provider + model in the chat header (from configured providers).
POST /api/chat resolves the API key from preferences and builds a language model.
A ToolLoopAgent runs with built-in demo tools and optional tRPC-derived tools.
The response streams back via createAgentUIStreamResponse; messages persist to the database.

Topics

Page	What you'll learn
Providers	Catalog, enabled providers, user keys, model + intelligence settings
Chat	UI components, chat rows, streaming API contract, mobile notes
Agents	`ToolLoopAgent`, built-in tools, tRPC-as-tools, extending the agent

MCP vs in-app AI

Do not confuse the two agent surfaces:

MCP — external tools for Cursor (/api/mcp), driven by apiExposure() on tRPC procedures.
In-app chat agent — product feature at /chat, driven by @zts/ai and POST /api/chat.

Package imports

import {
  createLanguageModel,
  createZtsAgent,
  resolveUserAiProvider,
} from "@zts/ai";
 
import { ENABLED_AI_PROVIDERS, AI_PROVIDERS } from "@zts/shared/config/ai-providers";
import { listConfiguredAiProviders } from "@zts/shared/ai/list-configured-providers";

See packages/ai/package.json for subpath exports used in tests and tree-shaking.

Env — feature flags including NEXT_PUBLIC_ENABLE_CHAT_PAGE
Database — chat and message tables
Monorepo layout — where packages/ai lives