使用 ADK 构建 Secret Manager 智能体:python-docs-samples 全局与区域密钥访问实战

原创2026-10-05 21:41:582,271 阅读
文章标签:示例工程

使用 ADK 构建 Secret Manager 智能体:python-docs-samples 全局与区域密钥访问实战

本指南以 python-docs-samples 仓库中的 secretmanager/snippets-adk/README.md 为核心,讲解如何用 Google Agent Development Kit(ADK)编写能够读取 Secret Manager 密钥的智能体(Agent),覆盖**全局(global)与区域(regional)**两种 Secret Manager 实例的接入方式。读完本文,你将掌握 ADK 智能体的环境配置、adk run 运行流程、测试验证方法,并能对照仓库源码理解 SecretManagerClient 的底层调用链。

一、示例概览:两种密钥访问场景

该目录下的示例全部位于 secretmanager/snippets-adk,按目标 Secret Manager 实例类型划分为两个文件夹:

目录 用途 核心差异
agent_global 从全局(global)Secret Manager 实例读取密钥 资源名不含 locations/...,客户端无需传区域参数
agent_regional 从区域(regional)Secret Manager 端点读取密钥 资源名包含 locations/{location},客户端需指定 location

两个文件夹内部结构完全一致,均由四个文件组成:智能体源码 agent.py、依赖声明 requirements.txt、测试依赖 requirements-test.txt、端到端测试 snippets_adk_test.py,另外还各有一个供仓库 CI 使用的 noxfile_config.py。

二、前置条件与环境准备

1. 创建并激活虚拟环境

文档建议使用 Python 虚拟环境隔离依赖,避免污染系统 Python:

python3 -m venv .venv
source .venv/bin/activate

2. 配置 Application Default Credentials

示例通过 Google Cloud 客户端库访问 Secret Manager,需要先建立本地身份凭据:

gcloud auth application-default login

3. 安装依赖

依赖按示例单独声明,需要为要运行的目标安装对应依赖。全局与区域示例的运行依赖都是 google-adk>=1.29(见 agent_global/requirements.txt 与 agent_regional/requirements.txt):

# 全局示例与测试
pip install -r agent_global/requirements.txt

# 区域示例与测试
pip install -r agent_regional/requirements.txt

运行测试还需额外安装 pytest(requirements-test.txt 中锁定版本为 pytest==9.0.3; python_version >= "3.10",即要求 Python 3.10 及以上):

pip install -r agent_global/requirements-test.txt

4. 设置环境变量

两个示例(及测试)必需的环境变量是:

  • GOOGLE_CLOUD_PROJECT:你的 Google Cloud 项目 ID。

以下变量仅在手动运行示例时必需,测试会自行创建临时密钥并注入环境,无需手动设置:

  • ADK_TEST_SECRET_ID:要访问的密钥 ID;
  • ADK_TEST_SECRET_VERSION(可选):密钥版本,默认值为 latest;
  • GOOGLE_CLOUD_PROJECT_LOCATION(区域示例必需):密钥所在的区域,例如 us-central1。

三、源码剖析:全局密钥访问 Agent

全局示例的核心逻辑集中在 agent_global/agent.py。它通过三个关键步骤完成"读取密钥 + 初始化智能体"。

1. 读取环境变量并组装资源名

project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
secret_id = os.environ.get("ADK_TEST_SECRET_ID")
secret_version = os.environ.get("ADK_TEST_SECRET_VERSION", "latest")

if not project_id or not secret_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT and ADK_TEST_SECRET_ID environment variables must be set.")

resource_name = f"projects/{project_id}/secrets/{secret_id}/versions/{secret_version}"

可见该示例会在缺失必需变量时立即抛出 ValueError,避免带着无效配置继续运行。注意全局密钥的完整资源名(Secret Version 格式)为:

projects/{project_id}/secrets/{secret_id}/versions/{secret_version}

其中 {project_id}、{secret_id}、{secret_version} 分别由上文三个环境变量填充,secret_version 缺省时取 latest。

2. 初始化 SecretManagerClient 并拉取密钥

client = SecretManagerClient()
secret_payload = client.get_secret(resource_name)

