Set up the environment

Before you work with Agent Engine, you need to make sure your environment is set up. You need to have a Google Cloud project with billing enabled, have the required permissions, set up a Cloud Storage bucket, and install the Vertex AI SDK for Python. Use the following topics to ensure ready to start working with Agent Engine.

For a reference Terraform example to streamline Agent Engine environment setup and deployment, consider exploring the agent-starter-pack.

Set up your Google Cloud project

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Vertex AI and Cloud Storage APIs.

   Enable the APIs

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the Vertex AI and Cloud Storage APIs.

   Enable the APIs

Note: To enable APIs, you need the serviceusage.services.enable permission. If you don't have this permission, ask your administrator to grant you the Service Usage Admin (roles/serviceusage.serviceUsageAdmin) role.

Get the required roles

To get the permissions that you need to use Agent Engine, ask your administrator to grant you the following IAM roles on your project:

• Vertex AI User (roles/aiplatform.user)
• Storage Admin (roles/storage.admin)

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Set up your service agent permissions

Agents that you deploy on Agent Engine run using the AI Platform Reasoning Engine Service Agent service account. This account has a Vertex AI Reasoning Engine Service Agent role that grants the default permissions required for deployed agents. You can view the full list of default permissions in the IAM documentation.

If you need additional permissions, you can grant this Service Agent additional roles by performing the following steps:

1. Go to the IAM page and check the "Include Google-provided role grants" checkbox.

   Go to IAM

2. Find the principal which matches [e-mail].

3. Add the required roles to the principal by clicking the edit button and then the save button.

Manually Generate a Service Agent

While the Reasoning Engine Service Agent is automatically provisioned during Agent Engine deployment, there might be scenarios where you need to manually generate it beforehand. This is particularly important when you need to grant specific roles to the service agent to ensure the deployment process has the necessary permissions and avoid potential deployment failures.

Here are the steps to manually generate a Reasoning Engine Service Agent:

1. Generate the Reasoning Engine Service Agent using the Google Cloud CLI.

   gcloud beta services identity create --service=aiplatform.googleapis.com --project=PROJECT-ID-OR-PROJECT-NUMBER

   Note: The response to the Google Cloud CLI command might display only the Vertex AI Service Agent. However, the Reasoning Engine Service Agent is also created.

2. Go to the IAM page and click Grant Access.

   Go to IAM

3. In Add principals section, in the New principals field, enter [e-mail].

4. In the Assign roles section, find and select the roles you need.

5. Click the Save button.

Create a Cloud Storage bucket

Agent Engine stages the artifacts of your deployed agents in a Cloud Storage bucket as part of the deployment process. Make sure the principal that is authenticated to use Vertex AI (either yourself or a service account) has Storage Admin access to this bucket. This is needed because Vertex AI SDK for Python writes your code to this bucket.

If you already have a bucket set up, you can skip this step. Otherwise, you can follow the standard instructions for creating a bucket.

Google Cloud console

1. In the Google Cloud console, go to the Cloud Storage Buckets page.

   Go to Buckets page

2. Click Create bucket.
3. On the Create a bucket page, enter your bucket information. To go to the next step, click Continue.
   • For Name your bucket, enter a name that meets the bucket naming requirements.
   • For Choose where to store your data, do the following:
     • Select a Location type option.
     • Select a Location option.
   • For Choose a default storage class for your data, select a storage class.
   • For Choose how to control access to objects, select an Access control option.
   • For Advanced settings (optional), specify an encryption method, a retention policy, or bucket labels.
4. Click Create.

Command line

Create a Cloud Storage bucket and configure it as follows:
• Replace STORAGE_CLASS with your preferred storage class.
• Replace LOCATION with your preferred location (ASIA, EU, or US)
• Replace BUCKET_NAME with a bucket name that meets the bucket name requirements.

gcloud storage buckets create gs://BUCKET_NAME --default-storage-class STORAGE_CLASS --location LOCATION

Install and initialize the Vertex AI SDK for Python

This section presumes that you have set up a Python development environment, or are using Colab (or any other suitable runtime that has set it up for you).

(Optional) Set up a virtual environment

We also recommend setting up a virtual environment to isolate your dependencies.

Installation

To minimize the set of dependencies that you have to install, we have separated out the dependencies into:

• agent_engines: the set of packages required for deployment to Agent Engine.
• langchain: the set of compatible LangChain packages.
• langgraph: the set of compatible LangGraph packages.

When installing the Vertex AI SDK for Python, you can specify the dependencies required (separated by commas). To install all of them:

pip install google-cloud-aiplatform[agent_engines,langchain,langgraph]

Authentication

Colab

Run the following code:

from google.colab import auth

auth.authenticate_user()

Cloud Shell

No action required.

Local Shell

Run the following command:

gcloud auth application-default login

Import and initialize the SDK

Run the following code to import and initialize the SDK for Agent Engine:

import vertexai
from vertexai import agent_engines

vertexai.init(
    project="PROJECT_ID",
    location="LOCATION",
    staging_bucket="gs://BUCKET_NAME",
)

• PROJECT_ID: Your project ID.
• LOCATION: Your cloud region.
• BUCKET_NAME: Your Google Cloud bucket.

What's next

• Develop an agent