Skip to content

feat(skills): fetch skill bundles from Orchestrator - #1996

Open
dianagrecu-uipath wants to merge 1 commit into
feat/skills-sdkfrom
feat/skills-orchestrator-source
Open

dianagrecu-uipath wants to merge 1 commit into
feat/skills-sdkfrom
feat/skills-orchestrator-source

Conversation

@dianagrecu-uipath

Copy link
Copy Markdown
Contributor

Stacked on #1962

The base is feat/skills-sdk (#1962). Merge #1962 first; this branch is then rebased onto main.

Summary

OrchestratorBundleSource replaces the placeholder from #1962, and orchestrator becomes the default UIPATH_SKILLS_SOURCE. Coded and low-code agents now fetch their bound skill bundles from Orchestrator. Nothing above the SkillBundleSource seam changes: SkillSet, the overrides, the spans, UiPath/uipath-langchain-python#1179 and UiPath/uipath-agents-python#829.

How a bundle is fetched:

  1. Lookup: GET /api/skill-bundles?search=<name> in the bundle's folder (folderPath), or in the job's folder when the reference names none. search matches part of a name, so the client keeps the exact match, or a match that differs only in case when there is no exact one. Two matches that differ only in case are invalid.
  2. Manifest: GET /api/bundles/{key}/versions/{version}. pinned sends the version as given (a version number, a tag or a sha256: digest); latest sends latest. The version is checked against those forms and URL-encoded before it reaches the path. The manifest gives the version number, the digest and the file sizes, and a version over the download limit is refused here, before any download.
  3. Archive: GET /api/bundles/{key}/versions/{digest}/archive, by the manifest's digest, so the files match the manifest even when latest moves in between.
  4. Unpack and copy: the zip is unpacked into a temporary folder, then copied into the bundle folder with the same rules as the local source (the copy code is now shared).

Archive safety:

  • An entry that is not a relative path inside the bundle (.., an absolute path, backslashes, empty segments) makes the bundle invalid; nothing is written outside the temporary folder.
  • Symbolic links and hidden files are skipped.
  • Each file is read with a cap (one byte over the per-file limit) and the total unpacked bytes are capped, so an archive that expands far beyond its manifest fails as too_large instead of filling the disk.
  • Limits: 4096 files and 48 MiB per version download; the existing 512 KiB per file and 24 MiB per bundle apply to what is copied.

Errors, as BundleFailure.reason:

Response Reason
401, 403 forbidden
404 on the lookup; 400 "folder does not exist" not_found
404 on the version version_not_found
Other 4xx; a malformed manifest or archive invalid
5xx after the SDK's retries; network errors; no configuration source_unavailable

Failure details carry Orchestrator's error message, never request headers.

Other changes:

  • SkillBundle.digest (optional) holds the resolved version's digest. The skill.bundle.resolved event and the Skill load span record it as skill.digest.
  • local stays available for local development and tests. An unknown UIPATH_SKILLS_SOURCE now falls back to the default (orchestrator) with a warning.
  • The local source's copy loop moved into a shared function; its behaviour is unchanged and its tests are untouched.
  • Docs: skills.md and environment_variables.md describe the new default and the forms a pinned version can take.

Test plan

  • packages/uipath-platform: full suite (2305 passed, 12 skipped), ruff check, ruff format --check, mypy --config-file pyproject.toml ..
  • New test_sources_orchestrator.py (33 tests, pytest-httpx): lookup and paging, case-only matches, pinned versions, unsafe versions refused before any request, the job-folder fallback, error mapping, the download limit, the digest check, path traversal, symbolic links, hidden and oversized files, the unpack limit, a file that is not a zip.
  • check_version_uniqueness.py and check_dependency_version_bumps.py pass against this PR's range.
  • Live, against a test tenant: load_all_async resolved a version pinned by number, latest and a version pinned by digest, and reported not_found and version_not_found for a missing bundle and a missing version.
  • End to end, low-code agent: an advanced-harness agent bound to a pinned bundle, run through a local robot on this branch, feat: add evaluation framework and CI/CD integration for csv-processor sample #1179 and feat: add assertion for the tools-evals integration tests #829 with the default source. The bundle resolved from Orchestrator, the model loaded both skills and the run succeeded.

Copilot AI balanced review requested due to automatic review settings November 16, 2026 14:34
@github-actions github-actions Bot added test:uipath-langchain Triggers tests in the uipath-langchain-python repository test:uipath-integrations labels Nov 16, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Archive downloads are fully buffered before size limits are checked, risking worker memory exhaustion, and corrupt ZIP entries are misclassified as source_unavailable instead of invalid.

2 open issues
What changed in this PR

Implements Orchestrator-backed skill bundle fetching behind the existing SDK source interface, enabling coded and low-code agents to resolve remote bundles without changing how they consume skills.

Changes:

  • Makes Orchestrator the default source, with bundle lookup, version resolution, archive extraction and error mapping.
  • Shares the local copy logic and adds resolved digests to bundle models and telemetry.
  • Updates documentation and tests for source selection, remote fetching and archive safety.
File Description
packages/​uipath/​docs/​core/​skills.md Documents remote fetching, pinned versions and digests.
packages/​uipath/​docs/​core/​environment_variables.md Documents Orchestrator as the default source.
packages/​uipath-platform/​tests/​services/​skills/​test_telemetry.py Tests digest attributes in events and spans.
packages/​uipath-platform/​tests/​services/​skills/​test_sources_orchestrator.py Tests lookup, versions, failures and archive safety.
packages/​uipath-platform/​tests/​services/​skills/​test_get_bundle_source.py Updates default-source and fallback tests.
packages/​uipath-platform/​src/​uipath/​platform/​skills/​skills.py Adds an optional resolved bundle digest.
packages/​uipath-platform/​src/​uipath/​platform/​skills/​_telemetry.py Records digests on resolution events and load spans.
packages/​uipath-platform/​src/​uipath/​platform/​skills/​_sources.py Implements Orchestrator fetching and shares copy logic.
packages/​uipath-platform/​src/​uipath/​platform/​skills/​_skills_service.py Updates service docstrings for the new default.
packages/​uipath-platform/​src/​uipath/​platform/​skills/​_constants.py Defines endpoints, lookup limits and archive limits.

Review effort: Balanced

{**headers, "Accept": "application/zip"},
step="version archive",
)
if len(response.content) > MAX_ARCHIVE_BYTES:
Comment on lines +663 to +664
except OSError as e:
raise BundleSourceError(f"cannot write skill bundle '{bundle}': {e}") from e
Comment on lines +653 to +720
def _unpack_and_copy(
bundle: str, archive: bytes, dest: Path, stop: threading.Event
) -> list[Skill]:
"""Unpack ``archive`` into a temporary folder, then copy its skills into ``dest``."""
try:
with tempfile.TemporaryDirectory(prefix="uipath-skill-bundle-") as tmp:
staging = Path(tmp)
_unpack(bundle, archive, staging, stop)
dest.mkdir(parents=True, exist_ok=True)
return _copy_bundle_skills(bundle, staging, dest, stop)
except OSError as e:
raise BundleSourceError(f"cannot write skill bundle '{bundle}': {e}") from e


