使用 ADK 构建 Secret Manager 智能体:python-docs-samples 全局与区域密钥访问实战
使用 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
-
在
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替换为实际值。 -
导出运行时变量并启动智能体:
export GOOGLE_CLOUD_PROJECT="your-project-id" export ADK_TEST_SECRET_ID="your-secret-id" adk run agent_globaladk 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
-
在
agent_regional目录中创建.env文件:GOOGLE_GENAI_USE_VERTEXAI=1 GOOGLE_CLOUD_PROJECT=your-project-id GOOGLE_CLOUD_LOCATION=your-region -
导出变量并启动:
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 的测试流程为:
- 自动创建临时密钥:使用
secretmanager.SecretManagerServiceClient创建名为python-adk-test-{uuid4}的密钥(复制策略为automatic),并添加版本,负载数据为b"test-payload"; - 注入环境变量:测试将
ADK_TEST_SECRET_ID设为临时密钥 ID、ADK_TEST_SECRET_VERSION设为latest(GOOGLE_CLOUD_PROJECT由运行测试的环境提供); - 以子进程方式运行
adk run agent_global(工作目录为snippets-adk,并向 stdin 输入exit\n以便正常退出); - 断言结果:进程返回码为 0,且标准输出同时包含
"Successfully fetched secret"与"Agent initialized successfully"; - 清理:teardown 中休眠 2 秒后删除临时密钥,若密钥已不存在则静默忽略(
NotFound)。
区域测试
agent_regional/snippets_adk_test.py 与全局测试结构一致,但有三处区域化差异:
locationfixture 固定为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 目录下的源码与测试文件。