Assistant

À propos de l'Assistant

L'assistant répond aux questions sur votre documentation via des requêtes en langage naturel. Il est intégré directement dans votre site de documentation, permettant aux utilisateurs de trouver rapidement des réponses.

Lorsque les utilisateurs posent des questions, l'assistant :

• Recherche et récupère le contenu pertinent de votre documentation en utilisant un serveur MCP.
• Cite les sources avec des liens navigables vers les pages référencées.
• Génère des exemples de code copiables pour aider les utilisateurs à implémenter les solutions.

Comment ça fonctionne

L'assistant utilise une architecture multi-agents :

1. Agent principal - Reçoit les questions des utilisateurs et décide quand rechercher dans la documentation
2. Agent de recherche - Utilise les outils du serveur MCP pour trouver le contenu pertinent
3. Génération de réponse - Synthétise les informations en réponses utiles et conversationnelles

Par défaut, l'assistant se connecte au serveur MCP intégré de votre documentation à /mcp, lui donnant accès à toutes vos pages sans configuration supplémentaire. Vous pouvez également vous connecter à un serveur MCP externe si nécessaire.

Démarrage rapide

1. Configurer l'authentification AI Gateway

Choisissez une de ces méthodes :

Clé API : créez une clé dans Vercel AI Gateway et ajoutez-la à votre environnement :

AI_GATEWAY_API_KEY=votre-cle-api

OIDC (uniquement sur Vercel) : VERCEL_OIDC_TOKEN est injecté automatiquement, il n'y a donc rien à ajouter en production. En local, lancez vercel env pull sur un projet lié.

2. Déployer

Déployez votre site, l'assistant est disponible dès que l'authentification est configurée.

Utiliser l'Assistant

Les utilisateurs peuvent interagir avec l'assistant de plusieurs façons :

Input flottant

Sur les pages de documentation, un champ de saisie flottant apparaît en bas de l'écran. Les utilisateurs peuvent taper leurs questions directement et appuyer sur Entrée pour obtenir des réponses.

Expliquer avec l'IA

Chaque page de documentation inclut un bouton Explain with AI dans la barre latérale de la table des matières. Cliquer sur ce bouton ouvre l'assistant avec la page actuelle comme contexte.

Chat en panneau latéral

Lorsqu'une conversation commence, un panneau coulissant s'ouvre sur le côté droit de l'écran. Ce panneau affiche l'historique de la conversation et permet aux utilisateurs de continuer à poser des questions.

Configuration

Configurez l'assistant via app.config.ts :

export default defineAppConfig({
  assistant: {
    // Afficher l'input flottant sur les pages de documentation
    floatingInput: true,

    // Afficher le bouton "Expliquer avec l'IA" dans la barre latérale
    explainWithAi: true,

    // Questions FAQ à afficher quand le chat est vide
    faqQuestions: [],

    // Raccourcis clavier
    shortcuts: {
      focusInput: 'meta_i'
    },

    // Icônes personnalisées
    icons: {
      trigger: 'i-lucide-sparkles',
      explain: 'i-lucide-brain'
    }
  }
})

Questions FAQ

Affichez des questions suggérées quand le chat est vide. Cela aide les utilisateurs à découvrir ce qu'ils peuvent demander.

Format simple

export default defineAppConfig({
  assistant: {
    faqQuestions: [
      'Comment installer Docus ?',
      'Comment personnaliser le thème ?',
      'Comment ajouter des composants à mes pages ?'
    ]
  }
})

Format avec catégories

Organisez les questions en catégories :

export default defineAppConfig({
  assistant: {
    faqQuestions: [
      {
        category: 'Démarrage',
        items: [
          'Comment installer Docus ?',
          'Quelle est la structure du projet ?'
        ]
      },
      {
        category: 'Personnalisation',
        items: [
          'Comment changer les couleurs du thème ?',
          'Comment ajouter un logo personnalisé ?'
        ]
      }
    ]
  }
})

Format multilingue

Pour une documentation multilingue, fournissez les questions FAQ par locale :

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

Raccourcis clavier

Configurez le raccourci clavier pour activer l'input flottant :

export default defineAppConfig({
  assistant: {
    shortcuts: {
      // Par défaut : 'meta_i' (Cmd+I sur Mac, Ctrl+I sur Windows)
      focusInput: 'meta_k' // Changer pour Cmd/Ctrl+K
    }
  }
})

Le format de raccourci utilise des underscores pour séparer les touches. Exemples courants :

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

Icônes personnalisées

Personnalisez les icônes utilisées par l'assistant :

export default defineAppConfig({
  assistant: {
    icons: {
      // Icône pour le bouton déclencheur et l'en-tête du panneau
      trigger: 'i-lucide-bot',

      // Icône pour le bouton "Expliquer avec l'IA"
      explain: 'i-lucide-lightbulb'
    }
  }
})

Les icônes utilisent le format Iconify (ex: i-lucide-sparkles, i-heroicons-sparkles).

Internationalisation

Tous les textes de l'interface sont automatiquement traduits selon la locale de l'utilisateur. Docus inclut des traductions intégrées pour l'anglais et le français.

Les textes suivants sont traduits :

• Titre et placeholder du panneau
• Textes des infobulles
• Libellés des boutons ("Effacer le chat", "Fermer", "Expliquer avec l'IA")
• Messages de statut ("Réflexion...", "Le chat est effacé au rechargement")

Désactiver des fonctionnalités

Désactiver l'input flottant

Masquez l'input flottant en bas des pages de documentation :

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

Désactiver "Explain with AI"

Masquez le bouton "Explain with AI" dans la barre latérale de documentation :

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

Désactiver l'assistant entièrement

Passez enabled à false pour désactiver l'assistant, même quand des identifiants AI Gateway sont disponibles :

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

