To deploy an agent on Agent Engine:
- (Optional) Define the package requirements
- (Optional) Define the source files
- (Optional) Organize the Cloud Storage directory
- (Optional) Define the resource metadata
- Create an
AgentEngine
instance
Before you begin
Before you deploy an agent, make sure you have completed the following tasks:
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 application 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,
- 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.
- The bundle is uploaded to Cloud Storage (under the corresponding sub-bucket) for staging the artifacts.
- The Cloud Storage URIs for the respective artifacts are specified in the PackageSpec.
- The 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.
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
Best Practices
- Pin your package versions (for reproducible builds). Common packages to keep
track of include:
google-cloud-aiplatform
,cloudpickle
,langchain
,langchain-core
,langchain-google-vertexai
, andpydantic
. - Minimize the number of dependencies in your application. This reduces the number of breaking changes when updating your dependencies and makes it easier to update your application 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