您可以将智能体开发套件 (ADK) 智能体连接到 Cloud Storage。借助此连接，您的智能体可以使用内置的 ADK 工具集。
作为 AI 开发者，您可以将 ADK 与 Cloud Storage 集成，以便将智能体连接到存储的数据。此集成有助于扩缩智能体工作负载。您可以使用 Cloud Storage 来持久保存长时间运行的任务的状态、内存和检查点。您还可以使用 Cloud Storage 在多代理工作流中共享中间文件。
本文档介绍了将 Cloud Storage 与 ADK 集成的好处。它涵盖了常见的使用场景和可用工具集的功能。如需查看分步设置说明和代码示例，请参阅 ADK 集成指南。
将 Cloud Storage 与 ADK 集成的优势
将 Cloud Storage 与代理集成后，代理可以处理大型文件、维护对话历史记录，并重复使用您现有的存储基础设施。
- 动态扩展上下文：让代理访问大型数据集、手册或媒体文件，而不会受到 LLM 一次可读取内容量的限制。
- 持久工件持久性：在对话历史记录之外可靠地存储临时文件、日志或生成的内容（例如报告或图片）。
- 支持任何制品类型：使用 Cloud Storage 作为共享存储空间，处理和生成不同格式的内容，包括文本、图片、音频和视频。
- 精细的访问权限控制：使用 IAM 角色精确控制代理对 Cloud Storage 的访问权限。ADK 使用标准 Google Cloud 身份验证来确保代理仅拥有访问数据或执行任务所需的最低权限。
使用场景
通过为代理配备 Cloud Storage 功能，您可以应对以下使用情形：
- 动态上下文检索，也称为检索增强生成 (RAG)
- 制品持久性和归档
- 大型载荷处理
- 自动化资源管理
通过 RAG 进行动态上下文检索
代理可以充当研究员，通过发现和读取 Cloud Storage 中的文档来实时回答问题。此方法适用于内部知识库或支持机器人。
- 政策查询：您可以让代理列出并读取
compliance-docs存储桶中的最新 PDF 手册，以回答用户有关公司政策的查询。 - 多对象合成：您可以构建一个代理，用于从多个存储对象中检索和组合信息，以合成统一的摘要。
制品持久性和归档
可靠地保存大量代理生成的数据，以供人工审核、其他系统使用或进行审核。
- 自动生成报告：您可以创建一个智能体，用于分析数据库指标、生成总结报告并将其上传到
reports-archive存储桶。 - 存储生成的多媒体内容：您可以配置多代理系统，将生成的图片或音频对象保存到 Cloud Storage，并仅返回存储 URI 或签名网址。
大型载荷处理
设计代理，使其使用存储 URI（文件路径），而不是将完整的文件内容粘贴到对话中。这样可以避免向 LLM 发送大型 CSV 或代码库所带来的高成本和低效率。
- 数据流水线处理程序：您可以让代理接收存储 URI，而不是使用大型 CSV 文件。然后，代理可以通过处理块或检查元数据来执行分析，并返回摘要信息中心。
- 解耦的工作流：您可以设计一个代理，使其充当接收 Cloud Storage 前缀、文件夹或存储桶的存储 URI 的主管。代理可以将此 URI 传递给后端工作器，以处理对象并将最终结果写回存储空间。此模式与 Cloud Run functions 或 Cloud Run 等事件驱动型服务兼容，可用于异步处理数据。
自动化资源管理
代理可以帮助优化存储空间用量、自动执行管理任务，以及跨多个存储分区强制执行治理。对于管理大量存储基础设施的团队而言，此功能特别有用。
- 基础设施审核：您可以创建代理来扫描存储桶配置（例如位置或存储类别），并建议优化或识别不合规的设置。
- 资源清理：您可以构建一个代理来识别空存储分区或过时的存储分区，并根据保留政策自动执行清理流程。
适用于 Cloud Storage 的 ADK 工具集
ADK 在 Python 中为 Cloud Storage 提供以下工具集。了解这两者有助于您定义智能体角色并限制其权限。
GCSToolset 用于数据管理
借助 GCSToolset 工具集，您的代理可以操作现有存储分区中的文件。可用于读取文档、上传结果或删除临时对象等任务。
- 读取对象：使用
get_object_data直接检索内容。 - 发现内容：使用
list_objects列出可用的对象。 - 检查对象属性：使用
get_object_metadata检查对象大小或Content-Type元数据。 - 上传并持久保留：使用
create_object创建新对象。 - 移除对象：使用
delete_objects移除临时对象。
GCSAdminToolset 适用于基础设施
使用 GCSAdminToolset 工具集来管理存储基础架构，例如创建存储分区或自动执行管理任务。
- 探索基础架构：使用
list_buckets列出项目中的存储分区。 - 预配存储空间：使用
create_bucket创建新存储分区。 - 重新配置存储空间：使用
update_bucket修改配置。 - 取消预配存储空间：使用
delete_bucket移除存储分区。 - 检查存储桶上下文：使用
get_bucket获取存储桶元数据，以检查存储桶位置、存储类别或访问权限控制。
最佳做法
为了在与 Cloud Storage 集成时优化代理性能和安全性，请考虑以下最佳实践：
- 将大型载荷与对话历史记录分离：避免直接将大型文件传递给代理。将它们存储在 Cloud Storage 中，然后发送文件引用 (URI)。这样可以降低 token 费用，并防止达到上下文限制。
- 应用最小权限原则：仅向代理授予执行其任务所需的最低权限。避免使用
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 集成指南。