AIREITERUn agent de code peut certes scraper une page destinée aux développeurs Google, mais il doit alors gérer lui-même la structure de la page, la découverte des contenus, les doublons et les citations. La Google Developer Knowledge API déporte ces tâches derrière une interface documentée. C’est le meilleur choix par défaut lorsqu’un agent a besoin de documentation Google à jour et traçable — avec une limite importante : son corpus est sélectionné et ne couvre pas l’ensemble du Web destiné aux développeurs Google.
Une API de récupération, pas d’exécution
La Google Developer Knowledge API rend la documentation publique destinée aux développeurs Google exploitable par machine. Google documente la recherche de documents, la récupération d’un document complet, la récupération par lot et les réponses sourcées dans la référence REST.
Ce service fournit du contexte en lecture seule à une application ou à un agent. Il ne donne pas accès à un projet Cloud privé, n’approuve pas une modification IAM, ne déploie pas de code et ne vérifie pas qu’une commande générée est sans risque. Toute opération d’écriture nécessite toujours des identifiants et des contrôles de politique distincts.
La frontière du corpus est déterminante. La documentation de l’API de Google porte sur la documentation publique pour développeurs, et non sur le Web en général. Elle ne remplace pas une recherche dans des dépôts GitHub arbitraires, Stack Overflow, des runbooks privés ou des bibliothèques tierces. Google précise également que le Markdown renvoyé est généré depuis le HTML source : il ne faut donc pas le considérer comme une copie octet pour octet de la page affichée.
Consultez la référence officielle de l’API et les notes de version pour vérifier la disponibilité et le comportement actuels.
Les opérations proposées par la Google Developer Knowledge API
La surface REST est suffisamment réduite pour être modélisée directement dans la politique d’un agent :
| Opération | Ce qu’elle renvoie | Cas d’usage idéal |
|---|---|---|
SearchDocumentChunks | Des extraits correspondants et les ressources de leurs documents parents | Trouver des éléments de preuve et des pages candidates |
GetDocument | Un document complet au format Markdown | Fournir à un agent le contexte de toute une page |
BatchGetDocuments | Plusieurs documents complets | Comparer des pages liées ou préchauffer un cache local |
AnswerQuery | Une réponse sourcée avec des références à l’appui | Répondre à une question ciblée sur la documentation |
Les résultats de recherche sont des extraits, pas nécessairement des pages complètes. La ressource parent d’un résultat sert de relais vers GetDocument ou BatchGetDocuments. Un client robuste regroupe les extraits dupliqués par parent avant de récupérer les pages ; sans cela, une même page peut occuper plusieurs emplacements de récupération tout en apportant peu de contexte supplémentaire.
Un nom de ressource suit généralement le format de ressource de document suivant :
documents/docs.cloud.google.com/storage/docs/creating-bucketsCe modèle de nom de ressource est pratique après une réponse de recherche, mais un agent devrait privilégier la valeur exacte de parent renvoyée par le service plutôt que reconstruire un nom de mémoire.
Chaque mode de recherche correspond à un niveau de preuve
SearchDocumentChunks privilégie les éléments de preuve. Utilisez-le lorsque l’agent recherche un indicateur précis, un paramètre, une autorisation, une note de version ou un fragment de code. L’appelant peut examiner l’extrait, conserver l’URI du document et décider s’il doit récupérer la page complète.
GetDocument et BatchGetDocuments servent à récupérer du contexte. Utilisez-les après une recherche lorsque la réponse dépend de prérequis, d’avertissements, de notes de migration ou de sections voisines qu’un seul extrait peut omettre. La récupération par lot est utile lorsqu’une question d’architecture couvre plusieurs pages officielles.
AnswerQuery est le mode de synthèse. Il convient à une question circonscrite telle que « Quelle option Google Cloud actuelle répond à ces contraintes ? », lorsque la réponse doit s’appuyer sur le corpus. Ce n’est pas une raison d’accepter une réponse fluide sans en vérifier les références. Pour des modifications de code à haut risque, la recherche suivie de la récupération des documents complets offre à l’agent une piste de preuves plus facile à inspecter.
Authentification : adaptez-la à l’appelant
Trois schémas d’authentification sont pratiques, mais ils ne répondent pas aux mêmes besoins.
| Appelant | Point de départ recommandé | Pourquoi |
|---|---|---|
| curl local ou prototype rapide | Clé API restreinte | Le chemin le plus rapide vers une première requête |
| Backend, worker ou client Python | Application Default Credentials (ADC) | Les identifiants restent dans l’environnement d’exécution plutôt que dans le code source |
| Client MCP interactif | OAuth si l’hôte le prend en charge ; sinon une clé restreinte | Évite de distribuer une même clé persistante entre les outils des utilisateurs |
Pour un démarrage rapide, créez ou sélectionnez un projet Google Cloud, activez developerknowledge.googleapis.com, puis créez une clé API limitée à la Developer Knowledge API. Ne placez jamais une clé non restreinte dans le prompt d’un agent, un dépôt, un bundle côté client ou un journal de débogage.
La commande minimale pour activer le service est :
gcloud services enable developerknowledge.googleapis.com \
--project="$PROJECT_ID"Pour une application gérée, ADC constitue généralement une frontière plus propre. La référence du client Python de Google décrit les identifiants découverts via l’environnement, ainsi que les clients synchrones et asynchrones. Le déploiement peut ainsi fournir l’identité au runtime, sans obliger l’application à analyser une clé issue d’un texte de configuration.
OAuth convient bien à un agent interactif, car c’est l’utilisateur — et non un secret statique partagé — qui autorise la connexion. Le flux OAuth exact dépend de l’hôte MCP. La prise en charge de l’authentification par le client doit être vérifiée indépendamment de l’API elle-même : un client acceptant une URL MCP peut malgré tout gérer différemment les en-têtes, les variables secrètes ou le renouvellement des jetons.
Un flux de récupération minimal
Un agent de production devrait délimiter explicitement la récupération des sources :
- Retirer de la question les secrets et le contenu sans rapport du dépôt.
- Rechercher dans le corpus officiel avec
SearchDocumentChunks. - Dédupliquer les résultats à partir de leur ressource de document parent.
- Récupérer les documents complets les plus pertinents lorsque la tâche nécessite le contexte environnant.
- Conserver l’URI, le titre, l’horodatage ou les métadonnées renvoyés, ainsi que les extraits sélectionnés.
- Demander au modèle de répondre uniquement à partir des éléments de preuve conservés.
- Exécuter les tests et contrôles de politique avant que l’agent ne modifie du code ou de l’infrastructure.
L’endpoint REST de recherche est documenté dans la référence REST de Google :
GET https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunksUne requête simple avec une clé API ressemble à ceci :
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"Avant de coder un parseur en dur, vérifiez le schéma de réponse et les noms de champs dans la référence REST actuelle. La recherche produit des extraits et des noms de documents parents ; la récupération de documents consomme ces noms.
Testez l’agent avec des réponses simulées ou figées couvrant les résultats vides, les parents absents, la pagination, les échecs d’authentification et les réponses de quota ou de limitation de débit. Gardez les nouvelles tentatives hors du prompt du modèle, avec un backoff borné et une solution de repli claire lorsque les éléments de preuve ne peuvent pas être récupérés.
API directe, MCP ou page Web ?
Une même source documentaire peut être exposée de trois manières :
| Situation | Voie recommandée | Raison |
|---|---|---|
| Un service a besoin d’une récupération reproductible et de citations | API REST ou bibliothèque cliente | L’application maîtrise le parsing, le cache et le stockage des preuves |
| Un assistant de code a besoin de contexte Google à la demande | Serveur MCP Developer Knowledge | L’agent peut appeler les outils de recherche et de récupération sans couche d’intégration sur mesure |
| Une page est absente du corpus pris en charge | Accès direct à la page ou connecteur de source distinct | Le corpus Developer Knowledge ne peut pas répondre à partir de sources manquantes |
| Une personne examine la mise en page, la navigation ou des exemples interactifs | Accès via navigateur/page | La récupération en Markdown ne remplace pas l’inspection visuelle d’une page |
La documentation MCP de Google indique l’endpoint https://developerknowledge.googleapis.com/mcp. MCP est un adaptateur pour agent, pas une base de connaissances différente. Voici une configuration représentative de serveur distant :
{
"mcpServers": {
"google-developer-knowledge": {
"serverUrl": "https://developerknowledge.googleapis.com/mcp",
"headers": {"x-goog-api-key": "${DEVELOPERKNOWLEDGE_API_KEY}"}
}
}
}Utilisez la syntaxe de variables secrètes documentée par l’hôte ; ne supposez pas que l’expansion littérale de ${...} fonctionne partout. La question du coût de contexte reste pertinente : exposer tous les outils à chaque tâche peut alourdir les définitions d’outils et la prise de décision. Une discussion d’utilisateurs sur les configurations d’agents multi-serveurs résume directement cette préoccupation :
« Les MCP sont très gourmands en contexte comparés aux skills, qui ne prennent que quelques lignes de texte jusqu’à leur invocation. » — u/junlim, discussion Reddit
C’est une raison de rendre le serveur MCP Developer Knowledge disponible de façon conditionnelle pour les tâches centrées sur Google, pas de l’abandonner. Un agent travaillant sur Firebase, Android, Google Cloud, Maps ou Flutter peut tirer parti de cette source ; un agent qui modifie une pile sans rapport ne devrait pas l’invoquer par défaut.
Dans quels cas l’API vaut mieux que le scraping de la documentation Google
Préférez l’API lorsque la plupart des conditions suivantes sont réunies :
- La tâche cible de la documentation pour développeurs détenue par Google.
- L’agent a besoin d’une recherche reproductible plutôt que d’un chargement ponctuel de page.
- La réponse doit inclure des citations ou conserver une piste de sources.
- L’agent doit distinguer un extrait pertinent du document complet.
- Le flux nécessite une pagination, des lots ou du cache structurés.
- Une refonte des pages ne devrait pas imposer un nouveau parseur HTML.
Le scraping peut toutefois rester la bonne solution de repli. Utilisez-le lorsque la page requise ne fait pas partie du corpus pris en charge, lorsqu’une interaction visuelle entre dans la tâche ou lorsque le HTML rendu exact et l’état de navigation comptent. Le scraping est également une sonde temporaire raisonnable pendant un incident si l’accès à l’API est indisponible, mais il ne devrait pas devenir silencieusement le contrat de récupération de production.
| Critère de décision | Developer Knowledge API | Scraping d’une page développeur |
|---|---|---|
| Découverte | Recherche du service dans son corpus indexé | Construire une recherche ou partir d’une URL connue |
| Sortie | Extraits, ressources de documents et Markdown | HTML ou contenu rendu de la page |
| Gestion des citations | La ressource parent et l’URI du document sont explicites | L’application doit extraire et conserver les liens |
| Maintenance liée à la mise en page | Le contrat d’API sert de frontière | Les sélecteurs peuvent casser après une refonte |
| Couverture | Corpus public pour développeurs pris en charge | Toute page publiquement accessible, sous réserve des règles d’accès et de robots |
| Fidélité visuelle | Ce n’est pas l’objectif | Peut préserver la mise en page rendue avec l’automatisation de navigateur |
| Contrôle de l’agent | Rechercher, récupérer, puis synthétiser | Généralement récupérer, parser, nettoyer et inférer |
L’API ne garantit pas que toute page nouvellement publiée soit disponible immédiatement. Les notes de version de Google décrivent les mises à jour d’indexation, mais un agent devrait traiter la fraîcheur comme une propriété à vérifier, et non comme la preuve que la page la plus récente est déjà indexée. Pour une migration le jour d’une sortie, comparez les métadonnées renvoyées avec la page officielle actuelle et échouez de manière sûre lorsque les preuves manquent.
La politique d’agent que je déploierais
Pour un agent de code spécialisé Google, j’appliquerais cette règle de routage :
- Détail d’implémentation précis : commencer par
SearchDocumentChunks; récupérer le document parent si l’extrait omet des prérequis. - Question d’architecture sur plusieurs pages : rechercher, puis utiliser
BatchGetDocumentssur le petit ensemble de parents pertinents. - Question explicative simple : utiliser
AnswerQuery, tout en exigeant des références dans la réponse. - Documentation non Google ou privée : router vers un autre connecteur approuvé.
- Écriture de code ou d’infrastructure : la récupération est consultative ; les tests, IAM, la revue et les contrôles de déploiement restent obligatoires.
Mettez en cache les documents complets lorsque la politique l’autorise, regroupez les recherches répétées et journalisez les URI des sources plutôt que des secrets bruts ou du contexte de dépôt superflu. Traitez le Markdown récupéré comme une entrée non fiable : une origine faisant autorité ne rend pas sans danger chaque instruction embarquée pour un agent doté d’outils capables d’écrire.
Le compromis non résolu est simple. L’API procure à un agent un contrat plus propre et plus auditable que le scraping HTML, mais elle renonce à la couverture et à la fidélité immédiate d’une page dans le navigateur. Faites de l’API le choix par défaut pour la documentation Google prise en charge, puis conservez le scraping ou un autre connecteur comme solution de repli explicite au lieu de mélanger les deux voies de manière invisible.
FAQ sur la Google Developer Knowledge API
La Developer Knowledge API est-elle équivalente à Google Search ?
Non. Il s’agit d’un service de récupération documentaire couvrant un corpus Google pour développeurs pris en charge, et non d’une API de recherche Web générale. Il ne recherchera pas automatiquement dans de la documentation privée, du contenu GitHub arbitraire ou toutes les pages liées à Google.
Faut-il utiliser AnswerQuery ou SearchDocumentChunks ?
Utilisez AnswerQuery pour une explication ciblée et fondée sur le corpus. Choisissez SearchDocumentChunks lorsque l’agent a besoin de preuves inspectables, d’une syntaxe exacte ou d’une piste de sources ; récupérez le document parent lorsqu’un extrait ne suffit pas.
Une clé API est-elle obligatoire ?
Une clé API restreinte constitue le chemin le plus rapide pour un prototype. Les clients backend peuvent utiliser ADC, et les intégrations MCP interactives peuvent employer OAuth si l’hôte le prend en charge. Ne supposez pas qu’un mécanisme d’authentification pris en charge par un client le sera automatiquement par un autre.
Un agent peut-il déployer des ressources Google Cloud avec l’API ?
Non. L’API fournit du contexte documentaire. Le déploiement requiert toujours des outils, identifiants, autorisations IAM, approbations et validations distincts.
Quand faut-il scraper à la place ?
Scrapez ou utilisez un connecteur de navigateur lorsque la page est hors du corpus de l’API, lorsque la mise en page visuelle compte ou lorsqu’il vous faut une page que l’index n’a pas encore remontée. Consignez explicitement cette solution de repli afin que l’agent ne présente pas du contenu scrapé comme une citation issue de l’API.
La recherche de l’API renvoie-t-elle une page complète ?
Non. La recherche renvoie des extraits de documents. Utilisez la ressource de document parent renvoyée avec GetDocument ou BatchGetDocuments lorsque la page Markdown complète est nécessaire.