这里的 SecretManagerClient 来自 ADK 官方集成模块 google.adk.integrations.secret_manager.secret_client(见 agent.py 第 22 行)。全局调用时构造函数不传任何参数,客户端会使用 Application Default Credentials 自动完成认证,然后通过 get_secret(resource_name) 拉取指定版本的密钥内容,存入 secret_payload,供后续智能体或工具使用。

3. 初始化 ADK Agent

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

Agent 来自 google.adk(第 21 行),此处指定了 Gemini 2.5 Flash 作为底层模型,并配置了智能体的名称、描述与系统指令。密钥拉取成功后,智能体初始化即告完成,程序打印 "Agent initialized successfully."。

四、源码剖析:区域密钥访问 Agent

区域示例 agent_regional/agent.py 与全局版本结构相同,差异集中在两点:

1. 资源名多出 location 段

project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_PROJECT_LOCATION")
secret_id = os.environ.get("ADK_TEST_SECRET_ID")
secret_version = os.environ.get("ADK_TEST_SECRET_VERSION", "latest")

if not project_id or not location or not secret_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_PROJECT_LOCATION, and ADK_TEST_SECRET_ID environment variables must be set.")

resource_name = f"projects/{project_id}/locations/{location}/secrets/{secret_id}/versions/{secret_version}"

区域密钥的资源名遵循区域版 Secret Version 格式:

projects/{project_id}/locations/{location}/secrets/{secret_id}/versions/{secret_version}

校验逻辑也相应增加:三个变量(项目 ID、区域、密钥 ID)全部必需,否则抛出 ValueError。

2. 客户端传入区域参数

client = SecretManagerClient(location=location)

与全局版本的关键区别在于,SecretManagerClient 构造时必须传入 location 参数。可以推断,ADK 的集成客户端会依据该参数解析出对应区域的 Secret Manager 端点(测试中对端点的拼装方式可见下文第六节),从而保证请求只路由到该区域实例。

五、运行示例:手动启动智能体

运行全局 Agent

  1. 在 agent_global 目录中、与 agent_global.py 同目录位置创建 .env 文件(注意:实际源码文件名为 agent.py,README 中表述为 agent_global.py,按 adk run 的目录约定运行):

    GOOGLE_GENAI_USE_VERTEXAI=1
    GOOGLE_CLOUD_PROJECT=your-project-id
    GOOGLE_CLOUD_LOCATION=your-region
    

    其中 GOOGLE_GENAI_USE_VERTEXAI=1 表示让 ADK 走 Vertex AI 的 Gemini 通道,GOOGLE_CLOUD_LOCATION 为模型调用所在的区域,需将 your-project-id、your-region 替换为实际值。

  2. 导出运行时变量并启动智能体:

    export GOOGLE_CLOUD_PROJECT="your-project-id"
    export ADK_TEST_SECRET_ID="your-secret-id"
    adk run agent_global
    

    adk run 需要在 snippets-adk 目录下执行,并直接以文件夹名 agent_global 作为参数(测试代码中 subprocess.run(<a href="https://link.gitcode.com/i/f27e7a8f9928bb5af7bbefc98c157617" target="_blank">"adk", "run", "agent_global"], cwd=PARENT_DIR) 也印证了这一点,见 [测试文件)。

运行区域 Agent

  1. 在 agent_regional 目录中创建 .env 文件:

    GOOGLE_GENAI_USE_VERTEXAI=1
    GOOGLE_CLOUD_PROJECT=your-project-id
    GOOGLE_CLOUD_LOCATION=your-region
    
  2. 导出变量并启动:

    export GOOGLE_CLOUD_PROJECT="your-project-id"
    export GOOGLE_CLOUD_PROJECT_LOCATION="your-region"
    export ADK_TEST_SECRET_ID="your-secret-id"
    adk run agent_regional
    

    相比全局示例,区域示例额外要求导出 GOOGLE_CLOUD_PROJECT_LOCATION——它同时决定资源名中的区域段与 SecretManagerClient 的访问端点,因此必须与实际密钥所在区域保持一致。

六、测试验证:端到端自动化用例

测试文件与示例同目录存放,使用 adk run 真实拉起智能体进程并断言其输出,属于端到端集成测试。

