Guia da Google Developer Knowledge API: autenticação, busca e agentes

Um agente de programação até pode extrair conteúdo de uma página para desenvolvedores do Google, mas então passa a carregar a responsabilidade pelo layout, pela descoberta de páginas, pela deduplicação e pelas citações. A Google Developer Knowledge API transfere esse trabalho para uma interface documentada. Para agentes que precisam de documentação atual do Google como contexto auditável, ela é a escolha padrão mais adequada — com uma ressalva importante: o corpus é selecionado, não corresponde a toda a web de desenvolvedores do Google.

A API recupera contexto; ela não executa ações

A Google Developer Knowledge API disponibiliza a documentação pública para desenvolvedores do Google em formato legível por máquinas. A documentação do Google descreve busca de documentos, recuperação de documentos completos, recuperação em lote e respostas fundamentadas na referência REST.

O serviço fornece contexto somente para leitura a aplicações e agentes. Ele não concede acesso a um projeto privado do Cloud, não aprova uma alteração de IAM, não faz deploy de código nem confirma que um comando gerado é seguro. Para qualquer operação de escrita, o agente continua precisando de credenciais próprias e controles de política.

O limite do corpus é relevante. A documentação da API do Google abrange documentação pública para desenvolvedores, e não a web em geral. Ela não substitui a busca em repositórios arbitrários do GitHub, Stack Overflow, runbooks privados ou bibliotecas de terceiros. O Google também informa que o Markdown retornado é gerado a partir do HTML de origem; portanto, ele não deve ser considerado uma cópia idêntica, byte a byte, da página renderizada.

Confirme a disponibilidade e o comportamento atuais na referência oficial da API e nas notas de versão.

O que a Google Developer Knowledge API oferece

A superfície REST é pequena o suficiente para ser modelada diretamente na política de um agente:

Os resultados de busca são trechos, não páginas completas garantidas. O recurso parent de um resultado é a ponte para GetDocument ou BatchGetDocuments. Um cliente robusto agrupa trechos duplicados por documento pai antes de buscar páginas; caso contrário, uma única página pode ocupar várias vagas de recuperação sem acrescentar muito contexto.

Um nome de recurso típico segue o formato de recurso de documento:

documents/docs.cloud.google.com/storage/docs/creating-buckets

Esse padrão de nome de recurso é útil depois de uma resposta de busca, mas o agente deve preferir o parent exato retornado pelo serviço em vez de montar um nome de memória.

Cada modo de busca entrega um tipo diferente de evidência

SearchDocumentChunks é o modo que prioriza evidências. Use-o quando o agente precisar de uma flag, parâmetro, permissão, observação de versão ou trecho de código exato. Quem chama a API pode inspecionar o trecho, manter a URI do documento e decidir se vale recuperar a página inteira.

GetDocument e BatchGetDocuments são modos de contexto. Use-os depois da busca quando a resposta depender de pré-requisitos, avisos, notas de migração ou seções próximas que um único trecho pode omitir. A recuperação em lote é útil quando uma questão de arquitetura envolve diversas páginas oficiais.

AnswerQuery é o modo de síntese. Ele se encaixa em uma pergunta delimitada, como “Qual opção atual do Google Cloud atende a estas restrições?”, quando a resposta precisa estar fundamentada no corpus. Isso não autoriza aceitar uma resposta bem escrita sem conferir as referências. Em mudanças de código de alto risco, a combinação de busca com recuperação do documento completo deixa um rastro de evidências mais inspecionável para o agente.

Autenticação: a escolha depende de quem chama

Há três padrões práticos de autenticação, mas cada um atende a um tipo de chamador diferente.

Para um início rápido, crie ou selecione um projeto do Google Cloud, habilite developerknowledge.googleapis.com e crie uma chave de API restrita à Developer Knowledge API. Não coloque uma chave sem restrições no prompt de um agente, em um repositório, em um bundle do lado do cliente ou em logs de depuração.

Um comando mínimo para habilitar o serviço é:

