Команда kapa.ai дала продуктовому агенту около 30 специализированных инструментов и один поиск по документации. По итогам 1 192 пользовательских диалогов поиск по базе знаний оказался самым востребованным инструментом — почти на уровне всех остальных вместе взятых.
Это не доказывает, что каждому агенту достаточно подключить RAG и забыть о качественных API. Но наблюдение хорошо показывает слепую зону типичной агентной архитектуры: схема инструмента объясняет, как вызвать функцию, но редко объясняет, что означает результат и когда этой функцией стоит пользоваться.
Что именно проверяла команда
Агент работал внутри продукта и отвечал на вопросы об аналитике: искал диалоги, строил графики, показывал настройки интеграций. Для этого у него были нативные инструменты вроде search_conversations и display_chart.
Отдельный search_knowledge_base читал документацию, примеры кода, FAQ поддержки и API reference. Авторы ожидали, что он станет запасным выходом для редких справочных вопросов. На практике документация выполняла сразу три разные задачи.
Роль № 1. Документация закрывает непредусмотренные вопросы
В 32,1% изученных диалогов поиск по базе знаний работал как fallback. Пользователи спрашивали не только об аналитике, для которой создавался агент, но и о настройке Slack, ошибках CORS или периодичности индексации сайта.
Ни один узкий инструмент не покрывал эти темы. Без документации агенту оставалось бы отказаться от ответа или достроить его по косвенным признакам. Второй вариант особенно опасен: уверенный текст легко принять за фактическое состояние продукта.
Отсюда первый практический вывод: границы агента определяются не его системным промптом, а ожиданиями пользователя. Если чат расположен внутри продукта, человек будет спрашивать обо всём продукте. Архитектура должна предусматривать честный справочный маршрут за пределами основного сценария.
Роль № 2. Инструмент сообщает состояние, документация — смысл
Примерно в 7% диалогов агент использовал и нативные инструменты, и базу знаний. Это небольшая доля, но именно она показывает правильное разделение ответственности.
Допустим, пользователь спрашивает, какой тип MCP-интеграции у него настроен и чем он отличается от других вариантов. list_integrations может вернуть текущее состояние аккаунта. Но сравнение типов интеграций, ограничения и рекомендуемые сценарии хранятся в документации.
Получается двухслойный ответ:
- инструмент возвращает актуальный факт о конкретном окружении;
- документация объясняет термин, последствия и доступные альтернативы.
Смешивать эти слои в одном источнике неудобно. Если зашить длинные продуктовые объяснения в tool description, контекст раздуется, а обновлять его станет трудно. Если оставить агенту только документацию, он не узнает живое состояние аккаунта.
Роль № 3. Документация помогает выбрать правильный инструмент
Самый интересный сценарий возник, когда документация понадобилась не для финального ответа, а для планирования.
Пользователь попросил найти диалоги с негативной тональностью. В продукте не существовало ни поля sentiment, ни соответствующего фильтра. Агент мог выдумать параметр или сообщить, что задача невозможна. Вместо этого он прочитал документацию, выяснил, что негативные сигналы отражаются через дизлайки и комментарии обратной связи, а затем построил корректный запрос существующим инструментом.
Здесь база знаний работает как семантический адаптер между языком пользователя и моделью данных. Пользователь говорит о «негативе», продукт хранит downvote и feedback_comment, а документация связывает эти два представления.
Это важнее обычного RAG-ответа. Агент не пересказывает найденный фрагмент, а использует его, чтобы составить проверяемый план действий.
Какая архитектура из этого следует
Для продуктового или внутреннего инженерного агента полезно разделить четыре контура:
- живое состояние — узкие read-only инструменты с понятными схемами;
- действия — отдельные mutation-инструменты с preconditions, approval и idempotency;
- семантика продукта — версия документации, соответствующая текущему API;
- политика — явные ограничения, определяющие, какие действия агенту разрешены.
Документация не должна подменять policy engine. Найденная в статье инструкция «удалите ресурс» не даёт агенту права выполнять удаление. Точно так же текст в базе знаний не должен считаться доказательством текущего состояния: для этого нужен read-back через API или другой источник истины.
Хорошая последовательность выглядит так:
- агент классифицирует запрос и определяет, достаточно ли ему схемы инструмента;
- при терминологической или продуктовой неоднозначности ищет релевантный раздел документации;
- строит типизированное действие;
- детерминированный слой проверяет схему, права и preconditions;
- после выполнения агент сверяет фактический результат.
Что подготовить команде документации
Подключить существующий сайт к поиску недостаточно. Документация для агентов должна быть пригодна не только для чтения человеком, но и для выбора действий.
Минимальный набор:
- стабильные заголовки и якоря;
- явные названия сущностей и соответствующие им поля API;
- отдельные разделы «когда использовать» и «когда не использовать»;
- примеры ошибок и способы отличить похожие состояния;
- версия документации и дата актуальности;
- ссылки из концептуальных страниц на точную API reference;
- описание последствий mutation, а не только happy path.
Полезно также измерять, какие поисковые запросы приводят агента к отказу или неверному tool call. Такой журнал превращает реальные диалоги в очередь улучшений для документации и тестовый набор для агента.
Где заканчивается доказательство
Числа kapa.ai нельзя автоматически переносить на любой продукт. Это данные одной команды, одного интерфейса и 1 192 разговоров; подробной независимой методологии или разметки всех категорий авторы не публикуют. Кроме того, сам поставщик развивает инструменты для поиска по документации, поэтому источник заинтересован в результате.
Но наблюдение можно проверить локально без большой программы исследований. Добавьте агенту отдельный docs-инструмент, логируйте причину его вызова и разберите хотя бы первые 100–200 реальных сессий. Важно различать три класса: ответ пользователю, объяснение результата нативного инструмента и подготовка следующего действия.
Если третий класс встречается регулярно, документация уже стала частью оркестратора. Значит, её версионирование, наблюдаемость и качество нужно оценивать так же серьёзно, как схемы API.