Agent Runtime SDK 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 Runtime, 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
# Mandatory for cross-project deployment and for use of the framework-specific templates.
vertexai.init(project=GCP_PROJECT, location=GCP_REGION)
client = vertexai.Client(project=GCP_PROJECT, location=GCP_REGION)
client.agent_engines.create(...)

The following namespaces for Agent Runtime 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 Runtime code to the client-based design. Note: The examples may omit imports, dependencies, and other boilerplate code to improve readability.

Creating an Agent Runtime 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 Runtime 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 Runtime 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 Runtime 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 Runtime instance

Before

agent_engine.delete(
    force=True,  # Optional
)

Alternatively, py import vertexai from vertexai import agent_engines vertexai.init( project=PROJECT, location=LOCATION, ) agent_engine = agent_engines.delete( resource_name, # Required. force=True, # Optional )

After

agent_engine.delete(
    force=True,     # Optional.
)

Alternatively, py import vertexai client = vertexai.Client( project=PROJECT, location=LOCATION, ) agent_engine = client.agent_engines.delete( name=resource_name, # Required. force=True, # Optional. )

Send feedback