From 9b92c881353f1d09549638ab998f86136bb08203 Mon Sep 17 00:00:00 2001 From: A Vertex SDK engineer Date: Thu, 27 Aug 2026 12:26:33 -0700 Subject: [PATCH] feat: Add sandboxes.pause() and sandboxes.resume() methods to the Agent Engine sandbox SDK across Python, Java, and JS SDKs. PiperOrigin-RevId: 972093505 --- agentplatform/_genai/sandboxes.py | 436 +++++++++++++++++++++++++ agentplatform/_genai/types/__init__.py | 16 + agentplatform/_genai/types/common.py | 106 ++++++ 3 files changed, 558 insertions(+) diff --git a/agentplatform/_genai/sandboxes.py b/agentplatform/_genai/sandboxes.py index 9ab6a6cc32..e5da4cf9f6 100644 --- a/agentplatform/_genai/sandboxes.py +++ b/agentplatform/_genai/sandboxes.py @@ -176,6 +176,28 @@ def _ListRuntimeSandboxesRequestParameters_to_vertex( return to_object +def _PauseRuntimeSandboxRequestParameters_to_vertex( + from_object: Union[dict[str, Any], object], + parent_object: Optional[dict[str, Any]] = None, +) -> dict[str, Any]: + to_object: dict[str, Any] = {} + if getv(from_object, ["name"]) is not None: + setv(to_object, ["_url", "name"], getv(from_object, ["name"])) + + return to_object + + +def _ResumeRuntimeSandboxRequestParameters_to_vertex( + from_object: Union[dict[str, Any], object], + parent_object: Optional[dict[str, Any]] = None, +) -> dict[str, Any]: + to_object: dict[str, Any] = {} + if getv(from_object, ["name"]) is not None: + setv(to_object, ["_url", "name"], getv(from_object, ["name"])) + + return to_object + + class Sandboxes(_api_module.BaseModule): def _create( @@ -641,6 +663,165 @@ def _get_sandbox_operation( self._api_client._verify_response(return_value) return return_value + def _pause( + self, + *, + name: str, + config: Optional[types.PauseRuntimeSandboxConfigOrDict] = None, + ) -> types.RuntimeSandboxOperation: + """ + Pauses a running Agent Runtime sandbox. + + Pausing releases the sandbox's compute resources while preserving its disk state + and connection metadata. The sandbox transitions to STATE_PAUSED and can be + resumed later without losing session state or its connection identity. + + """ + + parameter_model = types._PauseRuntimeSandboxRequestParameters( + name=name, + config=config, + ) + + request_url_dict: Optional[dict[str, str]] + if not self._api_client.vertexai: + raise ValueError( + "This method is only supported in Gemini Enterprise Agent Platform mode, not in Gemini Developer API mode." + ) + else: + request_dict = _PauseRuntimeSandboxRequestParameters_to_vertex( + parameter_model + ) + request_url_dict = request_dict.get("_url") + if request_url_dict: + path = "{name}/:pause".format_map(request_url_dict) + else: + path = "{name}/:pause" + + query_params = request_dict.get("_query") + if query_params: + path = f"{path}?{urlencode(query_params)}" + # TODO: remove the hack that pops config. + request_dict.pop("config", None) + + http_options: Optional[types.HttpOptions] = None + if ( + parameter_model.config is not None + and parameter_model.config.http_options is not None + ): + http_options = parameter_model.config.http_options + + request_dict = _common.convert_to_dict(request_dict) + request_dict = _common.encode_unserializable_types(request_dict) + + response = self._api_client.request("post", path, request_dict, http_options) + + response_dict = {} if not response.body else json.loads(response.body) + + return_value = types.RuntimeSandboxOperation._from_response( + response=response_dict, + kwargs=( + { + "config": { + "response_schema": getattr( + parameter_model.config, "response_schema", None + ), + "response_json_schema": getattr( + parameter_model.config, "response_json_schema", None + ), + "include_all_fields": getattr( + parameter_model.config, "include_all_fields", None + ), + } + } + if getattr(parameter_model, "config", None) + else {} + ), + ) + + self._api_client._verify_response(return_value) + return return_value + + def _resume( + self, + *, + name: str, + config: Optional[types.ResumeRuntimeSandboxConfigOrDict] = None, + ) -> types.RuntimeSandboxOperation: + """ + Resumes a paused Agent Runtime sandbox. + + Resuming brings the sandbox's compute back online while preserving the + sandbox's identity, connection endpoint (including any Private Service Connect + service attachment), and filesystem state from the moment of pause. The + sandbox transitions from STATE_PAUSED back to STATE_RUNNING. + + """ + + parameter_model = types._ResumeRuntimeSandboxRequestParameters( + name=name, + config=config, + ) + + request_url_dict: Optional[dict[str, str]] + if not self._api_client.vertexai: + raise ValueError( + "This method is only supported in Gemini Enterprise Agent Platform mode, not in Gemini Developer API mode." + ) + else: + request_dict = _ResumeRuntimeSandboxRequestParameters_to_vertex( + parameter_model + ) + request_url_dict = request_dict.get("_url") + if request_url_dict: + path = "{name}/:resume".format_map(request_url_dict) + else: + path = "{name}/:resume" + + query_params = request_dict.get("_query") + if query_params: + path = f"{path}?{urlencode(query_params)}" + # TODO: remove the hack that pops config. + request_dict.pop("config", None) + + http_options: Optional[types.HttpOptions] = None + if ( + parameter_model.config is not None + and parameter_model.config.http_options is not None + ): + http_options = parameter_model.config.http_options + + request_dict = _common.convert_to_dict(request_dict) + request_dict = _common.encode_unserializable_types(request_dict) + + response = self._api_client.request("post", path, request_dict, http_options) + + response_dict = {} if not response.body else json.loads(response.body) + + return_value = types.RuntimeSandboxOperation._from_response( + response=response_dict, + kwargs=( + { + "config": { + "response_schema": getattr( + parameter_model.config, "response_schema", None + ), + "response_json_schema": getattr( + parameter_model.config, "response_json_schema", None + ), + "include_all_fields": getattr( + parameter_model.config, "include_all_fields", None + ), + } + } + if getattr(parameter_model, "config", None) + else {} + ), + ) + + self._api_client._verify_response(return_value) + return return_value + _templates = None _snapshots = None @@ -815,6 +996,98 @@ def list( config, ) + def pause( + self, + *, + name: str, + poll_interval_seconds: float = 0.1, + config: Optional[types.PauseRuntimeSandboxConfigOrDict] = None, + ) -> types.RuntimeSandboxOperation: + """Pauses a running Agent Runtime sandbox. + + Pausing releases the sandbox's compute resources while preserving its disk + state and connection metadata. The sandbox transitions to STATE_PAUSED and + can be resumed later via ``resume()`` without losing session state or its + connection identity. + + Args: + name (str): + Required. The name of the agent runtime sandbox to pause. + projects/{project}/locations/{location}/agentRuntimes/{resource_id}/sandboxEnvironments/{sandbox_id} + poll_interval_seconds (float): + Optional. The interval in seconds to poll for pause completion. + config (PauseRuntimeSandboxConfigOrDict): + Optional. The configuration for the pause request. + + Returns: + RuntimeSandboxOperation: The operation for pausing the sandbox. + """ + if config is None: + config = types.PauseRuntimeSandboxConfig() + elif isinstance(config, dict): + config = types.PauseRuntimeSandboxConfig.model_validate(config) + + operation = self._pause( + name=name, + config=config, + ) + if config.wait_for_completion: + if not operation.done: + operation = _runtimes_utils._await_operation( + operation_name=operation.name, + get_operation_fn=self._get_sandbox_operation, + poll_interval_seconds=poll_interval_seconds, + ) + if operation.response: + operation.response = self.get(name=operation.response.name) + return operation + + def resume( + self, + *, + name: str, + poll_interval_seconds: float = 0.1, + config: Optional[types.ResumeRuntimeSandboxConfigOrDict] = None, + ) -> types.RuntimeSandboxOperation: + """Resumes a paused Agent Runtime sandbox. + + Resuming brings the sandbox's compute back online while preserving the + sandbox's identity, connection endpoint (including any Private Service + Connect service attachment), and filesystem state from the moment of + pause. The sandbox transitions from STATE_PAUSED back to STATE_RUNNING. + + Args: + name (str): + Required. The name of the paused agent runtime sandbox to resume. + projects/{project}/locations/{location}/agentRuntimes/{resource_id}/sandboxEnvironments/{sandbox_id} + poll_interval_seconds (float): + Optional. The interval in seconds to poll for resume completion. + config (ResumeRuntimeSandboxConfigOrDict): + Optional. The configuration for the resume request. + + Returns: + RuntimeSandboxOperation: The operation for resuming the sandbox. + """ + if config is None: + config = types.ResumeRuntimeSandboxConfig() + elif isinstance(config, dict): + config = types.ResumeRuntimeSandboxConfig.model_validate(config) + + operation = self._resume( + name=name, + config=config, + ) + if config.wait_for_completion: + if not operation.done: + operation = _runtimes_utils._await_operation( + operation_name=operation.name, + get_operation_fn=self._get_sandbox_operation, + poll_interval_seconds=poll_interval_seconds, + ) + if operation.response: + operation.response = self.get(name=operation.response.name) + return operation + def execute_code( self, *, @@ -1592,3 +1865,166 @@ async def _get_sandbox_operation( self._api_client._verify_response(return_value) return return_value + + async def _pause( + self, + *, + name: str, + config: Optional[types.PauseRuntimeSandboxConfigOrDict] = None, + ) -> types.RuntimeSandboxOperation: + """ + Pauses a running Agent Runtime sandbox. + + Pausing releases the sandbox's compute resources while preserving its disk state + and connection metadata. The sandbox transitions to STATE_PAUSED and can be + resumed later without losing session state or its connection identity. + + """ + + parameter_model = types._PauseRuntimeSandboxRequestParameters( + name=name, + config=config, + ) + + request_url_dict: Optional[dict[str, str]] + if not self._api_client.vertexai: + raise ValueError( + "This method is only supported in Gemini Enterprise Agent Platform mode, not in Gemini Developer API mode." + ) + else: + request_dict = _PauseRuntimeSandboxRequestParameters_to_vertex( + parameter_model + ) + request_url_dict = request_dict.get("_url") + if request_url_dict: + path = "{name}/:pause".format_map(request_url_dict) + else: + path = "{name}/:pause" + + query_params = request_dict.get("_query") + if query_params: + path = f"{path}?{urlencode(query_params)}" + # TODO: remove the hack that pops config. + request_dict.pop("config", None) + + http_options: Optional[types.HttpOptions] = None + if ( + parameter_model.config is not None + and parameter_model.config.http_options is not None + ): + http_options = parameter_model.config.http_options + + request_dict = _common.convert_to_dict(request_dict) + request_dict = _common.encode_unserializable_types(request_dict) + + response = await self._api_client.async_request( + "post", path, request_dict, http_options + ) + + response_dict = {} if not response.body else json.loads(response.body) + + return_value = types.RuntimeSandboxOperation._from_response( + response=response_dict, + kwargs=( + { + "config": { + "response_schema": getattr( + parameter_model.config, "response_schema", None + ), + "response_json_schema": getattr( + parameter_model.config, "response_json_schema", None + ), + "include_all_fields": getattr( + parameter_model.config, "include_all_fields", None + ), + } + } + if getattr(parameter_model, "config", None) + else {} + ), + ) + + self._api_client._verify_response(return_value) + return return_value + + async def _resume( + self, + *, + name: str, + config: Optional[types.ResumeRuntimeSandboxConfigOrDict] = None, + ) -> types.RuntimeSandboxOperation: + """ + Resumes a paused Agent Runtime sandbox. + + Resuming brings the sandbox's compute back online while preserving the + sandbox's identity, connection endpoint (including any Private Service Connect + service attachment), and filesystem state from the moment of pause. The + sandbox transitions from STATE_PAUSED back to STATE_RUNNING. + + """ + + parameter_model = types._ResumeRuntimeSandboxRequestParameters( + name=name, + config=config, + ) + + request_url_dict: Optional[dict[str, str]] + if not self._api_client.vertexai: + raise ValueError( + "This method is only supported in Gemini Enterprise Agent Platform mode, not in Gemini Developer API mode." + ) + else: + request_dict = _ResumeRuntimeSandboxRequestParameters_to_vertex( + parameter_model + ) + request_url_dict = request_dict.get("_url") + if request_url_dict: + path = "{name}/:resume".format_map(request_url_dict) + else: + path = "{name}/:resume" + + query_params = request_dict.get("_query") + if query_params: + path = f"{path}?{urlencode(query_params)}" + # TODO: remove the hack that pops config. + request_dict.pop("config", None) + + http_options: Optional[types.HttpOptions] = None + if ( + parameter_model.config is not None + and parameter_model.config.http_options is not None + ): + http_options = parameter_model.config.http_options + + request_dict = _common.convert_to_dict(request_dict) + request_dict = _common.encode_unserializable_types(request_dict) + + response = await self._api_client.async_request( + "post", path, request_dict, http_options + ) + + response_dict = {} if not response.body else json.loads(response.body) + + return_value = types.RuntimeSandboxOperation._from_response( + response=response_dict, + kwargs=( + { + "config": { + "response_schema": getattr( + parameter_model.config, "response_schema", None + ), + "response_json_schema": getattr( + parameter_model.config, "response_json_schema", None + ), + "include_all_fields": getattr( + parameter_model.config, "include_all_fields", None + ), + } + } + if getattr(parameter_model, "config", None) + else {} + ), + ) + + self._api_client._verify_response(return_value) + return return_value diff --git a/agentplatform/_genai/types/__init__.py b/agentplatform/_genai/types/__init__.py index 9349833bc4..fc3e0056b5 100644 --- a/agentplatform/_genai/types/__init__.py +++ b/agentplatform/_genai/types/__init__.py @@ -156,6 +156,7 @@ from .common import _ListSkillsRequestParameters from .common import _OptimizeRequestParameters from .common import _OptimizeRequestParameters +from .common import _PauseRuntimeSandboxRequestParameters from .common import _PredictParameters from .common import _PurgeMemoriesRequestParameters from .common import _QueryRuntimeRequestParameters @@ -163,6 +164,7 @@ from .common import _RecommendSpecRequestParameters from .common import _RemoveExamplesParameters from .common import _RestoreVersionRequestParameters +from .common import _ResumeRuntimeSandboxRequestParameters from .common import _RetrieveMemoriesRequestParameters from .common import _RetrieveMemoryProfilesRequestParameters from .common import _RetrieveRagContextsRequestParameters @@ -1378,6 +1380,9 @@ from .common import PairwiseMetricInstanceDict from .common import PairwiseMetricInstanceOrDict from .common import ParsedResponseUnion +from .common import PauseRuntimeSandboxConfig +from .common import PauseRuntimeSandboxConfigDict +from .common import PauseRuntimeSandboxConfigOrDict from .common import PointwiseMetricInput from .common import PointwiseMetricInputDict from .common import PointwiseMetricInputOrDict @@ -1792,6 +1797,9 @@ from .common import RestoreVersionOperation from .common import RestoreVersionOperationDict from .common import RestoreVersionOperationOrDict +from .common import ResumeRuntimeSandboxConfig +from .common import ResumeRuntimeSandboxConfigDict +from .common import ResumeRuntimeSandboxConfigOrDict from .common import RetrieveContextsConfig from .common import RetrieveContextsConfigDict from .common import RetrieveContextsConfigOrDict @@ -3422,6 +3430,12 @@ "ListRuntimeSandboxesResponse", "ListRuntimeSandboxesResponseDict", "ListRuntimeSandboxesResponseOrDict", + "PauseRuntimeSandboxConfig", + "PauseRuntimeSandboxConfigDict", + "PauseRuntimeSandboxConfigOrDict", + "ResumeRuntimeSandboxConfig", + "ResumeRuntimeSandboxConfigDict", + "ResumeRuntimeSandboxConfigOrDict", "SandboxEnvironmentTemplateCustomContainerSpec", "SandboxEnvironmentTemplateCustomContainerSpecDict", "SandboxEnvironmentTemplateCustomContainerSpecOrDict", @@ -4433,6 +4447,8 @@ "_GetRuntimeSandboxRequestParameters", "_ListRuntimeSandboxesRequestParameters", "_GetRuntimeSandboxOperationParameters", + "_PauseRuntimeSandboxRequestParameters", + "_ResumeRuntimeSandboxRequestParameters", "_CreateSandboxEnvironmentTemplateRequestParameters", "_DeleteSandboxEnvironmentTemplateRequestParameters", "_GetSandboxEnvironmentTemplateRequestParameters", diff --git a/agentplatform/_genai/types/common.py b/agentplatform/_genai/types/common.py index 78e93f310e..ee0f0130c0 100644 --- a/agentplatform/_genai/types/common.py +++ b/agentplatform/_genai/types/common.py @@ -17269,6 +17269,112 @@ class _GetRuntimeSandboxOperationParametersDict(TypedDict, total=False): ] +class PauseRuntimeSandboxConfig(_common.BaseModel): + """Config for pausing an Agent Runtime sandbox.""" + + http_options: Optional[genai_types.HttpOptions] = Field( + default=None, description="""Used to override HTTP request options.""" + ) + wait_for_completion: Optional[bool] = Field( + default=True, + description="""Waits for the operation to complete before returning.""", + ) + + +class PauseRuntimeSandboxConfigDict(TypedDict, total=False): + """Config for pausing an Agent Runtime sandbox.""" + + http_options: Optional[genai_types.HttpOptions] + """Used to override HTTP request options.""" + + wait_for_completion: Optional[bool] + """Waits for the operation to complete before returning.""" + + +PauseRuntimeSandboxConfigOrDict = Union[ + PauseRuntimeSandboxConfig, PauseRuntimeSandboxConfigDict +] + + +class _PauseRuntimeSandboxRequestParameters(_common.BaseModel): + """Parameters for pausing an Agent Runtime sandbox.""" + + name: Optional[str] = Field( + default=None, description="""Name of the agent runtime sandbox to pause.""" + ) + config: Optional[PauseRuntimeSandboxConfig] = Field( + default=None, description="""""" + ) + + +class _PauseRuntimeSandboxRequestParametersDict(TypedDict, total=False): + """Parameters for pausing an Agent Runtime sandbox.""" + + name: Optional[str] + """Name of the agent runtime sandbox to pause.""" + + config: Optional[PauseRuntimeSandboxConfigDict] + """""" + + +_PauseRuntimeSandboxRequestParametersOrDict = Union[ + _PauseRuntimeSandboxRequestParameters, _PauseRuntimeSandboxRequestParametersDict +] + + +class ResumeRuntimeSandboxConfig(_common.BaseModel): + """Config for resuming an Agent Runtime sandbox.""" + + http_options: Optional[genai_types.HttpOptions] = Field( + default=None, description="""Used to override HTTP request options.""" + ) + wait_for_completion: Optional[bool] = Field( + default=True, + description="""Waits for the operation to complete before returning.""", + ) + + +class ResumeRuntimeSandboxConfigDict(TypedDict, total=False): + """Config for resuming an Agent Runtime sandbox.""" + + http_options: Optional[genai_types.HttpOptions] + """Used to override HTTP request options.""" + + wait_for_completion: Optional[bool] + """Waits for the operation to complete before returning.""" + + +ResumeRuntimeSandboxConfigOrDict = Union[ + ResumeRuntimeSandboxConfig, ResumeRuntimeSandboxConfigDict +] + + +class _ResumeRuntimeSandboxRequestParameters(_common.BaseModel): + """Parameters for resuming an Agent Runtime sandbox.""" + + name: Optional[str] = Field( + default=None, description="""Name of the agent runtime sandbox to resume.""" + ) + config: Optional[ResumeRuntimeSandboxConfig] = Field( + default=None, description="""""" + ) + + +class _ResumeRuntimeSandboxRequestParametersDict(TypedDict, total=False): + """Parameters for resuming an Agent Runtime sandbox.""" + + name: Optional[str] + """Name of the agent runtime sandbox to resume.""" + + config: Optional[ResumeRuntimeSandboxConfigDict] + """""" + + +_ResumeRuntimeSandboxRequestParametersOrDict = Union[ + _ResumeRuntimeSandboxRequestParameters, _ResumeRuntimeSandboxRequestParametersDict +] + + class SandboxEnvironmentTemplateCustomContainerSpec(_common.BaseModel): """Specification for deploying from a custom container image."""