Register a custom ADK agent

Agent Registry lets you register custom agents that you build with the Agent Development Kit (ADK) and host on your own infrastructure so that other developers and orchestrator agents can discover them. By exposing an Agent Card that conforms to the Agent2Agent (A2A) protocol and manually registering the agent's endpoint, you make its A2A skills discoverable in Agent Registry.

Before you begin

  1. Set up Agent Registry.
  2. Get the project ID for the governance project where Agent Registry is enabled.
  3. 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 register custom ADK 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.

The Agent Card endpoint

So that Agent Registry can index your custom agent's capabilities, the agent must expose its metadata and available A2A skills using the Agent2Agent (A2A) protocol.

The A2A specification requires agents to serve an Agent Card, which is a JSON document describing the agent's identity and tools, at a specific endpoint, typically /.well-known/agent-card.json.

When you use the ADK's specific A2A server plugins or modules to register your agent, the framework can automatically generate and serve this Agent Card based on the Agent definition and tools you provide in your code.

Register the exposed agent

After you deploy the ADK agent to your hosting environment and it successfully serves its REST endpoints, instruct Agent Registry to discover it.

Because custom deployments require manual registration, you create a Service resource in the registry. Save your agent's generated Agent Card as a local JSON file, for example, agent-card.json.

Use gcloud CLI to register the agent with the gcloud agent-registry services create command, making sure to specify the a2a-agent-card specification type, and upload your local file using the --agent-spec-content flag:

gcloud agent-registry services create AGENT_NAME \
    --project=PROJECT_ID \
    --location=LOCATION \
    --display-name="DISPLAY_NAME" \
    --agent-spec-type=a2a-agent-card \
    --agent-spec-content=agent-card.json

The maximum file size for the specification file is 10 KB.

Replace the following:

  • AGENT_NAME: the name you want to give to your agent, for example, my-custom-agent.
  • PROJECT_ID: the project ID.
  • LOCATION: the registry location or region.
  • DISPLAY_NAME: the human-readable name of your agent.

After the Service resource is created, Agent Registry parses the Agent Card, creates a read-only Agent resource, and indexes the A2A skills defined in your ADK Python code so that other developers can search for them.