Skip to content

Deploy to Vertex AI Agent Engine

Supported in ADKPython

This deployment procedure describes how to perform a standard deployment of ADK agent code to Google Cloud Agent Engine. You should follow this deployment path if you have an existing Google Cloud project and if you want to carefully manage deploying an ADK agent to Agent Engine runtime environment. These instructions use Cloud Console, the gcloud command line interface, and the ADK command line interface (ADK CLI). This path is recommended for users who are already familiar with configuring Google Cloud projects, and users preparing for production deployments.

These instructions describe how to deploy an ADK project to Google Cloud Agent Engine runtime environment, which includes the following stages:

Setup Google Cloud project

To deploy your agent to Agent Engine, you need a Google Cloud project:

  1. Sign into Google Cloud:

    • If you're an existing user of Google Cloud:
    • If you are a new user of Google Cloud:
      • You can sign up for the Free Trial program. The Free Trial gets you a $300 Welcome credit to spend over 91 days on various Google Cloud products and you won't be billed. During the Free Trial, you also get access to the Google Cloud Free Tier, which gives you free usage of select products up to specified monthly limits, and to product-specific free trials.

  2. Create a Google Cloud project

    • If you already have an existing Google Cloud project, you can use it, but be aware this process is likely to add new services to the project.
    • If you want to create a new Google Cloud project, you can create a new one on the Create Project page.

  3. Get your Google Cloud Project ID

    • You need your Google Cloud Project ID, which you can find on your GCP homepage. Make sure to note the Project ID (alphanumeric with hyphens), not the project number (numeric).

    Google Cloud Project ID

  4. Enable Vertex AI in your project

    • To use Agent Engine, you need to enable the Vertex AI API. Click on the "Enable" button to enable the API. Once enabled, it should say "API Enabled".

  5. Enable Cloud Resource Manager API in your project

  6. Create a Google Cloud Storage (GCS) Bucket:

    • Agent Engine requires a GCS bucket to stage your agent's code and dependencies for deployment. If you already have a GCS bucket, you should create a new one specifically for deployment use.
    • Create a GCS bucket by following the instructions. You should start with the default settings when creating your first bucket.
    • Once you have created a storage bucket, you should be able to see it on the Cloud Storage Buckets page.
    • You need the GCS bucket path to set as your staging bucket. For example, if your GCS bucket name is "my-bucket", then your bucket path should be "gs://my-bucket".
Deploy without a GCS bucket

You can avoid using a Google Cloud Storage bucket for deployment using a different configuration method. For details on this method, see Deploy an Agent in the Agent Engine documentation.

Set up your coding environment

Now that you prepared your Google Cloud project, you can return to your coding environment. These steps require access to a terminal within your coding environment to run command line instructions.

Authenticate your coding environment with Google Cloud

  • You need to authenticate your coding environment so that you and your code can interact with Google Cloud. To do so, you need the gcloud CLI. If you have never used the gcloud CLI, you need to first download and install it before continuing with the steps below:

  • Run the following command in your terminal to access your Google Cloud project as a user:

    gcloud auth login

    After authenticating, you should see the message You are now authenticated with the gcloud CLI!.

  • Run the following command to authenticate your code so that it can work with Google Cloud:

    gcloud auth application-default login

    After authenticating, you should see the message You are now authenticated with the gcloud CLI!.

  • (Optional) If you need to set or change your default project in gcloud, you can use:

    gcloud config set project MY-PROJECT-ID

Define your agent

With your Google Cloud and coding environment prepared, you're ready to deploy your agent. The instructions assume that you have an agent project folder, such as:

multi_tool_agent/
├── .env
├── __init__.py
└── agent.py

For more details on the project files and format, see the multi_tool_agent code sample.

Deploy the agent

You can deploy from your terminal using the adk deploy command line tool. This process packages your code, builds it into a container, and deploys it to the managed Agent Engine service. This process can take several minutes.

The following example deploy command uses the multi_tool_agent sample code as the project to be deployed:

PROJECT_ID=my-project-id
LOCATION_ID=us-central1
GCS_BUCKET=gs://MY-CLOUD-STORAGE-BUCKET

adk deploy agent_engine \
        --project=$PROJECT_ID \
        --region=$LOCATION_ID \
        --staging_bucket=$GCS_BUCKET \
        --display_name="My First Agent" \
        multi_tool_agent

For region, you can find a list of the supported regions on the Vertex AI Agent Builder locations page. To learn about the CLI options for the adk deploy agent_engine command, see the ADK CLI Reference.

Deploy command output

Once successfully deployed, you should see the following output:

Creating AgentEngine
Create AgentEngine backing LRO: projects/123456789/locations/us-central1/reasoningEngines/751619551677906944/operations/2356952072064073728
View progress and logs at https://console.cloud.google.com/logs/query?project=hopeful-sunset-478017-q0
AgentEngine created. Resource name: projects/123456789/locations/us-central1/reasoningEngines/751619551677906944
To use this AgentEngine in another session:
agent_engine = vertexai.agent_engines.get('projects/123456789/locations/us-central1/reasoningEngines/751619551677906944')
Cleaning up the temp folder: /var/folders/k5/pv70z5m92s30k0n7hfkxszfr00mz24/T/agent_engine_deploy_src/20251219_134245

Note that you now have a RESOURCE_ID where your agent has been deployed (which in the example above is 751619551677906944). You need this ID number along with the other values to use your agent on Agent Engine.

Using an agent on Agent Engine

Once you have completed deployment of your ADK project, you can query the agent using the Vertex AI SDK, Python requests library, or a REST API client. This section provides some information on what you need to interact with your agent and how to construct URLs to interact with your agent's REST API.

To interact with your agent on Agent Engine, you need the following:

  • PROJECT_ID (example: "my-project-id") which you can find on your project details page
  • LOCATION_ID (example: "us-central1"), that you used to deploy your agent
  • RESOURCE_ID (example: "751619551677906944"), which you can find on the Agent Engine UI

The query URL structure is as follows:

https://$(LOCATION_ID)-aiplatform.googleapis.com/v1/projects/$(PROJECT_ID)/locations/$(LOCATION_ID)/reasoningEngines/$(RESOURCE_ID):query

You can make requests from your agent using this URL structure. For more information on how to make requests, see the instructions in the Agent Engine documentation Use an Agent Development Kit agent. You can also check the Agent Engine documentation to learn about how to manage your deployed agent. For more information on testing and interacting with a deployed agent, see Test deployed agents in Agent Engine.

Monitoring and verification

Test deployed agents

After completing deployment of your ADK agent you should test the workflow in its new hosted environment. For more information on testing an ADK agent deployed to Agent Engine, see Test deployed agents in Agent Engine.