feat: Add sandboxes.pause() and sandboxes.resume() methods to the Agent Engine sandbox SDK across Python, Java, and JS SDKs.

PiperOrigin-RevId: 971502868

Author: vertex-sdk-bot

src/converters/_sandboxenvironments_converters.ts

@@ -193,3 +193,29 @@ export function listAgentEngineSandboxesRequestParametersToVertex(
 
   return toObject;
 }
+
+export function pauseAgentEngineSandboxRequestParametersToVertex(
+  fromObject: types.PauseAgentEngineSandboxRequestParameters,
+): Record<string, unknown> {
+  const toObject: Record<string, unknown> = {};
+
+  const fromName = common.getValueByPath(fromObject, ['name']);
+  if (fromName != null) {
+    common.setValueByPath(toObject, ['_url', 'name'], fromName);
+  }
+
+  return toObject;
+}
+
+export function resumeAgentEngineSandboxRequestParametersToVertex(
+  fromObject: types.ResumeAgentEngineSandboxRequestParameters,
+): Record<string, unknown> {
+  const toObject: Record<string, unknown> = {};
+
+  const fromName = common.getValueByPath(fromObject, ['name']);
+  if (fromName != null) {
+    common.setValueByPath(toObject, ['_url', 'name'], fromName);
+  }
+
+  return toObject;
+}

src/converters/_sandboxes_converters.ts

@@ -193,3 +193,29 @@ export function listAgentEngineSandboxesRequestParametersToVertex(
 
   return toObject;
 }
+
+export function pauseAgentEngineSandboxRequestParametersToVertex(
+  fromObject: types.PauseAgentEngineSandboxRequestParameters,
+): Record<string, unknown> {
+  const toObject: Record<string, unknown> = {};
+
+  const fromName = common.getValueByPath(fromObject, ['name']);
+  if (fromName != null) {
+    common.setValueByPath(toObject, ['_url', 'name'], fromName);
+  }
+
+  return toObject;
+}
+
+export function resumeAgentEngineSandboxRequestParametersToVertex(
+  fromObject: types.ResumeAgentEngineSandboxRequestParameters,
+): Record<string, unknown> {
+  const toObject: Record<string, unknown> = {};
+
+  const fromName = common.getValueByPath(fromObject, ['name']);
+  if (fromName != null) {
+    common.setValueByPath(toObject, ['_url', 'name'], fromName);
+  }
+
+  return toObject;
+}

src/sandboxenvironments.ts

@@ -344,4 +344,88 @@ export class SandboxEnvironments extends BaseModule {
       );
     }
   }
