Agent Registry

Google Cloud Agent Registry Skill

Help users interact with the gcloud alpha agent-registry API by translating natural language into the correct gcloud command, showing it for approval, then executing it.

Workflow

1. Resolve session context — at the start of each session, silently run:

``bash gcloud config get-value project 2>/dev/null gcloud config get-value compute/region 2>/dev/null ` Store the results as SESSIONPROJECT and SESSIONLOCATION`. Use these as defaults.

1. Parse the user's request to identify the resource and action.
2. Construct the gcloud command using session defaults.
3. Approval:

• For list and describe commands: Skip explicit approval and execute immediately.
• For create, delete, or update commands: Show the command and ask for approval: "Ready to run this command? (yes/no)"

1. Execute and display the output.

Auth & Setup

# Check auth
gcloud auth list

# Login
gcloud auth login

# Set project
gcloud config set project PROJECT_ID

# (Optional) Set API override if needed
gcloud config set api_endpoint_overrides/agentregistry https://agentregistry.googleapis.com/

IAM Permissions

| Role | Access Level | |------|--------------| | roles/agentregistry.admin | Full administrative access | | roles/agentregistry.editor | Editor access | | roles/agentregistry.viewer | Read only access |

---

Resource Types & Registration

The primary command for registering resources is gcloud alpha agent-registry services create.

1. MCP Servers

Used to register Model Context Protocol servers.

# Register an MCP Server (example: GitHub)
# Ask user to paste contents of mcp-spec.json for --mcp-server-spec-content
gcloud alpha agent-registry services create github \
  --location=us-central1 \
  --display-name="GitHub MCP Server" \
  --description="Connects to GitHub" \
  --mcp-server-spec-type=tool-spec \
  --mcp-server-spec-content='PASTE_MCP_SPEC_JSON_HERE' \
  --interfaces='[{"protocolBinding": "jsonrpc", "url": "https://api.github.com/mcp"}]'

# List MCP Servers
gcloud alpha agent-registry mcp-servers list --location=us-central1

# Filter MCP Servers by Runtime
gcloud alpha agent-registry mcp-servers list \
  --location=us-central1 \
  --filter="attributes.\"agentregistry.googleapis.com/system/RuntimeReference\".uri:reasoningEngine"

# List Global MCP Servers
gcloud alpha agent-registry mcp-servers list --location=global

2. Agents

Used to register AI agents (e.g., A2A, Salesforce).

# Register an Agent (example: Salesforce)
gcloud alpha agent-registry services create salesforce \
  --location=us-central1 \
  --display-name="Salesforce Agent" \
  --description="Salesforce Einstein Agent" \
  --agent-spec-type=no-spec \
  --interfaces='[{"protocolBinding": "http-json", "url": "https://api.salesforce.com/agent/v1"}]'

# Register an A2A Agent (Special Case)
# Ask user to paste contents of agent_card.json for --agent-spec-content
gcloud alpha agent-registry services create testa2a \
  --location=us-central1 \
  --display-name="Test A2A Agent" \
  --description="Sample A2A Agent" \
  --agent-spec-type=a2a-agent-card \
  --agent-spec-content='PASTE_AGENT_CARD_JSON_HERE'

# List Agents
gcloud alpha agent-registry agents list --location=us-central1

# List Global Agents
gcloud alpha agent-registry agents list --location=global

3. Endpoints

Used to register service endpoints (e.g., Vertex AI models).

# Register an Endpoint (example: Gemini Models)
gcloud alpha agent-registry services create gemini-models \
  --location=us-central1 \
  --display-name="Vertex AI Model Garden" \
  --description="List of all models in Vertex AI Model Garden" \
  --endpoint-spec-type=no-spec \
  --interfaces='[{"protocolBinding": "jsonrpc", "url": "https://us-central1-aiplatform.googleapis.com/v1beta1/publishers/*/models"}]'

# List Endpoints
gcloud alpha agent-registry endpoints list --location=us-central1

# Update Endpoint Display Name
gcloud alpha agent-registry services update gemini-models \
  --display-name="Model Garden on Vertex AI" \
  --location=us-central1

4. GKE Based Agents

Used to configure Kubernetes deployments to be registered as an Agent or MCP Server. You can add the required apphub.cloud.google.com/functional-type annotation to YAML files using the provided python script.

# Ask the user if they want to process the current directory or a specific directory/file
# Ask the user if the functional type is an AGENT or MCP_SERVER

# Run the python script to annotate the YAML files
./scripts/annotate_gke.py /path/to/folder_or_file.yaml --type AGENT

5. Bindings

Used to connect a source agent to a target resource (another agent, MCP server, or endpoint) or an auth provider for delegated permissions.

# Create a binding to connect a source agent to a target resource
gcloud alpha agent-registry bindings create BINDING_NAME \
  --location=us-central1 \
  --display-name="My Custom Binding" \
  --source-identifier="SOURCE_ID" \
  --target-identifier="TARGET_ID"

