@uipath/skills 1.200.0 → 1.201.0-preview.433

package/skills/uipath-agents/SKILL.md

@@ -44,6 +44,7 @@ Determine the agent mode before proceeding:
 | Create/build/deploy coded agent | Coded | [coded/quickstart.md](references/coded/quickstart.md) | `coded/lifecycle/*`, `coded/frameworks/*` |
 | Select coded framework | Coded | [coded/quickstart.md](references/coded/quickstart.md) § Framework Selection | |
 | Add coded capabilities (HITL, RAG, tracing) | Coded | [coded/quickstart.md](references/coded/quickstart.md) | `coded/capabilities/*` |
+| Set a coded agent's environment variables, or reference an Orchestrator asset from one (`%ASSETS/<ASSET_NAME>%`) | Coded | [coded/lifecycle/environment-variables.md](references/coded/lifecycle/environment-variables.md) | `coded/lifecycle/file-sync.md` for what `.env` does and does not carry |
 | Call an Integration Service connector (Slack, Jira, Web Search) from a coded agent | Coded | [coded/capabilities/integration-service.md](references/coded/capabilities/integration-service.md) **+ then immediately read** [`uipath-platform/references/integration-service/agent-workflow.md`](../uipath-platform/references/integration-service/agent-workflow.md) — discovery lives there, not in `uipath-agents` | `coded/capabilities/sdk-services.md` § Connections |
 | Run coded evaluations | Coded | [coded/quickstart.md](references/coded/quickstart.md) § Evaluate | `coded/lifecycle/evaluate.md` |
 | Create or scaffold a new low-code agent project | Low-code | [lowcode/lowcode.md](references/lowcode/lowcode.md) § Quick Start | `lowcode/project-lifecycle.md`, `lowcode/agent-definition.md` |

package/skills/uipath-agents/references/coded/capabilities/context-grounding.md

@@ -21,16 +21,16 @@ To create, ingest, poll, search, or delete the index from the CLI instead of the
 
 ## Folder Targeting
 
-Context Grounding indexes live in Orchestrator folders. Pass a folder identifier whenever the index is not in the default folder resolved from your auth context — otherwise the service may return `400 FolderKey required`. `ContextGroundingRetriever` accepts `folder_path` or `folder_key`; `ContextGroundingVectorStore` accepts `folder_path`.
+Context Grounding indexes live in Orchestrator folders. Always pass a folder identifier, even when the index lives in the execution folder resolved from your auth context — omitting it can leave the `index` binding incorrectly applied, and the service may return `400 FolderKey required`. `ContextGroundingRetriever` accepts `folder_path` or `folder_key`; `ContextGroundingVectorStore` accepts `folder_path`.
 
 ```python
 retriever = ContextGroundingRetriever(index_name="my_index", folder_path="Shared/Knowledge")
 ```
 
-Add the supported folder argument for the component you use when cross-folder access is needed.
-
 ## Core Components
 
+Import paths below are LangChain/LangGraph (`uipath_langchain.*`). For LlamaIndex agents, use `uipath_llamaindex.retrievers.ContextGroundingRetriever` / `uipath_llamaindex.query_engines.ContextGroundingQueryEngine` — see [frameworks/llamaindex-integration.md](../frameworks/llamaindex-integration.md) § Context Grounding (RAG).
+
 ### ContextGroundingRetriever
 
 A document retrieval system using vector search to find relevant information based on natural language queries.

package/skills/uipath-agents/references/coded/capabilities/guardrails/guardrails-recommend.md

@@ -54,6 +54,8 @@ uip agent guardrails list --output json
 
 Build a lookup of `{ validatorId: status }` from the `Data` array. You will use this to filter recommendations.
 