L'assistant est aussi désactivé quand aucune authentification n'est disponible : supprimer AI_GATEWAY_API_KEY de votre environnement a donc le même effet :

# AI_GATEWAY_API_KEY=votre-cle-api

Sur Vercel avec OIDC, supprimez la variable d'environnement système auto-injectée dans les paramètres de votre projet.

Configuration avancée

Configurez les options avancées dans nuxt.config.ts sous docus.assistant.

export default defineNuxtConfig({
  docus: {
    assistant: {
      // Force l'activation ou la désactivation de l'assistant
      // Par défaut, détection automatique via les identifiants AI Gateway
      enabled: true,

      // Modèle IA (utilise le format AI SDK Gateway)
      model: 'google/gemini-3-flash',

      // Serveur MCP (chemin ou URL)
      mcpServer: '/mcp',

      // Chemin de l'endpoint API
      apiPath: '/__docus__/assistant'
    }
  }
})

Configuration du serveur MCP

L'assistant utilise un serveur MCP pour accéder à votre documentation. Vous avez deux options :

Utiliser le serveur MCP intégré (par défaut)

Par défaut, l'assistant utilise le serveur MCP intégré de Docus à /mcp :

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

Utiliser un serveur MCP externe

Connectez-vous à n'importe quel serveur MCP externe en fournissant une URL complète :

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

C'est utile lorsque vous voulez que l'assistant réponde aux questions d'une autre source de documentation, ou lors de la connexion à une base de connaissances centralisée.

Modèle IA personnalisé

L'assistant utilise google/gemini-3-flash par défaut. Vous pouvez le changer pour n'importe quel modèle supporté par AI SDK Gateway :

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

Fournisseur IA personnalisé

L'option model ci-dessus résout les modèles via Vercel AI Gateway, elle nécessite donc AI_GATEWAY_API_KEY ou VERCEL_OIDC_TOKEN. Pour utiliser un autre fournisseur (Mistral, OpenAI, Cloudflare AI Gateway, ou tout autre fournisseur supporté par l'AI SDK), activez explicitement l'assistant et fournissez votre propre endpoint.

1. Activer l'assistant et choisir un chemin

Passez enabled à true pour que l'assistant ne dépende plus des identifiants AI Gateway, et faites pointer apiPath vers la route que vous allez créer :

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

Votre route serveur est toujours prioritaire : quand vous définissez une route sur apiPath, Docus s'efface et n'enregistre pas son endpoint intégré à cet emplacement.

2. Installer un fournisseur

Installez le paquet du fournisseur AI SDK dont vous avez besoin, par exemple Mistral :

npm install @ai-sdk/mistral

pnpm add @ai-sdk/mistral

yarn add @ai-sdk/mistral

3. Implémenter l'endpoint

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

L'intégration s'arrête là : la recherche dans la documentation, le streaming et la gestion de l'annulation continuent de fonctionner, et tous les paramètres du modèle sont à vous.

Docus n'expose délibérément pas ces éléments sous forme d'options : les paramètres de modèle ne sont pas portables, donc toute liste serait incomplète pour un fournisseur ou un autre. Ce qu'il expose, c'est la plomberie que vous ne devriez pas avoir à copier-coller, sous forme d'utilitaires serveur auto-importés :

getAssistantDefaultOptions

Retourne de vraies options streamText : vous voyez et pouvez surcharger chacune d'elles.

model et messages ne sont pas inclus, pas plus que les options spécifiques au fournisseur comme providerOptions ou temperature, puisqu'elles ne sont pas portables.

Surchargez en définissant l'option après le spread :

return createAssistantResponse(streamText({
  ...await getAssistantDefaultOptions(event),
  model: mistral('mistral-large-latest'),
  // Gagne sur le 8000 par défaut
  maxOutputTokens: 4000,
  messages: await convertToModelMessages(messages)
}))

Pour ajouter du comportement à un callback plutôt que le remplacer, gardez une référence et rappelez-le, afin que la fermeture MCP ait toujours lieu :

const defaults = await getAssistantDefaultOptions(event)

return createAssistantResponse(streamText({
  ...defaults,
  model: mistral('mistral-large-latest'),
  messages: await convertToModelMessages(messages),
  onError: (payload) => {
    monRapporteurDErreurs(payload.error)
    // Ferme quand même le client MCP
    defaults.onError(payload)
  }
}))

getAssistantSystemPrompt

getAssistantDefaultOptions définit déjà ce prompt comme instructions : cet utilitaire ne sert donc qu'à l'étendre. Il retourne une simple chaîne, donc concaténez :

const defaults = await getAssistantDefaultOptions(event)

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

**Instructions supplémentaires :**
- Toujours mentionner la version minimale supportée
- Ne jamais spéculer sur la roadmap`
}))

Définissez instructions avec votre propre chaîne pour remplacer le prompt entièrement.

createAssistantResponse

Emballe un résultat de streamText dans le format de réponse attendu par l'interface de l'assistant, pour que votre route suive les futurs changements de format sans être modifiée.

Nom du site dans les réponses

L'assistant utilise automatiquement le nom de votre site dans ses réponses. Configurez le nom du site dans nuxt.config.ts :

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

Cela permet à l'assistant de répondre en tant qu'"assistant de Ma Documentation" et de parler avec autorité sur votre produit spécifique.

Accès programmatique

Utilisez le composable useAssistant pour contrôler l'assistant programmatiquement :

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

function askQuestion() {
  // Ouvrir l'assistant avec une question pré-remplie
  open('Comment configurer le thème ?', true)
}
</script>

<template>
  <UButton v-if="isEnabled" @click="askQuestion">
    Demander sur les thèmes
  </UButton>
</template>

API du composable