Agent Registry lets you register custom agents that you build with the
[Agent Development Kit (ADK)](https://github.com/google/adk-docs) and host on
your own infrastructure so that other developers and orchestrator agents can
discover them. By exposing an
[Agent Card](https://agent2agent.info/docs/concepts/agentcard/) that conforms to
the [Agent2Agent (A2A) protocol](https://a2a-protocol.org/latest/) and manually
registering the agent's endpoint, you make its
[A2A skills](https://docs.cloud.google.com/agent-registry/skills-architecture.md.txt#standalone-vs-a2a)
discoverable in Agent Registry.

## Before you begin

1. [Set up Agent Registry](https://docs.cloud.google.com/agent-registry/setup.md.txt).
2. For a single-project setup, get
   [the project ID](https://support.google.com/googleapi/answer/7014113)
   of the [governance project](https://docs.cloud.google.com/agent-registry/overview.md.txt#governance-project)
   where Agent Registry is enabled. If you configured a
   [management boundary](https://docs.cloud.google.com/agent-registry/boundaries-and-topology.md.txt) for multiple
   projects, use the ID of your management project for boundary-wide discovery
   and registration, or specify a member project ID for single-project
   operations.

3. To use the Google Cloud CLI commands in this document,
   [set up your gcloud CLI environment](https://docs.cloud.google.com/agent-registry/setup.md.txt#set-up-cli).

### Required roles

<br />


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](https://docs.cloud.google.com/iam/docs/roles-permissions/agentregistry.md.txt#agentregistry.editor) (`roles/agentregistry.editor`) IAM role on the [governance project](https://docs.cloud.google.com/agent-registry/overview.md.txt#governance-project)
where Agent Registry is enabled.


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

## 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](https://a2a-protocol.org/latest/).

The A2A specification requires agents to serve an
[Agent Card](https://agent2agent.info/docs/concepts/agentcard/), 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](https://docs.cloud.google.com/agent-registry/register-agents.md.txt#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`](https://docs.cloud.google.com/sdk/gcloud/reference/agent-registry/services/create.md.txt)
command, making sure to specify the `a2a-agent-card` specification type, and
upload your local file using the `--agent-spec-content` flag:

```bash
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](https://docs.cloud.google.com/agent-registry/search-agents-and-tools.md.txt).