Search for agents, tools, and skills

As your agentic ecosystem grows, finding the right agent or tool becomes critical. Agent Registry provides search capabilities that let you perform advanced keyword, prefix, and semantic searches across your agents, their skills, and your Model Context Protocol (MCP) servers.

This document explains how to construct search queries to discover capabilities within your environment.

Before you begin

Before you search for agents, tools, or skills in Agent Registry, register an agent or an MCP server. You also need your project ID to perform these tasks.

To use the gcloud CLI commands in this document, make sure you have set up your Google Cloud CLI environment.

Required roles

To get the permissions that you need to search for agents, tools, and skills in Agent Registry, ask your administrator to grant you the Agent Registry API Viewer (roles/agentregistry.viewer) IAM role on the project. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Search for agents and tools

To discover capabilities within your registry, you can search for registered agents and MCP servers.

Searching for agents matches their basic metadata, description, and descriptive A2A skills declared inline in their Agent Card. Searching for MCP servers matches their description and their deterministic tools.

You can perform a keyword search to find resources that match specific terms across their capabilities, such as an agent's A2A skill or an MCP server's tool. To understand how these capabilities are structured in the registry, see JSON schemas. For a complete list of searchable fields, see the API reference.

To search by keywords provide the --search-string flag. This parameter accepts free-text queries and supports logical operators: AND, OR, and NOT.

For example, search for an agent that can handle flight bookings:

gcloud agent-registry agents search \
  --project=PROJECT_ID \
  --location=REGION \
  --search-string="flight OR booking"

You can also search for an MCP server based on the specific tools it offers or its description. For example, search for an MCP server that provides database tools:

gcloud agent-registry mcp-servers search \
  --project=PROJECT_ID \
  --location=REGION \
  --search-string="database"

Replace the following:

  • PROJECT_ID: The project ID.
  • REGION: The registry region.

Prefix searches are highly optimized for latency, letting your applications retrieve relevant agents and tools dynamically as a user types.

If you are building an orchestrator interface or an autocomplete feature, you can perform prefix searches in Agent Registry to get results matching the beginning of a query string. Prefix searches use the suffix wildcard symbol (*) to match the beginning of a word.

For example, search for agents whose display name begins with a specific prefix, such as Best_A2A_*:

gcloud agent-registry agents search \
  --project=PROJECT_ID \
  --location=REGION \
  --search-string="displayName:Best_A2A_*"

Similarly, you can search for MCP servers whose display name begins with a specific prefix, such as Prod_Server_*:

gcloud agent-registry mcp-servers search \
  --project=PROJECT_ID \
  --location=REGION \
  --search-string="displayName:Prod_Server_*"

Replace the following:

  • PROJECT_ID: The project ID.
  • REGION: The registry region.

Search for standalone skills

You can search for standalone skills registered in Agent Registry. This feature lets you discover reusable capabilities to attach to your agents.

When you search for skills, you search for the default skill revision. To update the default revision of a skill, see Update skill metadata or default revision.

Search modes

You can use two search modes for skills based on your requirements:

  • Keyword search: Scans only basic metadata attributes such as the display name, description, name (URN), and skill ID. This mode is optimized for low-latency searches, matching, and name autocomplete. For an example, see Search for skills by keyword or expression.
  • Semantic search: Automatically indexes the complete contents of the SKILL.md payload, including natural language instructions, code structure, and assets. This mode matches conceptual themes and is optimized for orchestrator agents discovering relevant capability bundles dynamically, based on your intent. For an example, see Search for skills by semantic meaning.

Search fields and syntax

When searching by metadata or keyword strings, the following fields are indexed:

Field name Case behavior Prefix search All-fields search Description
displayName Case insensitive Yes Yes The user-facing name of the skill. Use this field to search for common names.
description Case insensitive No Yes The detailed description of the skill's purpose and functionality. Use this field to match keywords.
name Case insensitive Yes Yes The programmatic identifier of the skill. Use this field for matches on identifier strings.
skillId Case insensitive Yes Yes The logical Uniform Resource Name (URN) of the skill. Use this field to find a specific publisher's assets. For example, the format for Google-created skills is urn:skill:PUBLISHER_ID:NAMESPACE:SKILL_ID.
publisher Case insensitive Yes No The publisher associated with the skill. Use this field to filter by the publishing organization.
frontmatter.name Case insensitive No No The name of the skill defined in the frontmatter of the SKILL.md file.
frontmatter.description Case insensitive No No The description of the skill defined in the frontmatter of the SKILL.md file.
frontmatter.compatibility Case insensitive No No The compatibility of the skill defined in the frontmatter of the SKILL.md file.
frontmatter.license Case insensitive No No The license of the skill defined in the frontmatter of the SKILL.md file.
createTime Not applicable No No The timestamp when the skill was created. This field is only available in filters. Supports range operators, such as <, >, and exact matches.
updateTime Not applicable No No The timestamp when the skill was last updated. This field is only available in filters. Supports range operators, such as <, >, and exact matches.

The query string is attached to commands through the --query flag or query parameter, and it accepts logical arguments. You can use the following elements in your search requests:

  • Boolean operators: Include AND, OR, or NOT operators to chain requirements.
  • Field-specific filters: Target a field using the : operator, for example, displayName:database.
  • Prefix matching: Use the wildcard suffix :* to find matches starting with a specific prefix, for example, skillId:db-*.

Search for skills by keyword or expression

The following example searches for skills matching a specific display name prefix and description keyword:

gcloud alpha agent-registry skills search \
  --project=PROJECT_ID \
  --location=REGION \
  --query="displayName:db-* AND description:sql"

Replace the following:

  • PROJECT_ID: The project ID.
  • REGION: The registry region.

Search for skills by semantic meaning

The following example performs a semantic search to find skills related to database query handling, matching conceptual themes in the natural language query:

gcloud alpha agent-registry skills search \
  --project=PROJECT_ID \
  --location=REGION \
  --query="find skills to handle database queries" \
  --search-type=semantic

Replace the following:

  • PROJECT_ID: The project ID.
  • REGION: The registry region.

Public skills

Google's public skills are globally discoverable from all projects. For a list of available public skills, see the google/skills repository on GitHub.

When you perform a search, Agent Registry dynamically rewrites the logical resource names of public skills in the output to appear as if they are hosted in your local project to simplify integration.