使用 ADK 和 Cloud Run 的單一代理 AI 系統

• 明確定義代理式 AI 系統的業務目標，以及每個代理執行的工作。
• 選擇最符合需求的代理程式設計模式。
• 使用 ADK 即可有效率地建立、部署及管理代理架構。

• 在架構中設計面向人員的代理，支援自然語言互動。
• 請確保每個代理程式都清楚向其依附的用戶端傳達行動和狀態。
• 設計代理程式，偵測及處理模稜兩可的查詢和細微的互動。

• 請確保代理有足夠的脈絡，可追蹤多輪互動和工作階段參數。
• 清楚說明代理可使用的工具用途、引數和用法。
• 確保代理程式的回覆以可靠的資料來源為依據，減少幻覺。
• 實作邏輯來處理無相符內容的情況，例如提示離題。

AI 代理會帶來獨特且嚴重的安全風險，傳統的確定性安全做法可能無法充分降低這些風險。Google 建議採用方法，結合確定性安全控制選項的優勢，以及動態的推論型防禦機制。這項做法以三項核心原則為基礎：人類監督、審慎定義代理自主性，以及可觀測性。以下是符合這些核心原則的具體建議。

人工監督：代理式 AI 系統有時可能會發生故障或無法正常運作。舉例來說，模型可能會生成不準確的內容，或是代理可能會選取不當工具。在業務關鍵的代理式 AI 系統中，加入人機迴圈流程，讓人類主管監控、覆寫及暫停代理。舉例來說，人類使用者可以審查服務專員的輸出內容、核准或拒絕輸出內容，並提供進一步指引來修正錯誤或做出策略決策。這種方法結合了代理式 AI 系統的效率，以及人類使用者的批判性思考和領域專業知識。

代理的存取控管：使用 Identity and Access Management (IAM) 控制項設定代理權限。只授予每個代理執行工作、與工具和其他代理通訊所需的權限。這種做法有助於盡量降低安全漏洞的潛在影響，因為遭入侵的代理程式只能存取系統的其他部分。詳情請參閱「使用 IAM 控管 Agent Platform 存取權」。

監控：運用全方位追蹤功能監控代理的行為，清楚掌握代理採取的每個動作，包括推論過程、工具選擇和執行路徑。詳情請參閱「在 Agent Runtime 中記錄代理程式」和「在 ADK 中記錄」。

如要進一步瞭解如何保護 AI 代理，請參閱「AI 代理的安全防護」。

共同責任：安全是共同的責任。Agent Platform 可保護基礎架構，並提供工具和安全控管機制，協助您保護資料、程式碼和模型。您有責任正確設定服務、管理存取權控管措施，以及保護應用程式安全。詳情請參閱「 Agent Platform 共同責任」。

安全控管機制：Agent Platform 支援 Google Cloud 安全控管機制，可協助您符合資料落地、客戶自行管理的加密金鑰 (CMEK)、使用 VPC Service Controls 的網路安全，以及資料存取透明化控管機制等方面的要求。詳情請參閱下列說明文件：

• Agent Platform 的安全控管機制
• 生成式 AI 的安全控制項
• Agent Platform 和零資料保留

安全性：AI 模型可能會生成有害回覆，有時是為了回應惡意提示。

• 為提升安全性並降低代理式 AI 系統遭濫用的可能性，您可以設定內容篩選器，阻擋有害的輸入內容和回覆。詳情請參閱「安全與內容篩選器」。
• 如要檢查及清理推論要求和回覆，防範提示詞注入和有害內容等威脅，可以使用 Model Armor。Model Armor 可協助您防範惡意輸入內容、驗證內容安全性、保護私密/機密資料、維持法規遵循狀態，以及持續強制執行安全政策。

模型存取權：您可以設定組織政策，限制 Google Cloud 專案中可使用的 AI 模型類型和版本。詳情請參閱「控管對 Model Garden 模型的存取權」。

資料保護：如要探索及去識別化提示和回覆內容，以及記錄資料中的機密資料，請使用 Cloud Data Loss Prevention API。詳情請觀看「Protecting sensitive data in AI apps」影片。

傳輸安全：A2A 通訊協定規定，在正式環境中，所有 A2A 通訊都必須使用 HTTPS，並建議採用傳輸層安全標準 (TLS) 1.2 以上版本。

驗證：A2A 通訊協定會將驗證作業委派給標準網路機制 (例如 HTTP 標頭)，以及 OAuth2 和 OpenID Connect 等標準。每個代理程式都會在代理程式資訊卡中顯示驗證需求。詳情請參閱「A2A 驗證」。

連入安全防護 (適用於前端服務)：如要控管應用程式的存取權，請停用前端 Cloud Run 服務的預設 run.app 網址，並設定區域外部應用程式負載平衡器。除了將傳入應用程式的流量進行負載平衡，負載平衡器也會處理 SSL 憑證管理作業。如要加強保護，可以使用 Google Cloud Armor 安全性政策，為服務提供要求篩選、DDoS 防護和速率限制。

