Deploy an agent

Define the package requirements

Provide the set of packages required by the agent for deployment. The set of packages can either be a list of items to be installed by pip, or the path to a file that follows the Requirements File Format. Use the following best practices:

1. Pin your package versions for reproducible builds. Common packages to keep track of include the following: google-cloud-aiplatform, cloudpickle, langchain, langchain-core, langchain-google-vertexai, and pydantic.
2. Minimize the number of dependencies in your agent. This reduces the number of breaking changes when updating your dependencies and agent.

If the agent doesn't have any dependencies, you can set requirements to None:

requirements = None

If the agent uses a framework-specific template, you should specify the SDK version that is imported (such as 1.112.0) when developing the agent.

requirements = [ "google-cloud-aiplatform[agent_engines,adk]", # any other dependencies ]

requirements = [ "google-cloud-aiplatform[agent_engines]", "a2a-sdk>=0.3.4" # any other dependencies ]

requirements = [ "google-cloud-aiplatform[agent_engines,langchain]", # any other dependencies ]

requirements = [ "google-cloud-aiplatform[agent_engines,langgraph]", # any other dependencies ]

requirements = [ "google-cloud-aiplatform[agent_engines,ag2]", # any other dependencies ]

requirements = [ "google-cloud-aiplatform[agent_engines,llama_index]", # any other dependencies ]

You can also do the following with package requirements:

• Upper-bound or pin the version of a given package (such as google-cloud-aiplatform):

   requirements = [ # See https://pypi.org/project/google-cloud-aiplatform for the latest version. "google-cloud-aiplatform[agent_engines,adk]==1.112.0", ] 

• Add additional packages and constraints:

   requirements = [ "google-cloud-aiplatform[agent_engines,adk]==1.112.0", "cloudpickle==3.0", # new ] 

• Point to the version of a package on a GitHub branch or pull request:

   requirements = [ "google-cloud-aiplatform[agent_engines,adk] @ git+https://github.com/googleapis/python-aiplatform.git@BRANCH_NAME", # new ] 

• Maintain the list of requirements in a file (such as path/to/requirements.txt):

   requirements = "path/to/requirements.txt" 

  where path/to/requirements.txt is a text file that follows the Requirements File Format. For example:

   google-cloud-aiplatform[agent_engines,adk] cloudpickle==3.0 

Define additional packages

You can include local files or directories that contain local required Python source files. Compared to package requirements, this lets you use private utilities you have developed that aren't otherwise available on PyPI or GitHub.

If the agent does not require any extra packages, you can set extra_packages to None:

extra_packages = None

You can also do the following with extra_packages:

• Include a single file (such as agents/agent.py):

   extra_packages = ["agents/agent.py"] 

• Include the set of files in an entire directory (for example, agents/):

   extra_packages = ["agents"] # directory that includes agents/agent.py 

• Specify Python wheel binaries (for example, path/to/python_package.whl):

   requirements = [ "google-cloud-aiplatform[agent_engines,adk]", "cloudpickle==3.0", "python_package.whl", # install from the whl file that was uploaded ] extra_packages = ["path/to/python_package.whl"] # bundle the whl file for uploading 

Define environment variables

If there are environment variables that your agent depends on, you can specify them in the env_vars= argument. If the agent does not depend on any environment variables, you can set it to None:

env_vars = None

To specify the environment variables, there are a few different options available:

env_vars = { "VARIABLE_1": "VALUE_1", "VARIABLE_2": "VALUE_2", } # These environment variables will become available in Vertex AI Agent Engine # through `os.environ`, e.g. # # import os # os.environ["VARIABLE_1"] # will have the value "VALUE_1" # # and # # os.environ["VARIABLE_2"] # will have the value "VALUE_2" #

env_vars = { # ... (other environment variables and their values) "CLOUD_SQL_CREDENTIALS_SECRET": {"secret": SECRET_ID, "version": SECRET_VERSION_ID}, }

secret = os.environ.get("CLOUD_SQL_CREDENTIALS_SECRET") if secret: # Secrets are stored as strings, so use json.loads to parse JSON # payloads. return json.loads(secret)

env_vars = ["VARIABLE_1", "VARIABLE_2"] # This corresponds to the following code snippet: # # import os # # env_vars = { # "VARIABLE_1": os.environ["VARIABLE_1"], # "VARIABLE_2": os.environ["VARIABLE_2"], # }

You also need to follow the instructions in Set up the identity and permissions for your agent to grant your agent the Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) permission.

Define customized resource controls

You can specify runtime resource controls for the agent, such as the minimum and maximum number of application instances, resource limits for each container, and concurrency for each container.

• min_instances: The minimum number of application instances to keep running at all times, with a range of [0, 10]. The default value is 1.

• max_instances: The maximum number of application instances that can be launched to handle increased traffic, with a range of [1, 1000]. The default value is 100. If VPC-SC or PSC-I is enabled, the acceptable range is [1, 100].

• resource_limits: Resource limits for each container. Only cpu and memory keys are supported. The default value is {"cpu": "4", "memory": "4Gi"}.

  • The only supported values for cpu are 1, 2, 4, 6 and 8. For more information, see Configure CPU allocation.

  • The only supported values for memory are 1Gi, 2Gi, ... 32Gi.

  • For required CPU on different memory values, see Configure memory limits.

• container_concurrency: Concurrency for each container and agent server. The recommended value is 2 * cpu + 1. The default value is 9.

remote_agent = client.agent_engines.create( agent=local_agent, config={ "min_instances": 1, "max_instances": 10, "resource_limits": {"cpu": "4", "memory": "8Gi"}, "container_concurrency": 9, # ... other configs } )

For best practices on how to optimize runtime resources, see Optimize and scale Vertex AI Agent Engine Runtime.

Define build options

You can specify build options for the agent, such as installation scripts to run when building the agent's container image. This is useful for installing system dependencies (for example, gcloud cli, npx) or other custom setups. The scripts are run with root permissions.

To use installation scripts, create a directory named installation_scripts and place your shell scripts inside the directory:

 . ├── ... └── installation_scripts/ └── install.sh 

Next, specify the installation_scripts directory in extra_packages and the script paths in build_options:

extra_packages = [..., "installation_scripts/install.sh"] build_options = {"installation_scripts": ["installation_scripts/install.sh"]}

You can use one of the following common installation scripts:

#!/bin/bash # Exit immediately if a command exits with a non-zero status. set -e echo "--- Installing System-Wide Node.js v20.x ---" # 1. Install prerequisites apt-get update apt-get install -y ca-certificates curl gnupg # 2. Add the NodeSource repository GPG key mkdir -p /etc/apt/keyrings curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg # 3. Add the NodeSource repository for Node.js v20 NODE_MAJOR=20 echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list # 4. Update package lists again and install Node.js apt-get update apt-get install nodejs -y echo "--- System-wide Node.js installation complete ---" echo "Verifying versions:" # These commands will now work for ANY user because node and npx # are installed in /usr/bin/ which is in everyone's default PATH. node -v npm -v npx -v

#!/bin/bash # Exit immediately if a command exits with a non-zero status. set -e echo "Starting setup..." # Install uv apt-get update apt-get install -y curl curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR="/usr/local/bin" sh # These commands will now work for ANY user because uv and uvx # are installed in /usr/local/bin/ which is in everyone's default PATH. uv --version uvx --version

#!/bin/bash # Exit immediately if a command exits with a non-zero status. set -e apt-get install -y curl gpg curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | tee -a /etc/apt/sources.list.d/google-cloud-sdk.list apt-get update -y && apt-get install google-cloud-cli -y gcloud --version

Define the agent framework

You can specify the agent framework that your agent uses:

agent_framework = "google-adk"

The following are the supported values:

• google-adk
• langchain
• langgraph
• ag2
• llama-index
• custom

If agent_framework isn't specified, the value is auto-detected if you are deploying from an agent object. If you are deploying from source files, agent_framework defaults to `custom`.

Define a Cloud Storage folder

Staging artifacts are overwritten if they correspond to an existing folder in a Cloud Storage bucket. If necessary, you can specify the Cloud Storage folder for the staging artifacts. You can set gcs_dir_name to None if you don't mind potentially overwriting the files in the default folder:

gcs_dir_name = None

To avoid overwriting the files (such as for different environments such as development, staging, and production), you can set up corresponding folder, and specify the folder to stage the artifact under:

gcs_dir_name = "dev" # or "staging" or "prod"

If you want or need to avoid collisions, you can generate a random uuid:

import uuid gcs_dir_name = str(uuid.uuid4())

Define the display name

You can set the display name for the ReasoningEngine resource:

display_name = "Currency Exchange Rate Agent (Staging)"

Define the description

You can set the description of the ReasoningEngine resource:

description = """ An agent that has access to tools for looking up the exchange rate. If you run into any issues, please contact the dev team. """

Define the labels

You can set the labels of the ReasoningEngine resource as a dictionary of key-value string pairs. The following is an example:

labels = {"author": "username", "version": "latest"}

Configure a default agent identity

You can provision agents you deploy to Vertex AI Agent Engine with a unique identity upon creating your agent. The identity is tied to the Vertex AI Agent Engine's agent resource ID and is independent of the agent framework you used to develop the agent:

identity_type=AGENT_IDENTITY

For more information, see Create an agent with agent identity.

Configure a custom service account

You can configure a custom service account as the identity of your deployed agent, instead of the agent identity or default identity.

To do so, specify the email of your custom service account as the service_account when creating or updating the Agent Engine instance, for example:

# Create a new instance client.agent_engines.create( agent=local_agent, config={ "service_account": "my-custom-service-account@my-project.iam.gserviceaccount.com", # ... }, ) # Update an existing instance resource_name = "projects/{project_id}/locations/{location}/reasoningEngines/{reasoning_engine_id}" client.agent_engines.update( name=resource_name, agent=local_agent, config={ "service_account": "my-new-custom-service-account@my-project.iam.gserviceaccount.com", # ... }, )

Configure Private Service Connect interface

If you have Private Service Connect interface and DNS peering set up, you can specify your network attachment and private DNS peering while deploying your agent:

remote_agent = client.agent_engines.create( agent=local_agent, config={ "psc_interface_config": { "network_attachment": "NETWORK_ATTACHMENT", "dns_peering_configs": [ { "domain": "DOMAIN_SUFFIX", "target_project": "TARGET_PROJECT", "target_network": "TARGET_NETWORK", }, ], }, }, )

where

• NETWORK_ATTACHMENT is the name or full path of your network attachment. If the network attachment is created in a project (such as the Shared VPC host project) different from where you use Agent Engine, you need to pass the full path of your network attachment.
• DOMAIN_SUFFIX is the DNS name of the private Cloud DNS zone that you created when setting up the private DNS Peering.
• TARGET_PROJECT is the project that hosts the VPC network. It can be different from the Network Attachment project.
• TARGET_NETWORK is the VPC network name.

You can configure multiple agents to use either a single, shared network attachment or unique, dedicated network attachments. To use a shared network attachment, provide the same network attachment in the psc_interface_config for each agent you create.

Configure customer-managed encryption keys

You can use a custom key to encrypt your agent's data at rest. See Agent Engine Customer-managed encryption keys (CMEK) for more details.

To configure the custom key (CMEK) for your agent, you need to provide the key resource name to the encryption_spec parameter when creating the Agent Engine instance.

# The fully qualified key name kms_key_name = "projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME" remote_agent = client.agent_engines.create( agent=local_agent, config={ "encryption_spec": {"kms_key_name": kms_key_name}, # ... other parameters }, )