Search for agents and tools

As your agentic ecosystem grows, finding the right agent or tool becomes critical. Agent Registry provides search capabilities to let you perform advanced keyword and prefix searches across your agents and 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 or tools 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 and tools 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 by keywords

You can perform a keyword search to find resources that match specific terms across their capabilities, such as an agent's skills or an MCP server's tools. 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 alpha 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 alpha 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.

Search by prefix

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 alpha 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 alpha agent-registry mcp-servers search \
  --project=PROJECT_ID \
  --location=REGION \
  --search-string="displayName:Prod_Server_*"