您可以将智能体开发套件 (ADK) 智能体连接到 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 为 Cloud Storage 提供了以下 Python 工具集。了解这两者有助于您定义智能体角色并限制其权限。
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 集成指南。
- 如需将预构建的代理技能与 ADK 代理或 AI 编码辅助工具搭配使用，请参阅 Cloud Storage 代理技能。