refactor(platform): use UiPathConfig for trace context, expose extra_baggage API

Replace direct os.getenv() calls with UiPathConfig properties and remove
hardcoded source=agents baggage to keep uipath-platform framework-agnostic.
Add extra_baggage parameter so integration repos can inject their own entries.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ctiliescuuipath

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

@@ -1,20 +1,20 @@
 """W3C-style trace context headers for LLM Gateway requests."""
 
-import os
-
 from opentelemetry import trace
 from uipath.core.feature_flags import FeatureFlags
 
-from ..common.constants import (
-    ENV_FOLDER_KEY,
-    ENV_PROCESS_KEY,
-    ENV_UIPATH_PROCESS_UUID,
-)
+from ..common._config import UiPathConfig
 
 
-def build_trace_context_headers() -> dict[str, str]:
+def build_trace_context_headers(
+    extra_baggage: list[str] | None = None,
+) -> dict[str, str]:
     """Build W3C-style trace context headers from the current OpenTelemetry span.
 
+    Args:
+        extra_baggage: Additional baggage entries (e.g. ``["source=agents"]``)
+            that callers can inject alongside the platform-level entries.
+
     Returns an empty dict when the ``EnableTraceContextHeaders`` feature flag
     is not enabled, or when no active span is present.
     """
@@ -29,13 +29,14 @@ def build_trace_context_headers() -> dict[str, str]:
         span_id = format(ctx.span_id, "016x")
         headers["x-uipath-traceparent-id"] = f"00-{trace_id}-{span_id}"
 
-    baggage_parts: list[str] = ["source=agents"]
-    if folder_key := os.getenv(ENV_FOLDER_KEY):
+    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 := os.getenv(ENV_UIPATH_PROCESS_UUID):
+    if agent_id := UiPathConfig.process_uuid:
         baggage_parts.append(f"agentId={agent_id}")
-    if process_key := os.getenv(ENV_PROCESS_KEY):
+    if process_key := UiPathConfig.process_key:
         baggage_parts.append(f"processKey={process_key}")
-    headers["x-uipath-tracebaggage"] = ",".join(baggage_parts)
+    if baggage_parts:
+        headers["x-uipath-tracebaggage"] = ",".join(baggage_parts)
 
     return headers

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

@@ -121,6 +121,12 @@ def folder_path(self) -> str | None:
 
         return os.getenv(ENV_FOLDER_PATH, None)
 
+    @property
+    def process_key(self) -> str | None:
+        from uipath.platform.common.constants import ENV_PROCESS_KEY
+
+        return os.getenv(ENV_PROCESS_KEY, None)
+
     @property
     def process_uuid(self) -> str | None:
         from uipath.platform.common.constants import ENV_UIPATH_PROCESS_UUID

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

@@ -75,7 +75,7 @@ def test_no_traceparent_without_active_span(self) -> None:
 
 
 class TestBaggageHeader:
-    """When enabled, x-uipath-tracebaggage is populated from env vars."""
+    """When enabled, x-uipath-tracebaggage is populated from UiPathConfig."""
 
     def setup_method(self) -> None:
         FeatureFlags.reset_flags()
@@ -91,7 +91,6 @@ def test_all_env_vars_present(self) -> None:
             headers = build_trace_context_headers()
 
         baggage = headers["x-uipath-tracebaggage"]
-        assert "source=agents" in baggage
         assert "folderKey=folder-abc" in baggage
         assert "agentId=agent-123" in baggage
         assert "processKey=process-789" in baggage
@@ -102,14 +101,13 @@ def test_partial_env_vars(self) -> None:
             headers = build_trace_context_headers()
 
         baggage = headers["x-uipath-tracebaggage"]
-        assert "source=agents" in baggage
         assert "folderKey=folder-only" in baggage
 
-    def test_always_includes_source(self) -> None:
+    def test_no_baggage_without_env_vars(self) -> None:
         with patch.dict(os.environ, {}, clear=True):
             headers = build_trace_context_headers()
 
-        assert headers["x-uipath-tracebaggage"] == "source=agents"
+        assert "x-uipath-tracebaggage" not in headers
 
     def test_baggage_comma_separated(self) -> None:
         env = {
@@ -121,7 +119,25 @@ def test_baggage_comma_separated(self) -> None:
 
         baggage = headers["x-uipath-tracebaggage"]
         parts = baggage.split(",")
-        assert len(parts) == 3  # source + folderKey + agentId
+        assert len(parts) == 2  # folderKey + agentId
+
+    def test_extra_baggage_included(self) -> None:
+        env = {"UIPATH_FOLDER_KEY": "f1"}
+        with patch.dict(os.environ, env, clear=True):
+            headers = build_trace_context_headers(extra_baggage=["source=agents"])
+
+        baggage = headers["x-uipath-tracebaggage"]
+        assert "source=agents" in baggage
+        assert "folderKey=f1" in baggage
+
+    def test_extra_baggage_only(self) -> None:
+        with patch.dict(os.environ, {}, clear=True):
+            headers = build_trace_context_headers(
+                extra_baggage=["source=agents", "custom=value"]
+            )
+
+        baggage = headers["x-uipath-tracebaggage"]
+        assert baggage == "source=agents,custom=value"
 
 
 class TestBothHeaders: