Register and manage A2A agents

Agent-to-Agent (A2A) is an open communication protocol and a universal language for AI agents. It enables agents from different builders and platforms to discover each other, collaborate, and securely delegate tasks. This document explains how Gemini Enterprise admins can connect agents that are built using A2A to Gemini Enterprise, making them available to users in the Gemini Enterprise web app.

Before you begin

Make sure you have the following:

Configure authorization details

This step is optional. You only need to create OAuth authorization credentials if you want the agent to access Google Cloud resources, such as BigQuery tables, on behalf of a user.

Obtain authorization details

Follow these steps to obtain the authorization details.

  1. In the Google Cloud console, on the APIs & Services page, go to the Credentials page.

    Go to Credentials

  2. Select the Google Cloud project, which has the data source you want the agent to access. For example, select the project that contains the BigQuery dataset that you want the agent to query.

  3. Click Create credentials and select OAuth client ID.

  4. In Application type, select Web application.

  5. In the Authorized redirect URIs section, add the following URIs:

    • https://vertexaisearch.cloud.google.com/oauth-redirect
    • https://vertexaisearch.cloud.google.com/static/oauth/oauth.html

  6. Click Create.

  7. In the OAuth client created panel, click Download JSON. The downloaded JSON includes the Client ID, Authorization URI, Token URI, and Client secret for the selected Google Cloud project. You need these details to create an authorization resource:

Add an authorization resource to Gemini Enterprise

Run the following command to register an authorization resource with Gemini Enterprise:

REST

curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/loca
   tions/LOCATION/authorizations?authorizationId=AUTH_ID" \
   -d '{
      "name": "projects/PROJECT_ID/locations/LOCATION/authorizations/AUTH_ID",
      "serverSideOauth2": {
         "clientId": "OAUTH_CLIENT_ID",
         "clientSecret": "OAUTH_CLIENT_SECRET",
         "authorizationUri": "OAUTH_AUTH_URI",
         "tokenUri": "OAUTH_TOKEN_URI"
      }
   }'

Replace the following:

  • PROJECT_ID: the ID of your project.
  • ENDPOINT_LOCATION: the multi-region for your API request. Assign one of the following values:
    • us- for the US multi-region
    • eu- for the EU multi-region
    • global- for the Global location
    For more information, see Specify a multi-region for your data store.
  • LOCATION: the multi-region of your data store: global, us, or eu
  • AUTH_ID: The ID of the authorization resource. This is an arbitrary alphanumeric ID that you define. You need to reference this ID later when registering an Agent that requires OAuth support.
  • OAUTH_CLIENT_ID: the OAuth 2.0 client identifier you obtained when you created the OAuth credentials.
  • OAUTH_CLIENT_SECRET: the OAuth 2.0 client secret you obtained when you created the OAuth credentials.
  • OAUTH_AUTH_URI: the authorization URI you obtained when you created the OAuth credentials. It has the following format: https://accounts.google.com/o/oauth2/v2/auth?client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fbigquery&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
  • OAUTH_TOKEN_URI: the token URI you obtained when you created the OAuth credentials.

Register agent with Gemini Enterprise

Console

  1. In the Google Cloud console, go to the Gemini Enterprise page.

    Gemini Enterprise

  2. Click the name of the app that you want to register the agent with.

  3. Click Agents > Add Agents.

  4. In the Choose an agent type section, click Add for Custom agent via A2A.

  5. In the Agent card JSON field, enter the agent card details in JSON format. For a complete list of available fields, see the Agent2Agent (A2A) Protocol Official Specification. The following example only uses the required fields.

    For example:

    {
  "protocolVersion": "v1.0",
  "name": "Hello World Agent",
  "description": "Just a hello world agent",
  "url": "https://example.com/myagent",
  "iconUrl": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOTkiIGhlaWdodD0iOTkiIHN0eWxlPSJiYWNrZ3JvdW5kLWNvbG9yOmdyYXk7IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik0zMyAwaDMzdjMzSDMzeiBNMCAzM2gzM3YzM0gweiBNNjYgMzNoMzN2MzNINjZ6IE0zMyA2NmgzM3YzM0gzM3oiIGZpbGw9ImJsdWUiLz48L3N2Zz4=",
  "version": "1.0.0",
  "capabilities": {
  },
  "skills": [
    {
      "id": "data-analysis",
      "name": "Data Analysis",
      "description": "Data analysis",
      "tags": []
    }
  ],
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain"
  ]
}

  6. Click Import Agent > Next.

  7. Enter the Authorization details and click Finish.

REST

To create and register an agent with Gemini Enterprise, use the agents.create method. The following command uses only the required fields. For a complete list of available fields, see the Agent2Agent (A2A) Protocol Official Specification.

Run this command to register your A2A agent with Gemini Enterprise:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents \
-d '
{
  "name": "AGENT_NAME",
  "displayName": "AGENT_DISPLAY_NAME",
  "description": "AGENT_DESCRIPTION",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"name\":\"AGENT_NAME\",\"description\":\"AGENT_DESCRIPTION\",\"url\":\"AGENT_URL\",\"version\":\"AGENT_VERSION\",\"defaultInputModes\":[\"INPUT_MODE\"],\"defaultOutputModes\":[\"OUTPUT_MODE\"],\"capabilities\":{ CAPABILITIES },\"skills\":[SKILLS]}"
  }
}
'

Replace the following:

  • ENDPOINT_LOCATION: the multi-region for your API request. Assign one of the following values:
    • us- for the US multi-region
    • eu- for the EU multi-region
    • global- for the Global location
    For more information, see Specify a multi-region for your data store.
  • LOCATION: the multi-region of your data store: global, us, or eu
  • PROJECT_NUMBER: the number of your Google Cloud project.
  • APP_ID: the ID of the app with which you want to register the agent.
  • AGENT_NAME: the unique identifier for the agent.
  • AGENT_DISPLAY_NAME: the name of the agent that is displayed on the web app.
  • AGENT_DESCRIPTION: the description of what the agent can do.
  • AGENT_URL: the endpoint URL of the agent.
  • AGENT_VERSION: the version of the agent.
  • INPUT_MODE: the default input media type. For example, application/json or text/plain.
  • OUTPUT_MODE: the default output media type. For example, text/plain" or image/png.
  • CAPABILITIES: a JSON object containing supported A2A features. For example, \"streaming\": true or \"pushNotifications\": false.
  • SKILLS: a list of the AgentSkill object that the agent offers.

If you obtained the authorization details and want the agent to access Google Cloud resources on behalf of the user, add the authorization_config field to your JSON resource as follows:

"authorization_config"{
    "agent_authorization": "projects/PROJECT_NUMBER/locations/LOCATION/authorizations/AUTH_ID"
}

Replace AUTH_ID with the value that you used for AUTH_ID in the Add an authorization resource to Gemini Enterprise section.

Next steps

  • Use the agent that you registered with Gemini Enterprise on the web app.