From 7ac3f470a8339b8b9ff1d899b729ca9ad3204dd8 Mon Sep 17 00:00:00 2001 From: Daniel Joica Date: Tue, 17 Nov 2026 10:27:40 +0200 Subject: [PATCH 1/2] fix(guardrails): drop the client evaluate_guardrail span in jobs [AL-712] In a job, the Guardrails Service publishes its own span for each evaluation (e.g. "PII Detection"), so the client-side evaluate_guardrail span duplicated it. Skip the client span when a job key is set; local runs keep it, since the service span does not reach their trace. Co-Authored-By: Claude Opus 5.5 --- packages/uipath-platform/pyproject.toml | 2 +- .../guardrails/_guardrails_service.py | 40 ++++++++- .../tests/services/test_guardrails_service.py | 81 +++++++++++++++++++ packages/uipath-platform/uv.lock | 2 +- packages/uipath/uv.lock | 2 +- 5 files changed, 123 insertions(+), 4 deletions(-) diff --git a/packages/uipath-platform/pyproject.toml b/packages/uipath-platform/pyproject.toml index 413a6c63c..1fa8ed8c6 100644 --- a/packages/uipath-platform/pyproject.toml +++ b/packages/uipath-platform/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "uipath-platform" -version = "0.3.7" +version = "0.3.8" description = "HTTP client library for programmatic access to UiPath Platform" readme = { file = "README.md", content-type = "text/markdown" } requires-python = ">=3.11" diff --git a/packages/uipath-platform/src/uipath/platform/guardrails/_guardrails_service.py b/packages/uipath-platform/src/uipath/platform/guardrails/_guardrails_service.py index 2af4f0e87..5ef2b3a6f 100644 --- a/packages/uipath-platform/src/uipath/platform/guardrails/_guardrails_service.py +++ b/packages/uipath-platform/src/uipath/platform/guardrails/_guardrails_service.py @@ -132,7 +132,6 @@ def _parse_error_type(result_str: Any) -> Optional[GuardrailValidationErrorType] except ValueError: return None - @traced("evaluate_guardrail", run_type="uipath") def evaluate_guardrail( self, input_data: str | dict[str, Any], @@ -155,6 +154,45 @@ def evaluate_guardrail( Returns: GuardrailValidationResult: The outcome of the guardrail evaluation. """ + # In a job, the Guardrails Service publishes its own span for this + # evaluation, so a client span would only duplicate it. Local runs don't + # get that span in their trace, so they keep the client one. + evaluate = ( + self._evaluate_guardrail + if UiPathConfig.job_key + else self._traced_evaluate_guardrail + ) + return evaluate( + input_data, + guardrail, + attachments=attachments, + termination_mode=termination_mode, + ) + + @traced("evaluate_guardrail", run_type="uipath") + def _traced_evaluate_guardrail( + self, + input_data: str | dict[str, Any], + guardrail: BuiltInValidatorGuardrail, + *, + attachments: list[GuardrailAttachment] | None = None, + termination_mode: GuardrailTerminationMode | None = None, + ) -> GuardrailValidationResult: + return self._evaluate_guardrail( + input_data, + guardrail, + attachments=attachments, + termination_mode=termination_mode, + ) + + def _evaluate_guardrail( + self, + input_data: str | dict[str, Any], + guardrail: BuiltInValidatorGuardrail, + *, + attachments: list[GuardrailAttachment] | None = None, + termination_mode: GuardrailTerminationMode | None = None, + ) -> GuardrailValidationResult: parameters = [ param.model_dump(by_alias=True) for param in guardrail.validator_parameters ] diff --git a/packages/uipath-platform/tests/services/test_guardrails_service.py b/packages/uipath-platform/tests/services/test_guardrails_service.py index 652b628fc..c7e7ccab5 100644 --- a/packages/uipath-platform/tests/services/test_guardrails_service.py +++ b/packages/uipath-platform/tests/services/test_guardrails_service.py @@ -1,8 +1,15 @@ import json import logging +from typing import Iterator import httpx import pytest +from opentelemetry import trace +from opentelemetry.sdk.trace import TracerProvider +from opentelemetry.sdk.trace.export import SimpleSpanProcessor +from opentelemetry.sdk.trace.export.in_memory_span_exporter import ( + InMemorySpanExporter, +) from pytest_httpx import HTTPXMock from uipath.core.guardrails import ( GuardrailScope, @@ -1490,3 +1497,77 @@ def test_evaluated_results_have_no_error_type( assert result.error_type is None assert result.reason == "Evaluated" assert not [r for r in caplog.records if r.name == _SERVICE_LOGGER] + + +@pytest.fixture +def recorded_spans(monkeypatch: pytest.MonkeyPatch) -> Iterator[InMemorySpanExporter]: + """Record every span, including any @traced would open, in memory.""" + provider = TracerProvider() + exporter = InMemorySpanExporter() + provider.add_span_processor(SimpleSpanProcessor(exporter)) + monkeypatch.setattr(trace, "get_tracer", provider.get_tracer) + yield exporter + provider.shutdown() + + +class TestEvaluateGuardrailSpan: + """In a job the Guardrails Service's span is the only evaluation span (AL-712).""" + + def _evaluate_under_caller( + self, + httpx_mock: HTTPXMock, + service: GuardrailsService, + url: str, + ) -> int: + httpx_mock.add_response( + url=url, status_code=200, json={"result": "PASSED", "details": ""} + ) + with trace.get_tracer("test").start_as_current_span("caller") as caller: + service.evaluate_guardrail("some text", _judge_guardrail()) + return caller.get_span_context().span_id + + def test_job_run_opens_no_client_span( + self, + httpx_mock: HTTPXMock, + service: GuardrailsService, + base_url: str, + org: str, + tenant: str, + recorded_spans: InMemorySpanExporter, + monkeypatch: pytest.MonkeyPatch, + ) -> None: + monkeypatch.setenv("UIPATH_JOB_KEY", "job-123") + monkeypatch.setenv("UIPATH_TRACE_ID", "0af7651916cd43dd8448eb211c80319c") + + caller_span_id = self._evaluate_under_caller( + httpx_mock, service, f"{base_url}{org}{tenant}{_VALIDATE_PATH}" + ) + + assert [s.name for s in recorded_spans.get_finished_spans()] == ["caller"] + # The service's span is parented directly to the caller's span. + request = httpx_mock.get_request() + assert request is not None + assert request.headers["x-uipath-traceparent-id"].split("-")[2] == format( + caller_span_id, "016x" + ) + + def test_local_run_keeps_client_span( + self, + httpx_mock: HTTPXMock, + service: GuardrailsService, + base_url: str, + org: str, + tenant: str, + recorded_spans: InMemorySpanExporter, + monkeypatch: pytest.MonkeyPatch, + ) -> None: + monkeypatch.delenv("UIPATH_JOB_KEY", raising=False) + + caller_span_id = self._evaluate_under_caller( + httpx_mock, service, f"{base_url}{org}{tenant}{_VALIDATE_PATH}" + ) + + spans = {s.name: s for s in recorded_spans.get_finished_spans()} + assert set(spans) == {"caller", "evaluate_guardrail"} + parent = spans["evaluate_guardrail"].parent + assert parent is not None and parent.span_id == caller_span_id diff --git a/packages/uipath-platform/uv.lock b/packages/uipath-platform/uv.lock index 4530e2ed5..525de4ee2 100644 --- a/packages/uipath-platform/uv.lock +++ b/packages/uipath-platform/uv.lock @@ -1095,7 +1095,7 @@ dev = [ [[package]] name = "uipath-platform" -version = "0.3.7" +version = "0.3.8" source = { editable = "." } dependencies = [ { name = "anyio" }, diff --git a/packages/uipath/uv.lock b/packages/uipath/uv.lock index 6b4d34ce2..4fd25d665 100644 --- a/packages/uipath/uv.lock +++ b/packages/uipath/uv.lock @@ -2762,7 +2762,7 @@ wheels = [ [[package]] name = "uipath-platform" -version = "0.3.7" +version = "0.3.8" source = { editable = "../uipath-platform" } dependencies = [ { name = "anyio" }, From 098aa61fc57650bc55db4e96c07ae36f3a0eff2e Mon Sep 17 00:00:00 2001 From: Daniel Joica Date: Tue, 17 Nov 2026 10:56:33 +0200 Subject: [PATCH 2/2] refactor(guardrails): split evaluate_guardrail into helpers [AL-712] Addresses Sonar findings on #1997: reduce the cognitive complexity of the validate call by moving the payload, headers, request and result mapping into their own helpers (no behaviour change), and split a composite test assertion. Co-Authored-By: Claude Opus 5.5 --- .../guardrails/_guardrails_service.py | 135 ++++++++++-------- .../tests/services/test_guardrails_service.py | 3 +- 2 files changed, 75 insertions(+), 63 deletions(-) diff --git a/packages/uipath-platform/src/uipath/platform/guardrails/_guardrails_service.py b/packages/uipath-platform/src/uipath/platform/guardrails/_guardrails_service.py index 5ef2b3a6f..b08ab4537 100644 --- a/packages/uipath-platform/src/uipath/platform/guardrails/_guardrails_service.py +++ b/packages/uipath-platform/src/uipath/platform/guardrails/_guardrails_service.py @@ -1,3 +1,4 @@ +import json import logging import re from typing import Any, Optional @@ -193,13 +194,38 @@ def _evaluate_guardrail( attachments: list[GuardrailAttachment] | None = None, termination_mode: GuardrailTerminationMode | None = None, ) -> GuardrailValidationResult: - parameters = [ - param.model_dump(by_alias=True) for param in guardrail.validator_parameters - ] + spec = RequestSpec( + method="POST", + endpoint=Endpoint("/agentsruntime_/api/execution/guardrails/validate"), + json=self._build_validate_payload( + input_data, guardrail, attachments, termination_mode + ), + ) + request_kwargs: dict[str, Any] = { + "json": spec.json, + "headers": self._build_validate_headers(spec, attachments), + } + if attachments: + request_kwargs["timeout"] = _ATTACHMENT_VALIDATE_TIMEOUT_SECONDS + + response_data, span_id = self._send_validate_request(spec, request_kwargs) + return self._to_validation_result(response_data, span_id, guardrail.name) + + @staticmethod + def _build_validate_payload( + input_data: str | dict[str, Any], + guardrail: BuiltInValidatorGuardrail, + attachments: list[GuardrailAttachment] | None, + termination_mode: GuardrailTerminationMode | None, + ) -> dict[str, Any]: + """Build the body of a validate request.""" payload: dict[str, Any] = { "validator": guardrail.validator_type, "input": input_data if isinstance(input_data, str) else str(input_data), - "parameters": parameters, + "parameters": [ + param.model_dump(by_alias=True) + for param in guardrail.validator_parameters + ], "guardrailName": guardrail.name, } if guardrail.validator_type == BYO_VALIDATOR_TYPE: @@ -212,16 +238,20 @@ def _evaluate_guardrail( payload["attachments"] = [a.model_dump(by_alias=True) for a in attachments] if termination_mode is not None: payload["terminationMode"] = termination_mode.value - spec = RequestSpec( - method="POST", - endpoint=Endpoint("/agentsruntime_/api/execution/guardrails/validate"), - json=payload, - ) - # Include trace context headers for server-side span correlation, plus - # the execution source (x-uipath-guardrails-source) and job key headers - # for licensing/metering correlation. The execution source is read from - # the execution context, propagated from the runtime context. - trace_headers = build_trace_context_headers(extra_baggage=["source=agents"]) + return payload + + def _build_validate_headers( + self, + spec: RequestSpec, + attachments: list[GuardrailAttachment] | None, + ) -> dict[str, str]: + """Build the headers of a validate request. + + Includes trace context headers for server-side span correlation, plus + the execution source (x-uipath-guardrails-source) and job key headers + for licensing/metering correlation. The execution source is read from + the execution context, propagated from the runtime context. + """ source_headers: dict[str, str] = {} execution_source = self._execution_context.execution_source if execution_source: @@ -229,62 +259,44 @@ def _evaluate_guardrail( folder_headers: dict[str, str] = {} if attachments and UiPathConfig.folder_key: folder_headers[HEADER_FOLDER_KEY] = UiPathConfig.folder_key - request_headers = { + return { **(spec.headers or {}), - **trace_headers, + **build_trace_context_headers(extra_baggage=["source=agents"]), **source_headers, **header_job_key(), **folder_headers, } - request_kwargs: dict[str, Any] = { - "json": spec.json, - "headers": request_headers, - } - if attachments: - request_kwargs["timeout"] = _ATTACHMENT_VALIDATE_TIMEOUT_SECONDS - span_id = None + def _send_validate_request( + self, spec: RequestSpec, request_kwargs: dict[str, Any] + ) -> tuple[dict[str, Any], str | None]: + """Send a validate request; return the response body and the service span id.""" try: - response = self.request( - spec.method, - url=spec.endpoint, - **request_kwargs, - ) - span_id = self._extract_span_id_from_traceparent( - response.headers.get("x-uipath-traceparent-id") - ) - response_data = response.json() + response = self.request(spec.method, url=spec.endpoint, **request_kwargs) except EnrichedException as e: - # Handle 403 responses: API returns 403 with valid JSON body for - # ENTITLEMENTS_MISSING or FEATURE_DISABLED cases - if e.status_code == 403: - # Access the original HTTPStatusError to get the full response - original_error = e.__cause__ - if ( - isinstance(original_error, HTTPStatusError) - and original_error.response - ): - try: - span_id = self._extract_span_id_from_traceparent( - original_error.response.headers.get( - "x-uipath-traceparent-id" - ) - ) - response_data = original_error.response.json() - except Exception: - # If JSON parsing fails, re-raise the original exception - raise - else: - # Try to parse from response_content if available - try: - import json - - response_data = json.loads(e.response_content) - except Exception: - raise - else: + # The API returns 403 with a valid JSON body for ENTITLEMENTS_MISSING + # or FEATURE_DISABLED; any other error is raised. + if e.status_code != 403: raise + # Read the full response from the original HTTPStatusError when + # there is one, else parse the body kept on the exception. + original_error = e.__cause__ + if isinstance(original_error, HTTPStatusError) and original_error.response: + response = original_error.response + else: + return json.loads(e.response_content), None + span_id = self._extract_span_id_from_traceparent( + response.headers.get("x-uipath-traceparent-id") + ) + return response.json(), span_id + def _to_validation_result( + self, + response_data: dict[str, Any], + span_id: str | None, + guardrail_name: str, + ) -> GuardrailValidationResult: + """Map a validate response body to a GuardrailValidationResult.""" result_str = response_data.get("result", "") reason = response_data.get("details", "") @@ -294,7 +306,7 @@ def _evaluate_guardrail( # guardrail action still fires, and report why on error_type. logger.warning( "Guardrail '%s' could not be evaluated (%s): %s", - guardrail.name, + guardrail_name, result_str, reason, ) @@ -302,7 +314,6 @@ def _evaluate_guardrail( else: result = self._parse_result(result_str) - # Prepare model data model_data: dict[str, Any] = { "result": result.value, "reason": reason, diff --git a/packages/uipath-platform/tests/services/test_guardrails_service.py b/packages/uipath-platform/tests/services/test_guardrails_service.py index c7e7ccab5..ba4e177d0 100644 --- a/packages/uipath-platform/tests/services/test_guardrails_service.py +++ b/packages/uipath-platform/tests/services/test_guardrails_service.py @@ -1570,4 +1570,5 @@ def test_local_run_keeps_client_span( spans = {s.name: s for s in recorded_spans.get_finished_spans()} assert set(spans) == {"caller", "evaluate_guardrail"} parent = spans["evaluate_guardrail"].parent - assert parent is not None and parent.span_id == caller_span_id + assert parent is not None + assert parent.span_id == caller_span_id