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

[radu-mocanu]

Summary

• uipath init mints a stable agentId into uipath.json, preserved across re-init and backfilled for existing projects
• uipath pack sources the package projectId from uipath.json#agentId, falling back to the legacy .telemetry.json ProjectKey
• llmops spans now carry agentId read from uipath.json (cached), falling back to the PROJECT_KEY env var
• span path caches only the agentId string, not the whole uipath.json (immutable value, no shared-mutable-cache footgun)

Why

a coded agent needs one stable identifier that survives authoring, packaging, and runtime so traces and deployed releases correlate back to the same agent. anchoring it in uipath.json also decouples the id from telemetry being enabled.

[Copilot]

Pull request overview

This PR introduces a stable agentId stored in uipath.json and wires it through project initialization, packaging (operate.json projectId), and LLMOps span attributes to enable consistent correlation across authoring, packaging, and runtime.

Changes:

• Add agentId to the uipath.json schema and mint/backfill it during uipath init (preserving existing values).
• Update uipath pack to source operate.json#projectId from uipath.json#agentId, with fallback to legacy .uipath/.telemetry.json ProjectKey.
• Update span attribute resolution to prefer cached uipath.json#agentId, falling back to PROJECT_KEY, and add/adjust tests accordingly.

Reviewed changes

Copilot reviewed 10 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/uipath/src/uipath/_cli/models/uipath_json_schema.py	Adds agentId field to the typed uipath.json configuration model.
packages/uipath/src/uipath/_cli/cli_init.py	Mints/backfills agentId into uipath.json during uipath init.
packages/uipath/src/uipath/_cli/_utils/_project_files.py	Introduces resolve_existing_project_id() to reuse Studio Web/env or legacy telemetry ProjectKey.
packages/uipath/src/uipath/_cli/cli_pack.py	Switches packaging to use agentId as projectId and removes old inline telemetry lookup.
packages/uipath/tests/cli/test_init.py	Adds coverage for minting/backfilling/preserving agentId across init scenarios.
packages/uipath/tests/cli/test_pack.py	Adds coverage for projectId sourcing from agentId and legacy telemetry fallback.
packages/uipath-platform/src/uipath/platform/common/_span_utils.py	Adds cached read of agentId from uipath.json and uses it for span agentId.
packages/uipath-platform/tests/services/test_span_utils.py	Adds tests for agentId resolution priority and caching behavior; clears cache between tests.
packages/uipath/pyproject.toml	Bumps uipath version.
packages/uipath/uv.lock	Updates lockfile metadata / versions.
packages/uipath-platform/pyproject.toml	Bumps uipath-platform version.
packages/uipath-platform/uv.lock	Updates lockfile metadata / versions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[RobinMennens-UiPath]

Took a pass focused on the agentId behavior across the coded agent types, regressions, and the spans. Two things I'd like to align on before this goes in:

For plain functions and declarative agents this is end-to-end correct. But langgraph/llamaindex agents build their own operate.json in the plugin repos and won't source projectId from uipath.json#agentId until we mirror this there. Is there a follow-up tracking that, or is the expectation that those plugins start reading uipath.json#agentId?

Separately, on alignment with the vertical-solutions-check-agent-id.yml check: that check looks for a coded agent's ID only in .uipath/.telemetry.json#ProjectKey or .uipath/local-project-id.json#projectId — not in uipath.json#agentId. With telemetry disabled, create_telemetry_config_file doesn't write .telemetry.json, and we don't write local-project-id.json either, so an agent inited by this PR would have its ID only in uipath.json and the CI check would report it as missing. Are we updating that check to read uipath.json#agentId too, or should init also write one of the files it expects? These two need to agree.

[radu-mocanu]

But langgraph/llamaindex agents build their own operate.json in the plugin repos and won't source projectId from uipath.json#agentId

This is not true.
All UiPath Coded Agents are using the same packager. No changes are needed in the integration repos.

[radu-mocanu]

Separately, on alignment with the vertical-solutions-check-agent-id.yml check

This is not a concern for the coded agents SDK. the changes are backwards compatible, meaning that existing IDs will still be honored. newly created agents will indeed drop telemetry.json file. Any consumer (like that gh action) need to be updated to reflect the new behaviour -> uipath.json as the source of truth.

[github-actions]

🚨 Heads up: uipath-integrations cross-tests are FAILING 🚨

Your changes may break one or more integrations in uipath-integrations-python:

• uipath-openai-agents
• uipath-google-adk
• uipath-agent-framework
• uipath-llamaindex
• uipath-pydantic-ai

⚠️ These checks are NOT enforced by branch protection rules. Please review the failures before merging.

🔍 Inspect the failed run →

[sonarqubecloud]

Quality Gate failed

Failed conditions
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

[alexandra-c]

Could we extend this to cover function project types as well? agentId isn't the right name for a coded function, could we detect the project type and use functionId accordingly, or pick a generic name that works for both?

[RobinMennens-UiPath]

Could we extend this to cover function project types as well? agentId isn't the right name for a coded function, could we detect the project type and use functionId accordingly, or pick a generic name that works for both?

If you ask me, everything that can run on the UiPath platform should have a unique GUID identifier that never changes. RPA, coded functions, coded agents, low code agents, etc.
ProjectId kind of already seems a generic candidate for that.. but agentId already got introduced as a special ID just for agents.
We either keep introducing special IDs such as functionId, or we try to limit the number of IDs we have and stick to a generic ProjectId or something similar
CC @JosephMar

[radu-mocanu]

We either keep introducing special IDs such as functionId, or we try to limit the number of IDs we have and stick to a generic ProjectId or something similar

Agreed. the problem is that we already have a ProjectKey (similar to project id, that is the release key from orchestrator). to be consistent with the agentId naming (which is already the established field for low code agents today) I would use functionId for functions. I will also consult with the team regarding this since it would be a spec decision

[JosephMar]

We either keep introducing special IDs such as functionId, or we try to limit the number of IDs we have and stick to a generic ProjectId or something similar

Agreed. the problem is that we already have a ProjectKey (similar to project id, that is the release key from orchestrator). to be consistent with the agentId naming (which is already the established field for low code agents today) I would use functionId for functions. I will also consult with the team regarding this since it would be a spec decision

IMO every product should define its own GUID (I imagine you'll need this exposed downstream at some point). For Agents we are exposing a concrete AgentIId which must be separate from ProjectId (because of flow) so the generic approach might not work well unless you also include a discriminator, but at that point having separate IDs is probably similar overhead

@jepadil23 FYI this is similar to what we are solving for Trace service ID hierarchy

[jepadil23]

idea LGTM, only resolve if possible build issues