Manage agents

Agent Registry lets you inspect, update, and remove registered agents so that your registry accurately reflects the active capabilities in your AI ecosystem. You can list and view all registered agents, update the metadata or endpoint of manually registered agents, and remove agents that are no longer in use.

Before you begin

Register your agents in Agent Registry.
Get the project ID for the governance project where Agent Registry is enabled.
To use the Google Cloud CLI commands in this document, set up your gcloud 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 governance project where Agent Registry is enabled. 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, A2A skills, and associated metadata.

List and view all agents

You can list all agents registered in your environment and view their detailed configurations, such as their endpoints, A2A skills, and associated metadata:

Console

In the Google Cloud console, go to Agent Registry:

Go to Agent Registry
From the project picker, select the Google Cloud project where you set up Agent Registry.
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.
To view the full details of an agent, click the agent's name.

gcloud

To list all agents in a specific location, run the gcloud agent-registry agents list command:

gcloud 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

In the Google Cloud console, go to Agent Registry:

Go to Agent Registry
From the project picker, select the Google Cloud project where you set up Agent Registry.
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.
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 by passing the --filter flag to the gcloud agent-registry agents list command:

gcloud 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, you can use the following filters:
- To filter by display name, use displayName='DISPLAY_NAME'.
- To search by the globally unique agent identifier (URN), use agentId='urn:agent:AGENT_URN'.

Terraform

To retrieve a specific registered agent by filtering against its metadata, configure the google_agent_registry_agent data source with the filter argument:

data "google_agent_registry_agent" "filtered_agent" {
  location = "REGION"
  filter   = "displayName=\"DISPLAY_NAME\""
}

Replace the following:

REGION: the registry region.
DISPLAY_NAME: the human-readable name of the agent to filter by, for example, Support Agent.

View details of an agent

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

Console

In the Google Cloud console, go to Agent Registry:

Go to Agent Registry
From the project picker, select the Google Cloud project where you set up Agent Registry.
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.
Click the name of the agent that you want to view.

The details page includes tabs for the agent details.
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 appear for agents built on managed runtimes, such as Agent Runtime on Gemini Enterprise Agent Platform:
- Overview: core details from the agent, including the agent's name, identifier, location, description, and runtime. The overview also displays A2A skills and the runtime reference, 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, run the gcloud agent-registry agents describe command:

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

Replace the following:

AGENT_NAME: the name of your agent, for example, my-custom-agent.
PROJECT_ID: the project ID.
REGION: the registry region.

Terraform

To retrieve details about a specific registered agent using its ID, configure the google_agent_registry_agent data source:

data "google_agent_registry_agent" "my_agent" {
  location = "REGION"
  agent_id = "AGENT_ID"
}

output "agent_create_time" {
  description = "The timestamp when the agent was registered."
  value       = data.google_agent_registry_agent.my_agent.create_time
}

output "agent_update_time" {
  description = "The timestamp when the agent was last updated."
  value       = data.google_agent_registry_agent.my_agent.update_time
}

Replace the following:

REGION: the registry region.
AGENT_ID: the unique identifier 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.

In Agent Registry, Agent resources are read-only discovery resources. To update a manually registered agent, you must update its writable Service resource directly. For automatically registered agents, update the agent in its underlying runtime so that Agent Registry synchronizes the changes.

Console

Update available agent details from the Google Cloud console:

In the Google Cloud console, go to Agent Registry:

Go to Agent Registry
From the project picker, select the Google Cloud project where you set up Agent Registry.
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.
Click the name of the agent that you want to update.
On the Overview tab of the agent, click Edit.
In the Edit service panel, enter the updated information of your agent, such as its new name or description.
Click Save.

gcloud

Run the gcloud agent-registry services update command 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 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 agent-registry services update AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL
```
Replace the following:
- AGENT_NAME: the name of your agent, for example, my-support-agent.
- PROJECT_ID: the project ID.
- REGION: the registry region.
- ENDPOINT_URL: the new agent 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 agent-registry services update AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --agent-spec-content=AGENT_SPEC_FILE
```
Replace the following:
- AGENT_NAME: the name of your agent, for example, my-support-agent.
- PROJECT_ID: the project ID.
- REGION: the registry region.
- AGENT_SPEC_FILE: the path to the new agent specification file, for example, new-agent-card.json. The maximum file size for the specification file is 10 KB.

Terraform

To update your registered agent's metadata, endpoint URL, or specification, modify the parameters of the existing google_agent_registry_service resource in your configuration, and then run terraform apply:

resource "google_agent_registry_service" "rest_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "New Display Name"
  description  = "Updated description of the agent's purpose."

  agent_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "ENDPOINT_URL"
    protocol_binding = "PROTOCOL"
  }
}

Replace the following:

REGION: the registry region.
AGENT_NAME: the unique name you want to give to your agent, for example, my-support-agent.
ENDPOINT_URL: the agent's API endpoint URL, for example, https://api.example.com/v1/agents/1234.
PROTOCOL: the protocol binding for the endpoint. Valid values are HTTP_JSON, GRPC, or JSONRPC.

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 its Service resource. This action removes the agent from search results and makes it undiscoverable to other tools:

Console

In the Google Cloud console, go to Agent Registry:

Go to Agent Registry
From the project picker, select the Google Cloud project where you set up Agent Registry.
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.
Click the name of the agent that you want to remove.
On the Overview tab of the agent, click Delete.
In the confirmation dialog, enter DELETE to confirm the action.
Click Delete.

gcloud

Run the gcloud agent-registry services delete command:

gcloud 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.

Terraform

Remove the google_agent_registry_service resource representing the agent from your Terraform configuration, and then run terraform apply.

What's next

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

Manage agents Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Required roles

Discover available agents

List and view all agents

Console

gcloud

Filter registered agents

Console

gcloud

Terraform

View details of an agent

Console

gcloud

Terraform

Update agent metadata and endpoints

Console

gcloud

Terraform

Remove an agent

Console

gcloud

Terraform

What's next

Manage agents