def _unpack(bundle: str, archive: bytes, staging: Path, stop: threading.Event) -> None:
"""Write the archive's files under ``staging``, refusing anything outside it.

An entry that is not a relative path inside the bundle makes the archive
``invalid``. Hidden files and symbolic links are left out. Each file is cut
at one byte over ``MAX_FILE_BYTES``, so the copy step still sees it as too
large and skips it with its usual warning; the bytes written in all stay
within ``MAX_ARCHIVE_BYTES``.
"""
try:
zf = zipfile.ZipFile(io.BytesIO(archive))
except zipfile.BadZipFile as e:
raise BundleSourceError(
f"skill bundle '{bundle}' archive is not a zip file", reason="invalid"
) from e
with zf:
infos = zf.infolist()
if len(infos) > MAX_ARCHIVE_ENTRIES:
raise BundleSourceError(
f"skill bundle '{bundle}' has over {MAX_ARCHIVE_ENTRIES} files",
reason="too_large",
)
root = staging.resolve()
written = 0
for info in infos:
_check(stop)
if info.is_dir():
continue
name = info.filename
parts = name.split("/")
if "\\" in name or any(part in ("", ".", "..") for part in parts):
raise BundleSourceError(
f"skill bundle '{bundle}' archive entry {name!r} is not a "
"relative path inside the bundle",
reason="invalid",
)
if not all(is_plain_name(part) for part in parts):
continue
if (info.external_attr >> 16) & _FILE_TYPE_MASK == _SYMLINK:
logger.warning("Skipping symbolic link %s in bundle '%s'", name, bundle)
continue
target = (staging / name).resolve()
if root not in target.parents:
raise BundleSourceError(
f"skill bundle '{bundle}' archive entry {name!r} leaves the bundle",
reason="invalid",
)
target.parent.mkdir(parents=True, exist_ok=True)
written += _write_capped(zf, info, target, MAX_FILE_BYTES + 1, stop)
if written > MAX_ARCHIVE_BYTES:
raise BundleSourceError(
f"skill bundle '{bundle}' unpacks to over {MAX_ARCHIVE_BYTES} bytes",
reason="too_large",
)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A damaged archive is reported as source_unavailable, but the PR's error table says a malformed archive is 'invalid'. Only a non-zip file (at ZipFile()) and OSError are handled. Errors raised while reading an entry (a CRC mismatch gives zipfile.BadZipFile, a broken deflate stream gives zlib.error) are not caught, so _failure_for's catch-all reports them as source_unavailable with the raw error text. An archive with both a file 'a' and a file 'a/SKILL.md' fails at target.parent.mkdir with an OSError and is reported as source_unavailable with 'cannot write skill bundle'. Copilot raised the CRC case too.

