Skip to main content

AI Assistant Setup

Ask the Docs configuration

The phase-1 docs assistant uses an API route plus `OPENAI_API_KEY`. It is designed as a lightweight routing and summarization tool for the docs site, not as a replacement for the curated information architecture.

What it needs

  • an `OPENAI_API_KEY` environment variable
  • a runtime that supports the API route
  • the docs site build plus serverless execution in Vercel

Required environment variable​

OPENAI_API_KEY=your_key_here

Local and preview runtime note​

The assistant calls /api/ask-the-docs.

  • In local development, npm start launches both the docs site and a local Ask the Docs API.
  • In deployed environments, the page uses the Vercel serverless route.

If you see a 404 plus an error like Unexpected token '<', the browser is receiving an HTML 404 page instead of JSON from the API route.

Recommended local workflow:

npm start

That starts:

  • the normal Docusaurus dev server
  • a local Ask the Docs API at http://127.0.0.1:8787

The page automatically uses the local AI API in that workflow.

If you want the docs site without the local AI helper, use:

npm run start:docs

npm run dev:ai remains available as an alias for the combined local workflow.

If you want to test the production-style serverless route specifically, use:

vercel dev

If you run into local function errors, make sure the repo has installed dependencies and the local TypeScript configuration is usable by Vercel's function runtime.

What the assistant does in phase 1​

Good at

This first version is best used as a docs router and summary layer.

  • answering high-level questions about how the product works
  • routing readers to product versus operations docs
  • summarizing where to start by audience or task
Not for

The assistant should not be treated as the source of truth over the docs themselves.

  • security policy decisions
  • final rollout readiness decisions
  • exact implementation details when code-local docs differ

Decision

Recommended usage

Use `Ask the Docs` to get oriented quickly, then open the linked product or operations pages for the authoritative human-curated answer.