# Create a binding for delegated permissions (using an auth provider)
gcloud alpha agent-registry bindings create BINDING_NAME \
  --location=us-central1 \
  --display-name="Auth Provider Binding" \
  --source-identifier="SOURCE_ID" \
  --auth-provider="projects/PROJECT_ID/locations/REGION/connectors/AUTH_PROVIDER_ID"

# List Bindings
gcloud alpha agent-registry bindings list --location=us-central1

# View Binding Details
gcloud alpha agent-registry bindings describe BINDING_NAME --location=us-central1

# Update a Binding
gcloud alpha agent-registry bindings update BINDING_NAME \
  --display-name="New Display Name" \
  --location=us-central1

# Delete a Binding
gcloud alpha agent-registry bindings delete BINDING_NAME --location=us-central1

Agent Dashboard

The Agent Dashboard provides a consolidated view of all agents in the current project, searching across both global and the regional location (default: us-central1).

To generate the dashboard, run:

./scripts/agent-dashboard.sh

The output will be a Markdown table containing the following fields:

• Name: The ID of the agent.
• Display Name: The human-readable name.
• Location: The region where the agent is registered.
• Runtime: The reference to the agent's runtime.

MCP Server Dashboard

The MCP Server Dashboard provides a consolidated view of all MCP servers in the current project, searching across both global and the regional location (default: us-central1).

To generate the dashboard, run:

./scripts/mcp-dashboard.sh

The output will be a Markdown table containing the following fields:

• Name: The ID of the MCP server.
• Display Name: The human-readable name.
• Location: The region where it is registered.
• Tools: List of tools provided by the server.
• Runtime: The reference to the runtime.

---

Detailed Command Reference

All commands support --location (required) and --project (optional).

| Group | Commands | |-------|----------| | agents | list, describe, search | | mcp-servers | list, describe, search | | endpoints | list, describe | | services | create, list, describe, update, delete | | bindings | create, list, describe, update, delete | | operations | list, describe |

Service Creation Flags

| Flag | Description | |------|-------------| | --display-name | Human-readable name | | --description | Brief summary of the service | | --interfaces | JSON array of protocol bindings and URLs | | --mcp-server-spec-type | Type: no-spec, tool-spec | | --mcp-server-spec-content| JSON content of the spec | | --agent-spec-type | Type: no-spec, a2a-agent-card | | --agent-spec-content | JSON content for a2a-agent-card | | --endpoint-spec-type | Type: no-spec |

---

Natural Language → Command Examples

| User says | Command | |-----------|---------| | "List my MCP servers" | gcloud alpha agent-registry mcp-servers list --location=us-central1 | | "Configure this GKE deployment as an agent" | ./scripts/annotate_gke.py /path/to/folder_or_file.yaml --type AGENT | | "Make my deployments in this folder MCP Servers" | ./scripts/annotate_gke.py /path/to/folder_or_file.yaml --type MCP_SERVER | | "Show me information on agent X" | gcloud alpha agent-registry agents describe X --location=us-central1 | | "Register a new GitHub MCP server with this spec..." | gcloud alpha agent-registry services create github ... --mcp-server-spec-content='...' | | "Check status of operation Y" | gcloud alpha agent-registry operations describe Y --location=us-central1 | | "List all registered services" | gcloud alpha agent-registry services list --location=us-central1 | | "Show all agents where the runtime is reasoningEngine" | gcloud alpha agent-registry agents list --location=us-central1 --filter="attributes.\"agentregistry.googleapis.com/system/RuntimeReference\".uri:reasoningEngine" | | "Show agents with identity containing 'service-432423'" | gcloud alpha agent-registry agents list --location=us-central1 --filter="attributes.\"agentregistry.googleapis.com/system/RuntimeIdentity\".principal:service-432423" | | "Create a new A2A agent called my-a2a" | gcloud alpha agent-registry services create my-a2a --agent-spec-type=a2a-agent-card ... | | "Show me all MCP servers where the runtime is my-runtime" | gcloud alpha agent-registry mcp-servers list --location=us-central1 --filter="attributes.\"agentregistry.googleapis.com/system/RuntimeReference\".uri:my-runtime" | | "List all global agents" | gcloud alpha agent-registry agents list --location=global | | "List global MCP servers" | gcloud alpha agent-registry mcp-servers list --location=global | | "show me a dashboard for my agents" | ./scripts/agent-dashboard.sh | | "show me a dashboard for my mcp servers" | ./scripts/mcp-dashboard.sh | | "Change display name of gemini-models to 'Vertex AI Model Garden'" | gcloud alpha agent-registry services update gemini-models --display-name="..." --location=us-central1 | | "Which agents in us-central1 are based on reasoning engine?" | gcloud alpha agent-registry agents list --location=us-central1 --filter="attributes.\"agentregistry.googleapis.com/system/RuntimeReference\".uri:reasoningEngine" | | "List all vertex ai agents" | gcloud alpha agent-registry agents list --location=us-central1 --filter="attributes.\"agentregistry.googleapis.com/system/RuntimeReference\".uri:reasoningEngine" | | "Show agents with agent engine runtime" | gcloud alpha agent-registry agents list --location=us-central1 --filter="attributes.\"agentregistry.googleapis.com/system/RuntimeReference\".uri:reasoningEngine" | | "Which MCP Server has a tool named searchdocuments?" | gcloud alpha agent-registry mcp-servers list --location=us-central1 --filter="tools.name:search_documents" | | "Find all servers with the getdocument tool" | gcloud alpha agent-registry mcp-servers list --location=us-central1 --filter="tools.name:get_document" | | "Search for all reasoning engine agents by agent ID" | gcloud alpha agent-registry agents list --location=us-central1 --filter="agentId:reason" | | "Search for Cloud Run MCP servers by MCP Server ID" | gcloud alpha agent-registry mcp-servers list --location=us-central1 --filter="mcpServerId:run" | | "Search for agents by skill name model" | gcloud alpha agent-registry agents search --location=us-central1 --search-string="skills.name:model" | | "Search for agents with display name containing Assessor" | gcloud alpha agent-registry agents search --location=us-central1 --search-string="displayName:Assessor*" | | "Search for MCP servers containing the display name GitHub" | gcloud alpha agent-registry mcp-servers search --location=us-central1 --search-string="displayName:GitHub*" | | "Create a binding between agent A and server B" | gcloud alpha agent-registry bindings create my-binding --source-identifier="URN_A" --target-identifier="URN_B" --location=us-central1 | | "List all bindings" | gcloud alpha agent-registry bindings list --location=us-central1 | | "Show details for binding X" | gcloud alpha agent-registry bindings describe X --location=us-central1 | | "Delete binding Y" | gcloud alpha agent-registry bindings delete Y --location=us-central1 |

