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.64"
+version = "0.1.65"
 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_id
 
 
 def build_trace_context_headers(
@@ -40,8 +40,8 @@ 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:
-        baggage_parts.append(f"agentId={agent_id}")
+    if id := resolve_id():
+        baggage_parts.append(f"agentId={id}")
     if process_key := UiPathConfig.process_key:
         baggage_parts.append(f"processKey={process_key}")
     if baggage_parts:

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,31 @@
 DEFAULT_SOURCE = 10
 
 
+@lru_cache(maxsize=1)
+def _read_config_id() -> Optional[str]:
+    """Return ``id`` from ``uipath.json``, cached for the process lifetime."""
+    from uipath.platform.common._config import UiPathConfig
+
+    try:
+        with open(UiPathConfig.config_file_path, "r") as f:
+            id = json.load(f).get("id")
+    except (OSError, json.JSONDecodeError):
+        return None
+
+    return id if isinstance(id, str) and id else None
+
+
+def resolve_id() -> Optional[str]:
+    """Resolve the id: ``uipath.json#id`` then ``UIPATH_PROCESS_UUID``.
+
+    Single resolver for every consumer (span attribute, trace baggage, eval
+    telemetry) so they cannot diverge.
+    """
+    from uipath.platform.common._config import UiPathConfig
+
+    return _read_config_id() or UiPathConfig.process_uuid
+
+
 class AttachmentProvider(IntEnum):
     ORCHESTRATOR = 0
 
@@ -281,9 +307,12 @@ def otel_span_to_uipath_span(
             ]
             attributes_dict["links"] = links_list
 
+        id = resolve_id()
+        if id:
+            attributes_dict["agentId"] = 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 +326,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_id
+
+        _read_config_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_id_cache():
+    """Isolate the process-global id cache between tests."""
+    from uipath.platform.common._span_utils import _read_config_id
+
+    _read_config_id.cache_clear()
+    yield
+    _read_config_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_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_id
+
+        _read_config_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_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_id
+
+        _read_config_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_id_is_cached(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path
+    ) -> None:
+        from uipath.platform.common._span_utils import _read_config_id
+
+        _read_config_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_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_id() == "first"
+
+        _read_config_id.cache_clear()
+        assert _read_config_id() == "second"
+
+
 class TestNormalizeIds:
     """Tests for OTEL ID normalization functions."""
 

packages/uipath-platform/uv.lock

@@ -121,6 +121,14 @@ Running `uipath init` will process these function definitions and create the cor
 
 `uipath init` generates one `<entrypoint>.mermaid` file per function/agent containing a static call graph, rendered in the UiPath Orchestrator UI. These files are regenerated on every `uipath init`.
 ///
+
+/// warning
+### About the `id` field
+
+The first `uipath init` mints a stable `id` (GUID) into `uipath.json` and preserves it across subsequent runs. It is what identifies your project consistently wherever it is deployed and run.
+
+Do not change or remove it. Changing it makes the project look like a brand-new, unrelated one, so you lose the link to everything previously published and tracked under the old id. `uipath pack` rejects an `id` that is not a valid GUID.
+///
 ---
 
 ::: mkdocs-click

packages/uipath/docs/cli/index.md

@@ -1,13 +1,13 @@
 [project]
 name = "uipath"
-version = "2.10.82"
+version = "2.10.83"
 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"
 dependencies = [
   "uipath-core>=0.5.17, <0.6.0",
   "uipath-runtime>=0.11.0, <0.12.0",
-  "uipath-platform>=0.1.63, <0.2.0",
+  "uipath-platform>=0.1.65, <0.2.0",
   "click>=8.3.1",
   "httpx>=0.28.1",
   "pyjwt>=2.10.1",

packages/uipath/pyproject.toml

@@ -9,6 +9,11 @@
       "type": "string",
       "description": "Reference to this JSON schema for editor support"
     },
+    "id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Stable unique identifier for the project, minted once on the first 'uipath init' and preserved for its lifetime. Used as the package 'projectId' at pack time. Do not change it."
+    },
     "runtimeOptions": {
       "type": "object",
       "description": "Runtime behavior configuration",

packages/uipath/specs/uipath.schema.json

@@ -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_id
+
         if UiPathConfig.project_id:
             properties["ProjectId"] = UiPathConfig.project_id
-        if UiPathConfig.agent_id:
-            properties["AgentId"] = UiPathConfig.agent_id
+        if id := resolve_id():
+            properties["AgentId"] = id
 
         if UiPathConfig.organization_id:
             properties["CloudOrganizationId"] = UiPathConfig.organization_id