AIREITERАгент для программирования вполне может распарсить страницу Google для разработчиков. Но тогда на него ложатся поиск нужных страниц, зависимость от вёрстки, устранение дублей и работа с цитатами. Google Developer Knowledge API прячет эти задачи за документированным интерфейсом. Если агенту нужна актуальная документация Google с проверяемыми источниками, это предпочтительный вариант — с важной оговоркой: API работает с отобранным корпусом, а не со всем вебом для разработчиков Google.
Это API для поиска знаний, а не для выполнения действий
Google Developer Knowledge API предоставляет публичную документацию Google для разработчиков в машиночитаемом виде. В REST-справочнике Google описаны поиск по документам, получение документа целиком, пакетное получение и ответы с опорой на источники.
Сервис даёт приложению или агенту контекст в режиме только для чтения. Он не открывает доступ к приватному проекту Cloud, не подтверждает изменение IAM, не развёртывает код и не проверяет безопасность сгенерированной команды. Для любых операций записи агенту по-прежнему нужны отдельные учётные данные и контроль со стороны политик.
Границы корпуса здесь принципиальны. Согласно документации API, сервис охватывает публичную документацию для разработчиков, а не весь интернет. Он не заменяет поиск по произвольным репозиториям GitHub, Stack Overflow, закрытым runbook-инструкциям или сторонним библиотекам. Google также отмечает, что возвращаемый Markdown генерируется из исходного HTML, поэтому он не обязан побайтно совпадать с отрисованной страницей.
Текущую доступность и поведение сервиса сверяйте по официальному справочнику API и журналу изменений.
Какие операции есть в Google Developer Knowledge API
REST-интерфейс достаточно компактный, чтобы напрямую описать его в политике агента:
| Операция | Что возвращает | Когда использовать |
|---|---|---|
SearchDocumentChunks | Подходящие фрагменты и ресурсы родительских документов | Искать подтверждения и страницы-кандидаты |
GetDocument | Один полный документ в Markdown | Дать агенту контекст всей страницы |
BatchGetDocuments | Несколько полных документов | Сопоставить связанные страницы или прогреть локальный кэш |
AnswerQuery | Ответ с опорой на источники и ссылками на них | Ответить на ограниченный вопрос по документации |
Результаты поиска — это фрагменты, а не обязательно страницы целиком. Ресурс parent в результате служит указателем для GetDocument или BatchGetDocuments. Надёжный клиент сначала группирует повторяющиеся фрагменты по родительскому документу и только затем запрашивает страницы. Иначе одна страница займёт несколько слотов выдачи, почти не добавив контекста.
Типичное имя ресурса выглядит так, как описано в формате ресурсов документов:
documents/docs.cloud.google.com/storage/docs/creating-bucketsЭтот шаблон имени полезен после поискового ответа, однако агенту лучше использовать точное значение parent, которое вернул сервис, а не составлять имя по памяти.
Режимы поиска задают разный уровень доказательности
SearchDocumentChunks — режим, в котором на первом месте стоят подтверждения. Выбирайте его, когда агенту нужны точный флаг, параметр, разрешение, примечание о версии или фрагмент кода. Вызывающая сторона может проверить фрагмент, сохранить URI документа и решить, нужно ли загружать страницу полностью.
GetDocument и BatchGetDocuments нужны для получения контекста. Используйте их после поиска, если ответ зависит от предварительных условий, предупреждений, заметок о миграции или соседних разделов, которых может не оказаться в одном фрагменте. Пакетное получение особенно удобно, когда вопрос по архитектуре затрагивает несколько официальных страниц.
AnswerQuery — режим синтеза. Он подходит для ограниченного вопроса вроде «Какой из актуальных вариантов Google Cloud соответствует этим ограничениям?», когда ответ должен опираться на корпус документации. Но беглый и убедительно написанный ответ нельзя принимать без проверки ссылок. Для рискованных изменений в коде связка поиска и получения полного документа оставляет агенту более прозрачную цепочку подтверждений.
Аутентификация: отталкивайтесь от типа клиента
На практике есть три схемы аутентификации, и каждая рассчитана на своего вызывающего клиента.
| Клиент | С чего начать | Почему |
|---|---|---|
| Локальный curl или быстрый прототип | Ограниченный API-ключ | Самый быстрый путь к первому запросу |
| Бэкенд, воркер или Python-клиент | Application Default Credentials (ADC) | Учётные данные остаются в среде выполнения, а не в исходном коде |
| Интерактивный MCP-клиент | OAuth, если его поддерживает хост; иначе ограниченный ключ | Не приходится раздавать один долгоживущий ключ пользовательским инструментам |
Для быстрого старта создайте или выберите проект Google Cloud, включите developerknowledge.googleapis.com и создайте API-ключ, ограниченный Developer Knowledge API. Не размещайте неограниченный ключ в промпте агента, репозитории, клиентской сборке или отладочном логе.
Минимальная команда для включения сервиса:
gcloud services enable developerknowledge.googleapis.com \
--project="$PROJECT_ID"Для управляемого приложения ADC обычно создаёт более чистую границу. В справочнике Python-клиента Google описаны учётные данные, обнаруживаемые через окружение, а также синхронные и асинхронные клиенты. При таком подходе идентичность задаёт окружение развёртывания, а приложению не приходится извлекать ключ из конфигурационного текста.
OAuth хорошо подходит интерактивному агенту: подключение разрешает пользователь, а не общий статический секрет. Конкретный OAuth-поток зависит от MCP-хоста. Поддержку аутентификации в клиенте нужно проверять отдельно от самого API: клиент, принимающий MCP URL, может по-разному работать с заголовками, переменными секретов и обновлением токенов.
Минимальный сценарий получения данных
В production-агенте границу получения контекста стоит сделать явной:
- Уберите из вопроса секреты и несвязанный контент репозитория.
- Выполните поиск по официальному корпусу через
SearchDocumentChunks. - Устраните дубли, сгруппировав результаты по ресурсу родительского документа.
- Получите наиболее релевантные полные документы, если задаче нужен окружающий контекст.
- Сохраните возвращённые URI, заголовок, временную метку или метаданные, а также выбранные выдержки.
- Поручите модели отвечать только на основе сохранённых подтверждений.
- Перед изменением кода или инфраструктуры запустите тесты и проверки политик.
REST-эндпоинт поиска указан в REST-справочнике Google:
GET https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunksПростой запрос с API-ключом выглядит так:
curl --get \
'https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks' \
--data-urlencode 'query=Cloud Storage bucket retention policy' \
--data-urlencode 'pageSize=5' \
--data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"Перед тем как жёстко зафиксировать парсер, сверьте актуальную схему ответа и названия полей с текущим REST-справочником. Поиск возвращает фрагменты и имена родительских документов, а получение документов использует эти имена.
Проверяйте агента на замокированных или сохранённых ответах: пустая выдача, отсутствие родительских ресурсов, пагинация, ошибки аутентификации, превышение квот и ограничение частоты запросов. Повторные попытки должны быть вне промпта модели, с ограниченной задержкой между попытками и понятным запасным сценарием на случай, когда подтверждения получить не удалось.
Прямой API, MCP или веб-страница?
Один и тот же источник документации можно предоставить тремя способами:
| Ситуация | Оптимальный путь | Причина |
|---|---|---|
| Сервису нужно воспроизводимое получение данных и цитаты | REST API или клиентская библиотека | Приложение контролирует разбор, кэширование и хранение подтверждений |
| Ассистенту для программирования нужен контекст Google по запросу | Developer Knowledge MCP server | Агент вызывает инструменты поиска и получения данных без дополнительной обвязки |
| Страница находится за пределами поддерживаемого корпуса | Прямой доступ к странице или отдельный коннектор источника | Корпус Developer Knowledge не ответит за отсутствующие источники |
| Человек изучает вёрстку, навигацию или интерактивные примеры | Доступ через браузер или страницу | Получение Markdown не заменяет визуальную проверку страницы |
В документации MCP Google указан эндпоинт https://developerknowledge.googleapis.com/mcp. MCP — это адаптер для агента, а не отдельная база знаний. Примерная конфигурация удалённого сервера выглядит так:
{
"mcpServers": {
"google-developer-knowledge": {
"serverUrl": "https://developerknowledge.googleapis.com/mcp",
"headers": {"x-goog-api-key": "${DEVELOPERKNOWLEDGE_API_KEY}"}
}
}
}Используйте синтаксис переменных секретов, который документирован для конкретного хоста; не рассчитывайте, что буквальная подстановка ${...} сработает везде. Не менее важен и вопрос стоимости контекста: если давать агенту все инструменты для каждой задачи, растёт объём их описаний и нагрузка на выбор действия. Один из участников обсуждения о конфигурациях агентов с несколькими серверами сформулировал это прямо:
«MCP потребляют значительно больше контекста, чем skills: последние занимают лишь несколько строк, пока их не вызовут». — u/junlim, обсуждение на Reddit
Это аргумент в пользу условного подключения Developer Knowledge MCP server для задач, связанных с Google, а не повод полностью от него отказываться. Агенту, работающему с Firebase, Android, Google Cloud, Maps или Flutter, источник будет полезен; агенту, который редактирует несвязанный стек, не стоит вызывать его по умолчанию.
Когда API лучше скрапинга документации Google
Выбирайте API, если выполняется большинство следующих условий:
- Задача относится к документации Google для разработчиков.
- Агенту нужен воспроизводимый поиск, а не разовое получение одной страницы.
- Ответу необходимы цитаты или сохранённая цепочка источников.
- Агент должен отличать релевантный фрагмент от полного документа.
- В сценарии нужны структурированные пагинация, пакетная обработка или кэширование.
- Редизайн страниц не должен требовать нового HTML-парсера.
Скрапинг всё же остаётся разумным запасным вариантом. Используйте его, когда нужная страница не входит в поддерживаемый корпус, когда задача требует визуального взаимодействия или важны точный отрисованный HTML и состояние навигации. Скрапинг также годится как временная проверка во время инцидента, если API недоступен, но не должен незаметно превращаться в production-контракт для получения данных.
| Фактор выбора | Developer Knowledge API | Скрапинг страницы для разработчиков |
|---|---|---|
| Поиск | Поиск сервиса по его индексированному корпусу | Нужно организовать поиск или начать с известного URL |
| Результат | Фрагменты, ресурсы документов и Markdown | HTML или содержимое отрисованной страницы |
| Работа с цитатами | Родительский ресурс и URI документа заданы явно | Приложение само извлекает и сохраняет ссылки |
| Поддержка вёрстки | Границей служит контракт API | Селекторы могут сломаться после редизайна |
| Покрытие | Поддерживаемый публичный корпус для разработчиков | Любая публично доступная страница с учётом правил доступа и robots |
| Визуальная точность | Не является целью | При браузерной автоматизации можно сохранить отрисованную вёрстку |
| Управление агентом | Найти, получить, затем синтезировать | Обычно получить, распарсить, очистить и интерпретировать |
API не гарантирует, что каждая только что опубликованная страница мгновенно появится в выдаче. В журнале изменений Google описаны обновления индексации, однако агенту следует проверять актуальность, а не считать, что новейшая страница уже проиндексирована. Для миграции в день релиза сопоставляйте возвращённые метаданные с текущей официальной страницей и отказывайтесь от действий при отсутствии подтверждений.
Политика для агента, которую я бы внедрил
Для агента по программированию, ориентированного на Google, я бы использовал такие правила маршрутизации:
- Точная деталь реализации: сначала
SearchDocumentChunks; получите родительский документ, если во фрагменте нет предварительных условий. - Вопрос по проектированию, затрагивающий несколько страниц: выполните поиск, затем вызовите
BatchGetDocumentsдля небольшого набора релевантных родительских документов. - Простой пояснительный вопрос: используйте
AnswerQuery, но требуйте ссылки в ответе. - Документация не Google или закрытая документация: направляйте запрос в другой одобренный коннектор.
- Изменение кода или инфраструктуры: получение документации носит рекомендательный характер; тесты, IAM, ревью и средства контроля развёртывания остаются обязательными.
Кэшируйте полные документы там, где это разрешено политиками, подавляйте повторяющиеся поисковые запросы и логируйте URI источников, а не исходные секреты или ненужный контекст репозитория. Считайте полученный Markdown недоверенным вводом: авторитетность источника не делает безопасными все встроенные инструкции для агента с инструментами записи.
Компромисс остаётся простым. API даёт агенту более чистый и проверяемый контракт, чем HTML-скрапинг, но уступает браузеру в покрытии и мгновенной точности отображения страницы. Для поддерживаемой документации Google API стоит сделать вариантом по умолчанию, а скрапинг или другой коннектор оставить явным запасным путём, не смешивая оба подхода незаметно.
FAQ по Google Developer Knowledge API
Developer Knowledge API — это то же самое, что Google Search?
Нет. Это сервис получения документации из поддерживаемого корпуса Google для разработчиков, а не API для поиска по всему интернету. Он не будет автоматически искать в закрытой документации, произвольном содержимом GitHub или на всех страницах, связанных с Google.
Что выбрать: AnswerQuery или SearchDocumentChunks?
Используйте AnswerQuery для ограниченного пояснения с опорой на источники. Выбирайте SearchDocumentChunks, когда агенту нужны проверяемые подтверждения, точный синтаксис или цепочка источников; если фрагмента недостаточно, получите родительский документ.
Обязательно ли нужен API-ключ?
Ограниченный API-ключ — самый быстрый путь для прототипа. Бэкенд-клиенты могут использовать ADC, а интерактивные MCP-интеграции — OAuth, если его поддерживает хост. Не считайте, что способ аутентификации, доступный в одном клиенте, автоматически поддерживается в другом.
Может ли агент разворачивать ресурсы Google Cloud через API?
Нет. API предоставляет контекст документации. Для развёртывания по-прежнему нужны отдельные инструменты, учётные данные, разрешения IAM, подтверждения и проверки.
Когда вместо этого нужен скрапинг?
Используйте скрапинг или браузерный коннектор, если страница находится вне корпуса API, важна визуальная вёрстка или нужна страница, которую индекс ещё не показал. Явно фиксируйте такой запасной путь, чтобы агент не выдавал скрапленный контент за цитату, полученную через API.
Возвращает ли API при поиске страницу целиком?
Нет. Поиск возвращает фрагменты документов. Когда нужна полная Markdown-версия страницы, используйте ресурс родительского документа из ответа с GetDocument или BatchGetDocuments.