Deploy an agent

To deploy an agent on Vertex AI Agent Engine:

  1. (Optional) Define the package requirements
  2. (Optional) Define the source files
  3. (Optional) Organize the Cloud Storage directory
  4. (Optional) Define the resource metadata
  5. Create an AgentEngine instance

Before you begin

Before you deploy an agent, make sure you have completed the following tasks:

  1. Set up your environment.
  2. Develop an agent.

Step 1: Define the package requirements

Provide the set of packages required by the agent for it to be deployed. It can either be a list of items to be installed by pip, or the path to a file that follows the Requirements File Format.

If the agent does not have any dependencies, you can set it to None:

requirements = None

If the agent uses a framework-specific template, you should specify the SDK version that is imported (e.g. 1.77.0) when developing the agent.

LangChain 

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

LangGraph 

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

[Optional] Version constraints

If you want or need to upper-bound or pin the version of a given package (e.g. google-cloud-aiplatform):

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

You can add additional packages and constraints to the list:

requirements = [
    "google-cloud-aiplatform[agent,langgraph]==1.75.0",
    "cloudpickle==3.0", # new
]

[Optional] Developmental Branch

You can point to the version of a package that is on a GitHub branch or pull request, for example:

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

[Optional] Requirements File Format

You can maintain the list of requirements in a file (e.g. 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,langchain]
cloudpickle==3.0

Step 2: Extra packages

You can include local files or directories that contain local Python source files required. Compared to package requirements, this will allow you to use private utilities you have developed that are not otherwise available on PyPI or GitHub.

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

extra_packages = None

[Optional] Files and directories

To include a single file (e.g. agents/agent.py), you can add it to the list:

extra_packages = ["agents/agent.py"]

To include the set of files in an entire directory (e.g. agents/), you can specify the directory:

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

[Optional] Wheel binaries

You can include Python wheel binaries (e.g. path/to/python_package.whl) and specify them in the package requirements:

requirements = [
    "google-cloud-aiplatform[agent,langgraph]",
    "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

Step 3: Cloud Storage directory

The staging artifacts will be overwritten if they correspond to an existing sub-bucket (a folder in a Cloud Storage bucket). If necessary, you can specify the subbucket for the staging artifacts. This step is optional, and you can set it to None if you don't mind potentially overwriting the files in the default sub-bucket:

gcs_dir_name = None

To avoid overwriting the files (e.g. for different environments such as dev, staging, prod), you can set up the corresponding sub-buckets, and specify the sub-bucket to stage the artifact under, such as:

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

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

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

Step 4: Resource metadata

You can set metadata on the ReasoningEngine resource that gets created in Vertex AI, for example:

display_name = "Currency Exchange Rate Agent (Staging)"

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

For a full set of the parameters, visit the API reference.

Step 5: Create an AgentEngine instance

To deploy the agent on Vertex AI, use agent_engines.create and pass in the object as a parameter:

remote_agent = agent_engines.create(
    local_agent,                    # Required.
    requirements=requirements,      # Optional.
    extra_packages=extra_packages,  # Optional.
    gcs_dir_name=gcs_dir_name,      # Optional.
    display_name=display_name,      # Optional.
    description=description,        # Optional.
)

Deployment takes a few minutes to run. When deploying the agent,

  1. A bundle of artifacts is generated locally, comprising:
    • *.pkl a pickle file corresponding to local_agent.
    • requirements.txt a text file containing the package requirements.
    • dependencies.tar.gz a tar file containing any extra packages.
  2. The bundle is uploaded to Cloud Storage (under the corresponding sub-bucket) for staging the artifacts.
  3. The Cloud Storage URIs for the respective artifacts are specified in the PackageSpec.
  4. The Vertex AI Agent Engine service receives the request and builds containers and turns up HTTP servers on the backend.

Deployment latency is dependent on the total time it takes to install the required packages. Once deployed, remote_agent corresponds to an instance of local_agent that is running on Vertex AI and can be queried or deleted. It is separate from local instances of the agent.

Resource Identifier

Each deployed agent has a unique identifier. You can run the following command to get the resource_name identifier for your deployed agent:

remote_agent.resource_name

It will be a string of the format:

"projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/RESOURCE_ID"

where

  • PROJECT_ID is the Google Cloud project ID under which the deployed agent will run,
  • LOCATION is the region under which the deployed agent will run, and
  • RESOURCE_ID is the ID of the deployed agent as a reasoningEngine resource.

Best Practices

  1. Pin your package versions (for reproducible builds). Common packages to keep track of include: 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 makes it easier to update your agent over time for newer features.

Deploy in Production with Agent Starter Pack

The Agent Starter Pack is a collection of production-ready generative AI agent templates built for Vertex AI Agent Engine. It accelerates deployment by providing:

  • Pre-built Agent Templates: ReAct, RAG, multi-agent, and more.
  • Interactive Playground: Test and interact with your agent.
  • Automated Infrastructure: Uses Terraform for streamlined resource management.
  • CI/CD Pipelines: Automated deployment workflows leveraging Cloud Build.
  • Observability: Includes built-in support for Cloud Trace and Cloud Logging.

Get Started: Quickstart

What's next