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,25 @@
 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 ``PROJECT_KEY`` env var.
+    """
+    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
+
+
 class AttachmentProvider(IntEnum):
     ORCHESTRATOR = 0
 
@@ -281,9 +301,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 PROJECT_KEY env var injected by the executor.
+        agent_id = _read_config_agent_id() or env.get("PROJECT_KEY")
+        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"),
         ):

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.
 
@@ -166,6 +176,97 @@ def test_reference_id_chain(
         assert uipath_span.reference_id == expected
 
 
+class TestAgentIdResolution:
+    """`agentId` span attribute resolution.
+
+    Priority: `uipath.json#agentId` (cached, read once per process) > the legacy
+    `PROJECT_KEY` env var injected by the executor. When neither 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_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.73"
+version = "2.10.74"
 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,22 @@ 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
+                    config = UiPathJsonConfig.load_from_file(str(config_path))
+                    if not config.agent_id:
+                        config.agent_id = resolve_existing_project_id(
+                            current_directory
+                        ) or str(uuid.uuid4())
+                        config.save_to_file(config_path)
+                        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

packages/uipath/src/uipath/_cli/cli_init.py

@@ -8,11 +8,10 @@
 from pydantic import TypeAdapter
 
 from uipath._cli.models.runtime_schema import Bindings, EntryPoint, EntryPoints
-from uipath._cli.models.uipath_json_schema import RuntimeOptions, UiPathJsonConfig
+from uipath._cli.models.uipath_json_schema import UiPathJsonConfig
 from uipath.eval.constants import EVALS_FOLDER, LEGACY_EVAL_FOLDER
 from uipath.platform.common import UiPathConfig
 
-from ..telemetry._constants import _PROJECT_KEY, _TELEMETRY_CONFIG_FILE
 from ._telemetry import track_command
 from ._utils._common import determine_project_type
 from ._utils._console import ConsoleLogger
@@ -21,6 +20,7 @@
     files_to_include,
     get_project_config,
     read_toml_project,
+    resolve_existing_project_id,
     validate_config,
 )
 from ._utils._uv_helpers import handle_uv_operations
@@ -30,31 +30,6 @@
 schema = "https://cloud.uipath.com/draft/2024-12/entry-point"
 
 
-def get_project_id() -> str:
-    """Get project ID from telemetry file if it exists, otherwise generate a new one.
-
-    Returns:
-        Project ID string (either from telemetry file or newly generated).
-    """
-    # first check if this is a studio project
-    if project_id := UiPathConfig.project_id:
-        return project_id
-
-    telemetry_file = os.path.join(".uipath", _TELEMETRY_CONFIG_FILE)
-
-    if os.path.exists(telemetry_file):
-        try:
-            with open(telemetry_file, "r") as f:
-                telemetry_data = json.load(f)
-                project_id = telemetry_data.get(_PROJECT_KEY)
-                if project_id:
-                    return project_id
-        except (json.JSONDecodeError, IOError):
-            pass
-
-    return str(uuid.uuid4())
-
-
 def get_project_version(directory):
     toml_path = os.path.join(directory, "pyproject.toml")
     if not os.path.exists(toml_path):
@@ -72,14 +47,18 @@ def validate_config_structure(config_data):
 
 
 def generate_operate_file(
-    entrypoints: list[EntryPoint], runtimeOptions: RuntimeOptions, dependencies=None
+    entrypoints: list[EntryPoint],
+    config: UiPathJsonConfig,
+    dependencies=None,
 ):
     if not entrypoints:
         raise ValueError(
             "No entry points found in entry-points.json. Please run 'uipath init' to generate valid entry points."
         )
 
-    project_id = get_project_id()
+    # prefer agentId from uipath.json; fall back to the legacy
+    # .telemetry.json or SW project id.
+    project_id = config.agent_id or resolve_existing_project_id() or str(uuid.uuid4())
 
     project_type = determine_project_type(entrypoints)
     first_entry = entrypoints[0]
@@ -94,7 +73,7 @@ def generate_operate_file(
         "runtimeOptions": {
             "requiresUserInteraction": False,
             "isAttended": False,
-            "isConversational": runtimeOptions.is_conversational,
+            "isConversational": config.runtime_options.is_conversational,
         },
     }
 
@@ -238,9 +217,7 @@ def pack_fn(
     with open(config_path, "r") as f:
         config_data = TypeAdapter(UiPathJsonConfig).validate_python(json.load(f))
 
-    operate_file = generate_operate_file(
-        entrypoints, config_data.runtime_options, dependencies
-    )
+    operate_file = generate_operate_file(entrypoints, config_data, dependencies)
 
     # try to read bindings from bindings.json
     bindings_path = os.path.join(directory, str(UiPathConfig.bindings_file_path))

packages/uipath/src/uipath/_cli/cli_pack.py

@@ -68,6 +68,13 @@ class UiPathJsonConfig(BaseModelWithDefaultConfig):
         alias="$schema",
         description="Reference to the JSON schema for editor support",
     )
+    agent_id: str | None = Field(
+        default=None,
+        alias="agentId",
+        description="Stable unique identifier for the agent. Minted once at "
+        "project creation (by 'uipath init' or Studio Web) and preserved for the "
+        "lifetime of the project. Used as the package 'projectId' at pack time.",
+    )
     runtime_options: RuntimeOptions = Field(
         default_factory=RuntimeOptions,
         alias="runtimeOptions",