Overview
The AI Assistant is a built-in chat interface that provides intelligent, contextual answers to user questions about your documentation. It uses the Model Context Protocol (MCP) to search and retrieve relevant content, then generates helpful responses with source citations and code examples.The assistant requires an AI Gateway API key to function. Without this key, the assistant components will be automatically disabled.
How It Works
The assistant uses a multi-agent architecture powered by the AI SDK:- User Query - Users ask questions through the floating input or slideover interface
- MCP Tools - The AI uses your built-in MCP server to search and retrieve documentation pages
- Response Generation - The AI synthesizes information into conversational answers with citations
- Streaming UI - Responses stream in real-time with syntax-highlighted code blocks
/mcp, giving it access to all your pages without additional configuration.
Quick Start
Get an API Key
Visit Vercel AI Gateway and create an API key. AI Gateway supports multiple providers (OpenAI, Anthropic, Google, and more) through a unified API.
User Interface Components
Floating Input
A compact input field appears at the bottom center of documentation pages, allowing users to quickly ask questions without opening a panel. Features:- Auto-hides when the chat slideover is open
- Expands on focus for better typing experience
- Keyboard shortcut:
Cmd+I(Mac) orCtrl+I(Windows) - Press
Escapeto blur the input
Chat Slideover
When users submit a question, a side panel opens displaying the conversation. The panel includes:- Streaming responses with real-time text generation
- Syntax-highlighted code blocks using Shiki
- Source citations linking back to relevant documentation pages
- FAQ suggestions when the chat is empty
- Clear chat button to start a fresh conversation
Explain with AI Button
Each documentation page includes an “Explain with AI” button in the sidebar that opens the assistant with the current page as context.Configuration
Basic Options
Configure the assistant innuxt.config.ts:
nuxt.config.ts
Module Options
| Option | Type | Default | Description |
|---|---|---|---|
apiPath | string | /__docus__/assistant | API endpoint path for the chat |
mcpServer | string | /mcp | MCP server path or full URL |
model | string | google/gemini-3-flash | AI model identifier for AI SDK Gateway |
App Configuration
Customize the UI and behavior inapp.config.ts:
app.config.ts
FAQ Questions
Display suggested questions when the chat is empty to help users discover capabilities.Simple Array
app.config.ts
Categorized Questions
app.config.ts
Localized Questions
MCP Server Configuration
The assistant requires an MCP server to access your documentation content.Built-in MCP Server (Default)
Use Docus’s built-in MCP server that automatically exposes all your documentation pages:nuxt.config.ts
External MCP Server
Connect to any external MCP server by providing a full URL:nuxt.config.ts
AI Model Selection
The assistant usesgoogle/gemini-3-flash by default for fast, cost-effective responses. You can change to any model supported by AI SDK Gateway:
Customization
Site Name in Responses
The assistant automatically uses your site name in responses. Configure it innuxt.config.ts:
nuxt.config.ts
System Prompt
To customize the AI’s behavior and personality, you can override the system prompt by creating a custom server handler:server/api/__docus__/assistant.ts
Keyboard Shortcuts
Customize the keyboard shortcut for focusing the floating input:app.config.ts
meta_i- Cmd+I (Mac) / Ctrl+I (Windows)meta_k- Cmd+K (Mac) / Ctrl+K (Windows)ctrl_shift_p- Ctrl+Shift+P
Custom Icons
Replace the default icons with any Iconify icon:app.config.ts
Programmatic Control
Use theuseAssistant composable to control the assistant from your components:
Composable API Reference
| Property | Type | Description |
|---|---|---|
isEnabled | ComputedRef<boolean> | Whether assistant is enabled (API key present) |
isOpen | Ref<boolean> | Whether slideover is open |
isExpanded | Ref<boolean> | Whether panel is in expanded mode |
isMobile | Ref<boolean> | Whether viewport is mobile size |
panelWidth | ComputedRef<number> | Current panel width (360 or 520px) |
messages | Ref<UIMessage[]> | Chat message history |
pendingMessage | Ref<string?> | Message waiting to be sent |
faqQuestions | ComputedRef<FaqCategory[]> | FAQ questions from config |
open(message?, clear?) | Function | Open assistant with optional message |
close() | Function | Close assistant slideover |
toggle() | Function | Toggle open/closed state |
toggleExpanded() | Function | Toggle panel width |
clearMessages() | Function | Clear conversation history |
clearPending() | Function | Clear pending message |
Disabling Features
Disable Floating Input
app.config.ts
Disable “Explain with AI” Button
app.config.ts
Disable Assistant Entirely
Simply remove the environment variable:.env
Internationalization
All UI text is automatically translated based on the user’s locale. Docus includes built-in translations for English and French. Translated elements:- Slideover title and placeholder text
- Button labels (“Clear chat”, “Close”, “Explain with AI”)
- Tooltip texts
- Status messages (“Thinking…”, “Chat is cleared on refresh”)
Dependencies
The assistant module requires these packages (automatically installed with Docus):package.json
Troubleshooting
Assistant not appearing? Check that:
AI_GATEWAY_API_KEYis set in your environment- Your site is running in production mode or has the key in
.env - The MCP server is enabled and accessible at the configured path
Advanced: Custom Implementation
The assistant module is located inmodules/assistant/ and can be customized:
- Components:
runtime/components/- Vue components for UI - Composables:
runtime/composables/useAssistant.ts- State management - API Handler:
runtime/server/api/search.ts- Streaming chat endpoint - Types:
runtime/types.ts- TypeScript definitions