+
+  async pauseInternal(
+    params: types.PauseAgentEngineSandboxRequestParameters,
+  ): Promise<types.AgentEngineSandboxOperation> {
+    let response: Promise<types.AgentEngineSandboxOperation>;
+
+    let path: string = '';
+    let queryParams: Record<string, string> = {};
+    if (this.apiClient.isVertexAI()) {
+      const body =
+        converters.pauseAgentEngineSandboxRequestParametersToVertex(params);
+      path = common.formatMap(
+        '{name}/:pause',
+        body['_url'] as Record<string, unknown>,
+      );
+      queryParams = body['_query'] as Record<string, string>;
+      delete body['_url'];
+      delete body['_query'];
+      delete body['config'];
+
+      response = this.apiClient
+        .request({
+          path: path,
+          queryParams: queryParams,
+          body: JSON.stringify(body),
+          httpMethod: 'POST',
+          httpOptions: params.config?.httpOptions,
+          abortSignal: params.config?.abortSignal,
+        })
+        .then((httpResponse) => {
+          return httpResponse.json();
+        }) as Promise<types.AgentEngineSandboxOperation>;
+
+      return response.then((resp) => {
+        return resp as types.AgentEngineSandboxOperation;
+      });
+    } else {
+      throw new Error(
+        'This method is only supported by the Gemini Enterprise Agent Platform (previously known as Vertex AI).',
+      );
+    }
+  }
+
+  async resumeInternal(
+    params: types.ResumeAgentEngineSandboxRequestParameters,
+  ): Promise<types.AgentEngineSandboxOperation> {
+    let response: Promise<types.AgentEngineSandboxOperation>;
+
+    let path: string = '';
+    let queryParams: Record<string, string> = {};
+    if (this.apiClient.isVertexAI()) {
+      const body =
+        converters.resumeAgentEngineSandboxRequestParametersToVertex(params);
+      path = common.formatMap(
+        '{name}/:resume',
+        body['_url'] as Record<string, unknown>,
+      );
+      queryParams = body['_query'] as Record<string, string>;
+      delete body['_url'];
+      delete body['_query'];
+      delete body['config'];
+
+      response = this.apiClient
+        .request({
+          path: path,
+          queryParams: queryParams,
+          body: JSON.stringify(body),
+          httpMethod: 'POST',
+          httpOptions: params.config?.httpOptions,
+          abortSignal: params.config?.abortSignal,
+        })
+        .then((httpResponse) => {
+          return httpResponse.json();
+        }) as Promise<types.AgentEngineSandboxOperation>;
+
+      return response.then((resp) => {
+        return resp as types.AgentEngineSandboxOperation;
+      });
+    } else {
+      throw new Error(
+        'This method is only supported by the Gemini Enterprise Agent Platform (previously known as Vertex AI).',
+      );
+    }
+  }
 }

src/sandboxes.ts

@@ -354,4 +354,88 @@ export class Sandboxes extends BaseModule {
       );
     }
   }
+
+  async pauseInternal(
+    params: types.PauseAgentEngineSandboxRequestParameters,
+  ): Promise<types.AgentEngineSandboxOperation> {
+    let response: Promise<types.AgentEngineSandboxOperation>;
+
+    let path: string = '';
+    let queryParams: Record<string, string> = {};
+    if (this.apiClient.isVertexAI()) {
+      const body =
+        converters.pauseAgentEngineSandboxRequestParametersToVertex(params);
+      path = common.formatMap(
+        '{name}/:pause',
+        body['_url'] as Record<string, unknown>,
+      );
+      queryParams = body['_query'] as Record<string, string>;
+      delete body['_url'];
+      delete body['_query'];
+      delete body['config'];
+
+      response = this.apiClient
+        .request({
+          path: path,
+          queryParams: queryParams,
+          body: JSON.stringify(body),
+          httpMethod: 'POST',
+          httpOptions: params.config?.httpOptions,
+          abortSignal: params.config?.abortSignal,
+        })
+        .then((httpResponse) => {
+          return httpResponse.json();
+        }) as Promise<types.AgentEngineSandboxOperation>;
+
+      return response.then((resp) => {
+        return resp as types.AgentEngineSandboxOperation;
+      });
+    } else {
+      throw new Error(
+        'This method is only supported by the Gemini Enterprise Agent Platform (previously known as Vertex AI).',
+      );
+    }
+  }
+
+  async resumeInternal(
+    params: types.ResumeAgentEngineSandboxRequestParameters,
+  ): Promise<types.AgentEngineSandboxOperation> {
+    let response: Promise<types.AgentEngineSandboxOperation>;
+
+    let path: string = '';
+    let queryParams: Record<string, string> = {};
+    if (this.apiClient.isVertexAI()) {
+      const body =
+        converters.resumeAgentEngineSandboxRequestParametersToVertex(params);
+      path = common.formatMap(
+        '{name}/:resume',
+        body['_url'] as Record<string, unknown>,
+      );
+      queryParams = body['_query'] as Record<string, string>;
+      delete body['_url'];
+      delete body['_query'];
+      delete body['config'];
+
+      response = this.apiClient
+        .request({
+          path: path,
+          queryParams: queryParams,
+          body: JSON.stringify(body),
+          httpMethod: 'POST',
+          httpOptions: params.config?.httpOptions,
+          abortSignal: params.config?.abortSignal,
+        })
+        .then((httpResponse) => {
+          return httpResponse.json();
+        }) as Promise<types.AgentEngineSandboxOperation>;
+
+      return response.then((resp) => {
+        return resp as types.AgentEngineSandboxOperation;
+      });
+    } else {
+      throw new Error(
+        'This method is only supported by the Gemini Enterprise Agent Platform (previously known as Vertex AI).',
+      );
+    }
+  }
 }

