Register and manage ADK agents hosted on Vertex AI Agent Engine

This page describes how Gemini Enterprise admins can register Agent Development Kit (ADK) agents hosted on Vertex AI Agent Engine so they can be made available to users on the Gemini Enterprise web app.

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 ADK agent that is hosted on the Vertex AI Agent Engine. For more information, see Overview of Agent Development Kit.

Configure authorization details

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.

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

Go to Credentials
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.
Click Create credentials and select OAuth client ID.
In Application type, select Web application.
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
Click Create.
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 ADK agent with Gemini Enterprise

You can register your ADK 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 ADK agent using the Google Cloud console, follow these steps:

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

Gemini Enterprise
Click the name of the app that you want to register the agent with.
Click Agents > Add Agents.
In the Choose an agent type section, click Add for Custom agent via Agent Engine.
If you want the agent to access Google Cloud resources on behalf of you, follow these steps:
1. Click Add authorization.
2. Enter a unique value for Authorization name. An ID is generated based on the name and it cannot be changed later.
3. Enter the Client ID, Client secret, Authorization URI, and Token URI you generated in the Obtain authorization details section.
4. Click Add authorization.
Click Next.
To configure your agent, follow these steps:
1. Enter a name in the Agent name field. This value appears in the Gemini Enterprise web app as the display name of your agent.
2. Enter a description in the Describe your agent field. This value is used by an LLM to determine whether to invoke your agent in response to a user query.
3. Enter the Agent Engine reasoning engine resource path. The resource path has the following format:
```
    https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/ADK_RESOURCE_ID
 
```
  For more information on how to list the agents hosted on Vertex AI Agent Engine and get the resource path, see List deployed agents.
4. Configure the Tool settings:
  1. Enter a description for the Tool description field. This description is used by the LLM to understand the tool's purpose and to decide when to use it.
  2. Enter the name in the Input parameter name field. This is the parameter name for the function call. This parameter name hints to the LLM about the expected type of input, such as a question, command, or search_query.
  3. Enter the description for the Input parameter description field. This parameter description provides the LLM with more information about the parameter, such as the expected content and the actions to be performed.
5. Click Create.

REST

This code sample demonstrates how you can register your ADK agents.

   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/global/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents" \
      -d '{
         "displayName": "DISPLAY_NAME",
         "description": "DESCRIPTION",
         "icon": {
            "uri": "ICON_URI"
      },
      "adk_agent_definition": {
         "provisioned_reasoning_engine": {
            "reasoning_engine":
            "projects/PROJECT_ID/locations/REASONING_ENGINE_LOCATION/reasoningEngines/ADK_RESOURCE_ID"
         }
      },
   "authorization_config": {


   "tool_authorizations": [
   "projects/PROJECT_ID/locations/global/authorizations/AUTH_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.
APP_ID: the unique identifier for the Gemini Enterprise app.
DESCRIPTION : the description of the agent that's displayed in Gemini Enterprise.
ICON_URI: the public URI of the icon to display near the name of the agent. Alternatively, you can pass Base64-encoded image file contents, and in that case, use icon.content.
ADK_RESOURCE_ID: the ID of the reasoning engine endpoint where the ADK agent is deployed. For more information on how to list the agents hosted on Vertex AI Agent Engine and get the resource ID, see List deployed agents.
REASONING_ENGINE_LOCATION: the cloud location of the reasoning engine. For more information, see Reasoning engine location.
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.
```
 * <code><var>AUTH_ID</var></code>: the value that you used for
    <var>AUTH_ID</var> in the [Configure authorization details](#authorize-your-adk-agent)
    section.
```

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",
...
}

View the details of an ADK 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.

Update an ADK agent

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

Console

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

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

Gemini Enterprise
Click the name of the app that includes the agent you want to update.
Click Agents.
Click the name of the Agent engine agent that you want to update, and then click Edit.
Update the Display name, Description, or the Agent Engine reasoning engine.

The resource path has the following format:
```
  https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/ADK_RESOURCE_ID
```
For more information on how to list the agents hosted on Vertex AI Agent Engine and get the resource path, see List deployed agents.
Click Save.

REST

You can update all fields during the agent registration. However, the following fields must be updated:

displayName
description

reasoningEngine

This code sample demonstrates how you can update the registration of an existing ADK agent:

curl -X PATCH \
   -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/AGENT_RESOURCE_NAME" \
   -d '{
         "displayName": "DISPLAY_NAME",
         "description": "DESCRIPTION",
         "adkAgentDefinition": {
         "provisionedReasoningEngine": {
            "reasoningEngine":
            "projects/PROJECT_ID/locations/REASONING_ENGINE_LOCATION/reasoningEngine
            s/ADK_RESOURCE_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.
AGENT_RESOURCE_NAME: the resource name of the agent registration to be updated.
DISPLAY_NAME: required. the user-friendly name for your agent that displays in Gemini Enterprise.
DESCRIPTION: required. A brief explanation of what your agent does that's visible to users in Gemini Enterprise.
REASONING_ENGINE_LOCATION: required. The cloud location of the reasoning engine that you're creating an agent at. For more information, see Reasoning engine location.
ADK_RESOURCE_ID: the ID of the reasoning engine endpoint where the ADK agent is deployed. For more information on how to list the agents hosted on Vertex AI Agent Engine and get the resource ID, see List deployed agents.

Delete an ADK 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
}

Reasoning engine location

To make your API call to the correct reasoning engine location, use the following chart:

Cloud location that you're calling	Reasoning engine location
`us`	`us-central1`
`eu`	`europe-west1`
others (including `global`)	`us-central1`

Register and manage ADK agents hosted on Vertex AI Agent Engine Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Configure authorization details

Obtain authorization details

Add an authorization resource to Gemini Enterprise

REST

Register an ADK agent with Gemini Enterprise

Console

REST

List agents connected to an app

REST

View the details of an ADK agent

REST

Update an ADK agent

Console

REST

Delete an ADK agent

REST

Example command and result

Reasoning engine location

Register and manage ADK agents hosted on Vertex AI Agent Engine