To answer questions about agent health, relationships, dependencies, and policy compliance, you can run queries that correlate agent data, traffic data, and other resource data. The results are displayed as topology graph that you can explore.
A topology graph can help you to do the following:
- Map resource relationships: Visualize data associated with your agents, including, MCP servers, underlying infrastructure, endpoints, skills, and identities.
- Identify registration gaps: Identify discovered compute workloads that aren't registered in Agent Registry.
- Validate policy compliance: Identify vulnerabilities and security issues identified by Security Command Center.
- Analyze impacts of changes: Assess impacts of changes to access policies, endpoint credentials, or infrastructure that agent resources depend on.
You can run suggested queries, customize a suggested query, or create your own custom query.
Before you begin
Identify the Google Cloud project that you want to set up.
Security and compliance data provided by Security Command Center is only available for projects in a Google Cloud organization. If you want to migrate a project to an organization, see the migration instructions.
Set up the services that provide the resource data that you want to query:
To view software supply chain data such as build provenance, configure Developer Connect insights.
To view data for agent resources registered in Agent Registry, set up Agent Registry and register your agent resources.
To view agent traffic, instrument your AI applications.
To view security and compliance data, set up Security Command Center for security and compliance data. Activate Security Command Center at the organization level and configure the features that you want to use. Querying data from Security Command Center is only available for Premium and Enterprise tiers.
Enable the App Hub, App Topology, Cloud Asset Inventory, and Observability APIs, if any are not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.-
Verify that billing is enabled for your Google Cloud project.
If you are protecting services in a VPC Service Controls perimeter, update the perimeter to include App Topology and services that provide underlying data. Learn more.
Required roles
To get the permissions that
you need to view topology graphs,
ask your administrator to grant you the
App Topology Viewer (roles/apptopology.viewer) IAM role on the projects where you want to use App Topology.
For more information about granting roles, see Manage access to projects, folders, and organizations.
This predefined role contains the permissions required to view topology graphs. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to view topology graphs:
-
Get discovered resource data:
apptopology.discoveredResourcesTopologies.generate -
Get resource data data:
apptopology.sreDomainTopologies.generate
You might also be able to get these permissions with custom roles or other predefined roles.
About queries
App Topology queries consist of several components:
Nodes - Discovered or registered Google Cloud resources. Examples of nodes include:
- A Compute Engine VM
- A container image in Artifact Registry
- An agent
- A Cloud Monitoring alert
- An AI application
- A vulnerability
The query builder groups nodes by service.
Where clause: a filter that's applied to a node to refine the query based on the specific properties of the node.
Connections: A directional relationship between two nodes. Connections are context-aware, and only valid relationships are available for a selected node type. Examples include:
contained insends traffic toownsdepends on
The following example query searches for deployments that have a specific vulnerability:
The query establishes the key nodes of the investigation:
- Agent
- Vulnerability
The connection contains indicate the node relationships:
Agent contains Vulnerability
The Where clause filters vulnerability results to show a specific CVE.
Where Id = CVE-2026-24061
Use or customize a suggested query
App Topology provides query suggestions that you can use without any changes, or you can customize those suggestions to fit your specific requirements.
In the Google Cloud console, go to the Topology page.
In the project picker, select the project that contains your agents.
Under Quick Queries, click a query to see a preview of the query components.
To use the query, click Use suggestion. The query appears in the Show section.
To make changes to the query, add, edit, or remove components.
- To add a component to the query, click the plus icon () next to the node.
- To remove a component, click the close icon .
- To change the value of a
Whereclause, click the value.
You can click Undo to revert a change or Redo to re-apply changes you reverted with Undo.
As you build your query, the available nodes, filters, and connections are updated.
When you are finished editing the query, click Run query. If the results of your query includes Google Cloud discovered resources or resources registered in Agent Registry, a topology graph is displayed.
Graphs aren't available for query results that only include data types such as strings or counts.
Based on the results, you can edit the query and then click Run query to update the topology graph.
Explore the topology graph. The graph shows resources that match your query and the relationships between them.
- Icons represent nodes, discovered and registered resources and their resource type.
- Lines represent connections, the relationships between nodes.
You can interact with a topology in the following ways:
- Change the visualization by zooming in or out or repositioning nodes.
- View the label for a connection by hovering over the connection line between two nodes.
- Get information about a node or connection by selecting it.
- Hide or show the query panel by clicking Toggle panel .
If there are no results, try refining your query.
Create custom queries
To create a custom query, either start a new query or customize an existing suggested query using the following steps:
In the Google Cloud console, go to the Topology page.
In the project picker, select the project that contains your agents.
In the query builder, click and select a resource or finding as the primary node for your query, and then click Continue.
To refine your query, click the toggle for any filter or connection to enable it for the selected node. Define the value for each filter you enable.
To make changes to the query, add, edit, or remove components.
- To add a component to the query, click the plus icon () next to the node.
- To remove a component, click the close icon .
- To change the value of a
Whereclause, click the value.
You can click Undo to revert a change or Redo to re-apply changes you reverted with Undo.
As you build your query, the available nodes, filters, and connections are updated.
When you are finished editing the query, click Run query. If the results of your query includes Google Cloud discovered resources or resources registered in Agent Registry, a topology graph is displayed.
Graphs aren't available for query results that only include data types such as strings or counts.
Based on the results, you can edit the query and then click Run query to update the topology graph.
Explore the topology graph. The graph shows resources that match your query and the relationships between them.
- Icons represent nodes, discovered and registered resources and their resource type.
- Lines represent connections, the relationships between nodes.
You can interact with a topology in the following ways:
- Change the visualization by zooming in or out or repositioning nodes.
- View the label for a connection by hovering over the connection line between two nodes.
- Get information about a node or connection by selecting it.
- Hide or show the query panel by clicking Toggle panel .
Some limitations apply to queries. If there are no results, try refining your query.
What's next
- Register discovered agents in Agent Registry.