AI-агент

Зачем это нужно

Полнотекстовый поиск (см. Search) отвечает на
вопрос «где в документации встречается слово». Это быстро и
полезно, но часто нужно большее:

AI-агент Nextdocs — это разговорный помощник, который умеет
читать вашу документацию и код, отвечать, и действовать:
создавать и редактировать страницы, если вы его об этом попросите.

Код репозиториев агент не редактирует — он только читает.
Документация — его scope для изменений.

Как открыть

Что умеет агент

1. Поиск и ответы

Работает как умный поиск по вашим проектам:

Примеры вопросов:

2. Создание страниц

Попросите агента написать новую страницу — он создаст.

Примеры команд:

Что происходит:

  1. Агент формулирует структуру страницы.

  2. Пишет черновик на основе существующей документации и кода.

  3. Показывает вам превью: «Я собираюсь создать страницу X с
    таким-то содержимым. Подтвердить?»

  4. Вы жмёте Apply — страница создаётся. Или Reject — ничего
    не происходит.

Созданная страница попадает в историю как действие «agent_create»,
авторство — «Agent (via @your-name)». Вы всегда можете откатить.

3. Редактирование страниц

Попросите агента изменить существующую страницу.

Примеры команд:

Flow тот же: превью → подтверждение → применение. Агент всегда
показывает diff (что было vs что станет) перед тем как что-то
менять. Вы видите изменения построчно с подсветкой.

Изменения попадают в историю страницы как agent_update записи.
Rollback работает обычным способом (см. History).

4. Структурные операции

Агент может:

Все структурные изменения требуют явного подтверждения.

5. Поиск и извлечение

Эти задачи обычно идут без подтверждения — это read-only.

Что агент НЕ делает

Жёсткие границы — чтобы не сломать вашу систему:

Подтверждения действий

Когда агент собирается что-то сделать — показывает:

┌────────────────────────────────────────────────────┐
│ 📝 Update page «Auth flow»                         │
│                                                    │
│ Diff preview:                                      │
│ - Our JWT tokens rotate every 15 minutes...        │
│ + Our OAuth 2.0 access tokens rotate every 15      │
│ + minutes. Refresh tokens are issued on login...   │
│                                                    │
│ [✓ Apply] [✗ Reject] [✎ Edit before applying]     │
└────────────────────────────────────────────────────┘

Варианты:

Batch-операции

Если агент делает несколько операций за раз («создай 5 страниц» или
«обнови все упоминания X в 8 местах»), он показывает список
изменений и позволяет:

Цитирование источников

Как и обычный чат, агент всегда ссылается на то, откуда взял
факты:

Согласно странице "Release process" [1], релизы выпускаются по
вторникам. В момент выпуска автоматически обновляется changelog [2].

Sources:
[1] Release process — /projects/42/17
[2] Changelog automation — /projects/42/23

Клик на [1] / [2] — переход на страницу, подсветка цитируемого
фрагмента.

Если ответа в документации нет — прямо говорит: «В вашей
документации я не нашёл ответа на X. Предлагаю [создать страницу
про X] — могу сам набросать черновик по коду в репозитории?»

Как устроено под капотом

  1. Retrieval. Ваш запрос векторизуется, из всех страниц
    проекта + репозиториев выбираются наиболее релевантные
    фрагменты.

  2. Reasoning. LLM получает контекст + вопрос + список
    доступных инструментов (create_page, update_page, move_page,
    search_pages, read_file, etc.).

  3. Planning. Агент решает: ответить текстом или выполнить
    действие. Если действие — формулирует его как tool call.

  4. Preview. Результат возвращается вам как «я собираюсь
    сделать то-то и то-то, подтвердить?»

  5. Execution. После вашего Apply действия выполняются в
    реальном времени. Коллеги видят изменения моментально.

Это архитектура ReAct агента (Reasoning + Acting) с обязательной
фазой подтверждения.

Scope агента

Контекст определяется местом, где вы его открыли:

