From bb525781ccb0a5072c370923161694bfca1de0cc Mon Sep 17 00:00:00 2001 From: wukath Date: Thu, 14 May 2026 10:39:54 -0700 Subject: [PATCH 1/4] docs: add Google Cloud Skill Registry integration guide --- docs/skills/registry.md | 148 ++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 149 insertions(+) create mode 100644 docs/skills/registry.md diff --git a/docs/skills/registry.md b/docs/skills/registry.md new file mode 100644 index 0000000000..35003ad511 --- /dev/null +++ b/docs/skills/registry.md @@ -0,0 +1,148 @@ +--- +catalog_title: Google Cloud Skill Registry +catalog_description: Discover and fetch reusable Skills dynamically on-demand +catalog_icon: /integrations/assets/agent-platform.svg +catalog_tags: ["google", "skills"] +--- + +# Google Cloud Skill Registry + +
+ Supported in ADKPython v1.27.0Preview +
+ +The **Skill Registry** integration within the Agent Development Kit (ADK) allows developers to dynamically search, discover, and fetch remote Skills cataloged within a central repository. + +Rather than statically injecting every available skill into your agent's context window at initialization, the Skill Registry enables **on-demand targeted retrieval**. As your catalog of specialized capabilities scales to hundreds or thousands of skills, agents can dynamically discover, download, and activate the exact instructions and tools they need based on user intent. + +--- + +## Use Cases + +* **Context Window Optimization**: Save valuable tokens by only loading a skill's system instructions and tools when the user's prompt actually requires them. +* **Enterprise Reusability**: Build a central, managed repository of shared and private skills that multiple agents across different applications can consume. +* **Secure Isolation**: Automatically cache dynamically loaded skills within the agent's specific session state or isolated sandbox environments. + +--- + +## Prerequisites + +* A [Google Cloud project](https://docs.cloud.google.com/resource-manager/docs/creating-managing-projects). +* The **Skill Registry API** enabled in your Google Cloud project. +* Authentication configured for your environment. We recommend logging in using [Application Default Credentials](https://docs.cloud.google.com/docs/authentication/application-default-credentials) (`gcloud auth application-default login`). +* Environment variables `GOOGLE_CLOUD_PROJECT` set to your project ID and `GOOGLE_CLOUD_LOCATION` set to your deployment region (e.g., `us-central1`). + +--- + +## Installation + +The Skill Registry client is included in the core ADK library. Install it via pip: + +```bash +pip install google-adk +``` + +--- + +## Use with Agent + +To configure an agent to dynamically discover and load skills on demand, instantiate a `GCPSkillRegistry` and pass it as the `registry` parameter in your `SkillToolset`. + +```python +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. Initialize the GCP Skill Registry +# Project ID and location can also be set via GOOGLE_CLOUD_PROJECT +# and GOOGLE_CLOUD_LOCATION environment variables. +registry = GCPSkillRegistry( + project_id=os.environ.get("GOOGLE_CLOUD_PROJECT"), + location=os.environ.get("GOOGLE_CLOUD_LOCATION", "us-central1"), +) + +# 2. Create the SkillToolset with the Registry +# You can optionally pre-load some local skills as well. +skill_toolset = SkillToolset( + skills=[], + registry=registry +) + +# 3. Define your Agent with the SkillToolset +agent = Agent( + model="gemini-flash-latest", + name="registry_agent", + description="An agent that can dynamically discover and execute skills.", + instruction="You are a helpful assistant. Use search_skills and load_skill to leverage remote capabilities.", + tools=[skill_toolset], +) +``` + +--- + +## How it Works + +When you configure a `SkillToolset` with a remote registry, ADK automatically equips your agent with two built-in tools to manage the skill lifecycle: + +```mermaid +sequenceDiagram + autonumber + actor User + participant Agent as ADK Agent (LLM) + participant Toolset as SkillToolset + participant Registry as Vertex AI SDK + + User->>Agent: "How to optimize a BigQuery query?" + Note over Agent: LLM realizes it does not have
instructions for BigQuery locally. + + Agent->>Toolset: search_skills(query="BigQuery optimization") + Toolset->>Registry: Search matching skills + Registry-->>Toolset: Returns frontmatters (e.g., "bigquery") + Toolset-->>Agent: Returns list of matches (filtered) + + Note over Agent: LLM identifies "bigquery" as
the best candidate. + + Agent->>Toolset: load_skill(skill_name="bigquery") + Toolset->>Registry: Fetch remote skill details + Registry-->>Toolset: Returns skill payload + Note over Toolset: Unpacks payload &
caches skill in Session State + Toolset-->>Agent: Success. Skill loaded. + + Note over Agent: LLM appends skill instructions to system prompt,
making tools available. + Agent-->>User: Fulfills request utilizing BigQuery skill instructions! +``` + +### 1. Semantic Discovery (`search_skills`) +If the agent determines that its current system instructions are insufficient to answer a user query, it automatically invokes the `search_skills` tool. +* **Collision Prevention**: To prevent namespace conflicts, ADK automatically filters out registry skills that duplicate the name of any locally loaded skills. + +### 2. On-Demand Loading (`load_skill`) +Once the agent identifies a matching remote skill (e.g., `"bigquery"`), it invokes the `load_skill` tool. +* **SDK Fetch**: ADK calls the Vertex AI Client SDK to retrieve the remote skill. +* **Extraction & Parsing**: The remote payload is unpacked and parsed into an executable `Skill` object. +* **Agent Session Caching**: The skill instructions and resources are cached in the current agent session state so subsequent turns do not require additional remote API calls. +* **Prompt Enrichment**: The skill's instructions are appended to the system prompt, and any scripts or tools provided by the skill become instantly executable. + +--- + +## Configuration & API Reference + +### `GCPSkillRegistry` Configuration + +The `GCPSkillRegistry` client constructor accepts the following options: + +| Parameter | Type | Default | Description | +| :--- | :--- | :--- | :--- | +| `project_id` | `str` | `None` | The Google Cloud project ID. If omitted, falls back to `GOOGLE_CLOUD_PROJECT` env variable. | +| `location` | `str` | `None` | The Google Cloud region/location. If omitted, falls back to `GOOGLE_CLOUD_LOCATION` env variable. | + +### Methods + +* **`search_skills(query: str) -> List[Frontmatter]`**: + Performs a semantic or keyword query against the registry catalog, returning a list of skill frontmatter metadata (names and descriptions). +* **`get_skill(name: str, version: Optional[str] = None) -> Skill`**: + Fetches the remote skill payload using the Vertex AI Client SDK for a specific skill name (and optional revision/version), unpacks it, and returns a loaded `Skill` object. + +!!! warning "Internet Access Requirements" + Because the GCP Skill Registry interacts with Vertex AI services using the Vertex AI Client SDK, agents running in sandboxed environments without outbound network access to Vertex AI endpoints will fail to reach the registry. Ensure proper network access is configured or fall back to local, filesystem-loaded skills. diff --git a/mkdocs.yml b/mkdocs.yml index 97c116dda7..93a09757d2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -324,6 +324,7 @@ nav: - Tool limitations: tools/limitations.md - Skills for Agents: - skills/index.md + - Skill Registry: skills/registry.md - Run Agents: - Agent Runtime: - Agent Runtime: runtime/index.md From 411ea1ac497413803fc0663b925dbb469b046f02 Mon Sep 17 00:00:00 2001 From: Kathy Wu <108756731+wukath@users.noreply.github.com> Date: Thu, 14 May 2026 10:52:30 -0700 Subject: [PATCH 2/4] Remove catalog metadata from registry.md Removed catalog metadata from the Google Cloud Skill Registry documentation. --- docs/skills/registry.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/skills/registry.md b/docs/skills/registry.md index 35003ad511..644a1ab404 100644 --- a/docs/skills/registry.md +++ b/docs/skills/registry.md @@ -1,10 +1,3 @@ ---- -catalog_title: Google Cloud Skill Registry -catalog_description: Discover and fetch reusable Skills dynamically on-demand -catalog_icon: /integrations/assets/agent-platform.svg -catalog_tags: ["google", "skills"] ---- - # Google Cloud Skill Registry
From 34bff33bb1dc73674837de841cf35a4e29ee84c0 Mon Sep 17 00:00:00 2001 From: wukath Date: Thu, 14 May 2026 14:43:10 -0700 Subject: [PATCH 3/4] resolve comments --- .../skills-registry.md} | 19 ++++++++++++++----- mkdocs.yml | 2 +- 2 files changed, 15 insertions(+), 6 deletions(-) rename docs/{skills/registry.md => integrations/skills-registry.md} (90%) diff --git a/docs/skills/registry.md b/docs/integrations/skills-registry.md similarity index 90% rename from docs/skills/registry.md rename to docs/integrations/skills-registry.md index 644a1ab404..ba0a9ac818 100644 --- a/docs/skills/registry.md +++ b/docs/integrations/skills-registry.md @@ -1,3 +1,10 @@ +--- +catalog_title: Google Cloud Skill Registry +catalog_description: Dynamically search, discover, and fetch remote Skills +catalog_icon: /integrations/assets/agent-platform.svg +catalog_tags: ["google", "skills", "connectors"] +--- + # Google Cloud Skill Registry
@@ -25,6 +32,9 @@ Rather than statically injecting every available skill into your agent's context * Authentication configured for your environment. We recommend logging in using [Application Default Credentials](https://docs.cloud.google.com/docs/authentication/application-default-credentials) (`gcloud auth application-default login`). * Environment variables `GOOGLE_CLOUD_PROJECT` set to your project ID and `GOOGLE_CLOUD_LOCATION` set to your deployment region (e.g., `us-central1`). +!!! warning "Internet Access Requirements" + Since the GCP Skill Registry interacts with Vertex AI services using the Vertex AI Client SDK, agents running in sandboxed environments without outbound network access to Vertex AI endpoints will fail to reach the registry. Ensure proper network access is configured, or else the system falls back to local, filesystem-loaded skills. + --- ## Installation @@ -106,12 +116,14 @@ sequenceDiagram Agent-->>User: Fulfills request utilizing BigQuery skill instructions! ``` -### 1. Semantic Discovery (`search_skills`) +### Semantic Discovery (`search_skills`) If the agent determines that its current system instructions are insufficient to answer a user query, it automatically invokes the `search_skills` tool. + * **Collision Prevention**: To prevent namespace conflicts, ADK automatically filters out registry skills that duplicate the name of any locally loaded skills. -### 2. On-Demand Loading (`load_skill`) +### On-Demand Loading (`load_skill`) Once the agent identifies a matching remote skill (e.g., `"bigquery"`), it invokes the `load_skill` tool. + * **SDK Fetch**: ADK calls the Vertex AI Client SDK to retrieve the remote skill. * **Extraction & Parsing**: The remote payload is unpacked and parsed into an executable `Skill` object. * **Agent Session Caching**: The skill instructions and resources are cached in the current agent session state so subsequent turns do not require additional remote API calls. @@ -136,6 +148,3 @@ The `GCPSkillRegistry` client constructor accepts the following options: Performs a semantic or keyword query against the registry catalog, returning a list of skill frontmatter metadata (names and descriptions). * **`get_skill(name: str, version: Optional[str] = None) -> Skill`**: Fetches the remote skill payload using the Vertex AI Client SDK for a specific skill name (and optional revision/version), unpacks it, and returns a loaded `Skill` object. - -!!! warning "Internet Access Requirements" - Because the GCP Skill Registry interacts with Vertex AI services using the Vertex AI Client SDK, agents running in sandboxed environments without outbound network access to Vertex AI endpoints will fail to reach the registry. Ensure proper network access is configured or fall back to local, filesystem-loaded skills. diff --git a/mkdocs.yml b/mkdocs.yml index 93a09757d2..c9acb7541f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -324,7 +324,7 @@ nav: - Tool limitations: tools/limitations.md - Skills for Agents: - skills/index.md - - Skill Registry: skills/registry.md + - Skill Registry: integrations/skills-registry.md - Run Agents: - Agent Runtime: - Agent Runtime: runtime/index.md From 62d44115353340973fde09113c81d62cce1b376c Mon Sep 17 00:00:00 2001 From: Joe Fernandez Date: Tue, 19 May 2026 14:38:07 -0700 Subject: [PATCH 4/4] Update skills-registry.md --- docs/integrations/skills-registry.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/integrations/skills-registry.md b/docs/integrations/skills-registry.md index ba0a9ac818..020108ba06 100644 --- a/docs/integrations/skills-registry.md +++ b/docs/integrations/skills-registry.md @@ -11,9 +11,14 @@ catalog_tags: ["google", "skills", "connectors"] Supported in ADKPython v1.27.0Preview
-The **Skill Registry** integration within the Agent Development Kit (ADK) allows developers to dynamically search, discover, and fetch remote Skills cataloged within a central repository. +The **Google Cloud Skill Registry** integration within the Agent Development Kit (ADK) allows developers to dynamically search, discover, and fetch remote Skills cataloged within a central repository. -Rather than statically injecting every available skill into your agent's context window at initialization, the Skill Registry enables **on-demand targeted retrieval**. As your catalog of specialized capabilities scales to hundreds or thousands of skills, agents can dynamically discover, download, and activate the exact instructions and tools they need based on user intent. +Rather than statically injecting every available skill into your agent's context window at initialization, the Skill Registry enables **on-demand targeted retrieval**. As your catalog of specialized capabilities scales to hundreds or thousands of skills, agents can dynamically discover, download, and activate the exact instructions and tools they need based on user intent. For more information about the Skills Registry service, see the [Google Cloud Skills Registry](https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/skill-registry) documentation. + +!!! example "Preview release" + The Google Cloud Skills Registry feature is a Preview release. For + more information, see the + [launch stage descriptions](https://cloud.google.com/products#product-launch-stages). ---