Assistant

About the Assistant

The assistant answers questions about your documentation through natural language queries. It is embedded directly in your documentation site, so users can find answers quickly and succeed with your product.

When users ask questions, the assistant:

• Searches and retrieves relevant content from your documentation using an MCP server.
• Cites sources with navigable links to take users directly to referenced pages.
• Generates copyable code examples to help users implement solutions from your documentation.

How It Works

The assistant uses a multi-agent architecture:

1. Main Agent - Receives user questions and decides when to search documentation
2. Search Agent - Uses MCP server tools to find relevant content
3. Response Generation - Synthesizes information into helpful, conversational answers

By default, the assistant connects to your documentation's built-in MCP server at /mcp, giving it access to all your pages without additional configuration. You can also connect to an external MCP server if needed.

Quick Start

1. Set up AI Gateway authentication

Pick one of these methods:

API key: create a key in Vercel AI Gateway and add it to your environment:

AI_GATEWAY_API_KEY=your-api-key

OIDC (only on Vercel): VERCEL_OIDC_TOKEN is injected automatically, so there is nothing to add in production. For local dev, run vercel env pull on a linked project.

2. Deploy

Deploy your site, the assistant is available as soon as authentication is configured.

Using the Assistant

Users can interact with the assistant in multiple ways:

Floating Input

On documentation pages, a floating input appears at the bottom of the screen. Users can type their questions directly and press Enter to get answers.

Explain with AI

Each documentation page includes an Explain with AI button in the table of contents sidebar. Clicking this button opens the assistant with the current page as context, asking it to explain the content.

Slideover Chat

When a conversation starts, a slideover panel opens on the right side of the screen. This panel displays the conversation history and allows users to continue asking questions.

Configuration

Configure the assistant through app.config.ts:

export default defineAppConfig({
  assistant: {
    // Show the floating input on documentation pages
    floatingInput: true,

    // Show the "Explain with AI" button in the sidebar
    explainWithAi: true,

    // FAQ questions to display when chat is empty
    faqQuestions: [],

    // Keyboard shortcuts
    shortcuts: {
      focusInput: 'meta_i'
    },

    // Custom icons
    icons: {
      trigger: 'i-lucide-sparkles',
      explain: 'i-lucide-brain'
    }
  }
})

FAQ Questions

Display suggested questions when the chat is empty. This helps users discover what they can ask.

Simple Format

export default defineAppConfig({
  assistant: {
    faqQuestions: [
      'How do I install Docus?',
      'How do I customize the theme?',
      'How do I add components to my pages?'
    ]
  }
})

Category Format

Organize questions into categories:

export default defineAppConfig({
  assistant: {
    faqQuestions: [
      {
        category: 'Getting Started',
        items: [
          'How do I install Docus?',
          'What is the project structure?'
        ]
      },
      {
        category: 'Customization',
        items: [
          'How do I change the theme colors?',
          'How do I add a custom logo?'
        ]
      }
    ]
  }
})

Localized Format

For multi-language documentation, provide FAQ questions per locale:

export default defineAppConfig({
  assistant: {
    faqQuestions: {
      en: [
        { category: 'Getting Started', items: ['How do I install?'] }
      ],
      fr: [
        { category: 'Démarrage', items: ['Comment installer ?'] }
      ]
    }
  }
})

Keyboard Shortcuts

Configure the keyboard shortcut for focusing the floating input:

export default defineAppConfig({
  assistant: {
    shortcuts: {
      // Default: 'meta_i' (Cmd+I on Mac, Ctrl+I on Windows)
      focusInput: 'meta_k' // Change to Cmd/Ctrl+K
    }
  }
})

The shortcut format uses underscores to separate keys. Common examples:

• meta_i - Cmd+I (Mac) / Ctrl+I (Windows)
• meta_k - Cmd+K (Mac) / Ctrl+K (Windows)
• ctrl_shift_p - Ctrl+Shift+P

Custom Icons

Customize the icons used by the assistant:

export default defineAppConfig({
  assistant: {
    icons: {
      // Icon for the trigger button and slideover header
      trigger: 'i-lucide-bot',

      // Icon for the "Explain with AI" button
      explain: 'i-lucide-lightbulb'
    }
  }
})

Icons use the Iconify format (e.g., i-lucide-sparkles, i-heroicons-sparkles).

Internationalization

All UI texts are automatically translated based on the user's locale. Docus includes built-in translations for English and French.

The following texts are translated:

• Slideover title and placeholder
• Tooltip texts
• Button labels ("Clear chat", "Close", "Explain with AI")
• Status messages ("Thinking...", "Chat is cleared on refresh")

Disable Features

Disable the Floating Input

Hide the floating input at the bottom of documentation pages:

export default defineAppConfig({
  assistant: {
    floatingInput: false
  }
})

Disable "Explain with AI"

Hide the "Explain with AI" button in the documentation sidebar:

export default defineAppConfig({
  assistant: {
    explainWithAi: false
  }
})

