Google Cloud Agent Registry
Interact with Google Cloud Agent Registry using gcloud agent-registry (agents, mcp-servers, services, endpoints, bindings, skills, findings, publishers, ai-applications, operations), gcloud beta run (--functional-type and --identity-type for automatic registration of Cloud Run services and jobs), Kubernetes manifests and scripts/annotate_gke.py [blocked] (GKE automatic registration), gcloud resource-manager (boundary-configs, capability-configs, boundaries, and tags bindings for management boundaries), and Python ADK (google-adk).
Usage Attribution
MUST READ: Before executing any gcloud, REST API, or MCP command, you MUST read and follow the instructions in Usage Attribution [blocked].
Workflow
- Resolve session context — at the start of each session, silently run:
Store the results as
SESSION_PROJECTandSESSION_LOCATIONand use them as defaults. - Parse the user's request to identify the target resource and action.
- Construct the
gcloudcommand or Kubernetes manifest using session defaults. See gcloud Command Reference [blocked] for full flag synopses, command summary tables, and 60+ natural-language-to-command examples. - Documentation Fallback — if a user asks about a feature, flag, schema, or error message not covered in this skill, query the
developerknowledgeMCP server or public.md.txtdocumentation (see Documentation Fallback). - Approval:
- Read-only commands (
list,describe,search,get-iam-policy): Execute immediately without asking for approval. - Mutating commands (
create,delete,update,deploy,set-iam-policy,add-iam-policy-binding,remove-iam-policy-binding): Display the exact command and ask: "Ready to run this command? (yes/no)" - Multi-task requests: Always output the commands for every requested task in the same response before asking for approval.
- Read-only commands (
- Execute and display the output.
Prerequisites, Auth, Billing, Region & IAM Permissions
- Cloud SDK: Requires
gcloud560.0.0+ (beta2026.03.09+ for Cloud Run automatic registration; ensuregcloudis up to date for GAgcloud agent-registry skills). Do not install or update tools or packages on the host without explicit user approval; ifgcloudis missing, sharehttps://docs.cloud.google.com/sdk/docs/install-sdk.md.txtand fall back to.md.txtdocumentation. - Billing & Pricing: The target project must be linked to an active Google Cloud Billing account. For Cloud Run, GKE, or Vertex AI pricing, direct users to
https://cloud.google.com/pricing. - Region & Location Availability: Configure a default region (
gcloud config set compute/region us-central1) and verify supported regions athttps://docs.cloud.google.com/agent-registry/locations.md.txtandhttps://cloud.google.com/about/locations(note: Skills only supportglobal,us, oreu). - Authentication: Check active credentials first with
gcloud auth list. Becausegcloud auth loginandgcloud auth application-default loginlaunch interactive browser flows and stop responding in non-interactive shells, never execute them directly — if unauthenticated, ask the user to rungcloud auth login(for CLI sessions) orgcloud auth application-default login(for local Python ADK Application Default Credentials) in their own terminal, or configureGOOGLE_APPLICATION_CREDENTIALS.
Resource Types & Registration
- Manual Registration (
services create):gcloud agent-registry services createcreates a writableServiceresource to manually register external or cross-projectAgent,McpServer, andEndpointresources in Agent Registry, and automatically projects a corresponding read-onlyAgent,McpServer, orEndpointcatalog entry (agentregistry-{ID}, returned inregistryResourceonservices describe) used for runtime discovery and IAP/Agent Gateway policies.
1. MCP Servers
If the user has not provided the MCP tool spec JSON yet, ask: "Please paste the contents of your MCP server spec JSON file." and preview the command template using 'PASTE_MCP_SPEC_JSON_HERE':
2. Agents
For A2A agents, if the user has not pasted agent_card.json yet, ask: "Please paste the contents of your agent_card.json file." and preview the command template using 'PASTE_AGENT_CARD_JSON_HERE':
3. Endpoints, Services & Quick Add GCP Service (Composite Agent Gateway Registration)
Quick Add GCP Service (All 5 Endpoint URL Variants)
When an agent runs behind a governed Agent Gateway (default-deny egress), Google Cloud SDKs dynamically resolve endpoints across up to 5 hostname variants:
- Base:
https://${SERVICE_ID}.googleapis.com - Base mTLS:
https://${SERVICE_ID}.mtls.googleapis.com - Locational:
https://${LOCATION}-${SERVICE_ID}.googleapis.com(omit when--location=global) - Locational mTLS:
https://${LOCATION}-${SERVICE_ID}.mtls.googleapis.com(omit when--location=global) - Regional REP:
https://${SERVICE_ID}.${LOCATION}.rep.googleapis.com(omit when--location=global)
Register a single composite Service containing all applicable variants using scripts/quick-add-gcp-service.sh [blocked] or gcloud agent-registry services create (always previewing and asking for approval first):
- Service ID Length (
4–63chars): Service IDs must match^[a-z][a-z0-9-]{2,61}[a-z0-9]$. For 3-letter APIs (iam,kms,run,dns), suffix theServiceID (e.g.,${SERVICE_ID}-api) while keeping${SERVICE_ID}in the endpoint URLs. - Global Location Guardrail: When
--location=global, include onlyBaseandBase mTLSso invalid regional DNS names are not registered. - IAP Egress Policy Target: Bind
roles/iap.egressorfor the Agent Identity to the projectedEndpointcatalog ID (endpoints/agentregistry-{UUID}fromregistryResourceonservices describe), not the user-chosenServiceID.
4. GKE Agents & MCP Servers (Automatic Registration)
Configure GKE Deployment manifests for automatic discovery in Agent Registry (using metadata.name as the display name):
Use scripts/annotate_gke.py [blocked] to automatically add registry.gke.io/functional-type, apphub.cloud.google.com/functional-type, and the Pod template iam.gke.io/spiffe-identity-type: "agent-identity" annotation to existing YAML files (target path is required; supports --dry-run):
GKE Agent (Deployment + Service) & MCP Server (Deployment) Templates:
5. Cloud Run Agents & MCP Servers (Automatic Registration via --functional-type)
Register Cloud Run services and jobs automatically using gcloud beta run:
[!WARNING] Critical Cloud Run Guardrails:
- Immutability: Once
--functional-typeor--identity-typeis set on a Cloud Run service or job, it is immutable and cannot be changed or cleared.--functional-type=agentRequires--identity-type=agent-identity: Always include--identity-type=agent-identitywhenever--functional-type=agentis used (certificates are provisioned by default; opt out with--no-identity-certificate).- Updating Existing Services (
--no-trafficGuardrail): Transitioning an existing service to--identity-type=agent-identityassigns a new SPIFFE Agent Identity principal (principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME) that does not inherit the previous service account's IAM permissions. Recommend--no-trafficongcloud beta run services updateto stage IAM bindings before shifting traffic.- Cloud Run Jobs Cannot Be MCP Servers: Only Cloud Run services support
--functional-type=mcp-server; Cloud Run jobs only support--functional-type=agent.
6. Bindings
Connect a source agent to a target resource or an Auth Provider connector:
7. Skills & Skill Revisions
Manage reusable AI Skills, Skill Revisions, and Skill IAM policies using gcloud agent-registry skills.
[!IMPORTANT] Skills Guardrails (
--location,private-Prefix &--target-state):
- Supported Locations: Skills only work in
"global","us", or"eu"multi-regions. If a user asks for any single region (e.g.us-central1), do not pass that region togcloud. Explain that Skills are only supported inglobal,us, oreu, preview the command using a concrete supported multi-region (e.g.--location=us,--location=eu, or--location=global), and ask them to confirm which multi-region to use.- Automatic
private-Prefix: Runninggcloud agent-registry skills create my-skillautomatically prependsprivate-, creatingskills/private-my-skill. Subsequentdescribe,update,delete,revisions, and*-iam-policycommands must passprivate-my-skill(passingmy-skillfails withNOT_FOUND).- Target State & Scanning:
--target-state=active|disabled|draftsets the desired lifecycle state on creation (activerequires an initial revision via--payloador--gcs-source-uri;deprecatedanddecommissionedare also valid onupdate). Under the defaultenabled-blockingscanning policy,--target-state=activeentersDRAFT(STATE_DRAFT) until the background security scan passes with no findings.
8. AI Applications (ai-applications)
An AI Application (projects/{project}/locations/{location}/aiApplications/{ai_application}, including the regional default AI Application) groups agents, MCP servers, and endpoints under a governance perimeter.
9. Management Boundary Setup (Admin Governance)
Configure Folder/Organization hub-and-spoke perimeters using gcloud resource-manager (boundary-configs, capability-configs, boundaries, and tags bindings). Read Management Boundaries Guide [blocked] for the full IAM table, 6 interactive scoping questions, and 6-step provisioning workflow.
- Always Use Project Numbers (
projects/<PROJECT_NUMBER>): Cloud Resource Manager v3 requires project numbers (not project IDs) for--management-project=projects/<PROJECT_NUMBER>and--parent=//cloudresourcemanager.googleapis.com/projects/<PROJECT_NUMBER>. When given a project ID, output bothgcloud projects describe PROJECT_ID --format="value(projectNumber)"and thecapability-configs createcommand template (--types=agent-managementby default) in the same response. - Set
BoundaryConfigBefore Attaching Boundaries & Isolatedev/prodHubs: Setboundary-configs update --tag-key=...before attaching boundaries. Use separateCapabilityConfig+ Management Project +Boundaryper environment (devvs.prod) for strict catalog and IAM isolation. - Tag Rebinding Requires Delete-Then-Create: Moving a project between tag values (e.g.,
devtoprod) fails withFAILED_PRECONDITIONif you only runcreate; always runtags bindings deletefirst, thentags bindings create. - Safe 3-Step Teardown Order: Always output all 3 commands in order when deleting a boundary and capability config (noting that BYO projects are preserved with
isManagementProject=false, while Google-managed hubs are deleted):
Advanced Filtering & Search
Filtering (list --filter)
- URN Substring Filtering (
agentId&mcpServerId):agentId:urn:agent:projects-{project-number}:projects:{project-number}:locations:{location}:{platform-segments}mcpServerId:urn:mcp:projects-{project-number}:projects:{project-number}:locations:{location}:{platform-segments}- Platform segments:
aiplatform:reasoningEngines:{id}(Vertex AI Reasoning Engine),container:clusters:{cluster}:k8s:namespaces:{ns}:apps:deployments:{deploy}(GKE),run:services:{svc}orrun:jobs:{job}(Cloud Run).
- Attribute Mapping:
- "runtime" ("agent engine", "reasoning engine", "vertex ai" ->
reasoningEngine):attributes."agentregistry.googleapis.com/system/RuntimeReference".uri - "identity":
attributes."agentregistry.googleapis.com/system/RuntimeIdentity".principal - "tool" / "tool name" (on
mcp-servers list):tools.name
- "runtime" ("agent engine", "reasoning engine", "vertex ai" ->
Searching Agents, MCP Servers, and Skills (search)
- Agents (
gcloud agent-registry agents search): Supports--search-stringwith exact (=), token (:), and prefix (*) matching acrossagentId,displayName,skills.name,skills.id,skills.tags,skills.description, and booleanOR/AND. Note: Values with colons (URNs) must be quoted, and wildcard*is not supported onskills.description(use token match:instead). - MCP Servers (
gcloud agent-registry mcp-servers search): Supports--search-stringacrossmcpServerId,name, anddisplayName. - Skills (
gcloud agent-registry skills search): Supports--queryand--search-type=keywordor--search-type=semanticinglobal,us, oreu.
Python ADK Integration
Whenever the user asks to discover or connect to registered Agents (get_remote_a2a_agent) or MCP Servers (get_mcp_toolset) in Python using Google's Agent Development Kit (google-adk[a2a,agent-identity,mcp]), read and follow ADK Integration Guide [blocked].
Documentation Fallback (developerknowledge MCP Server)
For CLI synopses, read gcloud Command Reference [blocked]. If a user asks about a feature, Terraform resource (google_agent_registry_service), or error not covered in SKILL.md or references/, query the developerknowledge MCP server (search_documents + get_documents, or answer_query) or fetch the public .md.txt documentation pages:
https://docs.cloud.google.com/agent-registry/overview.md.txthttps://docs.cloud.google.com/agent-registry/automatic-registration.md.txthttps://docs.cloud.google.com/agent-registry/manual-registration.md.txthttps://docs.cloud.google.com/agent-registry/register-agents.md.txthttps://docs.cloud.google.com/agent-registry/register-mcp-servers.md.txthttps://docs.cloud.google.com/agent-registry/register-endpoints.md.txthttps://docs.cloud.google.com/agent-registry/register-skills.md.txthttps://docs.cloud.google.com/agent-registry/manage-skills.md.txthttps://docs.cloud.google.com/agent-registry/skills-architecture.md.txthttps://docs.cloud.google.com/agent-registry/scan-skills.md.txthttps://docs.cloud.google.com/agent-registry/boundaries-and-topology.md.txthttps://docs.cloud.google.com/agent-registry/access-control.md.txthttps://docs.cloud.google.com/agent-registry/roles-permissions.md.txthttps://docs.cloud.google.com/agent-registry/a2a-protocol.md.txthttps://docs.cloud.google.com/agent-registry/resolve-endpoints-and-build-orchestrators.md.txthttps://docs.cloud.google.com/agent-registry/search-agents-and-tools.md.txthttps://docs.cloud.google.com/agent-registry/identity-and-identifiers.md.txthttps://docs.cloud.google.com/agent-registry/troubleshooting.md.txthttps://docs.cloud.google.com/run/docs/ai/agent-platform-features.md.txt
Error Handling
- Verify Cloud SDK version (560.0.0+, updated for GA
skills) andbetacomponent (2026.03.09+ for Cloud Run). - Verify
--location/--region: Google Cloud remote MCP servers are discovered inglobal; Skills only supportglobal,us, oreu. - Ensure JSON strings passed to
--interfaces,--agent-spec-content, or--mcp-server-spec-contentare properly single-quoted for the shell. - Confirm required APIs (
agentregistry.googleapis.com,run.googleapis.com,apphub.googleapis.com) and IAM roles are enabled on the target project.


