feat: add stable agent id to uipath.json for packaging and spans

Author: radu-mocanu

packages/uipath-platform/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uipath-platform"
-version = "0.1.59"
+version = "0.1.60"
 description = "HTTP client library for programmatic access to UiPath Platform"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

packages/uipath-platform/src/uipath/platform/chat/llm_trace_context.py

@@ -5,7 +5,7 @@
 from uipath.core.tracing.span_utils import UiPathSpanUtils
 
 from ..common._config import UiPathConfig
-from ..common._span_utils import _SpanUtils
+from ..common._span_utils import _SpanUtils, resolve_agent_id
 
 
 def build_trace_context_headers(
@@ -40,7 +40,7 @@ def build_trace_context_headers(
     baggage_parts: list[str] = list(extra_baggage) if extra_baggage else []
     if folder_key := UiPathConfig.folder_key:
         baggage_parts.append(f"folderKey={folder_key}")
-    if agent_id := UiPathConfig.agent_id:
+    if agent_id := resolve_agent_id():
         baggage_parts.append(f"agentId={agent_id}")
     if process_key := UiPathConfig.process_key:
         baggage_parts.append(f"processKey={process_key}")

packages/uipath-platform/src/uipath/platform/common/_span_utils.py

@@ -5,6 +5,7 @@
 from dataclasses import dataclass, field
 from datetime import datetime
 from enum import IntEnum
+from functools import lru_cache
 from os import environ as env
 from typing import Any, Dict, List, Optional
 
@@ -19,6 +20,38 @@
 DEFAULT_SOURCE = 10
 
 
+@lru_cache(maxsize=1)
+def _read_config_agent_id() -> Optional[str]:
+    """Return ``id`` from ``uipath.json``, cached for the process lifetime.
+
+    Spans are produced on a hot path, so the project descriptor is read at most
+    once. Returns ``None`` when the file or the ``id`` field is absent, so
+    the caller can fall back to the legacy env vars.
+    """
+    from uipath.platform.common._config import UiPathConfig
+
+    try:
+        with open(UiPathConfig.config_file_path, "r") as f:
+            agent_id = json.load(f).get("id")
+    except (OSError, json.JSONDecodeError):
+        return None
+
+    return agent_id if isinstance(agent_id, str) and agent_id else None
+
+
+def resolve_agent_id() -> Optional[str]:
+    """Resolve the agent id.
+
+    ``uipath.json#id`` (minted at init time) falling back to
+    ``UIPATH_PROCESS_UUID`` injected by the executor at runtime. Single resolver
+    for every consumer carrying an agent identity (span attribute, trace
+    baggage, eval telemetry) so they cannot diverge.
+    """
+    from uipath.platform.common._config import UiPathConfig
+
+    return _read_config_agent_id() or UiPathConfig.process_uuid
+
+
 class AttachmentProvider(IntEnum):
     ORCHESTRATOR = 0
 
@@ -281,9 +314,12 @@ def otel_span_to_uipath_span(
             ]
             attributes_dict["links"] = links_list
 
+        agent_id = resolve_agent_id()
+        if agent_id:
+            attributes_dict["agentId"] = agent_id
+
         # Add process context attributes from environment variables
         for env_key, attr_key in (
-            ("PROJECT_KEY", "agentId"),
             ("UIPATH_PROCESS_KEY", "agentName"),
             ("UIPATH_PROCESS_VERSION", "agentVersion"),
         ):
@@ -297,10 +333,8 @@ def otel_span_to_uipath_span(
         # Top-level fields for internal tracing schema
         execution_type = attributes_dict.get("executionType")
         agent_version = attributes_dict.get("agentVersion")
-        reference_id = (
-            env.get("UIPATH_AGENT_ID")
-            or attributes_dict.get("agentId")
-            or attributes_dict.get("referenceId")
+        reference_id = attributes_dict.get("agentId") or attributes_dict.get(
+            "referenceId"
         )
         verbosity_level = attributes_dict.get("verbosityLevel")
 

packages/uipath-platform/tests/services/test_llm_trace_context.py

@@ -110,13 +110,16 @@ class TestBaggageHeader:
     """When enabled, x-uipath-tracebaggage is populated from UiPathConfig."""
 
     def setup_method(self) -> None:
+        from uipath.platform.common._span_utils import _read_config_agent_id
+
+        _read_config_agent_id.cache_clear()
         FeatureFlags.reset_flags()
         FeatureFlags.configure_flags({FEATURE_FLAG: True})
 
     def test_all_env_vars_present(self) -> None:
         env = {
             "UIPATH_FOLDER_KEY": "folder-abc",
-            "UIPATH_AGENT_ID": "agent-123",
+            "UIPATH_PROCESS_UUID": "agent-123",
             "UIPATH_PROCESS_KEY": "process-789",
         }
         with patch.dict(os.environ, env, clear=True):
@@ -135,22 +138,14 @@ def test_partial_env_vars(self) -> None:
         baggage = headers["x-uipath-tracebaggage"]
         assert "folderKey=folder-only" in baggage
 
-    def test_agent_id_from_agent_id_env(self) -> None:
-        env = {"UIPATH_AGENT_ID": "real-agent-id"}
+    def test_agent_id_from_process_uuid_env(self) -> None:
+        env = {"UIPATH_PROCESS_UUID": "real-agent-id"}
         with patch.dict(os.environ, env, clear=True):
             headers = build_trace_context_headers()
 
         baggage = headers["x-uipath-tracebaggage"]
         assert "agentId=real-agent-id" in baggage
 
-    def test_agent_id_falls_back_to_project_id(self) -> None:
-        env = {"UIPATH_PROJECT_ID": "project-123"}
-        with patch.dict(os.environ, env, clear=True):
-            headers = build_trace_context_headers()
-
-        baggage = headers["x-uipath-tracebaggage"]
-        assert "agentId=project-123" in baggage
-
     def test_no_agent_id_without_env_vars(self) -> None:
         env = {"UIPATH_FOLDER_KEY": "f1"}
         with patch.dict(os.environ, env, clear=True):
@@ -169,7 +164,7 @@ def test_no_baggage_without_env_vars(self) -> None:
     def test_baggage_comma_separated(self) -> None:
         env = {
             "UIPATH_FOLDER_KEY": "f1",
-            "UIPATH_AGENT_ID": "a1",
+            "UIPATH_PROCESS_UUID": "a1",
         }
         with patch.dict(os.environ, env, clear=True):
             headers = build_trace_context_headers()

packages/uipath-platform/tests/services/test_span_utils.py

@@ -10,6 +10,16 @@
 from uipath.platform.common import UiPathSpan, _SpanUtils
 
 
+@pytest.fixture(autouse=True)
+def _clear_agent_id_cache():
+    """Isolate the process-global agentId cache between tests."""
+    from uipath.platform.common._span_utils import _read_config_agent_id
+
+    _read_config_agent_id.cache_clear()
+    yield
+    _read_config_agent_id.cache_clear()
+
+
 class TestOTelToUiPathSpan:
     """OTEL attribute -> top-level UiPathSpan field mapping.
 
@@ -92,10 +102,11 @@ def test_verbosity_level_omitted_when_unset(self) -> None:
 class TestReferenceIdResolution:
     """`reference_id` resolution chain.
 
-    Priority: `UIPATH_AGENT_ID` env var > `agentId` attribute > `referenceId`
-    attribute. Falsy values (missing / empty string) at each step fall through
-    to the next source. The `referenceId` fallback exists for backwards
-    compatibility with older producers that only emit that attribute.
+    `reference_id` is derived from the span's resolved `agentId` attribute
+    (which itself goes through `resolve_agent_id()`), falling back to the
+    `referenceId` attribute. Falsy values (missing / empty string) at each step
+    fall through to the next source. The `referenceId` fallback exists for
+    backwards compatibility with older producers that only emit that attribute.
     """
 
     @pytest.mark.parametrize(
@@ -105,7 +116,7 @@ class TestReferenceIdResolution:
                 "env-agent",
                 {"agentId": "attr-agent", "referenceId": "attr-ref"},
                 "env-agent",
-                id="env-var-wins",
+                id="env-var-overrides-attr",
             ),
             pytest.param(
                 None,
@@ -140,10 +151,13 @@ def test_reference_id_chain(
         expected: str | None,
         monkeypatch: pytest.MonkeyPatch,
     ) -> None:
+        from uipath.platform.common._span_utils import _read_config_agent_id
+
+        _read_config_agent_id.cache_clear()
         if env_value is None:
-            monkeypatch.delenv("UIPATH_AGENT_ID", raising=False)
+            monkeypatch.delenv("UIPATH_PROCESS_UUID", raising=False)
         else:
-            monkeypatch.setenv("UIPATH_AGENT_ID", env_value)
+            monkeypatch.setenv("UIPATH_PROCESS_UUID", env_value)
 
         mock_span = Mock(spec=OTelSpan)
         mock_context = SpanContext(
@@ -166,6 +180,96 @@ def test_reference_id_chain(
         assert uipath_span.reference_id == expected
 
 
+class TestAgentIdResolution:
+    """`agentId` span attribute resolution via `resolve_agent_id()`.
+
+    Priority: `uipath.json#id` (cached, read once per process) >
+    `UIPATH_PROCESS_UUID` env var injected by the executor at runtime. When no
+    source is present the `agentId` attribute is omitted entirely.
+    """
+
+    @staticmethod
+    def _make_span() -> Mock:
+        mock_span = Mock(spec=OTelSpan)
+        mock_context = SpanContext(
+            trace_id=0x123456789ABCDEF0123456789ABCDEF0,
+            span_id=0x0123456789ABCDEF,
+            is_remote=False,
+        )
+        mock_span.get_span_context.return_value = mock_context
+        mock_span.name = "test-span"
+        mock_span.parent = None
+        mock_span.status.status_code = StatusCode.OK
+        mock_span.attributes = {}
+        mock_span.events = []
+        mock_span.links = []
+        now_ns = int(datetime.now().timestamp() * 1e9)
+        mock_span.start_time = now_ns
+        mock_span.end_time = now_ns + 1_000_000
+        return mock_span
+
+    @staticmethod
+    def _resolve(monkeypatch: pytest.MonkeyPatch, tmp_path) -> object:
+        from uipath.platform.common._span_utils import _read_config_agent_id
+
+        _read_config_agent_id.cache_clear()
+        monkeypatch.delenv("UIPATH_CONFIG_PATH", raising=False)
+        monkeypatch.chdir(tmp_path)
+        uipath_span = _SpanUtils.otel_span_to_uipath_span(
+            TestAgentIdResolution._make_span(), serialize_attributes=False
+        )
+        attributes = uipath_span.attributes
+        assert isinstance(attributes, dict)
+        return attributes.get("agentId")
+
+    def test_agent_id_from_uipath_json_wins_over_process_uuid(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path
+    ) -> None:
+        (tmp_path / "uipath.json").write_text(json.dumps({"id": "from-config"}))
+        monkeypatch.setenv("UIPATH_PROCESS_UUID", "from-env")
+        assert self._resolve(monkeypatch, tmp_path) == "from-config"
+
+    def test_agent_id_falls_back_to_process_uuid(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path
+    ) -> None:
+        # No uipath.json on disk.
+        monkeypatch.setenv("UIPATH_PROCESS_UUID", "from-env")
+        assert self._resolve(monkeypatch, tmp_path) == "from-env"
+
+    def test_agent_id_falls_back_when_config_has_no_id(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path
+    ) -> None:
+        (tmp_path / "uipath.json").write_text(json.dumps({"functions": {}}))
+        monkeypatch.setenv("UIPATH_PROCESS_UUID", "from-env")
+        assert self._resolve(monkeypatch, tmp_path) == "from-env"
+
+    def test_agent_id_absent_when_no_source(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path
+    ) -> None:
+        monkeypatch.delenv("UIPATH_PROCESS_UUID", raising=False)
+        assert self._resolve(monkeypatch, tmp_path) is None
+
+    def test_config_agent_id_is_cached(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path
+    ) -> None:
+        from uipath.platform.common._span_utils import _read_config_agent_id
+
+        _read_config_agent_id.cache_clear()
+        monkeypatch.delenv("UIPATH_CONFIG_PATH", raising=False)
+        monkeypatch.chdir(tmp_path)
+        config = tmp_path / "uipath.json"
+
+        config.write_text(json.dumps({"id": "first"}))
+        assert _read_config_agent_id() == "first"
+
+        # A later edit is not observed: the value is read once and cached.
+        config.write_text(json.dumps({"id": "second"}))
+        assert _read_config_agent_id() == "first"
+
+        _read_config_agent_id.cache_clear()
+        assert _read_config_agent_id() == "second"
+
+
 class TestNormalizeIds:
     """Tests for OTEL ID normalization functions."""
 

packages/uipath-platform/uv.lock

@@ -1,6 +1,6 @@
 [project]
 name = "uipath"
-version = "2.10.75"
+version = "2.10.76"
 description = "Python SDK and CLI for UiPath Platform, enabling programmatic interaction with automation services, process management, and deployment tools."
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

packages/uipath/pyproject.toml

@@ -308,10 +308,12 @@ def _enrich_properties(self, properties: dict[str, Any]) -> None:
         Args:
             properties: The properties dictionary to enrich.
         """
+        from uipath.platform.common._span_utils import resolve_agent_id
+
         if UiPathConfig.project_id:
             properties["ProjectId"] = UiPathConfig.project_id
-        if UiPathConfig.agent_id:
-            properties["AgentId"] = UiPathConfig.agent_id
+        if agent_id := resolve_agent_id():
+            properties["AgentId"] = agent_id
 
         if UiPathConfig.organization_id:
             properties["CloudOrganizationId"] = UiPathConfig.organization_id

packages/uipath/src/uipath/_cli/_evals/_telemetry.py

@@ -25,6 +25,34 @@
 logger = logging.getLogger(__name__)
 
 
+def resolve_existing_project_id(directory: str = ".") -> Optional[str]:
+    """Return an already-established project id for this project, if any.
+
+    Checks the Studio Web project env var first, then falls back to the legacy
+    ``ProjectKey`` stored in ``.uipath/.telemetry.json``. Returns ``None`` when
+    neither is present.
+
+    Args:
+        directory: The project root directory to look for the telemetry file in.
+    """
+    from ...telemetry._constants import _PROJECT_KEY, _TELEMETRY_CONFIG_FILE
+
+    if project_id := UiPathConfig.project_id:
+        return project_id
+
+    telemetry_file = os.path.join(directory, ".uipath", _TELEMETRY_CONFIG_FILE)
+    if os.path.exists(telemetry_file):
+        try:
+            with open(telemetry_file, "r") as f:
+                telemetry_data = json.load(f)
+                if project_id := telemetry_data.get(_PROJECT_KEY):
+                    return project_id
+        except (json.JSONDecodeError, IOError):
+            pass
+
+    return None
+
+
 class Severity(IntEnum):
     LOG = 0
     WARNING = 1