您可以将智能体开发套件 (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 集成指南。