Repository navigation
feat(skills): skill bundles for agents - #1962
cristian-groza wants to merge 2 commits into
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
Unbounded download buffering risks memory exhaustion, while blocking local-source operations prevent enforcement of the timeout and timely cancellation.
4 open issues
What changed in this PR
Adds preview skill-bundle support to the UiPath Python SDK, providing the platform layer for the planned LangChain integration.
Changes:
- Introduces
sdk.skillsfor bundle loading, file access, metadata retrieval and tracing, with local, mock and Orchestrator sources. - Adds
skillBundleoverrides and improves CLI handling of unsupported bindings and overwrite types. - Adds tests and documentation, and bumps
uipathto 2.14.45 anduipath-platformto 0.2.42.
| File | Description |
|---|---|
packages/uipath/uv.lock |
Updates package versions and platform dependencies. |
packages/uipath/tests/resource_overrides/test_resource_overrides.py |
Tests skill overrides and concise warnings. |
packages/uipath/tests/cli/test_studio_project_overwrites.py |
Tests Studio overwrite parsing and unknown-kind handling. |
packages/uipath/tests/cli/test_push.py |
Tests skipped-binding explanations. |
packages/uipath/src/uipath/_resources/CLI_REFERENCE.md |
Refreshes generated CLI documentation. |
packages/uipath/src/uipath/_cli/_utils/_studio_project.py |
Skips unrecognized Studio overwrites with warnings. |
packages/uipath/src/uipath/_cli/_utils/_common.py |
Adds concise overwrite-error formatting. |
packages/uipath/src/uipath/_cli/_push/_resolvers.py |
Clarifies why unsupported bindings are skipped. |
packages/uipath/scripts/update_agents_md.py |
Removes builtins. prefixes from generated signatures. |
packages/uipath/pyproject.toml |
Bumps SDK version and platform dependency floor. |
packages/uipath/mkdocs.yml |
Adds the Skills documentation page to navigation. |
packages/uipath/docs/core/skills.md |
Documents loading, sources, overrides and limits. |
packages/uipath/docs/core/release_notes.md |
Adds unreleased skill-support notes. |
packages/uipath/docs/core/environment_variables.md |
Documents skill-source configuration. |
packages/uipath/docs/core/agents.md |
Introduces skills in the agent guide. |
packages/uipath-platform/uv.lock |
Updates platform version and YAML dependencies. |
packages/uipath-platform/tests/test_uipath_facade.py |
Tests facade service types and caching. |
packages/uipath-platform/tests/services/tests_data/skills/ops/vendor-lookup/SKILL.md |
Adds a same-named skill fixture across bundles. |
packages/uipath-platform/tests/services/tests_data/skills/ops/bundle.json |
Defines operations bundle metadata. |
packages/uipath-platform/tests/services/tests_data/skills/finance/vendor-lookup/SKILL.md |
Adds a finance lookup skill fixture. |
packages/uipath-platform/tests/services/tests_data/skills/finance/invoice-triage/SKILL.md |
Adds an invoice-triage skill fixture. |
packages/uipath-platform/tests/services/tests_data/skills/finance/invoice-triage/reference/vendors.md |
Adds a nested reference-file fixture. |
packages/uipath-platform/tests/services/tests_data/skills/finance/bundle.json |
Defines finance bundle metadata. |
packages/uipath-platform/tests/services/skills/test_telemetry.py |
Tests skill spans, events and attributes. |
packages/uipath-platform/tests/services/skills/test_sources_orchestrator.py |
Tests API-backed downloads and failure handling. |
packages/uipath-platform/tests/services/skills/test_sources_local.py |
Tests local copying, filtering and size limits. |
packages/uipath-platform/tests/services/skills/test_skill_md.py |
Tests frontmatter description parsing. |
packages/uipath-platform/tests/services/skills/test_package_imports.py |
Tests lightweight imports and lazy exports. |
packages/uipath-platform/tests/services/skills/test_overwrites.py |
Tests override precedence and validation. |
packages/uipath-platform/tests/services/skills/test_models.py |
Tests models, manifests, reads and cleanup. |
packages/uipath-platform/tests/services/skills/test_layout.py |
Tests bundle layout helpers. |
packages/uipath-platform/tests/services/skills/test_get_bundle_source.py |
Tests environment-based source selection. |
packages/uipath-platform/tests/services/skills/helpers.py |
Shares skill-fixture paths. |
packages/uipath-platform/tests/services/skills/conftest.py |
Provides filesystem, retry and tracing fixtures. |
packages/uipath-platform/tests/services/skills/__init__.py |
Marks the skills tests as a package. |
packages/uipath-platform/tests/common/test_bindings_skill_bundle.py |
Tests typed skill-bundle overwrite parsing. |
packages/uipath-platform/src/uipath/platform/skills/skills.py |
Defines bundle models and SkillSet operations. |
packages/uipath-platform/src/uipath/platform/skills/_telemetry.py |
Records bundle-resolution and skill-read telemetry. |
packages/uipath-platform/src/uipath/platform/skills/_sources.py |
Implements local and API-backed bundle sources. |
packages/uipath-platform/src/uipath/platform/skills/_skills_service.py |
Coordinates loading, overrides, failures and cleanup. |
packages/uipath-platform/src/uipath/platform/skills/_skills_api.py |
Adds the Skills API client and folder-backed mock. |
packages/uipath-platform/src/uipath/platform/skills/_skill_md.py |
Extracts descriptions from YAML frontmatter. |
packages/uipath-platform/src/uipath/platform/skills/_overwrites.py |
Applies deployment overrides to bundle references. |
packages/uipath-platform/src/uipath/platform/skills/_layout.py |
Provides file discovery and path-validation helpers. |
packages/uipath-platform/src/uipath/platform/skills/_constants.py |
Defines shared names, limits and environment variables. |
packages/uipath-platform/src/uipath/platform/skills/__init__.py |
Exposes models and lazy service exports. |
packages/uipath-platform/src/uipath/platform/common/_bindings.py |
Adds the skill-bundle overwrite model. |
packages/uipath-platform/src/uipath/platform/common/__init__.py |
Exports the new overwrite type. |
packages/uipath-platform/src/uipath/platform/_uipath.py |
Exposes cached sdk.skills access. |
packages/uipath-platform/pyproject.toml |
Bumps platform version and adds YAML dependencies. |
Review effort: Balanced
… setup [PC-5187] Addresses the review of #1962: - LocalFolderBundleSource copies on a worker thread with a stop flag, so the event loop keeps running and the 20 s budget applies to it too. On timeout or cancellation the copy stops before its next file and materialize waits for the thread, so nothing lands in a bundle folder after the service removes it. - A temp folder that cannot be created is reported as source_unavailable on the span, the caller's source is closed, and the run continues. - A blank versionMode in a skillBundle overwrite counts as unset, like the other fields, instead of rejecting the whole entry. - A comment on the point-in-time Skill load span. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
02b75eb to
efcdc65
Compare
🚨 Heads up:
|
🚨 Heads up:
|
8d0ce67 to
c8701c3
Compare
Coded agents can use skill bundles, the versioned SKILL.md bundles that low-code agents use. uipath-platform (0.3.11): - uipath.platform.skills, exposed as sdk.skills. load_all_async(refs) resolves the bundles an agent declares, writes them to disk at run start and returns a SkillSet; load_async loads one bundle; both have sync twins. SkillSet offers names(), prompt_section(), read() and failures. - A bundle that cannot be resolved never fails the run: it is reported in failures with a reason (not_found, version_not_found, forbidden, too_large, invalid, source_unavailable). - Sources are chosen with UIPATH_SKILLS_SOURCE: local (the default, reading ./skills or UIPATH_SKILLS_LOCAL_ROOT) and orchestrator, a placeholder that reports every bundle as source_unavailable until the Orchestrator Skills API exists. Custom sources implement SkillBundleSource. - A skill folder holds SKILL.md in any case; it is written as SKILL.md. - Limits of 512 KiB per file, 24 MiB per bundle and 20 s per bundle. Scripts are copied, never executed. - Spans: "Skill bundles resolved" per load call and "Skill load - <bundle>/<skill>" per SKILL.md read. - SkillBundleResourceOverwrite: a skillBundle.<name>[.<folder>] resource overwrite replaces the whole binding, like the other bindings (name, folderPath and versionMode, plus version when pinned). load_all_async applies it before fetching; the agent keeps the declared name. An incomplete or invalid overwrite is skipped with a warning. - pyyaml becomes a direct dependency, for SKILL.md frontmatter. uipath (2.15.3, requires uipath-platform>=0.3.11): - uipath run, debug and eval skip a resource overwrite kind they do not know, with a one-line warning, instead of failing. - Docs: a new core/skills.md page, the skills environment variables, a link from agents.md, and the sdk.skills entries in SDK_REFERENCE.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Add skill_load_span, a context manager that keeps the Skill load span current while the SKILL.md is read, so the tool call that reads it becomes its child. The caller settles the load with loaded(size) or fail(reason); a load left unsettled, or one that raises, ends with an error status. record_skill_loaded now wraps it, so SkillSet.read is unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
c8701c3 to
3769349
Compare
|
| # an earlier run (a bundle no longer bound, a stale manifest) may | ||
| # survive. This runs before the source is built, so the reset | ||
| # happens even when the source cannot be. | ||
| if not _remove_tree(root): |
There was a problem hiding this comment.
This rmtrees the whole caller-supplied destination on every call, before anything is fetched. The default local root is ./skills, and #1179 documents destination=<workspace>/skills. When the workspace is the project dir, both are the same folder: the load wipes the authored skills and then reports not_found. I reproduced this with load_all([SkillBundleRef(name="ops")], destination=Path.cwd() / "skills"). A typo like destination=Path.cwd() would delete the project.
Suggest removing only what a previous run wrote (the bundle folders listed in the existing manifest, plus the manifest), refusing a non-empty folder with no manifest, and refusing a destination that overlaps the source root.
|
|
||
| try: | ||
| overwrites[key] = ResourceOverwriteParser.parse(key, value) | ||
| except Exception as e: # one unknown kind must not fail a debug or eval run |
There was a problem hiding this comment.
This catches every exception for every overwrite kind, not only unknown kinds. A malformed asset/queue/connection overwrite used to fail the debug/eval run. Now it is dropped with a warning and the run silently uses the design-time resource. That changes behaviour for existing bindings and isn't needed for skills. Could this be narrowed to an unknown resource_type, or moved to its own PR?
| return "" | ||
| if not isinstance(data, dict): | ||
| return "" | ||
| return str(data.get("description", "")).strip() |
There was a problem hiding this comment.
str() on whatever YAML produced causes a few problems:
- Alias bomb:
safe_loadkeeps aliases as shared references, andstr()expands them. A 334-byte frontmatter with nested aliases gives a 25 MB description; a few more levels run the process out of memory. This matters once bundles come from Orchestrator or third parties. - No length cap: the description goes into the system prompt via
prompt_section(), so a single SKILL.md can fill the context. - Wrong values:
description:with no value becomes"None", a list becomes"['a', 'b']", and a date becomes the stringified date.
Suggest accepting only str, otherwise "", and truncating to the spec's 1024 chars.
| stop.set() | ||
| # Shielded, so the thread is waited for even though this task was | ||
| # cancelled; it stops within one file. | ||
| await asyncio.wait([copy]) |
There was a problem hiding this comment.
When the copy is stopped, the task finishes with _Stopped, and asyncio.wait never retrieves that exception. Every timeout or cancel then logs ERROR asyncio: Task exception was never retrieved ... _Stopped with a traceback.
More broadly, the thread/stop-event/shield machinery exists only so a local dev copy (capped at 24 MiB) honours the 20 s budget. The Orchestrator source will get its timeout from the HTTP client. Could the local source skip the budget instead and drop this?
| ( | ||
| rel.as_posix() | ||
| for rel in ( | ||
| p.relative_to(skill_dir) for p in skill_dir.rglob("*") if p.is_file() |
There was a problem hiding this comment.
rglob/is_file() follow symlinks, so notes.md -> /some/file inside a skill gets copied, and read() returns the target's contents to the model. local is the default source, and a cloned or imported project is enough to pull arbitrary local files into the model's context. Suggest skipping symlinks (not p.is_symlink()).
| Yields: | ||
| The open load; call ``loaded`` or ``fail`` on it. | ||
| """ | ||
| with _tracer.start_as_current_span( |
There was a problem hiding this comment.
These spans are started without context=UiPathSpanUtils.get_parent_context(), which @traced uses (uipath-core/.../decorators.py) so that spans attach under the external LangGraph/LangChain parent. Without it, Skill load can end up with the wrong parent inside a tool call. Same applies at line 53.
Also, #1179 imports SkillLoad/skill_load_span from this private module. If it is part of the contract between packages, it should be exported publicly.
| ) | ||
| text = file.read_text(encoding="utf-8-sig", errors="replace") | ||
| if path == SKILL_FILE_NAME: | ||
| record_skill_loaded( |
There was a problem hiding this comment.
The span is opened and closed only after the file has already been read, so nothing is current during the read, and a read that raises records no span at all. That contradicts the last commit message and the skill_load_span docstring. Wrap the read in skill_load_span instead?
| self.load_all_async(refs, destination=destination, source=source) | ||
| ) | ||
|
|
||
| async def load_async( |
There was a problem hiding this comment.
| ``pinned`` uses a fixed version; ``latest`` takes the newest one at run start. | ||
| """ | ||
|
|
||
| # Keep in sync with the Literal on common._bindings.SkillBundleResourceOverwrite. |
There was a problem hiding this comment.
The version-mode rules are defined in three places (SkillBundleResourceOverwrite, SkillBundleRef, VersionMode) and kept aligned by comments. Could VersionMode live in common and be used by the overwrite model, so there is one definition?
| name: str = Field(alias="name") | ||
| folder_path: str = Field(alias="folderPath") | ||
| # Keep in sync with uipath.platform.skills.VersionMode. | ||
| version_mode: Literal["pinned", "latest"] = Field(alias="versionMode") |
There was a problem hiding this comment.
Question: an invalid skillBundle overwrite is skipped and the declared binding is used. For a prod override that pins a version, that means silently running a different bundle version. Is falling back intended here, rather than failing like an invalid binding of another kind would?





PR stack (skills for coded and low-code agents), merge in this order
sdk.skillsinuipath-platform0.3.11 andskillBundleoverrides inuipath2.15.3.uipath_langchain.skills(UiPathSkills,load_skilltool, skills middleware) and theskills-agentsample. Draft until this PR is released; it then raises its floors to these versions.uipath.platform.skillsanduipath_langchain.skills, so coded and low-code agents run one implementation. It bumps its pins once [1/3] and [2/3] are released.Summary
Agents can now use skill bundles: versioned folders of
SKILL.mdskills that the model loads on demand. This PR is the shared base for both kinds of agent:uipath_langchain.skills([2/3]), or callsdk.skillsdirectly.load_all_async.What it adds:
uipath.platform.skills/sdk.skills(uipath-platform):load_all_async(refs)resolves the bundles an agent declares, writes them to disk at run start and returns aSkillSet.load_asyncloads one bundle. Both have sync twins.SkillSetexposesnames(),prompt_section()(the## Skillssystem-prompt block),read(name, path)andfailures.failureswith a reason:not_found,version_not_found,forbidden,too_large,invalidorsource_unavailable(which also covers the per-bundle timeout).UIPATH_SKILLS_SOURCE:local(the default) reads./skills, orUIPATH_SKILLS_LOCAL_ROOT. A bundle's version comes from an optionalbundle.json.orchestratoris a placeholder: every bundle is reported assource_unavailableand the agent runs without skills. See "Orchestrator source" below.SkillBundleSource(materialize(ref, dest),aclose()) and raisesBundleSourceError(detail, reason=...).SKILL.mdin any case (skill.mdcounts); it is written to the bundle folder asSKILL.md, so every reader finds it by the usual name.Skill bundles resolvedspan per load call and aSkill load - <bundle>/<skill>span perSKILL.mdread.pyyamlbecomes a direct dependency ofuipath-platform, to read theSKILL.mdfrontmatter (uipathalready depends on it).skillBundle.<name>[.<folder>]resource overwrite (SkillBundleResourceOverwrite) replaces the whole binding, like every other binding:name,folderPathandversionModeare required, plusversionwhenversionModeispinned.load_all_asyncapplies it before fetching. Itsnameonly changes which bundle is fetched; the agent keeps the declared name (folder, prompt, manifest).uipath):uipath run/debug/evalskip a resource overwrite kind they don't know, with a one-line warning, instead of failing.core/skills.mdpage (mkdocs nav), the skills environment variables, a link fromagents.md, and thesdk.skillsentries in the generatedSDK_REFERENCE.md. Release notes are left for when the releases are cut.MANIFEST_FILE_NAMEis exported, so the advanced harness recognises a workspace the SDK materialized ([3/3]).uipath-platform0.3.11;uipath2.15.3, which requiresuipath-platform>=0.3.11.Orchestrator source
The Orchestrator skill bundle API is not generally available yet, so this PR does not call it: there is no HTTP client and no mock of the API, and
OrchestratorBundleSourceis a placeholder behind theSkillBundleSourceseam. A follow-up PR implementsOrchestratorBundleSource.materializeinuipath-platformand makesorchestratorthe default source;localstays available for local development and tests.SkillSet, the overrides, the spans, #1179 and #829 sit above the seam and do not change. The docs mark the feature as preview.Test plan
packages/uipath-platform: full suite (2266 passed, 12 skipped),ruff check,ruff format --check,mypy --config-file pyproject.toml ..packages/uipath: full suite (2733 passed, 1 xfailed),ruff check,ruff format --check,mypy --config-file pyproject.toml ..check_version_uniqueness.pyandcheck_dependency_version_bumps.pypass locally against this PR's range.localsource on a test tenant. Two bundles resolved, Claude Haiku 4.5 calledload_skill("ops/escalation-policy")and the run succeeded with theSkill loadspan recorded. Also checked:opsto thefinancefolder while the agent keeps the nameops;skill.mdloads.financebundle, 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 thelocalsource. The bundle resolved, the model loadedfinance/invoice-triageand thenfinance/vendor-lookup, and the run succeeded.