AIREITERUn agente de programación puede hacer scraping de una página para desarrolladores de Google, pero entonces tendrá que resolver por su cuenta el diseño de la página, el descubrimiento de contenido, la deduplicación y las citas. Google Developer Knowledge API traslada esas tareas a una interfaz documentada. Es la opción predeterminada más sólida cuando un agente necesita documentación actual de Google como contexto auditable, con una salvedad importante: su corpus es seleccionado, no abarca toda la web para desarrolladores de Google.
La API recupera información; no ejecuta acciones
Google Developer Knowledge API expone la documentación pública para desarrolladores de Google en un formato legible por máquinas. Google documenta la búsqueda de documentos, la recuperación de documentos completos, la recuperación por lotes y las respuestas fundamentadas en la referencia de REST.
El servicio aporta contexto de solo lectura para una aplicación o un agente. No concede acceso a un proyecto privado de Cloud, no aprueba un cambio de IAM, no despliega código ni valida que un comando generado sea seguro. Para cualquier operación de escritura, el agente seguirá necesitando credenciales independientes y controles de políticas.
El límite del corpus es relevante. La documentación de la API de Google cubre documentación pública para desarrolladores, no la web general. No sustituye la búsqueda en repositorios arbitrarios de GitHub, Stack Overflow, runbooks privados ni bibliotecas de terceros. Google también indica que el Markdown devuelto se genera a partir del HTML de origen, por lo que no debe considerarse una copia byte a byte de la página renderizada.
Confirma la disponibilidad y el comportamiento actuales en la referencia oficial de la API y las notas de la versión.
Qué ofrece Google Developer Knowledge API
La superficie REST es lo bastante reducida como para modelarla directamente en la política de un agente:
| Operación | Qué devuelve | Mejor uso |
|---|---|---|
SearchDocumentChunks | Fragmentos coincidentes y recursos de sus documentos padre | Localizar pruebas y páginas candidatas |
GetDocument | Un documento completo en Markdown | Aportar al agente el contexto del resto de la página |
BatchGetDocuments | Varios documentos completos | Comparar páginas relacionadas o precalentar una caché local |
AnswerQuery | Una respuesta fundamentada con referencias de apoyo | Responder a una pregunta acotada sobre documentación |
Los resultados de búsqueda son fragmentos, no páginas completas garantizadas. El recurso parent de cada resultado sirve de enlace hacia GetDocument o BatchGetDocuments. Un cliente robusto agrupa los fragmentos duplicados por padre antes de recuperar páginas; de lo contrario, una sola página puede ocupar varias posiciones de recuperación y aportar muy poco contexto adicional.
Un nombre de recurso típico sigue el formato de recurso de documento:
documents/docs.cloud.google.com/storage/docs/creating-bucketsEste patrón de nombre de recurso resulta útil tras una respuesta de búsqueda, pero un agente debería preferir el parent exacto que devuelve el servicio en lugar de construir un nombre de memoria.
Cada modo de búsqueda ofrece un tipo de evidencia distinto
SearchDocumentChunks es el modo centrado en la evidencia. Úsalo cuando el agente necesite una marca exacta, un parámetro, un permiso, una nota de versión o un fragmento de código. Quien llama puede inspeccionar el fragmento, conservar la URI de su documento y decidir si necesita recuperar la página completa.
GetDocument y BatchGetDocuments son modos de contexto. Úsalos después de buscar cuando la respuesta dependa de requisitos previos, advertencias, notas de migración o secciones cercanas que un único fragmento podría omitir. La recuperación por lotes es útil cuando una cuestión de diseño abarca varias páginas oficiales.
AnswerQuery es el modo de síntesis. Encaja con una pregunta acotada como “¿Qué opción actual de Google Cloud se ajusta a estas restricciones?” cuando la respuesta debe basarse en el corpus. No autoriza a aceptar una respuesta fluida sin revisar las referencias. Para cambios de código de alto riesgo, combinar búsqueda y recuperación del documento completo proporciona al agente un rastro de evidencia más inspeccionable.
Autenticación: elige según quién llama
Hay tres patrones prácticos de autenticación, pero no responden al mismo tipo de cliente.
| Cliente | Punto de partida recomendado | Motivo |
|---|---|---|
| curl local o prototipo rápido | Clave de API restringida | Es la vía más rápida para hacer la primera solicitud |
| Backend, worker o cliente de Python | Application Default Credentials (ADC) | Mantiene las credenciales en el entorno de ejecución, no en el código fuente |
| Cliente MCP interactivo | OAuth si el host lo admite; si no, una clave restringida | Evita distribuir una misma clave de larga duración entre herramientas de usuario |
Para empezar rápido, crea o selecciona un proyecto de Google Cloud, habilita developerknowledge.googleapis.com y crea una clave de API restringida a Developer Knowledge API. No incluyas una clave sin restricciones en el prompt de un agente, un repositorio, un bundle del lado cliente ni un registro de depuración.
El comando mínimo para habilitar el servicio es:
gcloud services enable developerknowledge.googleapis.com \
--project="$PROJECT_ID"En una aplicación gestionada, ADC suele ser un límite de seguridad más limpio. La referencia del cliente de Python de Google documenta credenciales detectadas desde el entorno, además de clientes síncronos y asíncronos. Así, el despliegue proporciona la identidad en tiempo de ejecución sin obligar a la aplicación a extraer una clave de texto de configuración.
OAuth encaja bien en un agente interactivo porque es el usuario, y no un secreto estático compartido, quien autoriza la conexión. El flujo exacto de OAuth depende del host de MCP. La compatibilidad de autenticación del cliente debe verificarse por separado de la propia API: un cliente que acepta una URL de MCP puede gestionar de otro modo las cabeceras, las variables de secretos o la renovación de tokens.
Flujo mínimo de recuperación
Un agente de producción debería dejar explícito el límite de recuperación:
- Elimina secretos y contenido no relacionado del repositorio antes de formular la consulta.
- Busca en el corpus oficial con
SearchDocumentChunks. - Deduplica los resultados mediante el recurso de documento padre.
- Recupera los documentos completos más relevantes cuando la tarea requiera contexto adicional.
- Conserva la URI devuelta, el título, la marca de tiempo o los metadatos y los extractos seleccionados.
- Pide al modelo que responda exclusivamente a partir de la evidencia conservada.
- Ejecuta pruebas y comprobaciones de políticas antes de que el agente cambie código o infraestructura.
El endpoint REST de búsqueda está documentado en la referencia de REST de Google:
GET https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunksUna solicitud sencilla con clave de API tiene este aspecto:
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"Antes de fijar un analizador en código, comprueba el esquema de respuesta y los nombres de campo exactos en la referencia actual de REST. La búsqueda produce fragmentos y nombres de documentos padre; la recuperación de documentos consume esos nombres.
Prueba el agente con respuestas simuladas o capturadas para cubrir resultados vacíos, padres ausentes, paginación, fallos de autenticación y respuestas de cuota o límite de velocidad. Mantén los reintentos fuera del prompt del modelo, con espera exponencial limitada y una alternativa clara cuando no pueda recuperarse evidencia.
¿API directa, MCP o página web?
La misma fuente de documentación puede exponerse de tres formas:
| Situación | Mejor vía | Motivo |
|---|---|---|
| Un servicio necesita recuperación y citas repetibles | API REST o biblioteca cliente | La aplicación controla el análisis, la caché y el almacenamiento de evidencias |
| Un asistente de programación necesita contexto de Google bajo demanda | Servidor MCP de Developer Knowledge | El agente puede llamar a herramientas de búsqueda y recuperación sin integración personalizada |
| Una página está fuera del corpus compatible | Acceso directo a la página u otro conector de fuentes | El corpus de Developer Knowledge no puede responder por fuentes ausentes |
| Una persona inspecciona el diseño, la navegación o ejemplos interactivos | Acceso mediante navegador o página | La recuperación en Markdown no permite inspeccionar la página visual |
La documentación de MCP de Google indica como endpoint https://developerknowledge.googleapis.com/mcp. MCP es un adaptador para el agente, no una base de conocimiento distinta. Una configuración representativa de servidor remoto sería:
{
"mcpServers": {
"google-developer-knowledge": {
"serverUrl": "https://developerknowledge.googleapis.com/mcp",
"headers": {"x-goog-api-key": "${DEVELOPERKNOWLEDGE_API_KEY}"}
}
}
}Utiliza la sintaxis de variables secretas documentada por el host; no des por hecho que la expansión literal de ${...} funciona en todos los casos. El coste de contexto sigue siendo importante: exponer todas las herramientas a todas las tareas puede añadir definiciones de herramientas y sobrecarga de decisión. Un debate entre usuarios sobre configuraciones de agentes con varios servidores lo resumía así:
“Los MCP consumen mucho contexto en comparación con las skills, que solo ocupan unas pocas líneas de texto hasta que se invocan.” — u/junlim, debate en Reddit
Es un motivo para habilitar condicionalmente el servidor MCP de Developer Knowledge en tareas centradas en Google, no para descartarlo. Un agente que trabaje con Firebase, Android, Google Cloud, Maps o Flutter puede beneficiarse de esta fuente; uno que edite una pila sin relación no debería invocarla de forma predeterminada.
Cuándo la API supera al scraping de documentación de Google
Usa la API cuando se cumplan la mayoría de estas condiciones:
- La tarea se centra en documentación para desarrolladores propiedad de Google.
- El agente necesita búsquedas repetibles, no una recuperación puntual de una página.
- La respuesta necesita citas o un rastro de fuentes conservado.
- El agente debe distinguir entre un fragmento relevante y el documento completo.
- El flujo requiere paginación, procesamiento por lotes o caché estructurados.
- Los rediseños de página no deberían obligar a crear un nuevo analizador de HTML.
El scraping puede seguir siendo la alternativa correcta. Úsalo si la página necesaria no está en el corpus compatible, si la interacción visual forma parte de la tarea o si importa el HTML renderizado exacto y el estado de navegación. También es una sonda temporal razonable durante un incidente si no hay acceso a la API, pero no debería convertirse silenciosamente en el contrato de recuperación de producción.
| Factor de decisión | Developer Knowledge API | Scraping de una página para desarrolladores |
|---|---|---|
| Descubrimiento | Búsqueda del servicio en su corpus indexado | Hay que crear una búsqueda o partir de una URL conocida |
| Salida | Fragmentos, recursos de documentos y Markdown | HTML o contenido de página renderizado |
| Flujo de citas | El recurso padre y la URI del documento son explícitos | La aplicación debe extraer y conservar los enlaces |
| Mantenimiento del diseño | El contrato de la API marca el límite | Los selectores pueden romperse tras rediseños |
| Cobertura | Corpus público para desarrolladores compatible | Cualquier página accesible públicamente, sujeta a reglas de acceso y robots |
| Fidelidad visual | No es su objetivo | Puede conservar el diseño renderizado con automatización de navegador |
| Control del agente | Buscar, recuperar y sintetizar | Normalmente, obtener, analizar, limpiar e inferir |
La API no garantiza que cada página publicada recientemente esté disponible de inmediato. Las notas de la versión de Google describen actualizaciones de indexación, pero un agente debe tratar la actualidad como una propiedad que hay que comprobar, no como prueba de que la página más reciente ya está indexada. Para una migración el día del lanzamiento, compara los metadatos devueltos con la página oficial actual y falla de forma segura si falta evidencia.
La política de agente que pondría en producción
Para un agente de programación específico de Google, aplicaría esta regla de enrutamiento:
- Detalle de implementación exacto: primero
SearchDocumentChunks; recupera el documento padre si el fragmento no incluye los requisitos previos. - Pregunta de diseño entre varias páginas: busca y después usa
BatchGetDocumentscon el pequeño conjunto de padres relevantes. - Pregunta explicativa sencilla:
AnswerQuery, pero exige referencias en la respuesta. - Documentación privada o ajena a Google: dirígela a otro conector aprobado.
- Escritura de código o infraestructura: la recuperación es orientativa; las pruebas, IAM, la revisión y los controles de despliegue siguen siendo obligatorios.
Almacena en caché documentos completos donde las políticas lo permitan, evita búsquedas repetidas con debounce y registra las URI de las fuentes en lugar de secretos sin procesar o contexto innecesario del repositorio. Trata el Markdown recuperado como entrada no confiable: que el origen sea autorizado no implica que toda instrucción incrustada sea segura para un agente con herramientas capaces de escribir.
La disyuntiva pendiente es sencilla. La API ofrece al agente un contrato más limpio y auditable que el scraping de HTML, pero renuncia a la cobertura y a la fidelidad inmediata de la página que aporta un navegador. Elige la API como opción predeterminada para la documentación de Google compatible y conserva el scraping u otro conector como alternativa explícita, en vez de mezclar ambos caminos de forma invisible.
Preguntas frecuentes sobre Google Developer Knowledge API
¿Developer Knowledge API es lo mismo que Google Search?
No. Es un servicio de recuperación de documentación sobre un corpus compatible de Google para desarrolladores, no una API de búsqueda web general. No buscará automáticamente documentación privada, contenido arbitrario de GitHub ni todas las páginas relacionadas con Google.
¿Debo usar AnswerQuery o SearchDocumentChunks?
Usa AnswerQuery para una explicación acotada y fundamentada. Usa SearchDocumentChunks cuando el agente necesite evidencia inspeccionable, sintaxis exacta o un rastro de fuentes; recupera el documento padre cuando un fragmento no sea suficiente.
¿Es obligatoria una clave de API?
Una clave de API restringida es la vía más rápida para un prototipo. Los clientes de backend pueden usar ADC, y las integraciones MCP interactivas pueden utilizar OAuth si el host lo admite. No des por supuesto que la autenticación compatible con un cliente lo es automáticamente con otro.
¿Puede un agente usar la API para desplegar recursos de Google Cloud?
No. La API proporciona contexto de documentación. El despliegue continúa requiriendo herramientas, credenciales, permisos de IAM, aprobaciones y validación independientes.
¿Cuándo debería hacer scraping en su lugar?
Haz scraping o utiliza un conector de navegador cuando la página esté fuera del corpus de la API, cuando importe el diseño visual o cuando necesites una página que el índice aún no haya mostrado. Registra explícitamente esa alternativa para que el agente no presente contenido extraído mediante scraping como una cita respaldada por la API.
¿La API devuelve una página completa en los resultados de búsqueda?
No. La búsqueda devuelve fragmentos de documentos. Usa el recurso de documento padre devuelto con GetDocument o BatchGetDocuments cuando necesites la página completa en Markdown.