Manage snapshots

Sandbox snapshots in Gemini Enterprise Agent Platform let you save the current state of a sandbox and restore it later. This is useful for lifecycle management tasks such as restoring a known good state or exploring variation branches.

Snapshots provide several benefits for managing your agent workflows:

  • State persistence: Save the exact state of the sandbox, including installed libraries, file system changes, and memory state.
  • Efficiency: Instead of recreating a complex environment from scratch, you can restore it from a snapshot in seconds.
  • Checkpointing: Create checkpoints during a long-running agent task to allow recovery if something goes wrong.
  • Branching: Create multiple sandboxes from the same snapshot to explore different paths or test variations.

Limitations

You cannot restore a sandbox snapshot to a new sandbox environment if any of the following conditions are true:

  • The new sandbox uses a different server architecture (for example, amd64 versus arm64).
  • The new sandbox uses a different sandbox runtime version (for example, after a GKE cluster upgrade).
  • The new sandbox uses a different container image URI.

Create a snapshot

To create a snapshot of a sandbox, use the Python SDK:

import vertexai

client = vertexai.Client(project='PROJECT_ID', location='LOCATION')
sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

snapshot_operation = client.agent_engines.sandboxes.snapshots.create(
    source_sandbox_environment_name=sandbox_name,
    config={
        "display_name": "DISPLAY_NAME",
        "ttl": "3600s",
    }
)
print(f"Snapshot creation initiated: {snapshot_operation.name}")

Replace the following:

  • PROJECT_ID: Your Google Cloud project ID.
  • LOCATION: The Google Cloud region of your resource. See Supported regions.
  • INSTANCE_ID: The Agent Platform instance ID.
  • SANDBOX_ID: The existing sandbox ID to create a snapshot for.
  • DISPLAY_NAME: A descriptive display name for your snapshot.

Restore from a snapshot

You can restore a sandbox state by referencing a saved snapshot when creating a new sandbox environment:

agent_instance_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID
snapshot_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

# Restore from a snapshot
new_sandbox_operation = client.agent_engines.sandboxes.create(
    name=agent_instance_name,
    config={
        "display_name": "restored-sandbox",
        "sandbox_environment_snapshot": snapshot_name,
    }
)

List snapshots

To list all sandbox snapshots associated with an Agent Platform instance:

snapshots_response = client.agent_engines.sandboxes.snapshots.list(name=agent_instance_name)

for snapshot in snapshots_response.sandbox_environment_snapshots:
    print(snapshot.name)

View snapshot details

To view the configuration of a specific sandbox snapshot:

snapshot = client.agent_engines.sandboxes.snapshots.get(name=snapshot_name)
print(snapshot)

Delete a snapshot

To explicitly delete a sandbox snapshot when they are no longer needed:

client.agent_engines.sandboxes.snapshots.delete(name=snapshot_name)
print("Snapshot deleted.")