用 adk-python 打造 GCS 管理 Agent：GCSAdminToolset 实战指南

用 adk-python 打造 GCS 管理 AgentGCSAdminToolset 实战指南【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python本指南以 adk-python 仓库中的 GCS Admin Tools 示例contributing/samples/integrations/gcs_admin/README.md为核心讲解如何基于google.adk.integrations.gcs模块提供的list_buckets、get_bucket、create_bucket、update_bucket、delete_bucket五个管理工具构建一个可通过自然语言完成 Google Cloud StorageGCS存储桶全生命周期管理的 Agent。读完本文你将掌握该示例 Agent 的完整代码结构、三种凭据接入方式ADC、服务账号密钥、交互式 OAuth的配置方法以及工具底层实现与安全边界。示例概述GCS 管理 Agent 能做什么该示例演示了 ADK 中由google.adk.integrations.gcs模块分发的 GCS 管理工具核心入口是GCSAdminToolset。它把 5 个 GCS 存储桶管理操作封装为 Agent 可调用的工具工具名功能list_buckets列出 Google Cloud 项目中的 GCS 存储桶名称get_bucket获取某个 GCS 存储桶的元数据信息create_bucket创建新的 GCS 存储桶update_bucket更新 GCS 存储桶的属性delete_bucket删除 GCS 存储桶在示例 agent.py 中这些工具被挂载到一个名为gcs_admin的LlmAgent上模型默认gemini-2.5-flash根据用户的自然语言指令自动选择并调用合适的工具从而实现用一句话管理存储桶的效果。示例 Agent 代码全解析示例的核心文件 agent.py 结构清晰可以分为三部分凭据类型开关、工具初始化、Agent 定义。1. 凭据类型开关# Define an appropriate credential type. # Set to None to use Application Default Credentials (ADC). # This is the recommended way to use your gcloud credentials locally: # Run gcloud auth application-default login in your terminal first. CREDENTIALS_TYPE NoneCREDENTIALS_TYPE是整个示例的模式开关可选值为None使用 ADC、AuthCredentialTypes.SERVICE_ACCOUNT服务账号密钥、AuthCredentialTypes.OAUTH2交互式 OAuth。枚举定义位于 src/google/adk/auth/auth_credential.py其中OAUTH2 oauth2、SERVICE_ACCOUNT serviceAccount。2. 工具能力与凭据初始化# Define GCS admin tool config (default is READ_ONLY; add Capabilities.READ_WRITE for modification access) tool_settings GCSToolSettings(capabilities[Capabilities.READ_WRITE])这里通过GCSToolSettings显式声明了工具的读写能力详见下文能力开关一节。随后根据CREDENTIALS_TYPE分支构造GCSCredentialsConfigOAUTH2 分支从环境变量OAUTH_CLIENT_ID、OAUTH_CLIENT_SECRET读取客户端凭据并声明 OAuth 作用域scopes[ https://www.googleapis.com/auth/cloud-platform, https://www.googleapis.com/auth/devstorage.full_control, ]SERVICE_ACCOUNT 分支通过google.auth.load_credentials_from_file(service_account_key.json)加载服务账号密钥文件路径需替换为你自己的密钥文件。默认分支ADC通过google.auth.default()获取应用默认凭据。最后将二者组合成工具集gcs_admin_toolset GCSAdminToolset( credentials_configcredentials_config, gcs_tool_settingstool_settings )3. Agent 定义root_agent LlmAgent( modelgemini-2.5-flash, namegcs_admin, description( Agent to assist with Google Cloud Storage (GCS) administrative tasks such as listing buckets. ), instruction\ You are a GCS admin agent with access to GCS administrative tools. Make use of those tools to assist the user with bucket management tasks. , tools[gcs_admin_toolset], )注意两点变量名必须叫root_agent调试 CLI 才能识别它为根 Agenttools列表传入的是整个GCSAdminToolset而非单个工具工具集会展开为多个工具。能力开关Capabilities 与 GCSToolSettingsGCSAdminToolset的读写能力由 settings.py 中的Capabilities枚举控制Capabilities.READ_ONLY值read_only只允许读操作这是GCSToolSettings.capabilities的默认值。也就是说如果你不显式配置Agent 只会暴露get_bucket和list_buckets两个只读工具。Capabilities.READ_WRITE值read_write同时开放读与写操作示例中通过GCSToolSettings(capabilities[Capabilities.READ_WRITE])启用此时create_bucket、update_bucket、delete_bucket才会被注入。这一开关的作用机制可以在 admin_toolset.py 的get_tools方法中看到只读工具get_bucket、list_buckets在包含READ_ONLY或READ_WRITE任一能力时注册而写工具create_bucket、update_bucket、delete_bucket仅在包含READ_WRITE时注册。这意味着默认配置下 Agent无法执行任何修改操作这对防止模型误删存储桶是很实用的安全边界。GCSToolSettings还支持tool_filterToolPredicate | list[str]用于按名称筛选工具与local_file_root字段——后者是本地文件路径解析根目录模型传入的本地文件上传/下载路径只有在该目录内才被允许用于约束 Agent 对自身文件系统的访问。另外GCSAdminToolset在构造时使用了工具名前缀DEFAULT_GCS_TOOL_NAME_PREFIX gcs见 admin_toolset.py因此最终暴露给模型的工具名为gcs_list_buckets、gcs_get_bucket、gcs_create_bucket等。凭据接入的三种模式示例文档提供了三种让工具获得 GCS 访问权限的方式可按开发阶段选择。模式一应用默认凭据ADC推荐本地开发这是最简单的方式直接用你自己的 Google Cloud 身份同时驱动工具和 LLM安装 Google Cloud CLIgcloud。在终端执行gcloud auth application-default login。配置环境使用支持 ADC 的 Vertex AI 而非 AI Studioexport GOOGLE_GENAI_USE_ENTERPRISETRUEexport GOOGLE_CLOUD_PROJECT{your-project-id}确保已启用 Vertex AI API 并授予相应权限启用 APIgcloud services enable aiplatform.googleapis.com授予角色gcloud projects add-iam-policy-binding {your-project-id} --memberuser:{your-email} --roleroles/aiplatform.user将agent.py中的CREDENTIALS_TYPE设为None。运行 Agent。对应代码路径是 agent.py 的else分支google.auth.default()会读取通过gcloud auth application-default login生成的 ADC 凭据文件。模式二服务账号密钥适合 Agent 开发者想用服务账号凭据快速跑通开发的场景工具会以该凭据执行按照 Google Cloud 官方文档创建服务账号密钥user-managed keys。在agent.py中设置CREDENTIALS_TYPEAuthCredentialTypes.SERVICE_ACCOUNT。下载密钥文件并将代码中的service_account_key.json替换为你的密钥文件路径。运行 Agent。对应代码见 agent.py使用google.auth.load_credentials_from_file加载密钥。模式三交互式 OAuth适合需要以终端用户身份授权、走完整 OAuth 流程的场景在 Google Cloud Console 创建 OAuth 2.0 凭据客户端类型务必选择 web获得 client id 与 client secret。在 OAuth 同意屏幕consent screen声明作用域https://www.googleapis.com/auth/cloud-platform与https://www.googleapis.com/auth/devstorage.full_control后者用于审查用途。在 Authorized redirect URIs 中添加http://localhost/dev-ui/——注意这里的localhost只是你访问 dev UI 的主机名需替换为你实际访问 dev UI 的主机名。首次运行时需要在 Chrome 中允许 localhost 弹窗用于完成授权跳转。在你的.env文件中追加两个变量不要另建.env直接放进存放 Vertex AI 或 Dev ML 凭据的那个.envOAUTH_CLIENT_ID{your client id}OAUTH_CLIENT_SECRET{your client secret}在agent.py中设置CREDENTIALS_TYPEAuthCredentialTypes.OAUTH2并运行 Agent。对应代码见 agent.py它读取两个环境变量并构造带作用域的GCSCredentialsConfig。从源码看GCSCredentialsConfig继承自BaseGoogleCredentialsConfiggcs_credentials.py默认作用域为https://www.googleapis.com/auth/devstorage.full_control并使用固定的 token 缓存键gcs_token_cachetoken 缓存机制支持交互式授权的一次登录、后续复用。配置 LLM 服务无论哪种模式都需要在.env文件中配置 LLM 服务。使用 Google AI Studio 时设置GOOGLE_GENAI_USE_ENTERPRISEFALSEGOOGLE_API_KEY{your api key}使用 Google Cloud Vertex AI 时则设置GOOGLE_GENAI_USE_ENTERPRISETRUE与GOOGLE_CLOUD_PROJECT配合 ADC 模式。底层实现五个管理工具的原理工具的真实逻辑位于 admin_tool.py它们统一通过 client.py 中的get_gcs_client创建google.cloud.storage.Client携带adk-gcs-tool google-adk/{version}的 User-Agent并遵循统一的返回结构成功时返回{status: SUCCESS, results: ...}异常时返回{status: ERROR, error_details: ...}异常信息会回传给模型以便其自我修正。list_buckets(project_id, credentials, page_sizeNone, page_tokenNone)列出项目内所有存储桶。支持分页——传入page_size时走分页器返回results桶名列表及可选的next_page_token不传page_size时一次性返回全部桶名。对应测试 tests/unittests/integrations/gcs/test_gcs_admin_tool.py 验证了基本列举与分页两个场景分页时max_results1, page_tokentoken会被透传给底层客户端。get_bucket(bucket_name, credentials)获取桶元数据通过读取bucket._properties返回属性字典。create_bucket(project_id, bucket_name, credentials, locationNone)创建新桶location可选不传时使用默认区域。成功后返回Bucket {name} created successfully.。update_bucket(bucket_name, credentials, versioning_enabledNone, uniform_bucket_level_access_enabledNone)更新桶属性当前支持两个布尔开关开启版本控制bucket.versioning_enabled与开启统一桶级访问bucket.iam_configuration.uniform_bucket_level_access_enabled。任一参数被显式设置非None时才调用bucket.patch()提交变更。delete_bucket(bucket_name, credentials)删除指定存储桶成功后返回Bucket {name} deleted successfully.。从代码看create_bucket、update_bucket、delete_bucket均属于写操作只有启用READ_WRITE能力后才会被注入工具集这与上文的能力开关设计相互印证。实战用示例提示词驱动 Agent示例文档给出了 5 条可直接试用的自然语言提示词覆盖了工具的增删改查全流程List all buckets in the my-project project.列出 my-project 项目中的所有存储桶Show me metadata for the my-bucket bucket.查看 my-bucket 桶的元数据Create a new bucket named my-bucket in my-project.在 my-project 中创建名为 my-bucket 的新桶Enable versioning and uniform bucket-level access on my-bucket.为 my-bucket 开启版本控制与统一桶级访问Delete the GCS bucket my-bucket.删除 GCS 存储桶 my-bucket其中第四条提示词正好命中update_bucket的两个布尔参数第五条则验证了删除操作的链路。注意事项与安全提示写操作默认关闭GCSToolSettings默认能力是READ_ONLY只有显式传入Capabilities.READ_WRITE才会暴露创建、更新、删除工具。生产环境应遵循最小权限原则。本地文件访问受限local_file_root未设置时GCS 工具的上传/下载本地文件功能保持禁用设置后解析到该目录之外的路径会被拒绝。工具为实验性特性GCSAdminToolset与GCSToolSettings均带有experimental装饰器对应FeatureName.GCS_ADMIN_TOOLSET、GCS_TOOL_SETTINGS接口在未来版本中可能调整。OAuth 重定向交互式 OAuth 的授权重定向 URI 必须与实际访问 dev UI 的主机名一致且首次授权需放行浏览器弹窗。要深入了解或扩展可以继续阅读仓库中的相关文件示例代码 contributing/samples/integrations/gcs_admin/agent.py、工具集实现 src/google/adk/integrations/gcs/admin_toolset.py、工具函数实现 src/google/adk/integrations/gcs/admin_tool.py、配置模型 src/google/adk/integrations/gcs/settings.py以及单元测试 tests/unittests/integrations/gcs/test_gcs_admin_tool.py。【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考