src/types/common.ts

@@ -188,6 +188,22 @@ export enum DefaultContainerCategory {
   DEFAULT_CONTAINER_CATEGORY_SHELL_SANDBOX = 'DEFAULT_CONTAINER_CATEGORY_SHELL_SANDBOX',
 }
 
+/** Output only. The state of the PSC service automation. */
+export enum PscAutomationState {
+  /**
+   * Should not be used.
+   */
+  PSC_AUTOMATION_STATE_UNSPECIFIED = 'PSC_AUTOMATION_STATE_UNSPECIFIED',
+  /**
+   * The PSC service automation is successful.
+   */
+  PSC_AUTOMATION_STATE_SUCCESSFUL = 'PSC_AUTOMATION_STATE_SUCCESSFUL',
+  /**
+   * The PSC service automation has failed.
+   */
+  PSC_AUTOMATION_STATE_FAILED = 'PSC_AUTOMATION_STATE_FAILED',
+}
+
 /** Input only. Action to take on the source SandboxEnvironment after the snapshot is taken. This field is only used in CreateSandboxEnvironmentSnapshotRequest and it is not stored in the resource. */
 export enum PostSnapshotAction {
   /**
@@ -2329,6 +2345,8 @@ export declare interface SandboxEnvironmentConnectionInfo {
   sandboxInternalIp?: string;
   /** Output only. The routing token for the SandboxEnvironment. */
   routingToken?: string;
+  /** Output only. The name of the PSC-E service attachment created for private ingress to this SandboxEnvironment. Only populated when the template enables private ingress (see SandboxEnvironmentTemplate.ingress_control_config). VPC-SC customers use this to create a PSC endpoint in their VPC. */
+  serviceAttachment?: string;
 }
 
 /** A sandbox environment. */
@@ -2515,6 +2533,50 @@ export declare interface GetAgentEngineSandboxOperationParameters {
   config?: GetAgentEngineOperationConfig;
 }
 
