Register a custom ADK agent

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.

If you build a custom agent using the Agent Development Kit (ADK) and host it on your own infrastructure, you can make it discoverable in Agent Registry by exposing an Agent Card and manually registering its endpoint.

This document explains how to make sure your ADK agent conforms to the Agent2Agent (A2A) protocol, letting the registry index its skills.

The Agent Card endpoint

To enable Agent Registry to understand your custom agent's capabilities, the agent must expose its metadata and available 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 Google Cloud CLI to register the service, making sure to specify the a2a-agent-card specification type, and upload your local file using the --agent-spec-content flag:

gcloud alpha 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

Note: The agent specification file you upload must not exceed 10 KB in size.

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 is created, Agent Registry parses the Agent Card, creates a discoverable Agent resource, and indexes the skills defined in your ADK Python code so that other developers can search for them.