Comment on lines +625 to +635
def _reason_for(status: int, error_code: str | None, step: str) -> FailureReason:
"""The ``BundleFailure.reason`` for an HTTP error status."""
if status in (401, 403):
return "forbidden"
if status == 404:
return "not_found" if step == "bundle lookup" else "version_not_found"
if status == 400 and error_code == _FOLDER_NOT_FOUND:
return "not_found"
if 400 <= status < 500:
return "invalid"
return "source_unavailable"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

429 (rate limited) and 408 (timeout) are reported as 'invalid' after the SDK's retries run out. BaseService.request_async retries 408/429/502/503/504/524 up to 5 attempts. If they still fail, _reason_for puts every remaining 4xx under 'invalid', which means a broken bundle; a temporary server problem fits 'source_unavailable' better. This follows the PR's own 'Other 4xx → invalid' row; the row is the issue.

Comment on lines +554 to +567
async def archive(
self, key: uuid.UUID, digest: str, headers: dict[str, str]
) -> bytes:
"""The zip of the version with ``digest``; its entries are the manifest paths."""
response = await self._get(
f"{BUNDLE_ENDPOINT.format(key=key)}/versions/{quote(digest, safe='')}/archive",
{**headers, "Accept": "application/zip"},
step="version archive",
)
if len(response.content) > MAX_ARCHIVE_BYTES:
raise BundleSourceError(
f"version archive is over {MAX_ARCHIVE_BYTES} bytes", reason="too_large"
)
return response.content

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The archive is read fully into memory before its size is checked. request_async reads the whole body, and only then does len(response.content) > MAX_ARCHIVE_BYTES run. A body much larger than the manifest says is refused only after it is all in memory. The risk is low: the manifest limit runs first and the server is Orchestrator. Copilot raised this too.

Comment on lines +558 to +563
response = await self._get(
f"{BUNDLE_ENDPOINT.format(key=key)}/versions/{quote(digest, safe='')}/archive",
{**headers, "Accept": "application/zip"},
step="version archive",
)
if len(response.content) > MAX_ARCHIVE_BYTES:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The download limit is checked after the whole archive is buffered. A response larger than 48 MiB can exhaust worker memory before it is rejected.

Comment on lines +732 to +735
with zf.open(info) as source, target.open("wb") as sink:
while written < limit:
_check(stop)
chunk = source.read(min(_READ_CHUNK, limit - written))

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Corrupt ZIP entries are reported as source_unavailable instead of invalid. Only errors opening the ZIP are translated; errors while reading its entries escape.

@dianagrecu-uipath
dianagrecu-uipath force-pushed the feat/skills-orchestrator-source branch from 4662e12 to 46c75df Compare November 18, 2026 09:31
@github-actions

Copy link
Copy Markdown

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

Your changes may break the uipath-langchain-python integration.

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

🔍 Inspect the failed run →

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

test:uipath-integrations test:uipath-langchain Triggers tests in the uipath-langchain-python repository

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants