AIREITER程式設計 Agent 當然可以直接爬取 Google 開發人員文件頁面，但頁面結構解析、內容發現、重複結果去除與引用來源保存，全都得自己處理。Google Developer Knowledge API 把這些工作收斂到有文件可查的介面中。若 Agent 需要取得可追溯、具時效性的 Google 官方文件作為上下文，這通常是更合適的預設選項；不過有個前提：它提供的是經整理的語料庫，並非整個 Google 開發人員網站。
這是文件擷取 API，不是執行 API
Google Developer Knowledge API 將公開的 Google 開發人員文件轉為機器可讀內容。Google 在REST 參考文件中說明了文件搜尋、完整文件擷取、批次擷取，以及具依據回答等功能。
這項服務提供的是供應用程式或 Agent 使用的唯讀上下文。它不會讓你存取私有 Cloud 專案、不會核准 IAM 變更、不會部署程式碼，也不會替你判定生成的指令是否安全。Agent 若要執行任何寫入操作，仍需另外具備憑證與政策閘門。
語料庫邊界很重要。Google 的API 文件明確指出，服務涵蓋的是公開開發人員文件，不是一般網路內容。因此，它不能取代對任意 GitHub 儲存庫、Stack Overflow、私有操作手冊或第三方函式庫的搜尋。Google 也提到，回傳的 Markdown 是由來源 HTML 產生，不應將它視為頁面渲染結果的逐位元組副本。
目前的可用性與實際行為，仍應以官方 API 參考文件及版本資訊為準。
Google Developer Knowledge API 提供哪些操作
REST 介面不大，很適合直接納入 Agent 政策模型：
| 操作 | 回傳內容 | 適用情境 |
|---|---|---|
SearchDocumentChunks | 相符的內容區塊及其父文件資源 | 尋找證據與候選頁面 |
GetDocument | 一份完整的 Markdown 文件 | 為 Agent 補足頁面前後文 |
BatchGetDocuments | 多份完整文件 | 比較相關頁面，或預熱本機快取 |
AnswerQuery | 附帶支援參考資料的具依據回答 | 回答範圍明確的文件問題 |
搜尋結果是內容區塊，不保證是完整頁面。結果中的 parent 資源，就是後續交給 GetDocument 或 BatchGetDocuments 的依據。穩健的用戶端應先依 parent 對重複區塊分組，再擷取頁面；否則同一頁可能占掉多個擷取名額，卻沒有帶來多少額外上下文。
典型的資源名稱格式可參考文件資源格式：
documents/docs.cloud.google.com/storage/docs/creating-buckets這個資源名稱模式有助於理解搜尋回應，但 Agent 不應憑記憶自行組出名稱，而應優先使用服務回傳的精確 parent 值。
不同搜尋模式，代表不同的證據契約
SearchDocumentChunks 是以證據為優先的模式。當 Agent 需要精確的旗標、參數、權限、版本備註或程式碼片段時，應使用它。呼叫端可以檢查內容區塊、保留文件 URI，並決定是否需要進一步擷取完整頁面。
GetDocument 與 BatchGetDocuments 則是取得上下文的模式。若答案取決於前置條件、警告、遷移說明，或單一區塊可能漏掉的相鄰段落，便應在搜尋後使用它們。當設計問題橫跨多個官方頁面時，批次擷取尤其實用。
AnswerQuery 是整合回答模式。當問題有明確範圍，例如「在這些限制下，目前哪個 Google Cloud 選項最合適？」且回答應以語料庫為依據時，它很適用。但這不表示可以不看參考來源，就直接接受一段流暢的回答。若涉及高風險程式碼變更，搜尋加上完整文件擷取，能讓 Agent 留下更容易檢查的證據軌跡。
驗證方式要配合呼叫端
實務上有三種驗證模式，但它們適合的呼叫端並不相同。
| 呼叫端 | 建議起點 | 原因 |
|---|---|---|
| 本機 curl 或快速原型 | 受限制的 API 金鑰 | 最快能送出第一個請求 |
| 後端、Worker 或 Python 用戶端 | Application Default Credentials (ADC) | 讓憑證留在執行環境，而非原始碼中 |
| 互動式 MCP 用戶端 | 主機支援時使用 OAuth；否則使用受限制的金鑰 | 避免在使用者工具間散發同一把長期有效金鑰 |
若是快速開始，先建立或選擇一個 Google Cloud 專案，啟用 developerknowledge.googleapis.com，再建立一把僅限 Developer Knowledge API 使用的 API 金鑰。切勿把未受限制的金鑰放進 Agent 提示詞、儲存庫、前端 bundle 或除錯日誌。
最基本的服務啟用指令如下：
gcloud services enable developerknowledge.googleapis.com \
--project="$PROJECT_ID"對受管理的應用程式而言，ADC 通常是更乾淨的界線。Google 的Python 用戶端參考文件說明了由環境探索憑證的方式，以及同步與非同步用戶端。這讓部署環境能在執行階段提供身分，而不是強迫應用程式從設定文字中解析金鑰。
對互動式 Agent 來說，OAuth 很合適，因為是使用者授權連線，而非依賴共用的靜態密鑰。實際 OAuth 流程取決於 MCP 主機。用戶端的驗證支援必須與 API 本身分開確認；即使某個用戶端能接受 MCP URL，也不代表它處理標頭、祕密變數或權杖更新的方式完全相同。
最小可行的文件擷取流程
正式環境中的 Agent，應把擷取邊界定義得很清楚：
- 先從問題中移除祕密資訊與無關的儲存庫內容。
- 使用
SearchDocumentChunks搜尋官方語料庫。 - 依父文件資源去除重複結果。
- 若任務需要完整上下文，再擷取最相關的完整文件。
- 保留服務回傳的 URI、標題、時間戳記或中繼資料，以及選取的摘錄。
- 要求模型只能根據保留的證據作答。
- 在 Agent 變更程式碼或基礎架構前，執行測試與政策檢查。
搜尋用 REST 端點記載於 Google 的REST 參考文件：
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 參考文件確認實際回應結構與欄位名稱。搜尋會產生內容區塊與父文件名稱；文件擷取則會使用這些名稱。
應以模擬或快照回應測試 Agent，涵蓋空結果、缺少 parent、分頁、驗證失敗，以及配額或速率限制回應。重試邏輯應放在模型提示詞之外，採用有上限的退避機制，並在無法取得證據時提供清楚的備援處理。
該用直接 API、MCP，還是網頁？
同一份文件來源，可以透過三種方式提供：
| 情境 | 最佳途徑 | 原因 |
|---|---|---|
| 服務需要可重複的擷取與引用 | REST API 或用戶端函式庫 | 應用程式可自行掌控剖析、快取與證據保存 |
| 程式設計助理需要隨需取得 Google 上下文 | Developer Knowledge MCP server | Agent 不必撰寫額外整合程式，即可呼叫搜尋與擷取工具 |
| 頁面不在支援的語料庫內 | 直接存取頁面或使用另一個來源連接器 | Developer Knowledge 語料庫無法回答未收錄的來源 |
| 人員要檢查版面、導覽或互動式範例 | 瀏覽器／頁面存取 | Markdown 擷取不是視覺頁面檢視 |
Google 的MCP 文件將端點列為 https://developerknowledge.googleapis.com/mcp。MCP 是給 Agent 使用的轉接層，不是另一套知識庫。典型的遠端伺服器設定形式如下：
{
"mcpServers": {
"google-developer-knowledge": {
"serverUrl": "https://developerknowledge.googleapis.com/mcp",
"headers": {"x-goog-api-key": "${DEVELOPERKNOWLEDGE_API_KEY}"}
}
}
}請使用主機文件所定義的祕密變數語法；不要假設字面上的 ${...} 在所有環境都能展開。上下文成本同樣值得考量：每個任務都暴露所有工具，可能增加工具定義與決策負擔。一則討論多伺服器 Agent 架構的真實使用者留言，直接點出了這個顧慮：
「相較於 skills，MCP 非常吃上下文；skills 在被呼叫前只占幾行文字。」— u/junlim，Reddit discussion
這不是放棄 Developer Knowledge MCP server 的理由，而是應讓它只在 Google 相關任務中按條件啟用。處理 Firebase、Android、Google Cloud、Maps 或 Flutter 的 Agent 能從這個來源受益；修改無關技術堆疊的 Agent，則不應預設呼叫它。
哪些情況下 API 比爬取 Google 開發文件更合適
若多數條件成立，應優先使用 API：
- 任務目標是 Google 擁有的開發人員文件。
- Agent 需要可重複的搜尋，而不是單次抓取某個頁面。
- 回答需要引用來源或保留來源軌跡。
- Agent 必須能區分相關內容區塊與完整文件。
- 流程需要結構化分頁、批次處理或快取。
- 頁面重新設計後，不希望還得重寫 HTML 剖析器。
不過，爬取仍可能是正確的備援方案。當所需頁面不在支援語料庫中、任務包含視覺互動，或需要精確的渲染 HTML 與導覽狀態時，就應採用它。如果 API 無法使用，在事件處理期間先以爬取暫時探查也合理；但不該在沒有明確決策的情況下，悄悄變成正式環境的擷取契約。
| 決策因素 | Developer Knowledge API | 爬取開發人員頁面 |
|---|---|---|
| 內容發現 | 在其索引語料庫內由服務搜尋 | 自行建立搜尋機制，或從已知 URL 開始 |
| 輸出 | 內容區塊、文件資源與 Markdown | HTML 或渲染後的頁面內容 |
| 引用流程 | 父資源與文件 URI 明確可得 | 應用程式必須自行擷取並保存連結 |
| 版面維護 | 以 API 契約作為邊界 | 頁面改版後選擇器可能失效 |
| 涵蓋範圍 | 支援的公開開發人員語料庫 | 所有可公開存取的頁面，但受存取規則與 robots 規範限制 |
| 視覺保真度 | 不是設計目標 | 使用瀏覽器自動化時，可保留渲染後版面 |
| Agent 控制流程 | 先搜尋、再擷取、最後整合 | 通常要自行抓取、剖析、清理與推論 |
API 不保證每個剛發布的頁面都能立即使用。Google 的版本資訊會說明索引更新，但 Agent 應把新鮮度視為需要驗證的特性，不能把它當成最新頁面已經完成索引的證明。若是在發布當日進行遷移，應比對回傳的中繼資料與目前官方頁面；缺乏證據時，應採取失敗即關閉的策略。
我會部署的 Agent 政策
若是專門處理 Google 的程式設計 Agent，我會採用以下路由規則：
- 精確的實作細節：先使用
SearchDocumentChunks；如果內容區塊缺少前置條件，再擷取父文件。 - 跨頁的設計問題：先搜尋，再對少量相關 parent 使用
BatchGetDocuments。 - 單純的說明問題：使用
AnswerQuery，但要求回應附上參考資料。 - 非 Google 或私有文件：導向另一個經核准的連接器。
- 程式碼或基礎架構寫入：文件擷取只能作為建議；測試、IAM、審查與部署控制仍不可省略。
在政策允許的範圍內快取完整文件、對重複搜尋進行去彈跳處理，並記錄來源 URI，而不是原始祕密資訊或不必要的儲存庫上下文。也應將取得的 Markdown 視為不受信任的輸入：來源具權威性，不代表其中嵌入的每一項指令，對擁有寫入工具的 Agent 都是安全的。
尚未消失的取捨其實很直接：API 為 Agent 提供比 HTML 爬取更乾淨、更可稽核的契約，但也放棄了瀏覽器所提供的涵蓋範圍與即時頁面保真度。對支援的 Google 文件，應以 API 作為預設方案；爬取或其他連接器則應保留為明確的備援路徑，而不是讓兩條路徑在背後無聲混用。
Google Developer Knowledge API 常見問題
Developer Knowledge API 和 Google Search 一樣嗎？
不一樣。它是在支援的 Google 開發人員語料庫上運作的文件擷取服務，不是一般網路搜尋 API。它不會自動搜尋私有文件、任意 GitHub 內容，或所有與 Google 有關的頁面。
該用 AnswerQuery 還是 SearchDocumentChunks？
若要取得範圍明確且以文件為依據的說明，使用 AnswerQuery。若 Agent 需要可檢查的證據、精確語法或來源軌跡，則使用 SearchDocumentChunks；當內容區塊不足時，再擷取父文件。
一定需要 API 金鑰嗎？
受限制的 API 金鑰是最快的原型路徑。後端用戶端可以使用 ADC，而互動式 MCP 整合若主機支援，則可使用 OAuth。不要假設某個用戶端支援的驗證方式，另一個用戶端也一定支援。
Agent 可以用這個 API 部署 Google Cloud 資源嗎？
不行。這個 API 提供的是文件上下文。部署仍需另外使用工具、憑證、IAM 權限、核准流程與驗證機制。
什麼時候應該改用爬取？
當頁面不在 API 語料庫內、視覺版面很重要，或索引尚未收錄所需頁面時，請使用爬取或瀏覽器連接器。應明確記錄這項備援，避免 Agent 把爬取內容說成是由 API 支援的引用。
搜尋會回傳完整頁面嗎？
不會。搜尋回傳的是文件內容區塊。若需要完整 Markdown 頁面，請使用回傳的父文件資源搭配 GetDocument 或 BatchGetDocuments。