您可以將 Agent Development Kit (ADK) 代理程式連結至 Cloud Storage。建立連結後，代理就能使用內建的 ADK 工具組。
AI 開發人員可以將 ADK 與 Cloud Storage 整合，將代理連結至儲存的資料。這項整合功能可協助您擴充代理程式工作負載。您可以使用 Cloud Storage 持久儲存長時間執行的工作狀態、記憶體和檢查點。您也可以使用 Cloud Storage，在多個代理程式工作流程中分享中繼檔案。
本文說明整合 Cloud Storage 與 ADK 的優點。包括常見用途和可用工具組的功能。如需逐步設定操作說明和程式碼範例，請參閱 ADK 整合指南。
Cloud Storage 與 ADK 整合的優點
將 Cloud Storage 與代理整合後，代理就能處理大型檔案、維護對話記錄，並重複使用現有的儲存空間基礎架構。
- 動態擴充背景資訊：讓服務專員存取大型資料集、手冊或媒體檔案，不必擔心大型語言模型一次可讀取的資料量有限。
- 持久保存構件：在對話記錄之外，可靠地儲存臨時檔案、記錄或生成的項目 (例如報表或圖片)。
- 支援任何構件類型：使用 Cloud Storage 做為共用儲存空間，處理及生成不同格式，包括文字、圖片、音訊和影片。
- 精細的存取控管機制：使用 IAM 角色精確控管代理程式的 Cloud Storage 存取權。ADK 採用標準 Cloud de Confiance by S3NS 驗證機制，確保代理僅具備存取資料或執行工作所需的最低權限。
用途
為代理程式提供 Cloud Storage 儲存空間能力，即可解決下列用途：
- 動態檢索背景資訊，也稱為檢索增強生成 (RAG)
- 構件持續性和封存
- 處理大型酬載
- 自動化資源管理
透過 RAG 動態檢索情境資訊
代理程式可以充當研究人員，在 Cloud Storage 中尋找及閱讀文件，即時回答問題。這種做法適用於內部知識庫或支援機器人。
- 政策查詢：代理程式可以列出並讀取
compliance-docs儲存空間中的最新 PDF 手冊，回答使用者有關公司政策的查詢。 - 多物件合成：您可以建構代理，從多個儲存物件擷取及合併資訊，合成統一的摘要。
構件保留和封存
可靠地儲存大量代理生成的資料，供人工審查、其他系統或稽核使用。
- 自動產生報表：您可以建立代理程式，分析資料庫指標、產生摘要報表，並上傳至
reports-archive值區。 - 儲存生成的媒體：您可以設定多代理程式系統，將生成的圖片或音訊物件儲存至 Cloud Storage，並只傳回儲存空間 URI 或已簽署的網址。
處理大型酬載
設計代理程式時，請使用儲存空間 URI (檔案路徑)，而不是將完整檔案內容貼到對話中。這樣可避免將大型 CSV 或程式碼集傳送至 LLM，導致成本高昂且效率不彰。
- 資料管道處理常式：您可以讓代理接收儲存空間 URI，而非使用大型 CSV。接著，代理程式就能處理區塊或檢查中繼資料，然後執行分析並傳回摘要資訊主頁。
- 工作流程分離：您可以設計代理程式做為主管，接收 Cloud Storage 前置字元、資料夾或值區的儲存空間 URI。代理可以將這個 URI 傳遞給後端 worker，以便處理物件並將最終結果寫回儲存空間。這個模式與 Cloud Run functions 或 Cloud Run 等事件導向服務相容，可非同步處理資料。
自動化資源管理
代理可協助最佳化儲存空間用量、自動執行管理工作，以及在多個 bucket 之間強制執行管理。這項功能特別適合管理大量儲存基礎架構的團隊。
- 基礎架構稽核：您可以建立代理程式來掃描 bucket 設定 (例如位置或儲存空間類別)，並建議最佳化做法或找出不符規定的設定。
- 資源清理：您可以建構代理來找出空白或過時的 bucket，並根據資料保留政策自動執行清理程序。
Cloud Storage 的 ADK 工具組
ADK 提供下列 Cloud Storage 適用的 Python 工具組。瞭解這兩者有助於定義代理角色並限制其權限。
GCSToolset，瞭解如何管理資料
GCSToolset 工具組可讓代理程式操控現有 bucket 中的檔案。可用於讀取文件、上傳結果或刪除暫存物件等工作。
- 讀取物件：使用
get_object_data直接擷取內容。 - 探索內容：使用
list_objects列出可用物件。 - 檢查物件屬性：使用
get_object_metadata檢查物件大小或Content-Type中繼資料。 - 上傳及保留：使用
create_object建立新物件。 - 移除物件：使用
delete_objects移除暫時物件。
GCSAdminToolset 基礎架構
使用 GCSAdminToolset 工具組管理儲存空間基礎架構，例如建立 bucket 或自動執行管理工作。
- 探索基礎架構：使用
list_buckets列出專案中的 bucket。 - 佈建儲存空間：使用
create_bucket建立新的 bucket。 - 重新設定儲存空間：使用
update_bucket修改設定。 - 取消佈建儲存空間：使用
delete_bucket移除 bucket。 - 檢查 bucket 情境：使用
get_bucket取得 bucket 中繼資料，檢查 bucket 位置、儲存空間級別或存取控管機制。
最佳做法
整合 Cloud Storage 時，為提升代理程式效能和安全性，請考慮採用下列最佳做法：
- 將大型酬載與對話記錄分離：避免將大型檔案直接傳送給代理。請改為將檔案儲存在 Cloud Storage，並傳送檔案參照 (URI)。這可降低權杖成本，並避免達到內容限制。
- 套用最小權限原則：只授予代理執行工作所需的最低權限。除非要管理基礎架構，否則請避免使用
roles/storage.admin等廣泛角色。如要執行標準檔案作業，請使用目標角色 (例如roles/storage.objectUser或roles/storage.objectViewer)，並限制只能存取特定 bucket。 - 集中管理設定：避免在代理邏輯中硬式編碼 bucket 名稱或物件名稱路徑。使用環境變數或設定管理工具，在開發、測試和正式版儲存空間環境之間切換。
- 採用有效率的擷取策略：將 Cloud Storage 做為知識擷取層時，請勿將整個大型文件載入代理程式的環境。預先處理及分塊文件，或使用專屬搜尋工具，只擷取相關區隔。
限制
將 Cloud Storage 與 ADK 整合時，請注意下列限制：
- 不可變物件：Cloud Storage 物件不可變動。您無法將資料附加至現有物件。如果代理程式需要持續將事件記錄到單一檔案，則必須完全覆寫物件，或建立多個小型物件，並在稍後組合這些物件。
- 高頻率狀態管理的延遲時間：Cloud Storage 適合用於耐用的構件儲存空間和大型酬載。不過，使用 Cloud Storage 進行高頻率和低延遲狀態更新可能會導致延遲。舉例來說，追蹤快速對話中的每個回合，可能比使用記憶體內快取或資料庫慢。
- 缺乏多物件原子性：Cloud Storage 作業適用於個別物件。如果代理程式需要同時對多個檔案執行不可分割的更新，則必須在應用程式中實作協調邏輯。
後續步驟
- 如要查看詳細的程式碼範例、設定說明和參數參考資料，瞭解如何在 Python 應用程式中初始化 Cloud Storage 工具集，請參閱 ADK 整合指南。
- 如要搭配 ADK 代理或 AI 程式開發輔助使用預先建構的代理技能，請參閱「Cloud Storage 代理技能」。