Изменить scope в середине диалога нельзя — откройте новую сессию.

Память

Агент помнит контекст текущего диалога:

Это позволяет:

Вы: Покажи все страницы про аутентификацию.
Агент: [список 4 страниц]
Вы: Вторую — обнови, она устарела.
Агент: [понимает, о какой именно странице речь]

Тред живёт в пределах одной вкладки. Закрыли / перезагрузили —
новая сессия.

Права и ограничения

Агент выполняет действия от вашего имени:

Агент не может превысить ваши права. Вы не получите admin-
возможностей, попросив «агент, создай мне admin-доступ».

Аудит действий

Все действия агента записываются:

Если агент сломал страницу — это не «потерянная правка», это ровно
такая же history запись, как человеческая.

Примеры диалогов

Длинная задача

Вы: У нас появился новый микросервис billing-reconciliation. В
репе код уже есть, документации нет. Создай стартовую страницу
с разделами Overview, API, Dependencies, Owner.

Агент: Прочитал код сервиса в /repos/billing/billing-reconciliation.
Вижу: Go-сервис, 12 endpoint-ов в /api/v1, зависит от PostgreSQL
и Kafka. Owner не указан в metadata.

Предлагаю создать страницу "Billing Reconciliation" в разделе
"Services" со следующей структурой:

[превью текста страницы]

У кого уточнить owner? Могу оставить placeholder «TBD — см.
@billing-team».

[✓ Apply] [✗ Reject] [✎ Edit before applying]

Многошаговое действие

Вы: Я провёл ретроспективу команды. Создай страницу по шаблону:
разделы Plus, Minus, Action items. И ещё допиши на главной
странице команды ссылку на эту ретро.

Агент: Планирую:
1. Создать «Retro — April 2026» под /projects/platform/retros
2. Добавить ссылку на неё в конце /projects/platform/team-home

Apply all / Apply individually?

[Apply 1+2] [Apply 1] [Apply 2] [Reject]

Честное «не знаю»

Вы: Какой у нас SLA с провайдером хостинга?

Агент: В подключённых мне проектах я не нашёл информации об SLA
с хостингом. Похоже, это либо не задокументировано, либо
находится в приватной папке, к которой у меня нет доступа.

Могу создать черновик страницы «Hosting SLA», если вы
подскажете основные параметры? Или поискать упоминания в коде
инфраструктуры?

Приватность

Ограничения

Отличие от обычного чата в других продуктах

Возможность

Notion AI / Confluence Rovo

Nextdocs Agent

Ответить на вопрос по документации

✅

✅

Создать новую страницу по запросу

⚠️ в контексте writing

✅

Редактировать существующие страницы

⚠️ авто-suggestions

✅ с diff + подтверждением

Читать код из репозитория

❌

✅

Batch-операции с подтверждением

❌

✅

Audit log действий

⚠️

✅ полный

«Не знаю» вместо галлюцинаций

⚠️

✅ явно

Цитаты на источники

⚠️

✅ всегда

Типовые сценарии

Онбординг сотрудника. Новый инженер спрашивает: «как у нас
устроен процесс code review?». Получает связный ответ с ссылками.
Следом: «а где FAQ по этому?». Агент: «FAQ нет — могу создать,
собрав из комментариев в прошлых PR?» → создаёт.

Документирование нового сервиса. «Создай страницу для
билинга-reconciliation на основе кода». Агент читает репу,
генерирует черновик, вы корректируете, Apply.

Массовое обновление. «Мы переходим с JWT на OAuth 2.0. Найди
и обнови все упоминания JWT в документации на OAuth 2.0, сохраняя
смысл». Агент находит 12 мест, показывает diff каждого,
подтверждаете. 10 минут работы вместо часа.

Поиск ответа в истории решений. «Почему мы выбрали BigQuery,
а не Redshift?» — находит ADR, объясняет.

Структурная чистка. «Найди страницы, которые не обновлялись
больше года, и предложи их архивировать или удалить». Получаете
список с рекомендациями, решаете по каждой.