gcloud services enable developerknowledge.googleapis.com \
  --project="$PROJECT_ID"

Para uma aplicação gerenciada, ADC costuma ser uma fronteira mais limpa. A referência do cliente Python do Google documenta credenciais descobertas pelo ambiente, além de clientes síncronos e assíncronos. Assim, o ambiente de execução fornece a identidade no deploy, sem obrigar a aplicação a interpretar uma chave em um texto de configuração.

OAuth funciona bem para um agente interativo porque é o usuário, e não um segredo estático compartilhado, quem autoriza a conexão. O fluxo exato de OAuth depende do host MCP. O suporte à autenticação no cliente deve ser verificado separadamente da própria API: um cliente que aceita uma URL MCP ainda pode tratar cabeçalhos, variáveis secretas ou renovação de token de outra forma.

Um fluxo mínimo de recuperação

Em produção, um agente deve deixar explícita a fronteira de recuperação:

1. Remova segredos e conteúdo de repositório sem relação com a pergunta.
2. Busque no corpus oficial com SearchDocumentChunks.
3. Deduplicate os resultados pelo recurso do documento pai.
4. Recupere os documentos completos mais relevantes quando a tarefa exigir contexto ao redor.
5. Preserve a URI retornada, o título, o timestamp ou os metadados e os trechos selecionados.
6. Instrua o modelo a responder apenas com base nas evidências preservadas.
7. Execute testes e verificações de política antes de o agente alterar código ou infraestrutura.

O endpoint REST de busca está documentado na referência REST do Google:

GET https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks

Uma requisição simples com chave de API é assim:

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 fixar um parser no código, confira o esquema exato da resposta e os nomes dos campos na referência REST atual. A busca produz trechos e nomes de documentos pai; a recuperação de documentos consome esses nomes.

Teste o agente com respostas simuladas ou capturadas para resultados vazios, pais ausentes, paginação, falhas de autenticação e respostas de cota ou limite de taxa. Mantenha as tentativas fora do prompt do modelo, com backoff limitado e um fallback claro para quando não for possível recuperar evidências.

API direta, MCP ou página web?

A mesma fonte de documentação pode ser acessada de três formas:

A documentação de MCP do Google registra o endpoint como https://developerknowledge.googleapis.com/mcp. MCP é um adaptador para um agente, não uma base de conhecimento diferente. Uma configuração representativa de servidor remoto é:

{
  "mcpServers": {
    "google-developer-knowledge": {
      "serverUrl": "https://developerknowledge.googleapis.com/mcp",
      "headers": {"x-goog-api-key": "${DEVELOPERKNOWLEDGE_API_KEY}"}
    }
  }
}

Use a sintaxe de variável secreta documentada pelo host; não presuma que a expansão literal de ${...} funcione em todos os lugares. A questão do custo de contexto continua existindo: expor todas as ferramentas para todas as tarefas pode adicionar definições de ferramentas e sobrecarga de decisão. Uma discussão de usuários reais sobre configurações de agentes com múltiplos servidores resumiu bem a preocupação:

“MCPs consomem muito contexto em comparação com skills — que ocupam apenas algumas linhas de texto até serem invocadas.” — u/junlim, discussão no Reddit

Esse é um motivo para disponibilizar condicionalmente o servidor Developer Knowledge MCP em tarefas voltadas ao Google, não para abandoná-lo. Um agente que trabalha com Firebase, Android, Google Cloud, Maps ou Flutter pode se beneficiar dessa fonte; um agente que edita uma stack sem relação não deveria invocá-la por padrão.

Quando a API supera o scraping da documentação do Google

Use a API quando a maioria destas condições for verdadeira:

• A tarefa é voltada à documentação para desenvolvedores mantida pelo Google.
• O agente precisa de busca repetível, e não de uma captura pontual de página.
• A resposta exige citações ou um histórico de fontes preservado.
• O agente precisa distinguir um trecho relevante do documento completo.
• O fluxo precisa de paginação, processamento em lote ou cache estruturados.
• Redesenhos de página não devem exigir um novo parser de HTML.

