Agent Engine migration guide

In version v1.112.0 of the Vertex AI SDK, the agent_engines module within the Vertex AI SDK for Python was refactored to a client-based design.

The page describes the key changes to the module and how to migrate your existing code to the client based design.

For general information about Agent Engine, see Overview.

Key changes

At a high level, service client parameters are initialized on a per-client basis, and the client contains the relevant modules for service interactions.

Namely,

import vertexai
from vertexai import agent_engines

vertexai.init(project=GCP_PROJECT, location=GCP_REGION)
agent_engines.create(...)

is replaced by

import vertexai

client = vertexai.Client(project=GCP_PROJECT, location=GCP_REGION)
client.agent_engines.create(...)

The following namespaces for Vertex AI Agent Engine in the Vertex AI SDK are in the deprecation phase. Use the equivalent namespaces from the client-based Vertex AI SDK, which has full feature parity with the deprecated modules and packages.

Vertex AI SDK namespace	Impacted code	Client-based Vertex AI SDK replacement
vertexai.agent_engines	Impacted methods: vertexai.agent_engines.create vertexai.agent_engines.get vertexai.agent_engines.list vertexai.agent_engines.update vertexai.agent_engines.delete	Replacement: client.agent_engines.create client.agent_engines.get client.agent_engines.list client.agent_engines.update client.agent_engines.delete
client.agent_engines	Impacted methods: client.agent_engines.create_memory client.agent_engines.delete_memory client.agent_engines.generate_memories client.agent_engines.get_memory client.agent_engines.list_memories client.agent_engines.retrieve_memories client.agent_engines.create_session client.agent_engines.delete_session client.agent_engines.get_session client.agent_engines.list_sessions client.agent_engines.append_session_event client.agent_engines.list_session_events	Replacement: client.agent_engines.memories.create client.agent_engines.memories.delete client.agent_engines.memories.generate client.agent_engines.memories.get client.agent_engines.memories.list client.agent_engines.memories.retrieve client.agent_engines.sessions.create client.agent_engines.sessions.delete client.agent_engines.sessions.get client.agent_engines.sessions.list client.agent_engines.sessions.events.append client.agent_engines.sessions.events.list

Migrate to the client-based design

This section contains code snippets that demonstrate how to migrate your existing Agent Engine code to the client-based design.

Note: The examples may omit imports, dependencies, and other boilerplate code to improve readability.

Creating an Agent Engine instance

Before

import vertexai
from vertexai import agent_engines

vertexai.init(
  project=PROJECT,
  location=LOCATION,
  staging_bucket=STAGING_BUCKET,
)
agent_engines.create(
    local_agent,
    requirements=REQUIREMENTS,
    extra_packages=EXTRA_PACKAGES,
    # ...
)

After

import vertexai

client = vertexai.Client(
  project=PROJECT,
  location=LOCATION,
)
client.agent_engines.create(
    agent=local_agent,
    config={
        "staging_bucket": STAGING_BUCKET,
        "requirements": REQUIREMENTS,
        "extra_packages": EXTRA_PACKAGES,
        # ...
    },
)

Updating an Agent Engine instance

Before

import vertexai
from vertexai import agent_engines

vertexai.init(
  project=PROJECT,
  location=LOCATION,
  staging_bucket=STAGING_BUCKET,
)
agent_engines.update(
    resource_name,
    agent_engine=local_agent,
    requirements=REQUIREMENTS,
    extra_packages=EXTRA_PACKAGES,
    # ...
)

After

import vertexai

client = vertexai.Client(
  project=PROJECT,
  location=LOCATION,
)
client.agent_engines.update(
    name=resource_name,
    agent=local_agent,
    config={
        "staging_bucket": STAGING_BUCKET,
        "requirements": REQUIREMENTS,
        "extra_packages": EXTRA_PACKAGES,
        # ...
    },
)

Getting an Agent Engine instance

Before

import vertexai
from vertexai import agent_engines

vertexai.init(
  project=PROJECT,
  location=LOCATION,
)
agent_engine = agent_engines.get(resource_name)

After

import vertexai

client = vertexai.Client(
  project=PROJECT,
  location=LOCATION,
)
agent_engine = client.agent_engines.get(name=resource_name)

Listing Agent Engine instances

Before

import vertexai
from vertexai import agent_engines

vertexai.init(
  project=PROJECT,
  location=LOCATION,
)
agent_engine = agent_engines.list()

After

import vertexai

client = vertexai.Client(
  project=PROJECT,
  location=LOCATION,
)
agent_engine = client.agent_engines.list()

Deleting an Agent Engine instance

Before

import vertexai
from vertexai import agent_engines

vertexai.init(
  project=PROJECT,
  location=LOCATION,
)
agent_engine = agent_engines.list()

After

import vertexai

client = vertexai.Client(
  project=PROJECT,
  location=LOCATION,
)
agent_engine = client.agent_engines.list()