Register and manage A2A agents

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Agent-to-Agent (A2A) is an open communication protocol and a universal language for 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 and hosted on any platform to Gemini Enterprise, making them available to users in the Gemini Enterprise web app.

Tip: You must host and maintain your A2A agents for them to function within Gemini Enterprise.

Before you begin

Make sure you have the following:

• The Discovery Engine Admin role.

• Enable the Discovery Engine API. To enable the Discovery Engine API for the Google Cloud project, in the Google Cloud console, go to the Discovery Engine API page.

  Go to Discovery Engine API

• An existing Gemini Enterprise app. To create an app, see Create an app.

• An agent that uses the A2A protocol.

Configure authorization details

Note: This step is optional. OAuth authorization credentials are only required if the agent needs to access Google Cloud resources on behalf of a user.

Create OAuth 2.0 credentials for the agent to access Google Cloud resources, such as BigQuery tables, on a user's behalf.

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/locations/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 an A2A agent with Gemini Enterprise

You can register your A2A agent with Gemini Enterprise using either the Google Cloud console or the REST API. This makes the agent available to users within a Gemini Enterprise app.

Console

To register an A2A agent using the Google Cloud console, follow these steps:

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 Preview agent details > Next.

7. Complete the setup using one of the following methods:

   • If you want the agent to access Google Cloud resources on behalf of you, follow these steps:

     1. Enter Client ID, Client secret, Authorization URI, and Token URI you generated in the Obtain authorization details section.

     2. Enter the Scopes.

     3. Click Finish.

   • If you don't want the agent to access Google Cloud resources on behalf of you, click Skip & 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_ID/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": "{\"protocolVersion\":\"PROTOCOLVERSION\",\"name\":\"AGENT_NAME\",\"description\":\"AGENT_DESCRIPTION\",\"url\":\"AGENT_URL\",\"version\":\"AGENT_VERSION\",\"defaultInputModes\":[\"INPUT_MODE\"],\"defaultOutputModes\":[\"OUTPUT_MODE\"],\"capabilities\":{ CAPABILITIES },\"skills\":[SKILLS]}"
  },
  "authorizationConfig": {
    "agentAuthorization": "projects/PROJECT_ID/locations/LOCATION/authorizations/AUTH_ID"
  }
}
'

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_ID: the ID of your 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.
• PROTOCOLVERSION: the version of the A2A protocol the agent supports. For more information on the supported versions, see the A2A release notes.
• 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.
• authorizationConfig: 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.
  • AUTH_ID: the value that you used for AUTH_ID in the Add an authorization resource to Gemini Enterprise section.

Example command and result

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://global-discoveryengine.googleapis.com/v1alpha/projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents \
-d '
{
  "name": "Hello World Agent",
  "displayName": "Hello World Agent",
  "description": "Just a hello world agent",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"protocolVersion\":\"0.3.0\",\"name\":\"Hello World Agent\",\"description\":\"Just a hello world agent\",\"url\":\"https://example.com/myagent\",\"version\":\"1.0.0\",\"defaultInputModes\":[\"text\"],\"defaultOutputModes\":[\"text\"],\"capabilities\":{},\"skills\":[{\"description\":\"Chat with the Gemini agent.\",\"examples\":[\"Hello, world!\"],\"id\":\"chat\",\"name\":\"Chat Skill\",\"tags\":[\"chat\"]}]}"
  }
}
'

{
  "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
  "displayName": "Hello World Agent",
  "description": "Just a hello world agent",
  "createTime": "2025-10-20T20:53:35.490600996Z",
  "state": "ENABLED",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"protocolVersion\":\"0.3.0\",\"name\":\"Hello World Agent\",\"description\":\"Just a hello world agent\",\"url\":\"https://example.com/myagent\",\"version\":\"1.0.0\",\"capabilities\":{},\"defaultInputModes\":[\"text\"],\"defaultOutputModes\":[\"text\"],\"skills\":[{\"id\":\"chat\",\"name\":\"Chat Skill\",\"description\":\"Chat with the Gemini agent.\",\"tags\":[\"chat\"],\"examples\":[\"Hello, world!\"]}]}"
  }
}

List agents connected to an app

The following code sample demonstrates how you can get the details of all the agents connected to your app:

REST

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents"

Replace the variables with values:

• 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.
• PROJECT_ID: the ID of your Google Cloud project.
• LOCATION: the multi-region of your app: global, us, or eu.
• APP_ID: the ID of your Gemini Enterprise app.

If your agent isn't prebuilt by Google, the response includes a name field in the first few lines. The value of this field contains the Agent ID at the end of the path. For example, in the following response, the Agent ID is 12345678901234567890:

{
"name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
...
}

Example command and result

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents"