+/** Config for pausing an Agent Engine sandbox. */
+export declare interface PauseAgentEngineSandboxConfig {
+  /** Used to override HTTP request options. */
+  httpOptions?: genaiTypes.HttpOptions;
+  /** Abort signal which can be used to cancel the request.
+
+  NOTE: AbortSignal is a client-only operation. Using it to cancel an
+  operation will not cancel the request in the service. You will still
+  be charged usage for any applicable operations.
+       */
+  abortSignal?: AbortSignal;
+  /** Waits for the operation to complete before returning. */
+  waitForCompletion?: boolean;
+}
+
+/** Parameters for pausing an Agent Engine sandbox. */
+export declare interface PauseAgentEngineSandboxRequestParameters {
+  /** Name of the agent engine sandbox to pause. */
+  name: string;
+  config?: PauseAgentEngineSandboxConfig;
+}
+
+/** Config for resuming an Agent Engine sandbox. */
+export declare interface ResumeAgentEngineSandboxConfig {
+  /** Used to override HTTP request options. */
+  httpOptions?: genaiTypes.HttpOptions;
+  /** Abort signal which can be used to cancel the request.
+
+  NOTE: AbortSignal is a client-only operation. Using it to cancel an
+  operation will not cancel the request in the service. You will still
+  be charged usage for any applicable operations.
+       */
+  abortSignal?: AbortSignal;
+  /** Waits for the operation to complete before returning. */
+  waitForCompletion?: boolean;
+}
+
+/** Parameters for resuming an Agent Engine sandbox. */
+export declare interface ResumeAgentEngineSandboxRequestParameters {
+  /** Name of the agent engine sandbox to resume. */
+  name: string;
+  config?: ResumeAgentEngineSandboxConfig;
+}
+
 /** Specification for deploying from a custom container image. */
 export declare interface SandboxEnvironmentTemplateCustomContainerSpec {
   /** Required. The Artifact Registry Docker image URI (e.g., us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag) of the container image that is to be run on each worker replica. */
@@ -2607,6 +2669,36 @@ export declare interface CreateSandboxEnvironmentTemplateRequestParameters {
   config?: CreateSandboxEnvironmentTemplateConfig;
 }
 
+/** PSC config that is used to automatically create PSC endpoints in the user projects. */
+export declare interface PSCAutomationConfig {
+  /** Output only. Error message if the PSC service automation failed. */
+  errorMessage?: string;
+  /** Output only. Forwarding rule created by the PSC service automation. */
+  forwardingRule?: string;
+  /** Output only. IP address rule created by the PSC service automation. */
+  ipAddress?: string;
+  /** Required. The full name of the Google Compute Engine [network](https://cloud.google.com/compute/docs/networks-and-firewalls#networks). [Format](https://cloud.google.com/compute/docs/reference/rest/v1/networks/get): `projects/{project}/global/networks/{network}`. */
+  network?: string;
+  /** Required. Project id used to create forwarding rule. */
+  projectId?: string;
+  /** Output only. The state of the PSC service automation. */
+  state?: PscAutomationState;
+}
+
+/** Represents configuration for private service connect. */
+export declare interface PrivateServiceConnectConfig {
+  /** Required. If true, expose the IndexEndpoint via private service connect. */
+  enablePrivateServiceConnect?: boolean;
+  /** Optional. If set to true, enable secure private service connect with IAM authorization. Otherwise, private service connect will be done without authorization. Note latency will be slightly increased if authorization is enabled. */
+  enableSecurePrivateServiceConnect?: boolean;
+  /** A list of Projects from which the forwarding rule will target the service attachment. */
+  projectAllowlist?: string[];
+  /** Optional. List of projects and networks where the PSC endpoints will be created. This field is used by Online Inference(Prediction) only. */
+  pscAutomationConfigs?: PSCAutomationConfig[];
+  /** Output only. The name of the generated service attachment resource. This is only populated if the endpoint is deployed with PrivateServiceConnect. */
+  serviceAttachment?: string;
+}
+
 /** A sandbox environment template. */
 export declare interface SandboxEnvironmentTemplate {
   /** Output only. The timestamp when this SandboxEnvironmentTemplate was created. */
@@ -2631,6 +2723,8 @@ export declare interface SandboxEnvironmentTemplate {
     | 'FAILED';
   /** Output only. The timestamp when this SandboxEnvironmentTemplate was most recently updated. */
   updateTime?: string;
+  /** Optional. The configuration for private ingress (PSC-E) of this template. When set, the sandbox router is exposed privately via a PSC service attachment so VPC-SC customers can connect from their VPC over a private endpoint instead of the public internet. The resulting service attachment is surfaced on `SandboxEnvironment.connection_info.service_attachment`. Only the PSC-E (service-attachment/ingress) portion of `PrivateServiceConnectConfig` applies here: `enable_private_service_connect` and `project_allowlist` (the consumer projects allowed to connect). The nested `psc_interface_config` (PSC-I / egress) is not used for sandbox ingress; sandbox egress is configured via `egress_control_config` instead. */
+  ingressControlConfig?: PrivateServiceConnectConfig;
 }
 
 /** Operation that has an agent engine sandbox as a response. */