---

Advanced Filtering

To filter resources based on nested attributes with special characters (like dots or slashes), use double quotes around the key segments in the --filter flag.

> [!WARNING] > The double-quote escaping shown below (\") works in bash/zsh. Windows CMD or PowerShell users may need different escaping (e.g., " or `` " `) for nested attribute keys.

Filtering by agentId and mcpServerId: The agentId and mcpServerId fields uniquely identify an agent or MCP server and follow the URN model. For agents, agentId always begins with: urn:agent:projects-{project-number}:projects:{project-number}:locations:{location}:{other-segments} For MCP servers, mcpServerId always begins with: urn:mcp:projects-{project-number}:projects:{project-number}:locations:{location}:{other-segments} The {other-segments} can vary based on the platform, for example:

• Reasoning Engine: aiplatform:reasoningEngines:{reasoning-engine-id}
• GKE: container:clusters:{cluster-name}:k8s:namespaces:{namespace}:apps:deployments:{deployment-id}

You can filter agents and MCP servers by substring matching these fields. For example, --filter="agentId:reason" finds Reasoning Engine agents, and --filter="mcpServerId:run" finds Cloud Run MCP servers.

Mapping Tips:

• Map "runtime" to attributes."agentregistry.googleapis.com/system/RuntimeReference".uri.
• Map "identity" to attributes."agentregistry.googleapis.com/system/RuntimeIdentity".principal.
• Map "tool name" or "tool" to tools.name for MCP Server list commands.
• Synonyms: "agent engine", "reasoning engine", and "vertex ai" all refer to the runtime value reasoningEngine.
• Context Filtering: If the user asks about "agents", use the agents resource group (e.g., gcloud alpha agent-registry agents list), not mcp-servers or endpoints.

# Example: Show all agents where the runtime is reasoningEngine
gcloud alpha agent-registry agents list \
  --location=us-central1 \
  --filter="attributes.\"agentregistry.googleapis.com/system/RuntimeReference\".uri:reasoningEngine"

# Example: Show agents where identity contains a specific service account ID
gcloud alpha agent-registry agents list \
  --location=us-central1 \
  --filter="attributes.\"agentregistry.googleapis.com/system/RuntimeIdentity\".principal:service-432423"

# Example: Search for all reasoning engine agents using the agentId
gcloud alpha agent-registry agents list \
  --location=us-central1 \
  --filter="agentId:reason"

# Example: Search for cloud run MCP servers using the mcpServerId
gcloud alpha agent-registry mcp-servers list \
  --location=us-central1 \
  --filter="mcpServerId:run"

---

Searching Agents

When searching for agents, always default to using the mcp_agentregistry_search_agents MCP tool if the agentregistry MCP server is available. Use the gcloud alpha agent-registry agents search command as a fallback.

MCP Tool Usage (mcp_agentregistry_search_agents)

• parent: projects/{project}/locations/{location}
• searchString: Follows the same syntax as the gcloud command (e.g., skills.name:model, displayName:Assessor*).

gcloud Fallback Usage

You can search for agents using the gcloud alpha agent-registry agents search command. This command supports a --search-string flag with specific match types:

• Exact match (=): Matches the entire value exactly.

Example: `--search-string="agentId=\"urn:agent:

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: srinandan
• Source: srinandan/agent-registry-skill
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.