Key concepts

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.

This document explains the key terms and concepts related to Agent Registry.

Agent

An autonomous actor in your AI ecosystem, defined by its identifier and the specific skills it possesses.

Agent identifier

A globally unique, immutable name for the agent. This logical identifier provides a stable reference for consumers to call the agent, remaining constant regardless of underlying infrastructure changes.

Agent identifiers are generated automatically by Agent Registry during ingestion and follow a Uniform Resource Name (URN) format. The exact format depends on where the agent is deployed. The following are examples:

• Vertex AI Agent Engine: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:reasoningEngines:AGENT_ID
• Cloud Run services: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:services:SERVICE_NAME
• GKE deployments: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:containers:CLUSTER_NAME:namespace:NAMESPACE:deployment:DEPLOYMENT_NAME
• Gemini Enterprise: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:discoveryengine:INSTANCE_ID:root
• Google Workspace: urn:agent:googleapis.com:locations:global:workspaceagent:workspaceagent--a2a
• Manually registered agents: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:agentregistry:SERVICE_ID

Agent principal

The unique IAM identifier assigned to an agent, letting it hold permissions and be audited. It takes the form of a verifiable Google Cloud service account or a managed workload identity, such as a SPIFFE ID, bound to an agent or server.

Because this identity is bound directly to the compute resource of the agent's runtime, the principal string incorporates the exact path to that underlying resource. For example, an agent principal for an Vertex AI Agent Engine deployment looks like this:

principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/REGION/reasoningEngines/REASONING_ENGINE_ID

Agent Registry displays this identity as an output-only attribute when you view the details of an agent.

Agentic workflow

A sequence of steps where an AI agent independently determines tool usage, reasoning, and execution paths to accomplish a task.

Auth provider

A configuration within Agent Identity auth manager to store, acquire, and manage credentials, such as API keys or OAuth tokens, for connecting your agent to specific external tools and applications and define the authentication type.

Binding

A connection between a source agent and a target resource, such as another agent, an MCP server, or an endpoint. By creating bindings, you establish explicit relationships that let your orchestrator agents interact with downstream capabilities. Bindings are also used to associate an agent with an auth provider to support delegated permissions.

Data resource

A specific data context or dataset exposed by an MCP server that an agent can access to ground its responses or inform its actions.

Discovery

The process of querying the registry to find existing agents or MCP tools based on descriptions, tags, or skills. Discovery by skills is available for agents that expose their capabilities through an Agent Card, such as those implementing the Agent2Agent (A2A) protocol.

Endpoint

For the Agent Registry API, a resource that represents a target URL, typically a REST API, accessed by an agent. By abstracting these destinations into manageable resources, Agent Registry lets you centrally govern which external services an agent can access.

Model Context Protocol (MCP)

The open standard used to connect AI models to data sources and tools, replacing bespoke plugins.

MCP server (or server)

A service that implements the Model Context Protocol (MCP) to provide standardized tools and data resources to AI agents.

MCP server identifier

A globally unique, immutable Uniform Resource Name (URN) for an MCP server. Similar to agent identifiers, this name provides a stable reference for discovering specific toolsets.

The format depends on whether it is a built-in Google service or a registered external server. The following are examples:

• Google Cloud remote MCP servers: urn:mcp:googleapis.com:projects:PROJECT_NUMBER:locations:global:SERVICE_NAME
• Manually registered MCP servers: urn:mcp:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:agentregistry:SERVICE_ID

Registration

The process of adding a service to the registry. Agent Registry provides the following registration mechanisms:

• Automatic registration: Automatic ingestion of supported Google Cloud workloads, for example, in Vertex AI Agent Engine.
• Manual registration: Manual onboarding of custom or external workloads.

Resource URI

The physical runtime location or infrastructure that hosts an agent or MCP server. The Uniform Resource Identifier (URI) is the unique sequence of characters that identifies this runtime resource. For example, a resource URI can be a Vertex AI endpoint, a GKE deployment, or a Cloud Run service.

The resource URI differs from the agent identifier or MCP server identifier. These values are the unique names in URN format that identify your agents and MCP servers in the registry. In contrast, the resource URI points to the actual compute resource where the agent or server runs.

The path to the resource URI of an agent is embedded within the agent principal string to uniquely identify that workload in IAM policies.

Agent Registry displays this URI as an output-only attribute when you view the details of an agent.

You can use the resource URI to build queries in the topology graph to visualize traffic flows and relationships for specific agents. In the Agent Registry API, this value is represented by the agentregistry.googleapis.com/system/RuntimeReference attribute.

Service

For the Agent Registry API, the writable resource used to manually register custom or external workloads into the registry. A service represents an agent, an MCP server, or an endpoint that is manually added to your registry. You create and manage a Service resource to define the endpoint and metadata for workloads that Agent Registry doesn't automatically ingest.

Depending on the specification you provide, Agent Registry automatically projects this service onto the consumer side as a read-only Agent, McpServer, or Endpoint resource for discovery.

You always use the Service resource to create, edit, or delete registry entries. However, to get, list, or search for those entries, you query the read-only Agent, McpServer, or Endpoint resources.

Skill

A high-level capability possessed by an A2A agent. Skills are extracted from A2A agent cards and serve as the primary data points for agent discovery.

Tool

A deterministic function provided by an MCP server that an agent can invoke.