O scraping ainda pode ser o fallback correto. Use-o quando a página necessária não estiver no corpus compatível, quando a interação visual fizer parte da tarefa ou quando o HTML renderizado exato e o estado da navegação importarem. O scraping também é uma sondagem temporária razoável durante um incidente se o acesso à API estiver indisponível, mas não deve se transformar silenciosamente no contrato de recuperação de produção.

A API não garante que toda página recém-publicada estará disponível imediatamente. As notas de versão do Google descrevem atualizações de indexação, mas o agente deve tratar atualidade como uma propriedade a verificar, e não como prova de que a página mais nova já foi indexada. Em uma migração no dia do lançamento, compare os metadados retornados com a página oficial atual e interrompa o processo na ausência de evidências.

A política de agente que eu colocaria em produção

Para um agente de programação focado no Google, eu usaria esta regra de roteamento:

• Detalhe exato de implementação: comece com SearchDocumentChunks; busque o documento pai se o trecho não trouxer os pré-requisitos.
• Pergunta de arquitetura entre várias páginas: busque e depois use BatchGetDocuments para o pequeno conjunto de pais relevantes.
• Pergunta explicativa simples: use AnswerQuery, mas exija referências na resposta.
• Documentação não relacionada ao Google ou privada: direcione para outro conector aprovado.
• Alteração de código ou infraestrutura: a recuperação é apenas orientativa; testes, IAM, revisão e controles de deploy continuam obrigatórios.

Faça cache de documentos completos quando a política permitir, elimine buscas repetidas em sequência e registre URIs das fontes, não segredos brutos nem contexto desnecessário do repositório. Trate o Markdown recuperado como entrada não confiável: uma origem autorizada não torna segura toda instrução incorporada para um agente com ferramentas capazes de escrever.

O trade-off que resta é simples. A API oferece ao agente um contrato mais limpo e auditável do que o scraping de HTML, mas abre mão da cobertura e da fidelidade imediata de uma página no navegador. Adote a API como padrão para a documentação do Google compatível e mantenha o scraping ou outro conector como um fallback explícito, em vez de misturar os dois caminhos de forma invisível.

Perguntas frequentes sobre a Google Developer Knowledge API

A Developer Knowledge API é igual ao Google Search?

Não. Ela é um serviço de recuperação de documentação sobre um corpus compatível de desenvolvedores do Google, não uma API de busca na web em geral. Ela não buscará automaticamente documentação privada, conteúdo arbitrário do GitHub ou todas as páginas relacionadas ao Google.

Devo usar AnswerQuery ou SearchDocumentChunks?

Use AnswerQuery para uma explicação delimitada e fundamentada. Use SearchDocumentChunks quando o agente precisar de evidências inspecionáveis, sintaxe exata ou um histórico de fontes; recupere o documento pai se um trecho não for suficiente.

Uma chave de API é obrigatória?

Uma chave de API restrita é o caminho mais rápido para um protótipo. Clientes de backend podem usar ADC, e integrações MCP interativas podem usar OAuth se o host oferecer suporte. Não presuma que a autenticação aceita por um cliente seja automaticamente aceita por outro.

Um agente pode usar a API para fazer deploy de recursos do Google Cloud?

Não. A API fornece contexto de documentação. O deploy continua exigindo ferramentas, credenciais, permissões de IAM, aprovações e validação separados.

Quando devo fazer scraping?

Faça scraping ou use um conector de navegador quando a página estiver fora do corpus da API, quando o layout visual importar ou quando você precisar de uma página que o índice ainda não apresentou. Registre esse fallback de forma explícita para que o agente não apresente conteúdo extraído como uma citação respaldada pela API.

A API retorna uma página completa na busca?

Não. A busca retorna trechos de documentos. Use o recurso de documento pai retornado com GetDocument ou BatchGetDocuments quando precisar da página completa em Markdown.