From 99fd15c9bbf0d4b38100377fd50fb45f0bd87ff0 Mon Sep 17 00:00:00 2001 From: A Vertex SDK engineer Date: Wed, 18 Nov 2026 10:15:57 -0800 Subject: [PATCH] fix: raise API errors on mid-stream Agent Engine stream_query error frames Detect terminal JSON error frames (`errorCode`/`errorMessage`) emitted after an HTTP 200 streaming response starts and raise `google.genai.errors.APIError` in the GenAI Agent Engine and Agent Platform SDKs, while leaving normal payloads and ADK event objects unchanged. PiperOrigin-RevId: 1024779541 --- agentplatform/_genai/_runtimes_utils.py | 66 +++++ .../agentplatform/genai/test_agent_engines.py | 243 ++++++++++++++++++ vertexai/_genai/_agent_engines_utils.py | 61 +++++ 3 files changed, 370 insertions(+) diff --git a/agentplatform/_genai/_runtimes_utils.py b/agentplatform/_genai/_runtimes_utils.py index ed46877ed6..d98aef7454 100644 --- a/agentplatform/_genai/_runtimes_utils.py +++ b/agentplatform/_genai/_runtimes_utils.py @@ -1892,6 +1892,62 @@ def _strip_sse_framing(line: str) -> str: return payload[1:] if payload.startswith(" ") else payload +_STREAM_ERROR_KEYS = frozenset({"code", "message", "errorCode", "errorMessage"}) +_STREAM_ERROR_STATUS_CODES = { + "INVALID_ARGUMENT": 400, + "UNAUTHENTICATED": 401, + "PERMISSION_DENIED": 403, + "NOT_FOUND": 404, + "RESOURCE_EXHAUSTED": 429, + "UNAVAILABLE": 503, + "DEADLINE_EXCEEDED": 504, +} + + +def _raise_for_stream_error(parsed: Any) -> None: + """Raises `APIError` if `parsed` is a terminal stream error frame.""" + if ( + not isinstance(parsed, dict) + or "errorCode" not in parsed + or ("errorMessage" not in parsed and "message" not in parsed) + or not parsed.keys() <= _STREAM_ERROR_KEYS + ): + return + raw_code = parsed["errorCode"] + if raw_code is None or (isinstance(raw_code, str) and not raw_code.strip()): + raw_code = parsed.get("code") + if isinstance(raw_code, bool) or not raw_code: + return + raw_str = str(raw_code).strip() + upper = raw_str.upper().removeprefix("STATUSCODE.") + if upper in ("", "0", "OK"): + return + status: Optional[str] = None + if upper in _STREAM_ERROR_STATUS_CODES: + status_code, status = _STREAM_ERROR_STATUS_CODES[upper], upper + elif raw_str.isascii() and raw_str.isdigit(): + num = int(raw_str) + if num == 0 or 200 <= num < 300: + return + if 400 <= num < 600: + status_code = num + else: + status_code, status = 500, raw_str + else: + status_code = 500 + if upper != "NONE": + status = upper + message = parsed.get("errorMessage") or parsed.get("message") or "" + error_body: dict[str, Any] = {"code": status_code, "message": str(message)} + if status: + error_body["status"] = status + google_genai_errors.APIError.raise_error( + status_code, + {"error": error_body}, + None, + ) + + def _yield_parsed_json(http_response: google_genai_types.HttpResponse) -> Iterator[Any]: """Converts the body of the HTTP Response message to JSON format. @@ -1901,6 +1957,10 @@ def _yield_parsed_json(http_response: google_genai_types.HttpResponse) -> Iterat Yields: Any: A JSON object or line of the original body or None. + + Raises: + google.genai.errors.APIError: If the stream emits a terminal error + frame. """ if not http_response.body: yield None @@ -1916,6 +1976,7 @@ def _yield_parsed_json(http_response: google_genai_types.HttpResponse) -> Iterat line = json.loads(line) except Exception as e: logger.warning(f"failed to parse json: {line}. Exception: {e}") + _raise_for_stream_error(line) yield line @@ -1934,6 +1995,10 @@ def _yield_parsed_json_from_httpbody(body: httpbody_pb2.HttpBody) -> Iterator[An Yields: Any: A JSON object, a line of the original body, or the original body if it is not JSON, or None. + + Raises: + google.genai.errors.APIError: If the stream emits a terminal error + frame. """ content_type = getattr(body, "content_type", None) data = getattr(body, "data", None) @@ -1967,6 +2032,7 @@ def _yield_parsed_json_from_httpbody(body: httpbody_pb2.HttpBody) -> Iterator[An line = json.loads(line) except Exception as e: logger.warning(f"failed to parse json: {line}. Exception: {e}") + _raise_for_stream_error(line) yield line diff --git a/tests/unit/agentplatform/genai/test_agent_engines.py b/tests/unit/agentplatform/genai/test_agent_engines.py index c35fec395f..bc6e301c97 100644 --- a/tests/unit/agentplatform/genai/test_agent_engines.py +++ b/tests/unit/agentplatform/genai/test_agent_engines.py @@ -2133,6 +2133,159 @@ def test_module_loads_without_httpx(self): spec.loader.exec_module(module) assert module.httpx is None + @pytest.mark.parametrize( + "payload, expected_exc, expected_code, expected_status, expected_msg", + [ + ( + ( + '{"code": 429, "message": "Quota exceeded",' + ' "errorCode": "429", "errorMessage": "Quota exceeded"}' + ), + genai_errors.ClientError, + 429, + None, + "Quota exceeded", + ), + ( + ( + '{"code": 498, "message": "Bad input",' + ' "errorCode": "498", "errorMessage": "Bad input"}' + ), + genai_errors.ClientError, + 498, + None, + "Bad input", + ), + ( + ( + 'data: {"errorCode": "PERMISSION_DENIED",' + ' "errorMessage": "Egress denied"}\n\n' + ), + genai_errors.ClientError, + 403, + "PERMISSION_DENIED", + "Egress denied", + ), + ( + ( + '{"errorCode": "StatusCode.RESOURCE_EXHAUSTED",' + ' "errorMessage": "Rate limited"}' + ), + genai_errors.ClientError, + 429, + "RESOURCE_EXHAUSTED", + "Rate limited", + ), + ( + ( + '{"code": 1, "message": "Cancelled",' + ' "errorCode": "1", "errorMessage": "Cancelled"}' + ), + genai_errors.ServerError, + 500, + "1", + "Cancelled", + ), + ( + ( + '{"code": 500, "message": "Internal",' + ' "errorCode": null, "errorMessage": "Internal"}' + ), + genai_errors.ServerError, + 500, + None, + "Internal", + ), + ( + ( + '{"code": null, "message": "Unknown",' + ' "errorCode": "None", "errorMessage": "Unknown"}' + ), + genai_errors.ServerError, + 500, + None, + "Unknown", + ), + ], + ) + def test_yield_parsed_json_raises_on_stream_error_frame( + self, + payload, + expected_exc, + expected_code, + expected_status, + expected_msg, + ): + """Tests that terminal stream error frames raise APIError.""" + response = genai_types.HttpResponse(body=payload) + with pytest.raises(expected_exc) as exc_info: + # pylint: disable=protected-access + list(_runtimes_utils._yield_parsed_json(response)) + assert exc_info.value.code == expected_code + assert exc_info.value.status == expected_status + assert exc_info.value.message == expected_msg + + def test_yield_parsed_json_yields_prior_chunks_before_error_frame(self): + """Tests that chunks preceding a mid-stream error are still yielded.""" + response = genai_types.HttpResponse( + body=( + '{"output": "partial"}\n' + '{"code": 429, "message": "Quota exceeded",' + ' "errorCode": "429", "errorMessage": "Quota exceeded"}' + ) + ) + # pylint: disable=protected-access + gen = _runtimes_utils._yield_parsed_json(response) + assert next(gen) == {"output": "partial"} + with pytest.raises(genai_errors.ClientError) as exc_info: + next(gen) + assert exc_info.value.code == 429 + + @pytest.mark.parametrize( + "payload", + [ + { + "id": "evt-1", + "author": "agent", + "error_code": "SAFETY", + "error_message": "Blocked", + }, + { + "id": "evt-2", + "author": "agent", + "errorCode": "SAFETY", + "errorMessage": "Blocked", + }, + {"errorCode": "0", "errorMessage": ""}, + {"errorCode": "OK", "errorMessage": ""}, + {"errorCode": None, "errorMessage": None}, + {"errorCode": "200", "errorMessage": "ok"}, + {"code": "return 1", "message": "Python snippet"}, + {"code": 429, "message": "No errorCode key"}, + ], + ) + def test_yield_parsed_json_ignores_non_error_frames(self, payload): + """Tests that ADK events and non-error frames are yielded unchanged.""" + response = genai_types.HttpResponse(body=json.dumps(payload)) + # pylint: disable=protected-access + assert list(_runtimes_utils._yield_parsed_json(response)) == [payload] + + def test_yield_parsed_json_from_httpbody_raises_on_error_frame(self): + """Tests that HttpBody terminal stream error frames raise APIError.""" + body = httpbody_pb2.HttpBody( + content_type="text/event-stream", + data=( + b'data: {"errorCode": "PERMISSION_DENIED",' + b' "errorMessage": "Egress denied"}\n\n' + ), + ) + with pytest.raises(genai_errors.ClientError) as exc_info: + # pylint: disable=protected-access + list(_runtimes_utils._yield_parsed_json_from_httpbody(body)) + assert exc_info.value.code == 403 + assert exc_info.value.status == "PERMISSION_DENIED" + assert exc_info.value.message == "Egress denied" + def test_create_base64_encoded_tarball(self): with tempfile.TemporaryDirectory() as tmpdir: test_file_path = os.path.join(tmpdir, "test_file.txt") @@ -5256,6 +5409,96 @@ async def get_and_stream(): chunks = asyncio.run(get_and_stream()) assert chunks == [{"output": "CHUNK"}] + def test_get_runtime_and_async_stream_query_raises_on_midstream_error(self): + """Tests that async_stream_query raises APIError on mid-stream error.""" + + async def mock_async_generator(): + yield genai_types.HttpResponse(body='data: {"output": "CHUNK"}\n\n') + yield genai_types.HttpResponse( + body=( + 'data: {"code": 429, "message": "Quota exceeded",' + ' "errorCode": "429", "errorMessage": "Quota exceeded"}\n\n' + ) + ) + + # pylint: disable=protected-access + api_client = self.client.aio.runtimes._api_client + class_methods = [_TEST_AGENT_ENGINE_CLASS_METHOD_ASYNC_STREAM_QUERY] + with ( + mock.patch.object(api_client, "async_request") as get_request_mock, + mock.patch.object( + api_client, "async_request_streamed" + ) as stream_request_mock, + ): + get_request_mock.return_value = genai_types.HttpResponse( + body=json.dumps( + { + "name": _TEST_AGENT_ENGINE_RESOURCE_NAME, + "spec": {"classMethods": class_methods}, + } + ) + ) + stream_request_mock.return_value = mock_async_generator() + + received = [] + + async def get_and_stream(): + runtime = await self.client.aio.runtimes.get( + name=_TEST_AGENT_ENGINE_RESOURCE_NAME + ) + stream = runtime.async_stream_query(query=_TEST_QUERY_PROMPT) + async for chunk in stream: + received.append(chunk) + + with pytest.raises(genai_errors.ClientError) as exc_info: + asyncio.run(get_and_stream()) + assert received == [{"output": "CHUNK"}] + assert exc_info.value.code == 429 + assert exc_info.value.message == "Quota exceeded" + + def test_get_runtime_and_stream_query_raises_on_midstream_error(self): + """Tests that stream_query raises APIError on mid-stream error.""" + + def mock_stream_generator(): + yield genai_types.HttpResponse(body='{"output": "CHUNK"}\n') + yield genai_types.HttpResponse( + body=( + '{"errorCode": "PERMISSION_DENIED",' + ' "errorMessage": "Egress request is not authorized."}\n' + ) + ) + + # pylint: disable=protected-access + api_client = self.client.runtimes._api_client + with ( + mock.patch.object(api_client, "request") as get_request_mock, + mock.patch.object(api_client, "request_streamed") as stream_mock, + ): + get_request_mock.return_value = genai_types.HttpResponse( + body=json.dumps( + { + "name": _TEST_AGENT_ENGINE_RESOURCE_NAME, + "spec": { + "classMethods": [ + _TEST_AGENT_ENGINE_CLASS_METHOD_STREAM_QUERY, + ] + }, + } + ) + ) + stream_mock.return_value = mock_stream_generator() + + name = _TEST_AGENT_ENGINE_RESOURCE_NAME + runtime = self.client.runtimes.get(name=name) + received = [] + with pytest.raises(genai_errors.ClientError) as exc_info: + for chunk in runtime.stream_query(query=_TEST_QUERY_PROMPT): + received.append(chunk) + assert received == [{"output": "CHUNK"}] + assert exc_info.value.code == 403 + assert exc_info.value.status == "PERMISSION_DENIED" + assert exc_info.value.message == "Egress request is not authorized." + @mock.patch.object(runtimes.Runtimes, "_register_api_methods") @mock.patch.object(_runtimes_utils, "_await_async_operation") @mock.patch.object( diff --git a/vertexai/_genai/_agent_engines_utils.py b/vertexai/_genai/_agent_engines_utils.py index da2b57ad8b..66756dbd8f 100644 --- a/vertexai/_genai/_agent_engines_utils.py +++ b/vertexai/_genai/_agent_engines_utils.py @@ -1997,6 +1997,62 @@ def _strip_sse_framing(line: str) -> str: return payload[1:] if payload.startswith(" ") else payload +_STREAM_ERROR_KEYS = frozenset({"code", "message", "errorCode", "errorMessage"}) +_STREAM_ERROR_STATUS_CODES = { + "INVALID_ARGUMENT": 400, + "UNAUTHENTICATED": 401, + "PERMISSION_DENIED": 403, + "NOT_FOUND": 404, + "RESOURCE_EXHAUSTED": 429, + "UNAVAILABLE": 503, + "DEADLINE_EXCEEDED": 504, +} + + +def _raise_for_stream_error(parsed: Any) -> None: + """Raises `APIError` if `parsed` is a terminal stream error frame.""" + if ( + not isinstance(parsed, dict) + or "errorCode" not in parsed + or ("errorMessage" not in parsed and "message" not in parsed) + or not parsed.keys() <= _STREAM_ERROR_KEYS + ): + return + raw_code = parsed["errorCode"] + if raw_code is None or (isinstance(raw_code, str) and not raw_code.strip()): + raw_code = parsed.get("code") + if isinstance(raw_code, bool) or not raw_code: + return + raw_str = str(raw_code).strip() + upper = raw_str.upper().removeprefix("STATUSCODE.") + if upper in ("", "0", "OK"): + return + status: Optional[str] = None + if upper in _STREAM_ERROR_STATUS_CODES: + status_code, status = _STREAM_ERROR_STATUS_CODES[upper], upper + elif raw_str.isascii() and raw_str.isdigit(): + num = int(raw_str) + if num == 0 or 200 <= num < 300: + return + if 400 <= num < 600: + status_code = num + else: + status_code, status = 500, raw_str + else: + status_code = 500 + if upper != "NONE": + status = upper + message = parsed.get("errorMessage") or parsed.get("message") or "" + error_body: dict[str, Any] = {"code": status_code, "message": str(message)} + if status: + error_body["status"] = status + google_genai_errors.APIError.raise_error( + status_code, + {"error": error_body}, + None, + ) + + def _yield_parsed_json(http_response: google_genai_types.HttpResponse) -> Iterator[Any]: """Converts the body of the HTTP Response message to JSON format. @@ -2006,6 +2062,10 @@ def _yield_parsed_json(http_response: google_genai_types.HttpResponse) -> Iterat Yields: Any: A JSON object or line of the original body or None. + + Raises: + google.genai.errors.APIError: If the stream emits a terminal error + frame. """ if not http_response.body: yield None @@ -2021,6 +2081,7 @@ def _yield_parsed_json(http_response: google_genai_types.HttpResponse) -> Iterat line = json.loads(line) except Exception as e: logger.warning(f"failed to parse json: {line}. Exception: {e}") + _raise_for_stream_error(line) yield line