Quickstart: Discover an agent

Discovery is the core mechanism for accelerating development with agentic workloads. By searching within Agent Registry, you can find existing agents with the skills you need, such as an existing "Corporate Policy Agent" or a "Flight Booking Agent", instead of building duplicate integrations from scratch.

This quickstart shows you how to discover agents registered in Agent Registry.

Before you begin

Before you start this quickstart, register an agent in Agent Registry. 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 discover agents 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.

List available agents

View a complete list of all agents registered and indexed within the registry:

Console

  1. In the Google Cloud console, go to Agent Registry:

    Go to Agent Registry

  2. From the project picker, select the Google Cloud project where you set up Agent Registry.

  3. Select the Agents tab.

    The page displays a list of all registered agents and their details, such as name, identifier, description, runtime, and location.

  4. To view the full details of an agent, click the agent's name.

gcloud

To list all agents in a specific location, use the agents list command:

gcloud alpha agent-registry agents list \
  --project=PROJECT_ID \
  --location=REGION

Replace the following:

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

The output looks like the following example:

- name: projects/1234567890/locations/us-central1/agents/my-travel-agent
  displayName: Travel Orchestrator Agent
  description: 'Decomposes natural language travel requests into sub-tasks.'
  version: 1.0.0
  protocols:
    - type: A2A_AGENT
      protocolVersion: "0.3"
      interfaces:
        - url: https://api.example.com/.well-known/agent-card.json
          protocolBinding: HTTP_JSON
  attributes:
    agentregistry.googleapis.com/system/Framework:
      framework: "google-adk"
    agentregistry.googleapis.com/system/RuntimeIdentity:
      identity: "principal://..."
  card:
    type: A2A_AGENT_CARD
    content: {...}

The card field contains the full A2A Agent Card content when available.

Filter registered agents

If you have multiple agents, or if you want to confirm the registration of a specific agent, you can filter the list by the agent's metadata:

Console

  1. In the Google Cloud console, go to Agent Registry:

    Go to Agent Registry

  2. From the project picker, select the Google Cloud project where you set up Agent Registry.

  3. Select the Agents tab.

    The page displays a list of all registered agents and their details, such as name, identifier, description, runtime, and location.

  4. Filter the list by the agent's location or their runtime resource:

    • To filter by location, click the Location menu, select the locations you want to filter, and click Apply.
    • To filter by runtime, click the Runtime menu, select the runtimes you want to filter, and click Apply.

    The page displays a filtered list of the registered agents for your selected conditions.

gcloud

Filter your agent list to only return resources matching specific key-value pairs, using the --filter flag:

gcloud alpha agent-registry agents list \
  --project=PROJECT_ID \
  --location=REGION \
  --filter="FILTER_EXPRESSION"

Replace the following:

  • PROJECT_ID: The project ID.
  • REGION: The registry region.
  • FILTER_EXPRESSION: The filter expression for the agents that you want to filter. For example, to filter by display name, you can use displayName='DISPLAY_NAME'. To filter by the globally unique identifier (URN), you can use agentId='urn:agent:AGENT_URN'.

View agent details

If you have identified an agent you want to use, you can retrieve its full metadata, including its runtime endpoint and complete list of skills:

Console

  1. In the Google Cloud console, go to Agent Registry:

    Go to Agent Registry

  2. From the project picker, select the Google Cloud project where you set up Agent Registry.

  3. Select the Agents tab.

    The page displays a list of all registered agents and their details, such as name, identifier, description, runtime, and location.

  4. Click the name of the agent that you want to view.

    The details page includes tabs for the agent details.

  5. Click the corresponding tab to view specific agent details.

    Feature availability depends on your runtime. Tabs like Sessions, Playground, Memories, and Evaluation are specific capabilities that display for agents built on managed runtimes, such as Vertex AI Agent Engine:

    • Overview: Core details from the agent, including the agent's name, identifier, location, description, and runtime. The overview also displays skills and the resource URI, which you require for building queries in the topology graph.
    • Observability: Application-centric insights such as latency, traffic, errors, and token spend. This tab integrates with Google Cloud Observability tools to display real-time performance metrics and system-level utilization to help you manage costs and user experience. For more information, see the Observability overview.
    • Traces: The exact path of a conversation step-by-step, including detailed formatting of input and assistant messages to debug complex multi-agent reasoning loops or tool invocation errors in real time. For more information, see View agent traces.
    • Security: Findings from Model Armor and Security Command Center, including content policy violations, data leakage risks, and compliance assessments. For more information on security, see View security findings.
    • Topology: A visual map of the relationships and traffic flows between an agent, its assigned Agent Gateway, and the MCP servers it interacts with. For more information on Agent Gateway, see the Agent Gateway overview. For more information on topology, see View graphs for a registered agent.
    • Identity: The agent principal used for policy enforcement. You use this identity, for example, to configure auth provider bindings for authentication to tools and resources.
    • Sessions: Persistent conversation history and tracking of active interactions with the agent.
    • Playground: A direct chat interface to test the agent's behavior.
    • Memories: Long-term personalization features that generate or recall details from past conversations with the agent to preserve context across interactions.
    • Evaluation: Details of all agent evaluation tasks. This tab lets you create new evaluation tasks, upload metrics, and evaluate the agent's cognitive performance and model reliability against live traffic or synthetic simulations.

gcloud

To view the detailed metadata of a specific agent, use the agents describe command:

gcloud alpha agent-registry agents describe AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION

Replace the following:

  • AGENT_NAME: The name of your agent, for example, my-travel-agent.
  • PROJECT_ID: The project ID.
  • REGION: The registry region.

With the agent's endpoint, skill definitions, and output-only metadata, such as the underlying framework, runtime identity, and the full A2A Agent Card payload, you can securely bind your agent to your orchestrator workflows using the Agent Development Kit (ADK) or standard API requests.

What's next