您可以將 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 會使用標準 Google Cloud 驗證機制，確保服務專員只具備存取資料或執行工作所需的最低權限。
用途
為代理程式提供 Cloud Storage 功能，即可處理下列用途：
- 動態內容檢索，也稱為檢索增強生成 (RAG)
- 構件保留與封存
- 處理大型酬載
- 自動化資源管理
透過 RAG 動態擷取情境資訊
代理程式可以充當研究人員，在 Cloud Storage 中尋找及閱讀文件，即時回答問題。這種做法適用於內部知識庫或支援機器人。
- 政策查詢：代理程式可以列出並讀取
compliance-docs儲存空間中的最新 PDF 手冊，回答使用者有關公司政策的查詢。 - 多個物件的合成：您可以建立代理，從多個儲存空間物件擷取及合併資訊，合成統一摘要。
構件保留與封存
大量儲存代理程式產生的資料，供人工審查、其他系統或稽核使用。
- 自動產生報表：您可以建立代理程式，分析資料庫指標、產生摘要報表，並上傳至
reports-archive值區。 - 儲存生成的媒體：您可以設定多代理程式系統，將生成的圖片或音訊物件儲存到 Cloud Storage，並只傳回儲存 URI 或簽署的網址。
處理大型酬載
設計代理程式時，請使用儲存空間 URI (檔案路徑)，而不是將完整檔案內容貼到對話中。這樣可避免將大型 CSV 或程式碼庫傳送至 LLM，進而節省高昂的費用並提升效率。
- 資料管道處理常式：您可以讓代理程式接收儲存空間 URI，不必耗用大量 CSV 檔案。接著，代理程式就能處理區塊或檢查中繼資料，然後執行分析並傳回摘要資訊主頁。
- 工作流程分離：您可以設計代理程式做為主管，接收 Cloud Storage 前置字元、資料夾或值區的儲存 URI。代理程式可將這個 URI 傳遞至後端工作站，處理物件並將最終結果寫回儲存空間。這個模式與 Cloud Run functions 或 Cloud Run 等事件導向服務相容，可非同步處理資料。
自動化資源管理
代理可協助您最佳化儲存空間用量、自動執行管理工作，以及在多個值區中強制執行控管措施。對於管理大量儲存基礎架構的團隊來說，這項功能特別實用。
- 基礎架構稽核：您可以建立代理程式來掃描 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列出專案中的值區。 - 佈建儲存空間：使用
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。 - 集中管理設定：避免在代理程式邏輯中，對值區名稱或物件名稱路徑進行硬式編碼。使用環境變數或設定管理員，在開發、測試和正式儲存環境之間切換。
- 採用有效率的擷取策略：將 Cloud Storage 做為知識擷取層時，請勿將整個大型文件載入代理程式的內容。預先處理文件並分塊，或使用專用搜尋工具只擷取相關片段。
限制
將 Cloud Storage 與 ADK 整合時，請注意下列限制：
- 不可變動的物件：Cloud Storage 物件不可變動。你無法將資料附加至現有物件。如果代理程式需要將事件持續記錄到單一檔案，則必須完全覆寫物件，或建立多個小型物件，然後再組合這些物件。
- 高頻率狀態管理中的延遲：Cloud Storage 非常適合用於儲存耐用的構件和大型酬載。不過，使用 Cloud Storage 進行高頻率和低延遲的狀態更新可能會導致延遲。舉例來說，追蹤快速對話中的每個回合，可能比使用記憶體內快取或資料庫慢。
- 缺乏多物件原子性：Cloud Storage 作業適用於個別物件。如果代理程式需要同時對多個檔案進行不可分割的更新，則必須在應用程式中實作協調邏輯。
後續步驟
如要查看詳細的程式碼範例、設定說明和參數參考資料，瞭解如何在 Python 應用程式中初始化 Cloud Storage 工具集，請參閱 ADK 整合指南。