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.

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'
    }
  }
})

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

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).

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
    }
  }
})

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.

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'
    }
  }
})

Site Name

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.

Custom 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.

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

npm install @ai-sdk/mistral

pnpm add @ai-sdk/mistral

yarn add @ai-sdk/mistral

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

const mistral = createMistral()

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

  return createAssistantResponse(streamText({
    ...await getAssistantDefaultOptions(event),
    model: mistral('mistral-large-latest'),
    messages: await convertToModelMessages(messages)
  }))
})

return createAssistantResponse(streamText({
  ...await getAssistantDefaultOptions(event),
  model: mistral('mistral-large-latest'),
  // Wins over the default 8000
  maxOutputTokens: 4000,
  messages: await convertToModelMessages(messages)
}))

const defaults = await getAssistantDefaultOptions(event)

return createAssistantResponse(streamText({
  ...defaults,
  model: mistral('mistral-large-latest'),
  messages: await convertToModelMessages(messages),
  onError: (payload) => {
    myErrorReporter(payload.error)
    // Still closes the MCP client
    defaults.onError(payload)
  }
}))

const defaults = await getAssistantDefaultOptions(event)

return createAssistantResponse(streamText({
  ...defaults,
  model: mistral('mistral-large-latest'),
  messages: await convertToModelMessages(messages),
  instructions: `${defaults.instructions}

**Extra instructions:**
- Always mention the minimum supported version
- Never speculate about the roadmap`
}))

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