{
  "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
  "displayName": "Hello World Agent",
  "description": "Just a hello world agent",
  "createTime": "2025-10-20T20:53:35.490600996Z",
  "state": "ENABLED",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"name\":\"Hello World Agent\",\"description\":\"Just a hello world agent\",\"url\":\"https://example.com/myagent\",\"version\":\"1.0.0\",\"capabilities\":{},\"default_input_modes\":[\"text\"],\"default_output_modes\":[\"text\"],\"skills\":[{\"id\":\"chat\",\"name\":\"Chat Skill\",\"description\":\"Chat with the Gemini agent.\",\"tags\":[\"chat\"],\"examples\":[\"Hello, world!\"]}]}"
  }
}

View the details of an A2A agent

The following code sample demonstrates how you can retrieve the details of an agent that was registered with Gemini Enterprise:

REST

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

Replace the variables with values:

• 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.
• PROJECT_ID: the ID of your Google Cloud project.
• LOCATION: the multi-region of your app: global, us, or eu.
• APP_ID: the ID of your Gemini Enterprise app.
• AGENT_ID: The ID of the agent. You can find the agent ID by listing the agents connected to your app.

Example command and result

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://global-discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890"

{
  "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
  "displayName": "Hello World Agent",
  "description": "Just a hello world agent",
  "createTime": "2025-10-20T20:53:35.490600996Z",
  "state": "ENABLED",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"name\":\"Hello World Agent\",\"description\":\"Just a hello world agent\",\"url\":\"https://example.com/myagent\",\"version\":\"1.0.0\",\"capabilities\":{},\"default_input_modes\":[\"text\"],\"default_output_modes\":[\"text\"],\"skills\":[{\"id\":\"chat\",\"name\":\"Chat Skill\",\"description\":\"Chat with the Gemini agent.\",\"tags\":[\"chat\"],\"examples\":[\"Hello, world!\"]}]}"
  }
}

Update an A2A agent

You can modify the details of an existing A2A agent registered with Gemini Enterprise using either the Google Cloud console or the REST API.

Console

To update an A2A agent using the Google Cloud console, follow these steps:

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

   Gemini Enterprise

2. Click the name of the app that includes the agent you want to update.

3. Click Agents.

4. Click the name of the A2A (Custom) agent to update, and then click Edit.

5. In the Agent card JSON field, update 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": "v3.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.1.0",
     "capabilities": {
     },
     "skills": [
       {
         "id": "data-analysis",
         "name": "Data Analysis",
         "description": "Data analysis",
         "tags": []
       }
     ],
     "defaultInputModes": [
       "text/plain"
     ],
     "defaultOutputModes": [
       "text/plain"
     ]
   }
   

6. Click Save.

REST

To update details of an A2A agent that is registered with Gemini Enterprise, use the agents.patch 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 update your A2A agent with Gemini Enterprise:

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

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_ID: the ID of your project.
• APP_ID: the ID of the app that you want to register the agent.
• AGENT_ID: the ID of the agent. You can find the agent ID by listing the agents connected to your app.
• 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.
• PROTOCOLVERSION: the version of the A2A protocol that the agent supports. For more information on the supported versions, see the A2A release notes.
• 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.
• authorizationConfig: 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.
  • AUTH_ID: the value that you used for AUTH_ID in the Add an authorization resource to Gemini Enterprise section.

Example command and result

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://global-discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890 \
-d '
{
  "name": "Hello World Agent",
  "displayName": "Hello World Agent",
  "description": "Just a hello world agent",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"protocolVersion\":\"0.3.0\",\"name\":\"Hello World Agent\",\"description\":\"Just a hello world agent\",\"url\":\"https://example.com/myagent\",\"version\":\"1.1.0\",\"defaultInputModes\":[\"text\"],\"defaultOutputModes\":[\"text\"],\"capabilities\":{  },\"skills\":[{\"description\":\"Chat with the Gemini agent.\",\"examples\":[\"Hello, world!\"],\"id\":\"chat\",\"name\":\"Chat Skill\",\"tags\":[\"chat\"]}]}"
  }
}
'

{
  "name": "projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
  "displayName": "Hello World Agent",
  "description": "Just a hello world agent",
  "createTime": "2025-10-20T20:53:35.490600996Z",
  "state": "ENABLED",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"name\":\"Hello World Agent\",\"description\":\"Just a hello world agent\",\"url\":\"https://example.com/myagent\",\"version\":\"1.0.0\",\"capabilities\":{},\"defaultInputModes\":[\"text\"],\"defaultOutputModes\":[\"text\"],\"skills\":[{\"id\":\"chat\",\"name\":\"Chat Skill\",\"description\":\"Chat with the Gemini agent.\",\"tags\":[\"chat\"],\"examples\":[\"Hello, world!\"]}]}"
  }P
}

Delete an A2A agent

The following code sample demonstrates how you can delete an agent that is connected to your app:

REST

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

Replace the variables with values:

• 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.
• PROJECT_ID: the ID of your Google Cloud project.
• LOCATION: the multi-region of your app: global, us, or eu
• APP_ID: the ID of your Gemini Enterprise app.
• AGENT_ID: the ID of the agent. You can find the agent ID by listing the agents connected to your app.

Example command and result

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://global-discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890"

{
  "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890/operations/delete-agent-12345678901234567890",
  "done": true
}

What's next

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