Google Cloud Skill Registry¶

Supported in ADKPython v1.27.0Preview

Agent Development Kit (ADK) 中的 Google Cloud Skill Registry 集成允许开发者动态搜索、发现和获取在中央仓库中注册的远程 Skill。

与在初始化时静态地将所有可用技能注入智能体的上下文窗口不同，Skill Registry 实现了按需定向检索。随着你的专业能力目录扩展到数百甚至数千个技能，智能体可以根据用户意图动态发现、下载和激活所需的精确指令和工具。有关 Skill Registry 服务的更多信息，请参阅 Google Cloud Skills Registry 文档。

预览版

Google Cloud Skills Registry 功能为预览版。如需了解更多信息，请参阅发布阶段说明。

使用场景¶

上下文窗口优化：仅在用户提示确实需要时加载技能的系统指令和工具，从而节省宝贵的令牌。
企业复用：构建一个集中式、可管理的共享和私有技能仓库，供不同应用程序的多个智能体使用。
安全隔离：在智能体的特定会话状态或隔离的沙箱环境中自动缓存动态加载的技能。

前提条件¶

一个 Google Cloud 项目。
在 Google Cloud 项目中启用 Skill Registry API。
为你的环境配置身份验证。我们建议使用 Application Default Credentials 登录（gcloud auth application-default login）。
环境变量 GOOGLE_CLOUD_PROJECT 设置为你的项目 ID，GOOGLE_CLOUD_LOCATION 设置为你的部署区域（例如 us-central1）。

网络访问要求

由于 GCP Skill Registry 使用 Vertex AI Client SDK 与 Vertex AI 服务交互，在沙箱环境中运行且没有出站网络访问 Vertex AI 端点的智能体将无法访问该注册表。请确保配置了正确的网络访问，否则系统将回退到本地文件系统加载的技能。

安装¶

Skill Registry 客户端已包含在核心 ADK 库中。通过 pip 安装：

pip install google-adk

与智能体一起使用¶

要配置智能体按需动态发现和加载技能，请实例化一个 GCPSkillRegistry，并将其作为 registry 参数传递给 SkillToolset。

import os
from google.adk import Agent
from google.adk.integrations.gcp_skill_registry import GCPSkillRegistry
from google.adk.tools.skill_toolset import SkillToolset

# 1. 初始化 GCP Skill Registry
# 项目 ID 和区域也可以通过 GOOGLE_CLOUD_PROJECT
# 和 GOOGLE_CLOUD_LOCATION 环境变量设置。
registry = GCPSkillRegistry(
    project_id=os.environ.get("GOOGLE_CLOUD_PROJECT"),
    location=os.environ.get("GOOGLE_CLOUD_LOCATION", "us-central1"),
)

# 2. 使用注册表创建 SkillToolset
# 你也可以选择预加载一些本地技能。
skill_toolset = SkillToolset(
    skills=[], 
    registry=registry
)

# 3. 使用 SkillToolset 定义智能体
agent = Agent(
    model="gemini-flash-latest",
    name="registry_agent",
    description="一个可以动态发现和执行技能的智能体。",
    instruction="你是一个得力的助手。使用 search_skills 和 load_skill 来利用远程能力。",
    tools=[skill_toolset],
)

工作原理¶

当你使用远程注册表配置 SkillToolset 时，ADK 会自动为你的智能体配备两个内置工具来管理技能生命周期：

sequenceDiagram
    autonumber
    actor User
    participant Agent as ADK Agent (LLM)
    participant Toolset as SkillToolset
    participant Registry as Vertex AI SDK

    User->>Agent: "如何优化 BigQuery 查询？"
    Note over Agent: LLM 意识到本地没有<br/>BigQuery 的指令。

    Agent->>Toolset: search_skills(query="BigQuery 优化")
    Toolset->>Registry: 搜索匹配的技能
    Registry-->>Toolset: 返回 frontmatter（例如 "bigquery"）
    Toolset-->>Agent: 返回匹配列表（已过滤）

    Note over Agent: LLM 确定 "bigquery" 为<br/>最佳候选。

    Agent->>Toolset: load_skill(skill_name="bigquery")
    Toolset->>Registry: 获取远程技能详情
    Registry-->>Toolset: 返回技能负载
    Note over Toolset: 解包负载并<br/>将会话状态中的技能缓存
    Toolset-->>Agent: 成功。技能已加载。

    Note over Agent: LLM 将技能指令附加到系统提示中，<br/>使工具可用。
    Agent-->>User: 利用 BigQuery 技能指令完成请求！

语义发现（`search_skills`）¶

如果智能体确定其当前的系统指令不足以回答用户查询，它会自动调用 search_skills 工具。

冲突预防：为防止命名空间冲突，ADK 会自动过滤出与任何本地加载的技能名称重复的注册表技能。

按需加载（`load_skill`）¶

一旦智能体识别到匹配的远程技能（例如 "bigquery"），它会调用 load_skill 工具。

SDK 获取：ADK 调用 Vertex AI Client SDK 来检索远程技能。
提取与解析：远程负载被解包并解析为可执行的 Skill 对象。
智能体会话缓存：技能指令和资源缓存在当前智能体会话状态中，因此后续轮次无需额外的远程 API 调用。
提示增强：技能的指令被附加到系统提示中，并且技能提供的任何脚本或工具立即可执行。

配置和 API 参考¶

`GCPSkillRegistry` 配置¶

GCPSkillRegistry 客户端构造函数接受以下选项：

参数	类型	默认值	说明
`project_id`	`str`	`None`	Google Cloud 项目 ID。如果省略，回退到 `GOOGLE_CLOUD_PROJECT` 环境变量。
`location`	`str`	`None`	Google Cloud 区域/位置。如果省略，回退到 `GOOGLE_CLOUD_LOCATION` 环境变量。

方法¶

search_skills(query: str) -> List[Frontmatter]：对注册表目录执行语义或关键词查询，返回技能 frontmatter 元数据列表（名称和说明）。
get_skill(name: str, version: Optional[str] = None) -> Skill：使用 Vertex AI Client SDK 为指定技能名称（和可选的修订版本）获取远程技能负载，解包并返回加载的 Skill 对象。