feat: add stable agentId 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/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,45 @@
 DEFAULT_SOURCE = 10
 
 
+@lru_cache(maxsize=1)
+def _read_config_agent_id() -> Optional[str]:
+    """Return ``agentId`` 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 ``agentId`` 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("agentId")
+    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 from a single, ordered set of sources.
+
+    Order: ``uipath.json#agentId`` (the stable id minted at init time) ->
+    ``UIPATH_AGENT_ID`` env var -> legacy ``PROJECT_KEY`` env var injected by
+    the executor. All span fields carrying an agent identity must go through
+    this helper so they cannot diverge.
+    """
+    from uipath.platform.common.constants import (
+        ENV_PROJECT_KEY,
+        ENV_UIPATH_AGENT_ID,
+    )
+
+    return (
+        _read_config_agent_id()
+        or env.get(ENV_UIPATH_AGENT_ID)
+        or env.get(ENV_PROJECT_KEY)
+    )
+
+
 class AttachmentProvider(IntEnum):
     ORCHESTRATOR = 0
 
@@ -281,9 +321,14 @@ def otel_span_to_uipath_span(
             ]
             attributes_dict["links"] = links_list
 
+        # agentId: prefer the stable id from uipath.json (cached), falling back
+        # to the legacy env vars injected by the executor.
+        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 +342,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_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,6 +151,10 @@ 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()
+        monkeypatch.delenv("PROJECT_KEY", raising=False)
         if env_value is None:
             monkeypatch.delenv("UIPATH_AGENT_ID", raising=False)
         else:
@@ -166,6 +181,129 @@ def test_reference_id_chain(
         assert uipath_span.reference_id == expected
 
 
+class TestAgentIdResolution:
+    """`agentId` span attribute resolution via `resolve_agent_id()`.
+
+    Priority: `uipath.json#agentId` (cached, read once per process) >
+    `UIPATH_AGENT_ID` env var > the legacy `PROJECT_KEY` env var injected by
+    the executor. 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.delenv("UIPATH_AGENT_ID", 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_env(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path
+    ) -> None:
+        (tmp_path / "uipath.json").write_text(json.dumps({"agentId": "from-config"}))
+        monkeypatch.setenv("PROJECT_KEY", "from-env")
+        assert self._resolve(monkeypatch, tmp_path) == "from-config"
+
+    def test_agent_id_from_uipath_json_wins_over_agent_id_env(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path
+    ) -> None:
+        (tmp_path / "uipath.json").write_text(json.dumps({"agentId": "from-config"}))
+        monkeypatch.setenv("UIPATH_AGENT_ID", "from-agent-env")
+        # _resolve clears UIPATH_AGENT_ID, so set it back after the fixture work
+        # is done via a direct resolve call instead.
+        from uipath.platform.common._span_utils import (
+            _read_config_agent_id,
+            resolve_agent_id,
+        )
+
+        _read_config_agent_id.cache_clear()
+        monkeypatch.chdir(tmp_path)
+        assert resolve_agent_id() == "from-config"
+
+    def test_agent_id_env_wins_over_project_key_env(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path
+    ) -> None:
+        # No uipath.json on disk.
+        from uipath.platform.common._span_utils import (
+            _read_config_agent_id,
+            resolve_agent_id,
+        )
+
+        _read_config_agent_id.cache_clear()
+        monkeypatch.chdir(tmp_path)
+        monkeypatch.setenv("UIPATH_AGENT_ID", "from-agent-env")
+        monkeypatch.setenv("PROJECT_KEY", "from-project-key")
+        assert resolve_agent_id() == "from-agent-env"
+
+    def test_agent_id_falls_back_to_project_key_env(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path
+    ) -> None:
+        # No uipath.json on disk.
+        monkeypatch.setenv("PROJECT_KEY", "from-env")
+        assert self._resolve(monkeypatch, tmp_path) == "from-env"
+
+    def test_agent_id_falls_back_when_config_has_no_agent_id(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path
+    ) -> None:
+        (tmp_path / "uipath.json").write_text(json.dumps({"functions": {}}))
+        monkeypatch.setenv("PROJECT_KEY", "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("PROJECT_KEY", 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({"agentId": "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({"agentId": "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

@@ -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

packages/uipath/src/uipath/_cli/_utils/_project_files.py

@@ -36,7 +36,7 @@
 from ._utils._common import determine_project_type
 from ._utils._console import ConsoleLogger
 from ._utils._constants import AGENT_INITIAL_CODE_VERSION, SCHEMA_VERSION
-from ._utils._project_files import read_toml_project
+from ._utils._project_files import read_toml_project, resolve_existing_project_id
 from .middlewares import Middlewares
 from .models.runtime_schema import Bindings, EntryPoint
 from .models.uipath_json_schema import UiPathJsonConfig
@@ -429,10 +429,26 @@ async def initialize() -> list[UiPathRuntimeSchema]:
                 config_path = UiPathConfig.config_file_path
                 if not config_path.exists():
                     config = UiPathJsonConfig.create_default()
+                    config.agent_id = resolve_existing_project_id(
+                        current_directory
+                    ) or str(uuid.uuid4())
                     config.save_to_file(config_path)
                     console.success(f"{Action.CREATED.value} '{config_path}' file.")
                 else:
-                    console.info(f"'{config_path}' already exists, skipping.")
+                    # backfill agentId if not present. Edit the raw JSON so the
+                    # rest of the user's file (key order, omitted defaults) is
+                    # left untouched.
+                    with open(config_path, "r") as f:
+                        raw_config = json.load(f)
+                    if not raw_config.get("agentId"):
+                        raw_config["agentId"] = resolve_existing_project_id(
+                            current_directory
+                        ) or str(uuid.uuid4())
+                        with open(config_path, "w") as f:
+                            json.dump(raw_config, f, indent=2)
+                        console.success(
+                            f"{Action.UPDATED.value} '{config_path}' file with 'agentId'."
+                        )
 
                 # Create bindings.json if it doesn't exist
                 bindings_path = UiPathConfig.bindings_file_path