使用者驗證：

• 貴機構內的使用者：如要驗證內部使用者對前端 Cloud Run 服務的存取權，請使用 Identity-Aware Proxy (IAP)。使用者嘗試存取 IAP 保護的資源時，IAP 會執行驗證及授權檢查。
• 貴機構外部使用者：如要驗證外部使用者對前端服務的存取權，請使用 Identity Platform 或 Firebase 驗證。如要管理外部使用者存取權，請設定應用程式來處理登入流程，並向 Cloud Run 服務發出經過驗證的 API 呼叫。

詳情請參閱「驗證使用者」。

容器映像檔安全性：為確保只有授權的容器映像檔會部署至 Cloud Run，您可以使用 二進位授權。如要找出並降低容器映像檔中的安全風險，請使用 Artifact Analysis 自動執行安全漏洞掃描。詳情請參閱「容器掃描總覽」。

資料落地：Cloud Run 可協助您符合資料落地規定。Cloud Run 函式會在所選區域中執行。

如需容器安全性的更多指引，請參閱「一般 Cloud Run 開發提示」。

資料加密：根據預設， Google Cloud會使用 Google-owned and Google-managed encryption keys加密靜態資料。如要使用您控管的加密金鑰保護代理程式資料，可以透過在 Cloud KMS 中建立及管理的客戶自行管理的加密金鑰 (CMEK) 達成。如要瞭解與 Cloud KMS 相容的服務，請參閱「相容服務」。 Google Cloud

降低資料竊取風險：如要降低資料竊取風險，請在基礎架構周圍建立 VPC Service Controls 範圍。VPC Service Controls 支援此參考架構使用的所有 Google Cloud 服務。

存取控管：為拓撲中的資源設定權限時，請遵循最小權限原則。

雲端環境安全：使用 Security Command Center 中的工具偵測安全漏洞、找出並防範威脅、定義及部署安全防護機制，以及匯出資料以供進一步分析。

部署後最佳化：在 Google Cloud中部署應用程式後，使用 Active Assist 取得建議，進一步提升安全性。請查看建議，並視環境需要套用。詳情請參閱「在 Active Assist 中查看建議」。

模擬失敗：將代理式 AI 系統部署到正式環境前，請先模擬正式環境，驗證系統是否正常運作。找出並修正問題和非預期的行為。

水平擴充：為確保高可用性和容錯能力，請在負載平衡器後方執行多個代理程式應用程式執行個體。這種做法也能將要求分散到各個執行個體，有助於減少延遲和逾時。部分代理程式執行階段會自動為您處理負載平衡，例如 Cloud Run 服務中的執行個體自動調度資源。

從服務中斷狀態復原：為確保代理程式能順利處理重新啟動作業並維持脈絡，請將狀態與執行階段分離。如要實作這類無狀態代理程式應用程式，請使用外部資料儲存區，例如資料庫或分散式快取。舉例來說，您可以使用 Memory Bank、Memorystore for Redis，或是 Cloud SQL 等資料庫服務。

處理錯誤：為利於診斷及排解錯誤，請實作記錄、例外狀況處理和重試機制。

容量規劃：如果要求數量超過分配的容量，系統會傳回錯誤代碼 429。對於業務關鍵且持續需要高輸送量的工作負載，您可以使用「佈建輸送量」預留輸送量。

模型端點可用性：如果資料可跨多個區域或國家/地區共用，您可以使用模型的全域端點。

基礎架構中斷時的穩定性： Cloud Run 是區域服務。這項服務會在區域內的多個可用區同步儲存資料，並自動平衡各可用區的流量。如果發生可用區中斷事件，Cloud Run 會繼續執行，資料也不會遺失。如果發生區域中斷，服務會停止運作，直到 Google 解決中斷問題為止。

水平擴充：Cloud Run 服務會為您處理執行個體自動調度資源。自動調度資源可確保執行個體能處理所有傳入要求、事件和 CPU 使用率，確保高可用性。

部署後最佳化：在 Google Cloud中部署應用程式後，使用 Active Assist 取得建議，進一步提升安全性。查看建議，並視環境情況套用。詳情請參閱「在 Active Assist 中查看建議」。

偵錯和分析：在代理程式應用程式中導入結構化記錄。記錄和追蹤功能可讓您以結構化格式擷取重要資訊，例如呼叫的工具、代理程式的輸入和輸出內容，以及每個步驟的延遲時間。

使用記錄進行監控：根據預設，寫入 stdout 和 stderr 串流的代理程式記錄會傳送至 Cloud Logging。如要進行進階記錄作業，可以將 Python 記錄器與 Logging 整合。如要完全控管記錄和結構化記錄，請使用 Logging 用戶端。詳情請參閱「記錄代理程式」和「在 ADK 中記錄」。

