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](https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/runtime/sdk-migration.md.txt#changes) to the module and how to [migrate your existing code](https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/runtime/sdk-migration.md.txt#migration) to the new SDK structure. For general information about Agent Runtime, see [Overview](https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/runtime.md.txt).

<br />

## 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,

```python
import vertexai
from vertexai import agent_engines
vertexai.init(project=GCP_PROJECT, location=GCP_REGION)
agent_engines.create(...)
```

is replaced by

```python
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

```python
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

```python
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

```python
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

```python
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

```python
import vertexai
from vertexai import agent_engines
vertexai.init(
  project=PROJECT,
  location=LOCATION,
)
agent_engine = agent_engines.get(resource_name)
```

### After

```python
import agentplatform
client = agentplatform.Client(
  project=PROJECT,
  location=LOCATION,
)
remote_agent = client.runtimes.get(name=resource_name)
```

### Listing Agent Runtime instances

### Before

```python
import vertexai
from vertexai import agent_engines
vertexai.init(
  project=PROJECT,
  location=LOCATION,
)
agent_engine = agent_engines.list()
```

### After

```python
import agentplatform
client = agentplatform.Client(
  project=PROJECT,
  location=LOCATION,
)
runtimes = client.runtimes.list()
```

### Deleting an Agent Runtime instance

### Before

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

Alternatively,

```python
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

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

Alternatively,

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