Manage agents

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Effective management of your fleet of agents requires keeping the registry accurate by viewing and updating service details as your workloads evolve, overriding metadata or removing agents that are no longer in use.

This document details how to view and modify your registered agent's details and configuration.

Before you begin

Before you manage agents, make sure your agents are registered 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 manage registered agents in Agent Registry, ask your administrator to grant you the Agent Registry API Editor (roles/agentregistry.editor) 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.

Discover available agents

After registering agents, you can discover them in your environment and view their detailed configurations, such as their endpoints, skills, and associated metadata.

List and view agents

You can list all agents registered in your environment and view their detailed configurations, such as their endpoints, skills, and associated 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. The list includes the agent's name, identifier, type, description, version, 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.

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. The list includes the agent's name, identifier, type, description, version, 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 metadata, using the --filter flag:

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

Replace FILTER_EXPRESSION with the filter expression for the agents that you want to filter. For example, you can use the following filters:

• To filter by display name, use displayName='DISPLAY_NAME'.
• To search by the globally unique identifier (URN), use agentId='urn:agent:AGENT_URN'.

View details from an agent

View details from a specific agent, including its protocols, skills, and identity:

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. The list includes the agent's name, identifier, type, description, version, 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 AGENT_NAME with the name of your agent, for example, my-custom-agent.

Update agent metadata and endpoints

If your agent's runtime URL changes, or you want to override its display name, description, or specification, you can update the agent metadata.

For the Agent Registry API, Agent resources are used for discovery. Therefore, you must update the registered Service resource directly.

Use the Google Cloud CLI with specific flags to modify the agent's parameters:

• Update the display name and description: Use the --display-name and --description flags, for example:

  gcloud alpha agent-registry services update AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --display-name="New display name" \
    --description="Updated description of the agent's purpose."
  

  Replace the following:

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

• Update the endpoint URL: Use the --interfaces flag to specify the new endpoint, for example:

  gcloud alpha agent-registry services update AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL
  

  Replace the following:

  • ENDPOINT_URL: The new agent service endpoint URL, for example, https://new-api.example.com/agent.
  • PROTOCOL: The protocol binding for the endpoint. Valid values are HTTP_JSON, GRPC, or JSONRPC.

• Update the agent's specification: Use the --agent-spec-content flag, for example, if you have a new Agent Card:

  gcloud alpha agent-registry services update AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --agent-spec-content=@AGENT_SPEC
  

  Note: The agent specification file you upload must not exceed 10 KB in size.

  Replace AGENT_SPEC with the name of the new agent specification, for example, new-agent-card.json.

Remove an agent

To delete agents that were automatically registered to Agent Registry, you must delete the underlying agent in its specific Google Cloud runtime. The agent is then automatically removed from the registry.

To remove a manually registered agent from the registry, you must delete the underlying Service resource. This action removes the agent from search results and makes it undiscoverable to other tools:

gcloud alpha agent-registry services delete AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION

Replace the following:

• AGENT_NAME: The name of the agent you want to remove, for example, my-support-agent.
• PROJECT_ID: The project ID.
• REGION: The registry region.

What's next

• Learn how to view agent relationships using a topology graph.
• Learn how to search for agents and tools using natural language queries.