Register and manage ADK agents hosted on Vertex AI Agent Engine

Console

To register an ADK 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. The Agentspage displays.

4. Click add Add agent. The Add an agentpanel displays.

5. Click Addfor Custom agent via Agent Engine. The Authorizationspage displays.

6. If you want the agent to access Google Cloud resources on your behalf, then each resource needs an authorization. To set up an authorization for a single resource, 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 can't be changed later.

   3. Enter the values that you generated in the Obtain authorization details section in the following fields:

      1. Enter the value in the Client IDfield.

      2. Enter the value in the Client secretfield.

      3. Enter the value in the Token URIfield.

      4. Enter the value in the Authorization URIfield. Construct the Authorization URI using the details from your OAuth credentials JSON file. Copy the following template, and replace the placeholders with your specific values.

         https://accounts.google.com/o/oauth2/v2/auth?client_id= YOUR_CLIENT_ID 
         &redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope= YOUR_CUSTOM_SCOPES 
         &include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent

      5. Click Done.

7. Click Next.

8. To configure your agent, follow these steps:

   1. Enter a name in the Agent namefield. This value appears in the Gemini Enterprise web app as the display name of your agent.

   2. Enter a description in the Describe your agentfield. This value is used by an LLM to determine whether to invoke your agent in response to a user query.

   3. Enter the Agent Engineresource path. The resource path has the following format:

      https:// LOCATION 
      -aiplatform.googleapis.com/v1/projects/ PROJECT_ID 
      /locations/ LOCATION 
      /reasoningEngines/ AGENT_ENGINE_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. Click Create.

REST

To register an ADK agent using the REST API, follow these steps:

• Add an authorization resource to Gemini Enterprise (optional)
• Register your ADK agent

Add the authorization resource to Gemini Enterprise (optional)

If the agent must access Google Cloud resources on behalf of a user, run the following command to register the authorization resource you created in the Configure authorization details (optional) section with Gemini Enterprise:

 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. Specify 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. To authorize your app, construct a specific Authorization URI using the details from your OAuth credentials JSON file. Copy the following template, and replace the placeholders with your specific values.

  https://accounts.google.com/o/oauth2/v2/auth?client_id= OAUTH_CLIENT_ID 
  &redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope= YOUR_CUSTOM_SCOPES 
  &include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent

  • YOUR_CUSTOM_SCOPES : you can add the scopes you need. For example, the following OAuth scope string requests read-only access to your Google Drive and Google Docs.

     scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdocuments.readonly 
    

• OAUTH_TOKEN_URI : the token URI you obtained when you created the OAuth credentials.

Register your ADK agent

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 
" 
 }, 
 "adkAgentDefinition": { 
 "provisionedReasoningEngine": { 
 "reasoningEngine": "projects/ PROJECT_ID 
/locations/ AGENT_ENGINE_LOCATION 
/reasoningEngines/ AGENT_ENGINE_ID 
" 
 } 
 }, 
 "authorizationConfig": { 
 "toolAuthorizations": [ 
 "projects/ PROJECT_NUMBER 
/locations/global/authorizations/ AUTH_ID 
" 
 ] 
 } 
 }' 
 

Replace the variables with values:

• ENDPOINT_LOCATION : the multi-region for your API request. Specify 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.

• PROJECT_NUMBER : the number 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 .

  • AGENT_ENGINE_ID : the ID of the Vertex AI Agent 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 .

  • AGENT_ENGINE_LOCATION : the cloud location of the Vertex AI Agent Engine endpoint. For more information, see Vertex AI Agent Engine location .

  • authorization_config : 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 Configure authorization details section.