AI Documentation Agent

What the AI Documentation Agent is

The AI Documentation Agent is a workspace-aware writing assistant built directly into the Web Editor. It helps you draft new pages, improve existing content, apply Documentation.AI components correctly, and refactor structure while keeping your site configuration in mind.

Where to find it in the Web Editor

You can open the Agent by clicking on the "AI Agent" icon from the bottom right corner of the Editor. When open, it displays a conversational panel where you can request changes.

Core capabilities

The Agent focuses on practical, page-level actions that accelerate your writing flow.

Draft new pages

You can ask the Agent to create structured content aligned to your component patterns. Useful prompt styles include:

• Draft a high-level overview of authentication options using clear sections and a Callout.

• Create a conceptual introduction to our API docs with Tabs for language variations.

• Turn these raw notes into a well‑structured guide with Columns and Cards.

• Generate a clean MDX draft for a new page that follows existing heading patterns.

Rewrite and edit existing content

The Agent can revise the current page while preserving structure, improving clarity, or applying components more consistently.

• Rewrite this section for clarity and shorten sentences without changing the technical meaning.

• Refactor this page so that it begins with context, then prerequisites, then a Steps section.

• Improve the flow of this page while keeping all technical details intact.

Apply Documentation.AI components

You can ask the Agent to add Cards, Columns, Steps, Mermaid diagrams, Tabs, Callouts, Expandables, and more.

Generate API documentation and code samples

The Agent can help you write request and response examples, create structured ParamField or ResponseField sections, or draft introductions for endpoints already imported via OpenAPI.

• Generate a client-side fetch sample for this POST endpoint.

• Write a Python example for the same request.

• Add ParamField and ResponseField examples for this endpoint.

const res = await fetch("/v1/payments", {
  method: "POST"
});

import requests
res = requests.post("/v1/payments")

Restructure and refactor pages

If a page has grown too long or disorganized, ask the Agent to propose a more readable flow. It can:

• Identify sections to split.

• Suggest consistent heading hierarchy.

• Highlight missing prerequisite or context sections.

• Apply component-based layouts to replace long text blocks.

Example prompts you can use immediately

Below are practical prompts tailored for Web Editor flows.

• Here are my raw notes. Turn them into a clean conceptual page using Callout and Columns components.

• Check this page for component errors and rewrite with valid MDX.

• Summarize this section and keep only essential details.

Limitations to keep in mind

The Agent is in active beta. Treat its output as a strong starting point, not a final draft.

Credit usage

Most tasks use a small number of credits. More complex multi-section rewrites or full-page drafts may cost more. For details, see the AI Credits page.

When to use the Agent vs editing manually

Use the Agent when:

• You want a first draft quickly.

• You need structural help or component rewrites.

• You want examples, API sections, or improved clarity.

• You are refactoring a page and want suggestions.

Edit manually when:

• You are making small fixes or micro-adjustments.

• You need pixel-perfect formatting or subtle wording changes.

• The page contains project-specific details the Agent is not aware of.