AIREITERUn coding agent può fare scraping di una pagina per sviluppatori di Google, ma in questo modo deve gestire in proprio struttura della pagina, individuazione delle fonti, deduplicazione e citazioni. La Google Developer Knowledge API sposta queste attività dietro un'interfaccia documentata. È in genere la scelta migliore quando un agente ha bisogno di documentazione Google aggiornata e verificabile come contesto, con un limite importante: il corpus è curato e non coincide con l'intero web dedicato agli sviluppatori Google.
Recupera informazioni, non esegue operazioni
La Google Developer Knowledge API rende disponibile in formato leggibile dalle macchine la documentazione pubblica per sviluppatori di Google. La documentazione Google copre ricerca nei documenti, recupero di documenti completi, recupero batch e risposte supportate da fonti nella referenza REST.
Il servizio fornisce contesto in sola lettura a un'applicazione o a un agente. Non concede accesso a un progetto Cloud privato, non approva modifiche IAM, non distribuisce codice e non verifica che un comando generato sia sicuro. Per qualunque operazione di scrittura, l'agente continua a richiedere credenziali separate e controlli di policy.
Il perimetro del corpus conta. La documentazione dell'API di Google riguarda la documentazione pubblica per sviluppatori, non il web generico. Non sostituisce la ricerca in repository GitHub arbitrari, Stack Overflow, runbook privati o librerie di terze parti. Google segnala inoltre che il Markdown restituito è generato dall'HTML sorgente: non va quindi considerato una copia byte per byte della pagina visualizzata.
Verifica disponibilità e comportamento correnti nella referenza API ufficiale e nelle note di rilascio.
Cosa espone la Google Developer Knowledge API
La superficie REST è abbastanza contenuta da poter essere modellata direttamente nelle policy di un agente:
| Operazione | Cosa restituisce | Uso ideale |
|---|---|---|
SearchDocumentChunks | Chunk corrispondenti e risorse dei documenti padre | Trovare evidenze e pagine candidate |
GetDocument | Un documento completo in Markdown | Fornire all'agente il contesto dell'intera pagina |
BatchGetDocuments | Più documenti completi | Confrontare pagine correlate o preriscaldare una cache locale |
AnswerQuery | Una risposta basata sul corpus con riferimenti di supporto | Rispondere a una domanda circoscritta sulla documentazione |
I risultati della ricerca sono chunk, non necessariamente pagine complete. La risorsa parent presente in un risultato è il collegamento a GetDocument o BatchGetDocuments. Un client robusto raggruppa i chunk duplicati per parent prima di recuperare le pagine; altrimenti una sola pagina può occupare più slot di recupero aggiungendo poco contesto utile.
Un tipico nome di risorsa segue il formato delle risorse documento:
documents/docs.cloud.google.com/storage/docs/creating-bucketsQuesto schema del nome risorsa è utile dopo una risposta di ricerca, ma l'agente dovrebbe preferire il valore parent esatto restituito dal servizio invece di costruire un nome a memoria.
Ogni modalità di ricerca offre un diverso tipo di evidenza
SearchDocumentChunks è la modalità che mette le evidenze al primo posto. Usala quando l'agente richiede un flag preciso, un parametro, un'autorizzazione, una nota sulla versione o un frammento di codice. Il chiamante può esaminare il chunk, conservarne l'URI del documento e decidere se recuperare la pagina completa.
GetDocument e BatchGetDocuments sono modalità orientate al contesto. Sono utili dopo la ricerca quando la risposta dipende da prerequisiti, avvisi, note di migrazione o sezioni adiacenti che un singolo chunk potrebbe omettere. Il recupero batch è utile quando una decisione progettuale coinvolge più pagine ufficiali.
AnswerQuery è la modalità di sintesi. È adatta a una domanda delimitata come “Quale opzione Google Cloud attuale soddisfa questi vincoli?”, quando la risposta deve essere basata sul corpus. Non è un motivo per accettare una risposta fluida senza verificarne i riferimenti. Per modifiche al codice ad alto rischio, ricerca più recupero del documento completo offre all'agente una traccia di evidenze più ispezionabile.
Autenticazione: sceglila in base al chiamante
Esistono tre schemi pratici di autenticazione, ma non sono intercambiabili.
| Chiamante | Punto di partenza consigliato | Perché |
|---|---|---|
| curl locale o prototipo rapido | Chiave API con restrizioni | È il modo più veloce per effettuare la prima richiesta |
| Backend, worker o client Python | Application Default Credentials (ADC) | Mantiene le credenziali nell'ambiente di runtime anziché nel codice sorgente |
| Client MCP interattivo | OAuth se l'host lo supporta; altrimenti una chiave con restrizioni | Evita di distribuire un'unica chiave di lunga durata fra gli strumenti degli utenti |
Per un quickstart, crea o seleziona un progetto Google Cloud, abilita developerknowledge.googleapis.com e crea una chiave API limitata alla Developer Knowledge API. Non inserire una chiave senza restrizioni in un prompt dell'agente, in un repository, in un bundle lato client o in un log di debug.
Il comando minimo per abilitare il servizio è:
gcloud services enable developerknowledge.googleapis.com \
--project="$PROJECT_ID"Per un'applicazione gestita, ADC rappresenta di solito un confine più pulito. La referenza del client Python di Google documenta le credenziali rilevate dall'ambiente e client sincroni e asincroni. In questo modo è il deployment a fornire l'identità tramite il runtime, senza costringere l'applicazione a leggere una chiave dal testo di configurazione.
OAuth è una scelta adatta per un agente interattivo, perché autorizza la connessione l'utente anziché un segreto statico condiviso. Il flusso OAuth esatto dipende dall'host MCP. Il supporto all'autenticazione nel client va verificato separatamente dall'API: un client che accetta un URL MCP può comunque gestire in modo diverso header, variabili segrete o rinnovo dei token.
Un flusso minimo per il recupero delle fonti
Un agente in produzione dovrebbe rendere esplicito il confine del recupero:
- Rimuovere dalla domanda segreti e contenuti non pertinenti del repository.
- Cercare nel corpus ufficiale con
SearchDocumentChunks. - Deduplicare i risultati in base alla risorsa del documento padre.
- Recuperare i documenti completi più rilevanti quando l'attività richiede contesto circostante.
- Conservare URI, titolo, timestamp o metadati restituiti, insieme agli estratti selezionati.
- Chiedere al modello di rispondere esclusivamente sulla base delle evidenze conservate.
- Eseguire test e controlli di policy prima che l'agente modifichi codice o infrastruttura.
L'endpoint REST per la ricerca è documentato nella referenza REST di Google:
GET https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunksUna semplice richiesta con chiave API è fatta così:
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"Prima di fissare un parser nel codice, verifica schema della risposta e nomi dei campi nella referenza REST aggiornata. La ricerca produce chunk e nomi dei documenti padre; il recupero dei documenti usa quei nomi.
Testa l'agente con risposte simulate o snapshot per risultati vuoti, parent mancanti, paginazione, errori di autenticazione e risposte di quota o rate limit. Mantieni i retry fuori dal prompt del modello, con backoff limitato e un fallback chiaro quando non è possibile recuperare evidenze.
API diretta, MCP o pagina web?
La stessa fonte documentale può essere esposta in tre modi:
| Situazione | Percorso migliore | Motivo |
|---|---|---|
| Un servizio richiede recuperi e citazioni ripetibili | API REST o libreria client | L'applicazione controlla parsing, cache e archiviazione delle evidenze |
| Un assistente di coding richiede contesto Google on demand | Developer Knowledge MCP server | L'agente può chiamare gli strumenti di ricerca e recupero senza integrazioni personalizzate |
| Una pagina è fuori dal corpus supportato | Accesso diretto alla pagina o connettore per un'altra fonte | Il corpus Developer Knowledge non può rispondere per fonti assenti |
| Una persona sta analizzando layout, navigazione o esempi interattivi | Browser/accesso alla pagina | Il recupero in Markdown non equivale all'ispezione visiva della pagina |
La documentazione MCP di Google indica come endpoint https://developerknowledge.googleapis.com/mcp. MCP è un adattatore per un agente, non una knowledge base differente. Una configurazione rappresentativa per un server remoto è:
{
"mcpServers": {
"google-developer-knowledge": {
"serverUrl": "https://developerknowledge.googleapis.com/mcp",
"headers": {"x-goog-api-key": "${DEVELOPERKNOWLEDGE_API_KEY}"}
}
}
}Usa la sintassi per le variabili segrete documentata dall'host; non dare per scontato che l'espansione letterale di ${...} funzioni ovunque. Resta inoltre il tema del costo di contesto: esporre ogni strumento a ogni attività può aggiungere definizioni degli strumenti e overhead decisionale. Una discussione fra utenti reali sulle configurazioni agent con più server ha espresso bene il problema:
“Gli MCP richiedono molto più contesto rispetto alle skill, che occupano solo poche righe di testo finché non vengono invocate.” — u/junlim, discussione su Reddit
È un motivo per rendere disponibile il server MCP Developer Knowledge in modo condizionale per le attività incentrate su Google, non per abbandonarlo. Un agente che lavora su Firebase, Android, Google Cloud, Maps o Flutter può trarre vantaggio dalla fonte; un agente che modifica uno stack non correlato non dovrebbe invocarla per impostazione predefinita.
Quando l'API è meglio dello scraping della documentazione Google
Usa l'API quando è vera la maggior parte di queste condizioni:
- L'attività riguarda documentazione per sviluppatori di proprietà di Google.
- L'agente richiede una ricerca ripetibile, non il recupero occasionale di una pagina.
- La risposta richiede citazioni o una traccia delle fonti conservata.
- L'agente deve distinguere un chunk rilevante dal documento completo.
- Il workflow richiede paginazione, batching o caching strutturati.
- Un restyling delle pagine non dovrebbe imporre un nuovo parser HTML.
Lo scraping può comunque essere il fallback corretto. Usalo quando la pagina richiesta non è nel corpus supportato, quando un'interazione visiva fa parte dell'attività o quando contano l'HTML renderizzato esatto e lo stato di navigazione. Lo scraping è anche una sonda temporanea ragionevole durante un incidente se l'accesso API non è disponibile, ma non dovrebbe trasformarsi silenziosamente nel contratto di recupero in produzione.
| Fattore decisionale | Developer Knowledge API | Scraping di una pagina per sviluppatori |
|---|---|---|
| Individuazione | Ricerca del servizio sul suo corpus indicizzato | Costruire una ricerca o partire da un URL noto |
| Output | Chunk, risorse documento e Markdown | HTML o contenuto della pagina renderizzata |
| Flusso di citazione | Risorsa padre e URI del documento sono espliciti | L'applicazione deve estrarre e conservare i link |
| Manutenzione del layout | Il contratto API è il confine | I selettori possono rompersi dopo un restyling |
| Copertura | Corpus pubblico per sviluppatori supportato | Qualunque pagina pubblicamente raggiungibile, soggetta a regole di accesso e robots |
| Fedeltà visiva | Non è l'obiettivo | Può preservare il layout renderizzato con l'automazione del browser |
| Controllo dell'agente | Cerca, recupera, poi sintetizza | In genere recupera, analizza, ripulisce e interpreta |
L'API non garantisce che ogni pagina pubblicata di recente sia disponibile all'istante. Le note di rilascio di Google descrivono gli aggiornamenti dell'indicizzazione, ma un agente dovrebbe considerare la freschezza una proprietà da verificare, non la prova che la pagina più nuova sia già indicizzata. Per una migrazione nel giorno del rilascio, confronta i metadati restituiti con la pagina ufficiale corrente e applica un fail closed quando mancano evidenze.
La policy per agenti che metterei in produzione
Per un coding agent specifico per Google, userei questa regola di instradamento:
- Dettaglio di implementazione preciso: prima
SearchDocumentChunks; recupera il documento padre se il chunk non contiene i prerequisiti. - Questione progettuale su più pagine: cerca, quindi usa
BatchGetDocumentsper il piccolo insieme di parent rilevanti. - Domanda esplicativa semplice:
AnswerQuery, ma richiedi riferimenti nella risposta. - Documentazione non Google o privata: instrada verso un altro connettore approvato.
- Scrittura su codice o infrastruttura: il recupero è consultivo; test, IAM, revisione e controlli di deployment restano obbligatori.
Metti in cache i documenti completi quando la policy lo consente, applica debounce alle ricerche ripetute e registra gli URI delle fonti anziché segreti grezzi o contesto non necessario del repository. Considera il Markdown recuperato come input non attendibile: l'origine autorevole non rende sicura ogni istruzione incorporata per un agente dotato di strumenti di scrittura.
Il compromesso irrisolto è semplice. L'API offre a un agente un contratto più pulito e verificabile rispetto allo scraping HTML, ma rinuncia alla copertura e alla fedeltà immediata della pagina offerte da un browser. Scegli l'API come impostazione predefinita per la documentazione Google supportata, mantenendo poi lo scraping o un altro connettore come fallback esplicito anziché mescolare i due percorsi in modo invisibile.
FAQ sulla Google Developer Knowledge API
La Developer Knowledge API è uguale a Google Search?
No. È un servizio di recupero della documentazione su un corpus Google per sviluppatori supportato, non un'API di ricerca web generica. Non cercherà automaticamente documentazione privata, contenuti GitHub arbitrari o tutte le pagine correlate a Google.
Meglio usare AnswerQuery o SearchDocumentChunks?
Usa AnswerQuery per una spiegazione circoscritta e basata sul corpus. Usa SearchDocumentChunks quando l'agente richiede evidenze ispezionabili, sintassi esatta o una traccia delle fonti; recupera il documento padre quando il chunk non basta.
È obbligatoria una chiave API?
Una chiave API con restrizioni è il percorso più rapido per un prototipo. I client backend possono usare ADC, mentre le integrazioni MCP interattive possono usare OAuth se l'host lo supporta. Non presumere che l'autenticazione supportata da un client sia automaticamente supportata da un altro.
Un agente può usare l'API per distribuire risorse Google Cloud?
No. L'API fornisce contesto documentale. Il deployment richiede comunque strumenti, credenziali, autorizzazioni IAM, approvazioni e validazione separati.
Quando dovrei fare scraping?
Fai scraping o usa un connettore browser quando la pagina è fuori dal corpus API, quando il layout visivo conta oppure quando ti serve una pagina che l'indice non ha ancora restituito. Registra esplicitamente questo fallback, così l'agente non presenterà contenuto estratto con scraping come una citazione supportata dall'API.
La ricerca API restituisce una pagina completa?
No. La ricerca restituisce chunk di documenti. Usa la risorsa del documento padre restituita con GetDocument o BatchGetDocuments quando serve la pagina Markdown completa.