Google Cloud Storage (GCS)¶

Supported in ADKPython v2.3.0

The GCSToolset 和 GCSAdminToolset 允许 ADK 智能体与 Google Cloud Storage (GCS) 交互，管理存储桶和读取/写入对象。

使用场景¶

对象管理：读取、下载、创建、上传、列出、检查元数据以及删除 GCS 对象。
存储桶管理：列出云存储桶、创建新存储桶、更改配置（如启用版本控制或统一存储桶级访问）以及删除存储桶。
数据集成：在智能体的工作流中动态使用云存储对象，例如处理文件和导入数据。

前置条件¶

在目标 Google Cloud 项目中启用 Google Cloud Storage API。
IAM 权限：经过身份验证的主体（应用程序默认凭据、服务账号或用户）必须具有正确的权限，包括 roles/storage.objectAdmin 和 roles/storage.admin，才能执行 GCS 存储桶和对象操作。
已配置 Google Cloud 项目 ID。

身份验证¶

GCSToolset 和 GCSAdminToolset 通过 GCSCredentialsConfig 支持多种身份验证机制：

应用程序默认凭据¶

推荐用于本地开发和部署到 Google Cloud，包括 Agent Runtime、Cloud Run 和 GKE。

import google.auth
from google.adk.integrations.gcs import GCSToolset
from google.adk.integrations.gcs.gcs_credentials import GCSCredentialsConfig

    # 加载应用程序默认凭据
credentials, _ = google.auth.default()

# Configure the toolset
credentials_config = GCSCredentialsConfig(credentials=credentials)
gcs_toolset = GCSToolset(credentials_config=credentials_config)

服务账号¶

允许从服务账号文件提供凭据。

import google.auth
from google.adk.integrations.gcs import GCSToolset
from google.adk.integrations.gcs.gcs_credentials import GCSCredentialsConfig

    # 加载服务账号凭据
credentials, _ = google.auth.load_credentials_from_file('path/to/key.json')

# Configure the toolset
credentials_config = GCSCredentialsConfig(credentials=credentials)
gcs_toolset = GCSToolset(credentials_config=credentials_config)

外部访问令牌¶

用于代表最终用户操作，例如通过 OAuth2 流程或外部身份提供者。

from google.oauth2.credentials import Credentials
from google.adk.integrations.gcs import GCSToolset
from google.adk.integrations.gcs.gcs_credentials import GCSCredentialsConfig

    # 假设 'user_token' 是通过外部 OAuth 流程获取的
credentials = Credentials(token=user_token)

# Configure the toolset
credentials_config = GCSCredentialsConfig(credentials=credentials)
gcs_toolset = GCSToolset(credentials_config=credentials_config)

外部身份验证提供者¶

适用于 Gemini Enterprise 等平台，其中令牌由环境或平台外部管理。

from google.adk.integrations.gcs import GCSToolset
from google.adk.integrations.gcs.gcs_credentials import GCSCredentialsConfig

    # 用于在会话状态中查找访问令牌的键
credentials_config = GCSCredentialsConfig(
    external_access_token_key="YOUR_AUTH_ID"
)
gcs_toolset = GCSToolset(credentials_config=credentials_config)

交互式身份验证 (ADK Web)¶

用于使用 adk web 界面触发 OAuth 2.0 登录流程的交互式会话。

from google.adk.integrations.gcs import GCSToolset
from google.adk.integrations.gcs.gcs_credentials import GCSCredentialsConfig

    # 提供 OAuth 2.0 客户端 ID 和密钥
credentials_config = GCSCredentialsConfig(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET"
)
gcs_toolset = GCSToolset(credentials_config=credentials_config)

与智能体配合使用¶

以下示例展示了如何配置凭据并实例化支持写入权限的存储工具集。

import google.auth
from google.adk.agents.llm_agent import LlmAgent
from google.adk.integrations.gcs import GCSToolset
from google.adk.integrations.gcs.settings import GCSToolSettings, Capabilities
from google.adk.integrations.gcs.gcs_credentials import GCSCredentialsConfig

# 1. Load Application Default Credentials (ADC)
application_default_credentials, _ = google.auth.default()

# 2. Configure credentials config
credentials_config = GCSCredentialsConfig(
    credentials=application_default_credentials
)

# 3. Configure settings (allow read and write operations)
tool_settings = GCSToolSettings(capabilities=[Capabilities.READ_WRITE])

# 4. Instantiate the GCS Toolset
gcs_toolset = GCSToolset(
    credentials_config=credentials_config, 
    gcs_tool_settings=tool_settings
)

# 5. Define an LLM Agent with the toolset
agent = LlmAgent(
    model="gemini-2.5-flash",
    name="gcs_agent",
    description="Agent for interacting with GCS buckets and objects.",
    instruction="""
        You are a storage assistant agent. Use the GCS tools to answer questions, 
        list objects, upload files, or perform admin tasks as requested.
    """,
    tools=[gcs_toolset]
)

可用工具¶

GCS 集成的功能分为两个主要工具集：

GCS 存储工具 (`GCSToolset`)¶

工具	描述
`gcs_get_bucket`	获取 GCS 存储桶的元数据信息。
`gcs_list_objects`	列出 GCS 存储桶中的对象名称。支持可选前缀筛选和分页。
`gcs_get_object_metadata`	获取指定 GCS 对象（blob）的元数据属性。
`gcs_create_object`	从内存字符串数据或本地文件上传在存储桶中创建新对象（blob）。
`gcs_get_object_data`	以字符串形式获取 GCS 对象的内容，或直接下载到本地文件。
`gcs_delete_objects`	从存储桶中删除多个 GCS 对象（blob）。

GCS 管理工具 (`GCSAdminToolset`)¶

工具	描述
`gcs_list_buckets`	列出 Google Cloud 项目中的 GCS 存储桶名称。
`gcs_create_bucket`	在指定位置创建新的 GCS 存储桶。
`gcs_update_bucket`	更新 GCS 存储桶的属性（例如版本控制或统一存储桶级访问）。
`gcs_delete_bucket`	删除 GCS 存储桶（存储桶必须为空）。

示例智能体¶

关于 GCS 智能体的完整、可直接运行的示例，包含详细的身份验证配置，请参见：