持續評估：定期對代理的輸出內容，以及代理產生輸出內容時採取的軌跡或步驟，進行質性評估。如要實作代理評估，可以使用 Gen AI Evaluation Service 或 ADK 支援的評估方法。

健康狀態和效能：使用 Google Cloud Observability 監控 Cloud Run 服務。在 Cloud Monitoring 中設定快訊，以便在發生錯誤率增加、延遲時間過長或資源用量異常等潛在問題時收到通知。

健康狀態和效能：使用 Google Cloud Observability 監控資料庫。在「監控」中設定快訊，以便在發生錯誤率提高、延遲時間過長或資源用量異常等潛在問題時收到通知。

資料庫工具：如要有效管理 AI 代理的資料庫工具，並確保代理安全處理連線集區和驗證等複雜作業，請使用 MCP Toolbox for Databases。這個位置可集中儲存及更新資料庫工具。您可以在代理之間共用工具，並更新工具，不必重新部署代理。工具箱包含各種資料庫工具，例如 AlloyDB for PostgreSQL，以及 MongoDB 等第三方資料庫。 Google Cloud

生成式 AI 模型：如要讓 AI 代理使用 Imagen 和 Veo 等 Google 生成式 AI 模型，可以透過 MCP 伺服器 Google Cloud 使用生成式媒體 API。

Google 安全性產品和工具：如要讓 AI 代理存取 Google 安全性產品和工具，例如 Google Security Operations、Google Threat Intelligence 和 Security Command Center，請使用 Google 安全性產品的 MCP 伺服器。

追蹤：使用 Trace 持續收集及分析追蹤記錄資料。追蹤資料可協助您快速找出並診斷複雜代理工作流程中的延遲問題。您可以在 Google Cloud 控制台的 Trace 探索工具頁面，透過視覺化方式進行深入分析。詳情請參閱「追蹤代理程式」。

成本分析與管理：如要分析及管理 Agent Platform 成本，建議您建立每秒查詢次數 (QPS) 和每秒權杖數 (TPS) 的基準指標。然後在部署後監控這些指標。基準也有助於規劃容量。舉例來說，您可根據基準判斷何時可能需要佈建輸送量。

模型選取：為 AI 應用程式選取的模型會直接影響費用和效能。如要找出最適合特定用途的模型，在效能和成本之間取得最佳平衡，請反覆測試模型。建議您先從最經濟實惠的機型開始，再逐步改用效能更強大的選項。

經濟實惠的提示：提示 (輸入) 和生成的內容 (輸出) 長度會直接影響效能和費用。撰寫簡短、直接且提供充分背景資訊的提示。設計提示，讓模型提供簡潔的回覆。 舉例來說，你可以加入「用 2 句話歸納重點」或「列出 3 個重點」等詞句。詳情請參閱提示設計最佳做法。

脈絡快取：如要降低要求成本，請使用脈絡快取，減少含有重複內容和較多輸入詞元的要求。

批次要求：視情況考慮批次預測。批次要求 的費用比標準要求低。

資源分配：建立 Cloud Run 服務時，您可以指定要分配的記憶體和 CPU 數量。從預設的 CPU 和記憶體分配量開始。觀察一段時間內的資源用量和成本，並視需要調整分配。詳情請參閱下列說明文件：

• 設定服務的記憶體限制
• 為服務設定 CPU 限制

費率最佳化：如果可以預測 CPU 和記憶體需求，就能透過承諾使用折扣 (CUD) 節省費用。

模型選取：為代理式 AI 系統選取模型時，請考量代理執行工作所需的功能。

提示最佳化：如要大規模快速改善及最佳化提示詞效能，並免除手動重寫提示詞的需要，請使用 Agent Platform 提示詞最佳化工具。這項工具可協助您有效調整不同模型的提示。

模型選取：為 AI 應用程式選取的模型會直接影響費用和效能。如要找出最適合特定用途的模型，在效能和成本之間取得最佳平衡，請反覆測試模型。建議您先從最經濟實惠的機型開始，再逐步改用效能更強大的選項。

提示工程：提示 (輸入) 和生成的內容 (輸出) 長度會直接影響效能和費用。撰寫簡短、直接且提供充分背景資訊的提示。設計提示，讓模型提供簡潔的回覆。舉例來說，你可以加入「用 2 句話歸納重點」或「列出 3 個重點」等詞句。詳情請參閱提示設計最佳做法。

脈絡快取：如要減少含有重複內容和較多輸入詞元的要求延遲時間，請使用脈絡快取。

資源分配：根據效能需求，設定要分配給 Cloud Run 服務的記憶體和 CPU。詳情請參閱下列說明文件：

• 為服務設定記憶體限制
• 為服務設定 CPU 限制

如需更多效能最佳化指南，請參閱一般 Cloud Run 開發提示。