Skip to content

feat(skills): skill bundles for agents - #1962

Open
cristian-groza wants to merge 2 commits into
mainfrom
feat/skills-sdk
Open

cristian-groza wants to merge 2 commits into
mainfrom
feat/skills-sdk

Conversation

@cristian-groza

@cristian-groza cristian-groza commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

PR stack (skills for coded and low-code agents), merge in this order

  1. [1/3] UiPath/uipath-python (this PR): sdk.skills in uipath-platform 0.3.11 and skillBundle overrides in uipath 2.15.3.
  2. [2/3] feat(skills): skill bundles for coded LangGraph agents [PC-5187] uipath-langchain-python#1179: uipath_langchain.skills (UiPathSkills, load_skill tool, skills middleware) and the skills-agent sample. Draft until this PR is released; it then raises its floors to these versions.
  3. [3/3] UiPath/uipath-agents-python#829: the low-code advanced harness, re-pointed to uipath.platform.skills and uipath_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.md skills that the model loads on demand. This PR is the shared base for both kinds of agent:

  • Coded agents use it through uipath_langchain.skills ([2/3]), or call sdk.skills directly.
  • Low-code agents on the advanced harness use it through the agents runtime ([3/3]), which calls the same 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 a SkillSet. load_async loads one bundle. Both have sync twins.
    • SkillSet exposes names(), prompt_section() (the ## Skills system-prompt block), read(name, path) and failures.
    • A bundle that can't be resolved never fails the run. It shows up in failures with a reason: not_found, version_not_found, forbidden, too_large, invalid or source_unavailable (which also covers the per-bundle timeout).
    • Sources are picked with UIPATH_SKILLS_SOURCE:
      • local (the default) reads ./skills, or UIPATH_SKILLS_LOCAL_ROOT. A bundle's version comes from an optional bundle.json.
      • orchestrator is a placeholder: every bundle is reported as source_unavailable and the agent runs without skills. See "Orchestrator source" below.
    • A custom source implements SkillBundleSource (materialize(ref, dest), aclose()) and raises BundleSourceError(detail, reason=...).
    • A skill folder holds SKILL.md in any case (skill.md counts); it is written to the bundle folder as SKILL.md, so every reader finds it by the usual name.
    • Limits: 512 KiB per file, 24 MiB per bundle, 20 s per bundle. Scripts in a skill are copied but never executed.
    • Traces: a Skill bundles resolved span per load call and a Skill load - <bundle>/<skill> span per SKILL.md read.
    • pyyaml becomes a direct dependency of uipath-platform, to read the SKILL.md frontmatter (uipath already depends on it).
  • Bindings and overrides:
    • A skillBundle.<name>[.<folder>] resource overwrite (SkillBundleResourceOverwrite) replaces the whole binding, like every other binding: name, folderPath and versionMode are required, plus version when versionMode is pinned.
    • load_all_async applies it before fetching. Its name only changes which bundle is fetched; the agent keeps the declared name (folder, prompt, manifest).
    • An incomplete or invalid overwrite is skipped with a warning and the declared binding is used.
  • CLI (uipath): uipath run/debug/eval skip a resource overwrite kind they don't know, with a one-line warning, instead of failing.
  • Docs: a new core/skills.md page (mkdocs nav), the skills environment variables, a link from agents.md, and the sdk.skills entries in the generated SDK_REFERENCE.md. Release notes are left for when the releases are cut.
  • MANIFEST_FILE_NAME is exported, so the advanced harness recognises a workspace the SDK materialized ([3/3]).
  • Versions: uipath-platform 0.3.11; uipath 2.15.3, which requires uipath-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 OrchestratorBundleSource is a placeholder behind the SkillBundleSource seam. A follow-up PR implements OrchestratorBundleSource.materialize in uipath-platform and makes orchestrator the default source; local stays 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

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

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.skills for bundle loading, file access, metadata retrieval and tracing, with local, mock and Orchestrator sources.
  • Adds skillBundle overrides and improves CLI handling of unsupported bindings and overwrite types.
  • Adds tests and documentation, and bumps uipath to 2.14.45 and uipath-platform to 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

cristian-groza added a commit that referenced this pull request Oct 29, 2026
… 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>
@github-actions

Copy link
Copy Markdown

🚨 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 →

@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 →

@dianagrecu-uipath dianagrecu-uipath changed the title feat(skills): skill bundles for coded agents [PC-5187] feat(skills): skill bundles for agents Nov 16, 2026
cristian-groza and others added 2 commits November 18, 2026 09:01
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>
@sonarqubecloud

Copy link
Copy Markdown

# 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):

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.

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

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.

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()

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.

str() on whatever YAML produced causes a few problems:

  • Alias bomb: safe_load keeps aliases as shared references, and str() 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])

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.

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()

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.

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(

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.

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(

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 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(

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.

load/load_async and SkillBundleLoadError have no caller here or in #1179/#829. They also add a second error model (raise) next to load_all's (never raise). load_all([ref]) covers this; could they be left out until there is a caller? Same for SkillBundleRef.key.

``pinned`` uses a fixed version; ``latest`` takes the newest one at run start.
"""

# Keep in sync with the Literal on common._bindings.SkillBundleResourceOverwrite.

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 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")

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.

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?

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 test:uipath-runtime

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants