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, Boards, 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")

Keep docs aligned with code changes

When you use the GitHub Integration and connect context repositories to a project, the Agent can use code files and recent commits from those repositories as context while editing your docs.

Point the Agent at the relevant change by sharing a commit URL, PR link, or commit hash in your prompt, or by pasting a short diff or summary. Then ask it to update or propose changes to the affected documentation pages.

Example prompts:

• Refer the new commit adds a new``* endpoint in our context repo. Draft a new reference page that matches the style of our existing team endpoints.*

• Use the latest commit to update parameter descriptions for* and call out the new** field in a Callout.*

• Review this PR that changes how rate limits work and suggest updates to the rate limits and error codes documentation.

Attach files for additional context

You can attach files directly to your Agent conversation to give it more context about your product, codebase, or existing content. This is useful when you want the Agent to reference specific material while drafting or editing pages.

To attach a file, click the 📎 icon next to the message input, select one or more files from your device, and send your message. The Agent reads the content of attached files and uses it to produce more accurate documentation.

Supported file types

Limits

• Up to 20 files per conversation.

• Attachments are kept for 30 days, then removed automatically.

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.

Review AI agent suggested changes

When the Agent proposes updates, you can review them before they become real edits in your docs.

Use the review flow to:

• Accept or reject suggested changes one file at a time.

• Accept all or reject all suggestions in one action.

• Review suggested file operations such as create, delete, rename, and move, not only content edits.

For content pages, suggested edits can be reviewed in a visual diff. Other file types use a code diff.

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

please see the AI Credits page for details

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.

• You want to align docs with recent code changes from connected context repositories.

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.