+> **`Validator` is not unique — key on `(Validator, IsByo)`, not `Validator` alone.** A tenant with a bring-your-own (BYOG) configuration for a validator has two entries sharing the same `Validator` name — one built-in, one BYO (`IsByo: true`, carrying `ByoValidatorName`/`ByoConnectionId`/`ByoConfigurationId`). Collapsing them loses the distinction and can point the discovery/wiring flow at the wrong entry. See [guardrails.md § BYO (bring-your-own) validators](guardrails.md#byo-bring-your-own-validators).
+
 > **Catalog vs. list — the key distinction:** The catalog lists all guardrails that exist on the platform (with rich metadata for reasoning). The guardrails list returns only those accessible to this tenant. Only recommend validators where `Status == "Available"` in the list.
 
 ### SDK Documentation (NEVER skipped — Python class names)
@@ -115,6 +117,8 @@ For **each entry** in the catalog (`guardrails[]` array from the cached JSON):
 
 Do **not** apply predetermined knowledge about which guardrail maps to which schema field. Let the catalog entry's authored fields drive every recommendation decision.
 
+> **Built-in vs. BYO — default to built-in.** When a matched validator has both a built-in entry and one or more `Available` BYO (`IsByo: true`) entries, recommend the standard SDK validator/middleware (built-in) by default, and mention a BYO alternative exists. Only wire in a specific BYO configuration when the user names it or asks for BYO explicitly — see [guardrails.md § BYO (bring-your-own) validators](guardrails.md#byo-bring-your-own-validators) for how that's actually referenced in code.
+
 ### Step 3 — De-duplicate Overlapping Validators
 
 Several catalog validators address the same threat. Recommending more than one of them at the same scope and stage is redundant — it doubles latency and cost on every call for marginal benefit (the canonical case is `prompt_injection` and `user_prompt_attacks`: both have `security_category: "adversarial_input"` and both run at LLM · PRE).
@@ -235,7 +239,7 @@ For each existing guardrail discovered in the Python file (Step 1 from Recommend
 
 ### Correctness Check
 
-From the SDK docs and the catalog, look up the validator class referenced in the code:
+From the SDK docs and the catalog, look up the validator class referenced in the code. **If the guardrails list has more than one entry sharing the referenced `Validator` name** (built-in plus BYOG), disambiguate by whether the code wires a BYO validator construct (`ByoValidator(...)` or `UiPathByoGuardrailMiddleware(...)`, identified by its `validator_name`) or the plain SDK validator/middleware class — match against the corresponding list entry's `IsByo` before reading `Parameters`/scopes for that entry.
 
 | Aspect | What to check |
 |--------|---------------|
@@ -295,3 +299,4 @@ python3 -c "import ast; ast.parse(open('graph.py').read())"
 13. **Class names and enum names come from the SDK docs** — never invent them. The SDK evolves; relying on memory produces stale code. For **import paths**, use the `langchain/guardrails/` page when the agent is LangChain (paths live in `uipath_langchain.guardrails`); for every other framework use the `core/guardrails/` page (paths live in `uipath.platform.guardrails`). See Rule 8.
 14. **Read [guardrails.md](guardrails.md) before writing any Python** — the middleware spread (`*`), decorator placement above `@tool` / factory, factory refactor, and import-source rules are specified there and cannot be safely inferred.
 15. **`EscalateAction` is the human-in-the-loop option only when the SDK docs expose it** — recommend it when the user wants a person to review/approve a flagged item rather than hard-block it. It requires a **deployed Action App** declared in `bindings.json` (`app_name` / `app_folder_path`) through the coded-agent bindings sync workflow; if the docs, app, or binding prerequisite is unavailable, fall back to Block/Log and say so — never silently drop the requested escalation. See Step 6 and [guardrails.md § Escalation action (HITL)](guardrails.md#escalation-action-human-in-the-loop).
+16. **`Validator` is not unique — disambiguate built-in vs. BYO by `IsByo` before matching on name.** A tenant can have both a built-in and one or more BYOG entries sharing the same `Validator` name. Key any lookup on `(Validator, IsByo)`, and default recommendations/wiring to the built-in SDK validator/middleware unless the user names a BYO configuration or asks for BYO. Never fabricate the BYO validator construct from memory — see [guardrails.md § BYO (bring-your-own) validators](guardrails.md#byo-bring-your-own-validators).

package/skills/uipath-agents/references/coded/capabilities/guardrails/guardrails.md

@@ -57,6 +57,87 @@ If the requested validator has `Status != "Available"` → tell the user and sto
 
 ---
 
+## BYO (bring-your-own) validators
+
+A validator can be fulfilled by a tenant-registered **external** provider (a "BYOG" configuration — e.g. Azure AI Content Safety, Databricks AI Guardrails) instead of UiPath's own built-in implementation. Registration is admin-side — Admin → AI Trust Layer → Guardrails Configurations, or `uip guardrails byo-configurations create` (see [uipath-platform § BYO Guardrail Configurations](/uipath:uipath-platform)); this section covers wiring an already-registered BYOG configuration into agent code.
+
+**Same rule as [Step 0](#step-0--fetch-official-documentation): confirm the constructor signature against the fetched SDK docs before writing code, and never invent arguments.** The two constructs below exist today; if a future fetch shows one missing or renamed, follow the fetched page and say so rather than writing what's here from memory.
+
+### Which construct exists where
+
+| Construct | Style | Ships in | Notes |
+|---|---|---|---|
+| `UiPathByoGuardrailMiddleware` | middleware | `uipath_langchain.guardrails` **only** | LangChain/LangGraph agents only — there is no framework-agnostic middleware. |
+| `ByoValidator` | decorator | `uipath.platform.guardrails` (**core**), re-exported by `uipath_langchain.guardrails` | Framework-agnostic class, so BYO is **not** LangChain-only. |
+
+> **BYO is not LangChain-only** — a common wrong inference, because the core SDK docs page historically omitted `ByoValidator`. The class is in core. What *is* LangChain-only is the middleware.
+>
+> The usual [Imports Pattern](#imports-pattern) rule still governs which module you import from: a LangChain agent imports from `uipath_langchain.guardrails` (adapter registration — see Critical Rule 8), everything else from `uipath.platform.guardrails`. And on a framework with no published adapter, the decorator carries the same silent-no-op risk it does for every other validator — that caveat belongs to the decorator *mechanism*, not to BYO.
+
+**Wire format** — both coded styles emit `validatorType: "byo"` plus `byoValidatorName: "<name>"`. The only field shared with low-code is `byoValidatorName`: a low-code `agent.json` pins the same BYOG configuration by adding `byoValidatorName` while keeping `validatorType` = the real validator id (e.g. `pii_detection`). `validatorType: "byo"` is the coded SDK wire format — never write it in a low-code `agent.json`.
+
+Discovery steps (in addition to the fetched docs):
+
+1. Confirm a BYOG configuration exists for the desired validator and get its identifying value:
+   ```bash
+   uip agent guardrails list --byo --output json
+   ```
+   Read `ByoValidatorName` from the matching entry — the validator name is the **only** value the code passes; it is unique across the tenant, and the platform resolves the underlying connection server-side from the stored configuration. Do not pass a connection id, and never guess or fabricate the name.
+2. Before wiring it in, cross-check the configuration's health on the admin side:
+   ```bash
+   uip guardrails byo-configurations list --output json
+   ```
+   Confirm `Enabled: true` and `ValidConnection: true` for the matching `ValidatorName`. A disabled configuration or a broken connection means the guardrail will fail at runtime (or silently fall back, depending on `FallbackOnUiPath`) — tell the user rather than wiring it in anyway. The admin-side fix (re-enable via `update <id> --enabled`, repoint the connection via `update <id> --connection-id`) is covered by [uipath-platform § BYO Guardrail Configurations](/uipath:uipath-platform).
+
+### BYO middleware (LangChain only)
+
+`validator_name`, `scopes`, and `action` are all required. `validator_parameters` is optional passthrough — BYO parameter schemas are connector-defined, so read the ids and allowed values from that entry's `Parameters` array in the discovery output rather than guessing. Spread with `*` like every other middleware.
+
+```python
+from uipath_langchain.guardrails import (
+    BlockAction,
+    UiPathByoGuardrailMiddleware,
+)
+from uipath.core.guardrails import GuardrailScope
+
+*UiPathByoGuardrailMiddleware(
+    validator_name="my-pii-guardrail",   # ByoValidatorName from `guardrails list --byo`
+    scopes=[GuardrailScope.AGENT],
+    action=BlockAction(),
+),
+```
+
+For Tool scope, pass the tool objects as usual:
+
+```python
+*UiPathByoGuardrailMiddleware(
+    validator_name="my-pii-guardrail",
+    scopes=[GuardrailScope.TOOL],
+    action=BlockAction(),
+    tools=[lookup_account_info],   # required whenever TOOL is in scopes
+),
+```
+
+### BYO decorator (any framework)
+
+The validator name is the **first positional argument**; `parameters` is keyword-only. Scope comes from the decorated target (`@tool` → Tool, LLM factory → Llm, agent factory → Agent), exactly as for the built-in validators.
+
+```python
+from uipath_langchain.guardrails import BlockAction, ByoValidator, guardrail
+
+byog_pii = ByoValidator("my-pii-guardrail")
+
+@guardrail(validator=byog_pii, action=BlockAction())
+def create_support_agent():
+    return create_agent(model=llm, tools=[lookup_account_info])
+```
+
+On a non-LangChain framework the same code works with `from uipath.platform.guardrails import BlockAction, ByoValidator, guardrail` — subject to the adapter caveat above.
+
+**Stages:** BYO validator capabilities are connector-defined and can't be known statically, so no stage restriction is applied — all stages are supported, and the middleware defaults to `PRE_AND_POST`.
+
+---
+
 ## Step 1 — Style Choice
 
 If the user has not specified **middleware** or **decorator**, ask before generating any code. Do not implement both unless explicitly asked.
@@ -178,7 +259,11 @@ Pass `scopes=[GuardrailScope.LLM]` or `[GuardrailScope.AGENT]`. No `tools=`.
 
 ### Stage is fixed by the validator — no `stage=` on middleware
 
-Middleware classes take **no `stage` argument**. Each validator's stage is fixed: input validators (`user_prompt_attacks`, `prompt_injection`, input PII) run PRE; `intellectual_property` runs POST (output-only). Adding `stage=GuardrailExecutionStage....` to a middleware call raises `TypeError`. Only the **decorator** (`@guardrail`) accepts `stage=`.
+Middleware classes for the **fixed-stage** validators take no `stage` argument: `UiPathUserPromptAttacksMiddleware`, `UiPathPromptInjectionMiddleware` (both PRE-only) and `UiPathIntellectualPropertyMiddleware` (POST-only). Passing `stage=` to those raises `TypeError` — their stage is a property of the validator, not a choice.
+
+> Validators whose stage genuinely varies **do** accept `stage=` on the middleware (defaulting to `PRE_AND_POST`) — PII, harmful content, LLM-as-judge, deterministic, and BYO. Confirm against the fetched `langchain/guardrails/` page for the validator you're wiring rather than assuming either way.
+
+For BYO middleware specifically, see [BYO (bring-your-own) validators](#byo-bring-your-own-validators).
 
 ### Intellectual property (output-only) middleware
 
@@ -211,6 +296,8 @@ Runs at POST (checks the LLM's output) — fixed by the validator, not a paramet
 
 Full documentation and examples: [Core Guardrails](https://uipath.github.io/uipath-python/core/guardrails/)
 
+For a bring-your-own (BYOG) validator, see [BYO (bring-your-own) validators](#byo-bring-your-own-validators) — `ByoValidator` slots into the same `@guardrail(validator=..., action=...)` shape as the built-ins.
+
 ### Tool scope — decorate the `@tool` function
 
 Place `@guardrail` **above** `@tool`:
@@ -398,3 +485,4 @@ For non-LangChain frameworks, there is no published adapter yet, so the decorato
 15. **`EscalateAction` requires a deployed Action App** referenced by `app_name` + `app_folder_path` and declared as an `app` resource in **`bindings.json`** — discover it with `uip solution resources list --kind App`, resolve duplicate names by folder, pass the literal name/folder in code (not env vars), and sync bindings with [../../lifecycle/bindings-reference.md](../../lifecycle/bindings-reference.md). Route the task with `TaskRecipient` when the user names a reviewer. See [Escalation action (HITL)](#escalation-action-human-in-the-loop).
 16. **Verify the escalation app schema when tenant access is available** — the app must expose the guardrail review inputs/outputs/outcomes listed in the prerequisite section. If the schema cannot be verified in a local smoke task, say that runtime readiness is unverified.
 17. **A HITL guardrail suspends, it doesn't block.** On violation `EscalateAction` suspends via `interrupt(CreateEscalation(...))`; it terminates **only on Reject** (Approve resumes). Verify by confirming the run suspends + a task is created — never expect a "block" for an escalation guardrail (Rule for the [verification step](#verify-guardrails-are-actually-wired-mandatory-after-writing-for-langchain-ml-guardrails)).
+18. **BYO: pass the validator name and nothing else, and get that name from discovery — never from memory.** `ByoValidatorName` comes from `uip agent guardrails list --byo`; there is **no connection-id argument** in either construct (the platform resolves the connection server-side from the configuration). Pick the construct by style, not by framework: `UiPathByoGuardrailMiddleware` is LangChain-only, while `ByoValidator` is a **core** class (`uipath.platform.guardrails`) re-exported by `uipath_langchain.guardrails` — so **BYO is not LangChain-only**, and a subagent or stale doc claiming otherwise is wrong. Import per Rule 8 regardless. Cross-check `Enabled`/`ValidConnection` via `uip guardrails byo-configurations list` before wiring one in. See [BYO (bring-your-own) validators](#byo-bring-your-own-validators).

package/skills/uipath-agents/references/coded/embedding-in-flows.md

@@ -98,6 +98,22 @@ Without `--local`, `registry list`/`get` query the tenant registry (Orchestrator
 
 ## Wiring the Agent's Inputs
 
-For inputs that reference flow variables, use `{ "type": "literal", "expression": "{{ $vars.X }}", "fieldType": "string" }` — NOT `=js:...` expressions. `=js:` ships as a literal string to the agent activity and fails at runtime with `Cannot find name '<identifier>'`.
+One `inputs.<field>` entry per property in the agent's input schema (`entry-points.json`, mirrored in the definition's `inputDefinition.properties`). Two valid value shapes, same binding:
+
+```json
+"inputs": {
+  "<INPUT_FIELD>": {
+    "type": "jsExpression",
+    "expression": "$vars.<UPSTREAM_NODE_ID>.output.<FIELD>",
+    "fieldType": "<FIELD_TYPE>"
+  }
+}
+```
+
+- `jsExpression` — bare `$vars...` expression, no `=js:` prefix. Upstream values read as `$vars.<nodeId>.output.<field>`; flow globals as `$vars.<global>`.
+- `literal` — text template; static text mixable with `{{ }}` interpolations: `{ "type": "literal", "expression": "{{ $vars.<UPSTREAM_NODE_ID>.output.<FIELD> }}", "fieldType": "<FIELD_TYPE>" }`.
+- `<FIELD_TYPE>` is the property's JSON-schema type from the agent's input schema (e.g. `string`, `boolean`, `number`) — read it from there, do not invent it.
+
+NEVER a plain `"=js:..."` string value — it ships as a literal string to the agent activity and fails at runtime with `Cannot find name '<identifier>'`. Complete worked example (trigger → agent → end): uipath-maestro-flow skill, agent-plugin reference § Wiring Inputs.
 
 Input-only rule. Mapping the agent's output back to a flow-level global on an End node DOES use `=js:` — see [variables-and-expressions.md § Variable Updates](../../../uipath-maestro-flow/references/shared/variables-and-expressions.md#variable-updates-variableupdates).

package/skills/uipath-agents/references/coded/frameworks/llamaindex-integration.md

@@ -268,15 +268,41 @@ See `../capabilities/conversational-agents.md` § Running Locally for the `--kee
 
 ### Context Grounding (RAG)
 
+Two RAG primitives ship in `uipath-llamaindex`. Pick by workflow shape:
+
+| Primitive | Import | Use when |
+|-----------|--------|----------|
+| `ContextGroundingQueryEngine` | `uipath_llamaindex.query_engines` | Retrieval + LLM synthesis in one call, or exposing the index as a `QueryEngineTool` in an agentic workflow. Constructor REQUIRES `response_synthesizer` (no default). |
+| `ContextGroundingRetriever` | `uipath_llamaindex.retrievers` | Deterministic workflow RAG — retrieve raw passages in a `@step`, then synthesize the answer with your own prompt and LLM call. |
+
+The query engine wraps `ContextGroundingRetriever` + your synthesizer internally — use the retriever directly when the workflow already has its own synthesis step.
+
+> **Prefer using these primitives — not raw `sdk.context_grounding.search()` / `search_async()`.** They return LlamaIndex `NodeWithScore` objects that plug into synthesizers and tools, and declare `index_name` + `folder_path` at one call site — the exact shape of the `index` binding entry (see [../lifecycle/bindings-reference.md](../lifecycle/bindings-reference.md)). `index` bindings have no virtual fallback: the index must exist in Orchestrator before `uip codedagent push`.
+
+Both accept `index_name`, `folder_path` (or `folder_key`), and `number_of_results` (default 10). Always pass `folder_path`, even when the index lives in the execution folder resolved from your auth context — omitting it can leave the `index` binding incorrectly applied. Instantiate both inside a `@step` — never at module level (same lazy-client rule as LLMs, § UiPathOpenAI above).
+
+#### ContextGroundingQueryEngine
+
+Build the required `response_synthesizer` with `get_response_synthesizer(llm=UiPathOpenAI())` — omitting it raises a constructor error:
+
 ```python
+from llama_index.core.response_synthesizers import get_response_synthesizer
+from uipath_llamaindex.llms import UiPathOpenAI
 from uipath_llamaindex.query_engines import ContextGroundingQueryEngine
-from llama_index.core.tools import QueryEngineTool, ToolMetadata
 
+# Inside a @step:
 query_engine = ContextGroundingQueryEngine(
     index_name="my_knowledge_base",
     folder_path="Shared",
-    response_synthesizer=response_synthesizer,
+    response_synthesizer=get_response_synthesizer(llm=UiPathOpenAI()),
 )
+response = await query_engine.aquery(ev.question)
+```
+
+As an agent tool:
+
+```python
+from llama_index.core.tools import QueryEngineTool, ToolMetadata
 
 tools = [
     QueryEngineTool(
@@ -289,6 +315,42 @@ tools = [
 ]
 ```
 
+#### Workflow RAG with ContextGroundingRetriever
+
+```python
+from llama_index.core.workflow import StartEvent, StopEvent, Workflow, step
+from uipath_llamaindex.llms import UiPathOpenAI
+from uipath_llamaindex.retrievers import ContextGroundingRetriever
+
+class QuestionEvent(StartEvent):
+    question: str
+
+class AnswerEvent(StopEvent):
+    answer: str
+
+class RagAgent(Workflow):
+    @step
+    async def answer(self, ev: QuestionEvent) -> AnswerEvent:
+        retriever = ContextGroundingRetriever(
+            index_name="my_knowledge_base",
+            folder_path="Shared",
+            number_of_results=5,
+        )
+        nodes = await retriever.aretrieve(ev.question)
+        if not nodes:
+            return AnswerEvent(answer="No relevant passages found in the knowledge base.")
+        passages = "\n\n".join(n.node.get_content() for n in nodes)
+        llm = UiPathOpenAI()
+        response = await llm.acomplete(
+            "Answer the question using ONLY the passages below. "
+            "If they do not answer it, say so.\n\n"
+            f"Passages:\n{passages}\n\nQuestion: {ev.question}"
+        )
+        return AnswerEvent(answer=str(response))
+
+workflow = RagAgent(timeout=60)
+```
+
 ### Human-in-the-Loop
 
 ```python

package/skills/uipath-agents/references/coded/lifecycle/deployment.md

@@ -122,9 +122,12 @@ In all three cases, when the downstream goal is consumption rather than upgrade:
 | `pyproject.toml` | You | Project name, version, dependencies |
 | `entry-points.json` | `uip codedagent init` | Entry points and input/output schemas |
 | `bindings.json` | `uip codedagent init` | Runtime bindings |
+| `.env` | You | Local-run environment variables + `UIPATH_PROJECT_ID`. Neither packaged nor pushed — see [environment-variables.md](environment-variables.md) |
 
 `uip codedagent deploy` and `invoke` read credentials (`UIPATH_URL`, `UIPATH_ACCESS_TOKEN`, org/tenant identifiers) from your active `uip login` session — no manual `.env` wiring is required.
 
+A deployed agent's environment variables come from Orchestrator (process- or job-level), not `.env`. To supply one from an asset instead of a literal, set its value to `%ASSETS/<ASSET_NAME>%` — resolved against the **job's** folder at dispatch. See [environment-variables.md](environment-variables.md).
+
 ## Typical Flow
 
 1. `uip codedagent run <ENTRYPOINT> '<input>'` — verify locally.

package/skills/uipath-agents/references/coded/lifecycle/environment-variables.md

@@ -0,0 +1,90 @@
+# Coded Agent Environment Variables
+
+Where a coded agent's environment variables are stored, which store the runtime reads, and how to pull a value from an Orchestrator asset instead of hardcoding it.
+
+## Three stores, one variable
+
+Not the same store. Only one is what the cloud runtime reads.
+
+| Store | Read by | Authored with |
+|-------|---------|---------------|
+| `<PROJECT_DIR>/.env` | Local runs only (`uip codedagent run`, `uipath run`) | Edit file directly |
+| Project configuration (AgentHub) | Cloud runtime, every debug and Studio Web run | Studio Web → agent properties → **Coded agent environment variables**. VS Code extension mirrors `.env` here on debug |
+| Orchestrator process / job environment variables | Published agent started as an Orchestrator job | `uip or processes update --environment-variables`, or per job on `jobs start` — see [`uipath-platform` run-jobs](../../../../uipath-platform/references/orchestrator/run-jobs.md) |
+
+Consequences:
+
+1. **`.env` is not pushed.** `uip codedagent push` excludes it — see [file-sync](file-sync.md) § Files Involved. Editing `.env` alone changes nothing in the cloud.
+2. **Local and cloud runs can disagree.** Different stores. Diagnose a cloud-only failure by comparing both, not by trusting `.env`.
+3. **No credentials in `.env`.** `UIPATH_URL`, `UIPATH_ACCESS_TOKEN`, org/tenant identifiers come from the `uip login` session. `UIPATH_PROJECT_ID` is the one identity value that belongs there.
+
+## Referencing an Orchestrator asset
+
+Set a variable's whole value to `%ASSETS/<ASSET_NAME>%`. The platform substitutes the asset's value before the agent process starts; the agent reads an ordinary environment variable and never calls the Assets API.
+
+```env
+MY_API_KEY=%ASSETS/ServiceApiKey%
+DATABASE_HOST=%ASSETS/DbHost%
+```
+
+```python
+import os
+
+api_key = os.getenv("MY_API_KEY")
+```
+
+The asset name stays out of the code, so it can be re-pointed per environment without a code change.
+
+### Format rules
+
+1. **Whole value only.** `%ASSETS/Name%` resolves. `https://%ASSETS/Host%/api` does not — passed through as literal text, no error.
+2. **Uppercase prefix: `%ASSETS/`.** One parser in the chain compares the prefix case-sensitively, so `%assets/Name%` silently fails to resolve on the published path even though the design-time editor accepts it.
+3. **Asset name matched case-insensitively.** Name only between the slash and closing `%` — no folder path.
+4. **One asset per variable.** No concatenation, no default value.
+
+### Lookup folder
+
+The reference carries no folder, so the folder comes from the launch path. Most common reason a reference resolves in one place but not another:
+
+| Launch path | Lookup folder |
+|-------------|---------------|
+| Debug run (Studio Web or VS Code extension) | User's **personal workspace** |
+| Published agent started as an Orchestrator job | The **job's** folder — not the agent's, not where the package was published |
+
+An asset that exists only in a solution folder resolves for the deployed agent but not while debugging. Create it in the personal workspace too when both paths are needed.
+
+### Asset value types
+
+`Text`, `Bool`, `Integer`, `Secret` resolve. `KeyValueList` and connection-string types have no single-string form and never resolve. Credential types behave differently across the debug and published paths — do not reference them from an environment variable.
+
+### Failures are silent
+
+> An unresolvable reference — asset missing from the lookup folder, no permission, unsupported value type, lowercase prefix — does NOT fail the job and does NOT log a user-visible error. The value resolves to empty and the variable is then dropped from the process environment, so the agent sees it as unset. Nothing anywhere reports why.
+
+Fail loudly in agent code instead:
+
+```python
+api_key = os.getenv("MY_API_KEY")
+if not api_key:
+    raise ValueError("MY_API_KEY is not set — check the referenced asset exists in the job's folder")
+```
+
+## Solution resources
+
+Saving env vars in Studio Web also registers each referenced asset as a resource on the surrounding solution.
+
+## Anti-patterns
+
+1. **Do not expect `%ASSETS/...%` to resolve locally.** Substitution is server-side. `uip codedagent run` reads `.env` verbatim, so `os.getenv` returns the literal `%ASSETS/Name%`. Put a real value in `.env` for local testing.
+2. **Do not embed a reference in a larger string.** Format rule 1 — no substitution, no warning.
+3. **Do not add a variable to `.env` and expect a cloud run to see it.** `.env` is not pushed. Update the project configuration, or debug from the VS Code extension, which mirrors the file.
+4. **Do not log a resolved secret.** After substitution it is an ordinary string in the process environment; dumping the environment exposes it.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Agent prints literal `%ASSETS/Name%` | Local run | Expected. Put a real value in `.env`. For a cloud run, check the project configuration, not `.env` |
+| Variable unset in a cloud run | Reference did not resolve, variable dropped | Confirm the asset exists in the lookup folder for that launch path: `uip or assets list --folder-path "<FOLDER_PATH>" --output json` |
+| Resolves when deployed, not when debugging | Asset is in the solution folder; debug looks in the personal workspace | Create the asset in the personal workspace too |
+| Stored with lowercase prefix | `%assets/` fails the case-sensitive prefix check on the published path | Rewrite as `%ASSETS/` |

package/skills/uipath-agents/references/coded/lifecycle/file-sync.md

@@ -35,6 +35,8 @@ UIPATH_PROJECT_ID=12345
 
 `UIPATH_URL`, `UIPATH_ACCESS_TOKEN`, and org/tenant identifiers come from the `uip login` session automatically — do not add them to `.env`.
 
+`.env` may also hold the agent's own runtime environment variables, but it is **not** pushed (see [Files Involved](#files-involved)) — editing it does not change what a cloud run sees. For the store the cloud runtime reads, and for referencing an Orchestrator asset with `%ASSETS/<ASSET_NAME>%`, see [environment-variables.md](environment-variables.md).
+
 ## Pull
 
 Downloads all files from the remote Studio Web project to your local workspace, preserving directory structure.
@@ -94,7 +96,7 @@ uip codedagent push --overwrite
 | `pyproject.toml`, `main.py`, `.py`, `.json`, `.yaml` | yes | Project source and metadata |
 | `uipath.json`, `entry-points.json`, `bindings.json` | yes | UiPath project configuration |
 | `uv.lock` | yes (skip with `--nolock`) | Dependency lockfile |
-| `__pycache__/`, `.git/`, `.uipath/`, `.env` | no | Build artifacts, VCS, secrets |
+| `__pycache__/`, `.git/`, `.uipath/`, `.env` | no | Build artifacts, VCS, secrets — for `.env` see [environment-variables.md](environment-variables.md) |
 
 Use `packOptions` in `uipath.json` to refine what gets included.
 

package/skills/uipath-agents/references/coded/quickstart.md

@@ -59,6 +59,7 @@ Each stage has a reference file with detailed instructions. Read **only** the re
 | **Setup** | [lifecycle/setup.md](lifecycle/setup.md) | `uv venv --python 3.13`, `source .venv/bin/activate`, `uip codedagent setup --force`, `uip codedagent new <name>`, `uv add <framework-package>`, `uv add uipath-dev --dev`, `uv sync`, `uip codedagent init` |
 | **Build** | [lifecycle/build.md](lifecycle/build.md) | Code agent logic with framework patterns |
 | **Bindings** | [lifecycle/bindings-reference.md](lifecycle/bindings-reference.md) | Sync resource overrides in `bindings.json` |
+| **Env vars** | [lifecycle/environment-variables.md](lifecycle/environment-variables.md) | Which store the cloud runtime reads (not `.env`); `%ASSETS/<ASSET_NAME>%` to pull a value from an Orchestrator asset |
 | **Run** | [lifecycle/running-agents.md](lifecycle/running-agents.md) | `uip codedagent run` |
 | **Evaluate** | [lifecycle/evaluate.md](lifecycle/evaluate.md) | `uip codedagent eval` |
 | **Deploy** | [lifecycle/deployment.md](lifecycle/deployment.md) | `uip codedagent deploy`, `uip codedagent invoke` |
@@ -250,24 +251,27 @@ Execute the following in order, end-to-end, in one pass — do not pause for con
 
    This auto-registers the flow as a project in the solution.
 
-3. **Scaffold the coded agent as a sibling folder.** From the solution root (still inside `<SolutionName>/`):
+3. **Scaffold the coded agent as a sibling folder.** From the solution root (still inside `<SolutionName>/`) — `uip codedagent new` scaffolds into the **current directory**, it does NOT create a subfolder, so create the agent folder first and run everything inside it:
 
    ```bash
+   mkdir "<AgentName>"
+   cd "<AgentName>"
    uv venv --python 3.13
    source .venv/bin/activate        # .venv\Scripts\activate on Windows
-   uv add <framework-package>       # e.g. uipath-langchain for LangGraph
-   uv add uipath-dev --dev
-   uv sync
+   uv pip install <framework-package>   # e.g. uipath-langchain for LangGraph
    uip codedagent setup --force
    uip codedagent new "<AgentName>"
+   uv add uipath-dev --dev
+   uv sync
    ```
 
+   `uv add` requires the `pyproject.toml` that `codedagent new` generates — run it only after `new`, never at the solution root.
+
    Result: `<SolutionName>/<AgentName>/` sibling to `<SolutionName>/<FlowName>/`.
 
-4. **Implement the agent's `main.py`** with lazy LLM initialization (LLM clients inside graph nodes only — never at module top level), then regenerate entry-points / bindings:
+4. **Implement the agent's `main.py`** with lazy LLM initialization (LLM clients inside graph nodes only — never at module top level), then regenerate entry-points / bindings (still inside `<AgentName>/`):
 
    ```bash
-   cd "<AgentName>"
    uip codedagent init
    ```
 

package/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails-recommend.md

@@ -33,7 +33,9 @@ else:
   uip agent guardrails catalog --output json > .guardrails-catalog-cache.json
   ```
 
-Inspect the saved JSON. If the output contains `"Code": "GuardrailCatalogUnavailable"`, surface the message to the user and **stop** — do not fall back to guessing. This means the catalog endpoint is not yet available for this tenant. Note: the CLI writes all structured output (both success and error JSON) to stdout, so the redirect captures error responses correctly — do not add `2>&1`.
+Inspect the saved JSON. **Only stop for the specific, structured signal that the catalog endpoint itself is unavailable:** the output contains `"Code": "GuardrailCatalogUnavailable"`. In that exact case, surface the message to the user and **stop** — do not fall back to guessing. Note: the CLI writes all structured output (both success and error JSON) to stdout, so the redirect captures error responses correctly — do not add `2>&1`.
+
+**A generic CLI parse error is a different signal — do not stop for it.** If the output is instead something like `"Message": "error: unknown command 'catalog'"` (a `ValidationError`/parse error, not `GuardrailCatalogUnavailable`), that means this CLI build predates the `catalog` subcommand — it is an older/local build, not a tenant-side unavailability. Do not halt the whole workflow on this. Fall back to `uip agent guardrails list` plus built-in reasoning about the request, note in the report that the catalog command wasn't available on this CLI build, and continue.
 
 The cache file is `.guardrails-catalog-cache.json` in the current working directory. Add it to `.gitignore` if one exists.
 
@@ -47,6 +49,8 @@ uip agent guardrails list --output json
 
 Build a lookup of `{ validatorId: status }` from the `Data` array. You will use this in Steps 2 and 5 to filter recommendations.
 
+> **`Validator` is not unique — key the lookup on `(Validator, IsByo)`, not `Validator` alone.** A tenant with a bring-your-own (BYOG) configuration for a validator sees two entries sharing the same `Validator` name — one built-in (`IsByo` absent/false), one BYO (`IsByo: true`, carrying `ByoValidatorName`/`ByoConfigurationId`/etc.). Collapsing them into a single `{ validatorId: status }` key silently picks whichever entry happens to win the collision and can validate against the wrong `Parameters`/`AllowedScopes`. See [guardrails.md § BYO (bring-your-own) guardrails](guardrails.md#byo-bring-your-own-guardrails).
+
 > **Catalog vs. list — the key distinction:** The catalog lists all guardrails that exist on the platform (with rich metadata for reasoning). The guardrails list returns only those accessible to this tenant. Only recommend validators where `Status == "Available"` in the list.
 
 ---
@@ -73,6 +77,11 @@ its input or output (literal word/phrase, regex, number, boolean, or always),
 use the custom deterministic recipe below. This decision happens before
 built-in catalog candidate ranking:
 
+0. **Run the Step 0 catalog and guardrails-list fetches now, even though this
+   branch does not use their content to pick a validator.** They are still
+   mandatory discovery/audit steps before writing any guardrail — this branch
+   only skips catalog-driven *ranking* (step 2 below), not the Step 0 calls
+   themselves.
 1. Treat quoted text and a distinct all-caps token such as `CONFIDENTIAL` as
    an exact literal predicate, even when the surrounding request is phrased
    semantically (for example, "worried it might publish CONFIDENTIAL content"
@@ -92,8 +101,8 @@ built-in catalog candidate ranking:
 Broad semantic threats without an exact mechanical predicate continue through
 the built-in catalog ranking in Step 2.
 
-Once this deterministic branch matches, the catalog/list calls remain
-mandatory discovery steps but cannot replace or override the custom rule with
+Once this deterministic branch matches, the Step 0 catalog/list calls (already
+run per step 0 above) cannot replace or override the custom rule with
 `llm_as_judge`, PII detection, or any other built-in validator.
 
 ### Step 2 — Catalog-Driven Recommendation Analysis
@@ -114,6 +123,8 @@ For **each entry** in the catalog (`guardrails[]` array from the cached JSON):
 
 Do **not** apply predetermined knowledge about which guardrail maps to which schema field. Let the catalog entry's authored fields drive every recommendation decision.
 
+> **Built-in vs. BYO — default to built-in.** When a matched validator has both a built-in entry and one or more `Available` BYO (`IsByo: true`) entries in the guardrails list, recommend the built-in implementation (omit `byoValidatorName`) by default, and mention that a BYO alternative exists. Only recommend a specific BYO configuration when the user names it or asks for BYO explicitly.
+
 ### Step 3 — De-duplicate Overlapping Validators
 
 Several catalog validators address the same threat. Recommending more than one of them at the same scope and stage is redundant — it doubles latency and cost on every call for marginal benefit (the canonical case is `prompt_injection` and `user_prompt_attacks`: both have `security_category: "adversarial_input"` and both run at Llm · PRE).
@@ -183,9 +194,12 @@ Generate a fresh UUID for each guardrail `id`.
 Write the new guardrail blocks to `agent.json`'s `guardrails[]` array. Then run:
 
 ```bash
+uip agent refresh "<AgentName>" --output json
 uip agent validate "<AgentName>" --output json
 ```
 
+`refresh` regenerates `entry-points.json` and `bindings_v2.json` so Studio Web sees the updated guardrails — always run it before `validate`, matching [guardrails.md](guardrails.md)'s base walkthrough.
+
 **Deterministic completion gate:** when the request matched the exact
 named-Tool branch, re-read `agent.json` before validation and confirm the
 written entry has `$guardrailType: "custom"`, Tool scope, the exact Tool name,
@@ -211,7 +225,7 @@ For each existing guardrail in `agent.json`'s `guardrails[]`:
 
 ### Correctness Check
 
-Run `uip agent guardrails list --output json` (from Step 0) and find the matching validator by `Validator` name. The `Parameters` array is the authoritative source for all validation rules:
+Run `uip agent guardrails list --output json` (from Step 0) and find the matching validator by `Validator` name. **If more than one entry shares that `Validator` name** (a built-in plus one or more BYOG entries), disambiguate before reading `Parameters`: the guardrail JSON carries `byoValidatorName` when it targets a specific BYO configuration — match on that against the list entries' `ByoValidatorName`; if the guardrail JSON has no `byoValidatorName`, it targets the built-in entry (`IsByo` absent/false). Validating against the wrong entry's `Parameters` produces false correctness findings. The `Parameters` array (of the correctly matched entry) is the authoritative source for all validation rules:
 
 | CLI field | What to check |
 |-----------|---------------|
@@ -252,7 +266,7 @@ If the user asks to fix identified issues: apply corrections to `agent.json`, ru
 ## Critical Rules
 
 1. **Always fetch catalog first** (use cache if fresh); **always fetch guardrails list second** (no cache). Both are required before any analysis.
-2. **If `GuardrailCatalogUnavailable`** → surface the message and stop. Do not fall back to guessing or hardcoded recommendations.
+2. **If the catalog call returns `"Code": "GuardrailCatalogUnavailable"`** → surface the message and stop. Do not fall back to guessing or hardcoded recommendations. **A generic CLI error (e.g. `"unknown command 'catalog'"`) is not this signal** — that means an older CLI build, not tenant unavailability; fall back to `guardrails list` + built-in reasoning and note the limitation in the report instead of halting.
 3. **Only recommend `Available` validators**. Mention `Unauthorised` ones to the user so they can contact their administrator.
 4. **Every recommendation must cite** the catalog entry's `when_to_use` or a specific `use_cases` item that matched the agent's context. Do not recommend a guardrail without explaining why it applies.
 5. **Never recommend two validators with the same `security_category` at the same scope and stage** (e.g. `prompt_injection` + `user_prompt_attacks` at Llm PRE). De-duplicate per Step 3: drop catalog-deprecated entries, keep the best fit, mention the alternative. Derive the grouping and deprecation from the catalog's own fields — do not hardcode validator names.
@@ -265,3 +279,4 @@ If the user asks to fix identified issues: apply corrections to `agent.json`, ru
 12. **All map-enum keys must exactly match the corresponding enum-list values** — no extra or missing keys. This is the most common correctness error.
 13. **Read [guardrails.md](guardrails.md) before writing any JSON** — discriminator fields, PascalCase constraints, and parameter shapes are specified there and cannot be safely inferred.
 14. **Do NOT use TaskCreate, TaskUpdate, or other task-tracking tools for guardrail edits.** Edit `agent.json` directly — task management tools add bookkeeping turns without benefit and push runs over their turn budget.
+15. **`Validator` is not unique — disambiguate built-in vs. BYO by `IsByo` before matching on name.** A tenant can have both a built-in and one or more BYOG entries sharing the same `Validator` name. Key any lookup on `(Validator, IsByo)`, and when an existing guardrail carries `byoValidatorName`, match it against `ByoValidatorName` — not `Validator` alone — before reading `Parameters`/`AllowedScopes` for correctness or recommendation. Default recommendations to the built-in entry unless the user asks for BYO. See [guardrails.md § BYO (bring-your-own) guardrails](guardrails.md#byo-bring-your-own-guardrails).

package/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails.md

@@ -625,9 +625,21 @@ Run `uip agent guardrails list --output json` to get the authoritative list. Onl
 | `GuardrailStages[scope]` | Valid execution stages for that scope |
 | `Parameters[].Id` | `validatorParameters[].id` |
 | `Parameters[].Type` | `validatorParameters[].$parameterType` |
+| `IsByo` | Disambiguates a bring-your-own (BYOG) entry from a built-in one — see [BYO (bring-your-own) guardrails](#byo-bring-your-own-guardrails) below. Not itself a JSON field. |
+| `ByoValidatorName` | `byoValidatorName` value — include this field to pin the guardrail to this exact BYO configuration. Required whenever more than one entry shares this `Validator` name (a built-in plus one or more BYOG configurations). |
 
 > **Important:** PII entity names use PascalCase (`"Email"`, not `"email_address"`). Harmful content categories use PascalCase (`"Hate"`, not `"hate"`). Scope values use PascalCase (`"Agent"`, `"Llm"`, `"Tool"`).
 
+## BYO (bring-your-own) guardrails
+
+A validator can be fulfilled by a tenant-registered **external** provider (a "BYOG" configuration — e.g. Azure AI Content Safety, Databricks AI Guardrails) instead of, or alongside, UiPath's own built-in implementation. A tenant admin registers these at Admin → AI Trust Layer → Guardrails Configurations or via `uip guardrails byo-configurations create`; see [uipath-platform § BYO Guardrail Configurations](/uipath:uipath-platform) for the admin-side lifecycle commands (`uip guardrails byo-configurations list|create|update|delete`).
+
+- **`Validator` is not unique.** A tenant with a BYOG `harmful_content` configuration sees **two** entries named `harmful_content` in `uip agent guardrails list` output — one built-in, one BYO. Use `IsByo` to tell them apart; never assume a single match.
+- **Filter to BYO-only entries** with `uip agent guardrails list --byo --output json` when the user specifically wants to see or target a BYO-backed validator.
+- **BYO entries carry extra fields**: `ByoValidatorName`, `ByoConnectionId`, `ByoConfigurationId`, `ByoConnectorName`, `ByoConnectorKey`, `FolderKey` — alongside the same `Parameters`/`AllowedScopes`/`GuardrailStages`/`Status` shape a built-in entry has.
+- **To author a guardrail against a specific BYO configuration**, build the `builtInValidator` guardrail exactly as for a built-in validator (same `validatorType`, same `validatorParameters` from that entry's `Parameters`), and add `byoValidatorName` set to that entry's `ByoValidatorName`. Omit it to use the built-in implementation. (`ByoConfigurationId` is the configuration's own admin-side id — useful for cross-referencing `uip guardrails byo-configurations list`, but it is not what the guardrail JSON carries; `ByoValidatorName` is unique per tenant and is the value that pins it.)
+- **`Status: "Disabled"` on a BYO entry** means the tenant switched that specific configuration off — the entry still shows (it doesn't vanish), so a disabled BYOG configuration is distinguishable from one that was never set up. Do not author a guardrail against a `Disabled` BYO entry; treat it the same as `Unauthorised` (skip, tell the user).
+
 ## Full Examples
 
 ### Example 1: Block PII in Agent and Tool Outputs
@@ -1030,6 +1042,7 @@ Add the `guardrails` array at the agent.json root level alongside `settings`, `m
 18. **Do not attempt OR logic within a single guardrail** — all rules and all fields within a guardrail are combined with AND. OR is not supported. To achieve OR behavior, create separate guardrails — one per condition branch.
 19. **Do not generate guardrails targeting unsupported tool types** — `matchNames` can only reference tools of supported types: agent, process, activity, builtInTool, ixpTool, or Integration Service connector. Do not generate guardrails with `matchNames` targeting other tool types.
 20. **Do not omit `matchNames` to target "all tools"** — always explicitly list every tool resource name in `matchNames`. Read the agent's `resources/` directory first. If the agent has no tool resources, do not add the guardrail.
+21. **Do not assume `Validator` is unique** — a tenant can have both a built-in and one or more bring-your-own (BYOG) entries sharing the same `Validator` name. Always check `IsByo` before treating two same-named entries as a duplicate or conflict, and set `byoValidatorName` when targeting a specific BYO entry. See [BYO (bring-your-own) guardrails](#byo-bring-your-own-guardrails).
 
 ## Walkthrough
 

package/skills/uipath-agents/references/lowcode/capabilities/inline-in-flow/inline-in-flow.md

@@ -213,8 +213,6 @@ Resource body shape is identical to the standalone-agent docs — only the folde
   "typeVersion": "1.0",
   "display": { "label": "Autonomous Agent" },
   "inputs": {
-    "systemPrompt": "You are an agentic assistant.",
-    "userPrompt": "What is the current date?",
     "source": "<projectId-uuid>",        // UUID linking to the inline agent directory
     "agentInputVariables": [],
     "agentOutputVariables": [
@@ -240,7 +238,7 @@ Resource body shape is identical to the standalone-agent docs — only the folde
 
 **Critical fields:**
 - `inputs.source` — The inline agent's `projectId` UUID. Must match the subdirectory name and `agent.json.projectId` inside the flow project. The definition still declares `model.source: true`, but flow-core hoists that identity field onto `inputs.source` for the `uipath.agent.autonomous` node instance.
-- `inputs.systemPrompt` / `inputs.userPrompt` — Current flow validation requires non-empty placeholders on the node. The canonical prompts still live in `agent.json.messages[]`.
+- `inputs.systemPrompt` / `inputs.userPrompt` — **do not write these keys.** A prompt string on the node makes the flow converter drop every `agentInputVariables[]` entry the prompt text does not reference. Empty strings fail `uip maestro flow validate`. The canonical prompts live in `agent.json.messages[]`. Validator behavior and the older-CLI fallback: [inline-agent guide § Refresh and Validate](../../../../../uipath-maestro-flow/references/author/references/plugins/inline-agent/impl.md#refresh-and-validate).
 - `definitions[]` — The `uipath.agent.autonomous` definition copied from the flow registry supplies `model.serviceType: "Orchestrator.StartInlineAgentJob"`, BPMN type, version, and context. Do not copy those fields into the node instance.
 - No node instance `model` block — the inline-agent source lives at `inputs.source`.