全局测试

agent_global/snippets_adk_test.py 的测试流程为:

  1. 自动创建临时密钥:使用 secretmanager.SecretManagerServiceClient 创建名为 python-adk-test-{uuid4} 的密钥(复制策略为 automatic),并添加版本,负载数据为 b"test-payload";
  2. 注入环境变量:测试将 ADK_TEST_SECRET_ID 设为临时密钥 ID、ADK_TEST_SECRET_VERSION 设为 latest(GOOGLE_CLOUD_PROJECT 由运行测试的环境提供);
  3. 以子进程方式运行 adk run agent_global(工作目录为 snippets-adk,并向 stdin 输入 exit\n 以便正常退出);
  4. 断言结果:进程返回码为 0,且标准输出同时包含 "Successfully fetched secret" 与 "Agent initialized successfully";
  5. 清理:teardown 中休眠 2 秒后删除临时密钥,若密钥已不存在则静默忽略(NotFound)。

区域测试

agent_regional/snippets_adk_test.py 与全局测试结构一致,但有三处区域化差异:

  • location fixture 固定为 us-east5;
  • 客户端通过 client_options={"api_endpoint": f"secretmanager.{location}.rep.googleapis.com"} 指定区域专用端点——这是区域 Secret Manager 与全局实例在 API 层面的核心区别;
  • 创建区域密钥时父路径为 projects/{project_id}/locations/{location},密钥资源路径同样带 locations/{location} 段,且未显式指定复制策略(区域密钥天然绑定所在区域)。

运行测试的命令(按 README 原文):

# 全局
pip install -r agent_global/requirements.txt
pip install -r agent_global/requirements-test.txt
pytest agent_global/snippets_adk_test.py

# 区域
pip install -r agent_regional/requirements.txt
pip install -r agent_regional/requirements-test.txt
pytest agent_regional/snippets_adk_test.py

此外,两个目录下的 noxfile_config.py 还展示了仓库 CI 的运行约束:忽略 Python 3.8/3.9/3.11/3.12/3.13 版本(即当前主要针对 3.10 测试)、强制类型标注检查,并通过 GOOGLE_CLOUD_PROJECT 环境变量决定测试项目。

七、常见问题与注意事项

  • 环境变量缺失报错:源码会在启动阶段直接抛出 ValueError 并给出缺失变量名提示。手动运行时请先确认 GOOGLE_CLOUD_PROJECT、ADK_TEST_SECRET_ID(区域示例还包括 GOOGLE_CLOUD_PROJECT_LOCATION)均已导出。
  • adk run 的工作目录:示例设计为在 snippets-adk 根目录执行,参数是子目录名(agent_global / agent_regional),不要在子目录内部直接运行,否则无法定位 Agent 定义。
  • 密钥版本默认值:不设置 ADK_TEST_SECRET_VERSION 时统一读取 latest 版本;如需读取历史版本,请显式指定版本号。
  • 区域端点差异:区域 Secret Manager 使用 secretmanager.{location}.rep.googleapis.com 形式的端点(测试源码可见),因此区域示例必须传 location;若误用全局客户端访问区域密钥,资源名与端点都会不匹配。
  • 依赖与 Python 版本:运行依赖要求 google-adk>=1.29,测试依赖 pytest==9.0.3 要求 Python 3.10 及以上,请使用匹配的 Python 版本创建虚拟环境。
  • 认证与授权:SecretManagerClient 依赖 ADC 凭据访问密钥,运行前需完成 gcloud auth application-default login,且当前账号需具备读取对应密钥的 IAM 权限(如 roles/secretmanager.secretAccessor)。

八、小结

通过本示例可以清晰看到 ADK 智能体接入 Secret Manager 的标准模式:SecretManagerClient 负责按资源名拉取密钥、Agent 负责组装对话能力,二者解耦后由 adk run 一键启动,测试则用真实云资源做端到端验证。若你的业务同时存在全局密钥与区域合规密钥,只需按 agent_global / agent_regional 两套模板分别适配资源名与 location 参数即可。更多仓库相关实现可继续阅读 secretmanager/snippets-adk 目录下的源码与测试文件。

登录后查看全文
python-docs-samples