Agent Runtime SDK migration guide

In version 2.0.1 of the Agent Platform SDK, the agent_engines module within the SDK was refactored and renamed to runtimes under the standalone agentplatform package. The page describes the key changes to the module and how to migrate your existing code to the new SDK structure. 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 agentplatform
# Mandatory for cross-project deployment and for use of the framework-specific templates.
client = agentplatform.Client(project=GCP_PROJECT, location=GCP_REGION)
client.runtimes.create(...)

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

Legacy namespace	Impacted code	Replacement (agentplatform)
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.runtimes.create client.runtimes.get client.runtimes.list client.runtimes.update client.runtimes.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.memory_banks.memories.create client.memory_banks.memories.delete client.memory_banks.memories.generate client.memory_banks.memories.get client.memory_banks.memories.list client.memory_banks.memories.retrieve client.sessions.create client.sessions.delete client.sessions.get client.sessions.list client.sessions.events.append client.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 agentplatform SDK 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 agentplatform
client = agentplatform.Client(
  project=PROJECT,
  location=LOCATION,
)
client.runtimes.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 agentplatform
client = agentplatform.Client(
  project=PROJECT,
  location=LOCATION,
)
client.runtimes.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 agentplatform
client = agentplatform.Client(
  project=PROJECT,
  location=LOCATION,
)
remote_agent = client.runtimes.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 agentplatform
client = agentplatform.Client(
  project=PROJECT,
  location=LOCATION,
)
runtimes = client.runtimes.list()

Deleting an Agent Runtime instance

Before

agent_engine.delete(
    force=True,  # Optional
)

Alternatively,

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

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

Alternatively,

import agentplatform
client = agentplatform.Client(
  project=PROJECT,
  location=LOCATION,
)
remote_agent = client.runtimes.delete(
    name=resource_name,  # Required.
    force=True,          # Optional.
)

Send feedback