Disable the Assistant Entirely

Set enabled to false to disable the assistant, even when AI Gateway credentials are available:

export default defineNuxtConfig({
  docus: {
    assistant: {
      enabled: false
    }
  }
})

The assistant is also disabled when no authentication is available, so removing AI_GATEWAY_API_KEY from your environment has the same effect:

# AI_GATEWAY_API_KEY=your-api-key

On Vercel with OIDC, remove the auto-injected system environment variable from your project settings.

Advanced Configuration

Configure advanced options in nuxt.config.ts under docus.assistant.

export default defineNuxtConfig({
  docus: {
    assistant: {
      // Force enable or disable the assistant
      enabled: true,

      // AI model (uses AI SDK Gateway format)
      model: 'google/gemini-3-flash',

      // MCP server (path or URL)
      mcpServer: '/mcp',

      // API endpoint path
      apiPath: '/__docus__/assistant'
    }
  }
})

MCP Server Configuration

The assistant uses an MCP server to access your documentation. You have two options:

Use the Built-in MCP Server (Default)

By default, the assistant uses Docus's built-in MCP server at /mcp:

export default defineNuxtConfig({
  docus: {
    assistant: {
      mcpServer: '/mcp'
    }
  }
})

Use an External MCP Server

Connect to any external MCP server by providing a full URL:

export default defineNuxtConfig({
  docus: {
    assistant: {
      mcpServer: 'https://other-docs.example.com/mcp'
    }
  }
})

This is useful when you want the assistant to answer questions from a different documentation source, or when connecting to a centralized knowledge base.

Custom AI Model

The assistant uses google/gemini-3-flash by default. You can change this to any model supported by the AI SDK Gateway:

export default defineNuxtConfig({
  docus: {
    assistant: {
      model: 'anthropic/claude-opus-4.5'
    }
  }
})

Custom AI Provider

The model option above resolves models through Vercel AI Gateway, so it requires AI_GATEWAY_API_KEY or VERCEL_OIDC_TOKEN. To use another provider (Mistral, OpenAI, Cloudflare AI Gateway, or anything else supported by the AI SDK), enable the assistant explicitly and provide your own endpoint.

1. Enable the assistant and pick a path

Set enabled: true so the assistant no longer depends on AI Gateway credentials, and point apiPath at the route you're about to create:

export default defineNuxtConfig({
  docus: {
    assistant: {
      enabled: true,
      apiPath: '/api/assistant'
    }
  }
})

Your own server route always takes precedence: when you define a route at apiPath, Docus steps aside and doesn't register its built-in endpoint there.

2. Implement the endpoint

The endpoint is a regular Nitro route, so you have two options:

Reuse the built-in handler

assistantSearchHandler is an auto-imported server util that contains the default endpoint logic: MCP tool wiring, streaming, and abort handling. Pass a model to change the provider.

Install the provider package you need, for example Mistral:

npm install @ai-sdk/mistral

pnpm add @ai-sdk/mistral

yarn add @ai-sdk/mistral

Then build the route:

import { createMistral } from '@ai-sdk/mistral'

const mistral = createMistral()

export default defineEventHandler(event => assistantSearchHandler(event, {
  model: mistral('mistral-large-latest')
}))

That's the whole integration: everything else, including the documentation-tuned system prompt, keeps working as before.

assistantSearchHandler accepts an optional config object as its second argument:

Write your own handler

Skip assistantSearchHandler entirely and implement the route yourself. The assistant UI talks to it through the AI SDK's DefaultChatTransport, so the handler only has to respect two things:

• It receives a POST with a { messages } body, where messages is an array of AI SDK UIMessage.
• It returns a UI message stream response, built with createUIMessageStreamResponse.

import { streamText, convertToModelMessages, toUIMessageStream, createUIMessageStreamResponse } from 'ai'
import { createMistral } from '@ai-sdk/mistral'

const mistral = createMistral()

export default defineEventHandler(async (event) => {
  const { messages } = await readBody(event)

  const result = streamText({
    model: mistral('mistral-large-latest'),
    instructions: getAssistantSystemPrompt('My Documentation'),
    messages: await convertToModelMessages(messages)
  })

  return createUIMessageStreamResponse({
    stream: toUIMessageStream({ stream: result.stream })
  })
})

Site Name in Responses

The assistant automatically uses your site name in its responses. Configure the site name in nuxt.config.ts:

export default defineNuxtConfig({
  site: {
    name: 'My Documentation'
  }
})

This makes the assistant respond as "the My Documentation assistant" and speak with authority about your specific product.

Programmatic Access

Use the useAssistant composable to control the assistant programmatically:

<script setup>
const { isEnabled, isOpen, open, close, toggle } = useAssistant()

function askQuestion() {
  // Open the assistant with a pre-filled question
  open('How do I configure the theme?', true)
}
</script>

<template>
  <UButton v-if="isEnabled" @click="askQuestion">
    Ask about themes
  </UButton>
</template>

Composable API