@uipath/skills 1.195.0

package/skills/uipath-agents/references/coded/capabilities/file-attachments.md

@@ -0,0 +1,99 @@
+# File Attachments
+
+How to work with files in a coded agent — as input, as output, or created mid-run.
+
+For the low-code equivalent, see `../../lowcode/capabilities/built-in-tools/analyze-attachments.md`.
+
+## File as Input
+
+Use `Attachment` on the `Input` model. `uip codedagent init` emits the `job-attachment` schema in `entry-points.json` so Studio Web and Orchestrator render a file picker at runtime.
+
+```python
+from pydantic import BaseModel
+from uipath.platform.attachments import Attachment
+
+class Input(BaseModel):
+    attachment: Attachment
+```
+
+Run `uip codedagent init` after the edit to refresh `entry-points.json`.
+
+Access fields as snake_case, e.g. `input.attachment.full_name`.
+
+`Attachment` carries metadata only. Fetch bytes via `sdk.attachments` (instantiate inside the function, never at module level):
+
+```python
+from uipath.platform import UiPath
+
+async def main(input: Input) -> Output:
+    uipath = UiPath()
+    async with uipath.attachments.open_async(attachment=input.attachment) as (att, response):
+        async for raw_bytes in response.aiter_raw():
+            ...
+```
+
+Sync equivalent: `sdk.attachments.open(...)`.
+
+## Creating Attachments
+
+Produce a file from the agent and attach it to the current job:
+
+```python
+from uipath.platform.common import UiPathConfig
+
+await uipath.jobs.create_attachment_async(
+    name="report.txt",
+    content=str(result),
+    folder_key=UiPathConfig.folder_key,
+    job_key=UiPathConfig.job_key,
+)
+```
+
+Standalone uploads (not tied to a job) go through `sdk.attachments` — see the SDK reference.
+
+## Local Testing
+
+`uip codedagent run` / `invoke` cannot upload attachments — the platform file picker only exists in Studio Web / Orchestrator. To exercise attachment logic locally without making `Input.attachment` optional, detect the run context via `UiPathConfig.job_key` (`None` outside a platform job, populated inside Orchestrator / Studio Web) and load bytes from an environment variable. Pass a placeholder `Attachment` in the CLI input just to satisfy validation — the agent ignores its fields on the local branch.
+
+```python
+import os
+from pathlib import Path
+from uipath.platform import UiPath
+from uipath.platform.common import UiPathConfig
+
+async def read_attachment_bytes(input: Input) -> bytes:
+    if UiPathConfig.job_key is None:
+        return Path(os.environ["UIPATH_LOCAL_ATTACHMENT"]).read_bytes()
+
+    uipath = UiPath()
+    async with uipath.attachments.open_async(attachment=input.attachment) as (_att, response):
+        return b"".join([chunk async for chunk in response.aiter_raw()])
+```
+
+Invoke locally — placeholder `Attachment` satisfies the schema, env var provides the real file:
+
+```bash
+UIPATH_LOCAL_ATTACHMENT=C:/tmp/sample.pdf uip codedagent run main '{"attachment": {"ID": "00000000-0000-0000-0000-000000000000", "FullName": "placeholder", "MimeType": "application/octet-stream"}}'
+```
+
+Same pattern for **creating** attachments — when `job_key is None`, write to disk instead of calling `jobs.create_attachment_async`:
+
+```python
+if UiPathConfig.job_key is None:
+    Path(os.environ.get("UIPATH_LOCAL_OUTPUT_DIR", ".")).joinpath("report.txt").write_text(str(result))
+else:
+    await uipath.jobs.create_attachment_async(
+        name="report.txt",
+        content=str(result),
+        folder_key=UiPathConfig.folder_key,
+        job_key=UiPathConfig.job_key,
+    )
+```
+
+## Gotchas
+
+- `uip codedagent run` / `invoke` cannot upload attachments — use the env-var fallback above, or test the platform path via Studio Web / Orchestrator.
+
+## References
+
+- `sdk-services.md` § Attachments, § Jobs

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

@@ -0,0 +1,284 @@
+# Guardrail Recommendation and Validation — Coded Agents
+
+This reference covers two workflows for Python coded agents (LangChain/LangGraph):
+- **Recommend**: The agent has no guardrails (or insufficient ones) → which guardrails should be added?
+- **Validate**: The agent already has guardrails → are they correctly configured and appropriate?
+
+Both workflows are driven by live data — the catalog (`uip agent guardrails catalog`) for recommendation reasoning, the guardrails list (`uip agent guardrails list`) for tenant-availability and parameter/scope constraints, and the live UiPath Python SDK docs (`WebFetch`) for mapping catalog `validator_id` values to Python middleware/Validator class names. Do not hardcode assumptions about which guardrail fits which agent type, or which Python class implements which validator.
+
+> **This file covers WHEN to add guardrails and WHY. For the exact Python writing patterns (middleware spread with `*`, decorator placement, factory refactors), always read [guardrails.md](guardrails.md) before editing the agent code.**
+
+---
+
+## Step 0 — Fetch Catalog, Available Validators, and SDK Docs (MANDATORY — do this before any analysis)
+
+### Catalog (cacheable — 30-minute TTL)
+
+The catalog is the same for all tenants (authored metadata, rarely changes). Cache it locally for 30 minutes to avoid redundant calls.
+
+```bash
+python3 -c "
+import os, time
+cache = '.guardrails-catalog-cache.json'
+if os.path.exists(cache) and (time.time() - os.path.getmtime(cache)) < 1800:
+    print('CACHE_HIT')
+else:
+    print('CACHE_MISS')
+"
+```
+
+- **CACHE_HIT**: read `.guardrails-catalog-cache.json` directly.
+- **CACHE_MISS**: fetch and save:
+  ```bash
+  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. 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`.
+
+The cache file is `.guardrails-catalog-cache.json` in the current working directory. Add it to `.gitignore` if one exists.
+
+### Guardrails List (NEVER cached — tenant-specific)
+
+This returns only guardrails available to the current tenant (filtered by entitlements and feature flags). Run it fresh every time:
+
+```bash
+uip agent guardrails list --output json
+```
+
+Build a lookup of `{ validatorId: status }` from the `Data` array. You will use this to filter recommendations.
+
+> **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)
+
+Coded agents reference guardrails by **Python class name** (e.g. `UiPathPIIDetectionMiddleware`, `PIIDetectionValidator`), not by `validator_id`. The catalog gives you the `validator_id`; the SDK docs give you the corresponding Python classes, import paths, scope/stage enums, and entity-type enums.
+
+Identify the agent's framework first (read `pyproject.toml` and the entrypoint imports), then fetch the SDK doc pages. Today only **LangChain** has a published UiPath guardrail adapter; for any other framework, the platform SDK is the only source.
+
+Always fetch the **core** page (validators, entity enums, scope/stage enums, action classes — usable on any framework):
+
+`https://uipath.github.io/uipath-python/core/guardrails/`
+
+If the agent is a **LangChain / LangGraph** agent (detected by `uipath-langchain` in `pyproject.toml` or `from langchain...` / `from langgraph...` imports), additionally fetch:
+
+`https://uipath.github.io/uipath-python/langchain/guardrails/`
+
+This is the LangChain adapter page — it documents the middleware classes, their supported scopes/stages, and the correct `uipath_langchain.guardrails` import paths. The framework adapter is needed for the `@guardrail` decorator / middleware to actually wrap the LLM / tool / agent (see [guardrails.md § Imports Pattern](guardrails.md#imports-pattern)).
+
+If the agent uses any other framework (LlamaIndex, OpenAI Agents, plain Python, etc.) there is no published framework adapter yet — only the core page applies. The decorator/middleware mechanism cannot auto-wrap those framework objects without an adapter; you may need to invoke validators directly. Do not invent doc URLs for frameworks that do not have one.
+
+Call `WebFetch` once per page. From the core page extract Validator classes, entity-type enums, `GuardrailScope` / `GuardrailExecutionStage`, and Action classes. From the LangChain page (when applicable) extract middleware classes, supported scopes/stages, extra parameters, and the correct `uipath_langchain.guardrails` import paths.
+
+**Use the fetched content as the sole source of truth.** Never rely on memory for class names, enum members, or import paths — the SDK evolves and the docs are the only reliable mapping.
+
+Build a `{ validator_id → { middleware_class, validator_class, entity_enum, allowed_scopes, allowed_stages } }` lookup in working memory by joining catalog entries with SDK class names.
+
+---
+
+## Recommend Mode
+
+Use when the agent has no guardrails or when the user asks which guardrails to add.
+
+### Step 1 — Read Agent Code
+
+Use `Glob` / `Grep` to locate the entrypoint Python file. Look for `create_agent`, `StateGraph`, or `@entrypoint`. Once found, read it to extract:
+
+- **System prompt text** — what does the agent do? What domains and behaviors are described?
+- **Input / output schemas** (`pydantic.BaseModel` classes or function signatures) — what data does the agent receive and produce?
+- **`@tool` functions** — name, docstring, signature. These become the targets of Tool-scoped guardrails.
+- **LLM factory** — is the LLM created inside a named function (e.g. `def create_llm(): return UiPathChat(...)`) or assigned directly at module level? Decorator-style LLM-scope guardrails require a factory.
+- **Agent factory** — is `create_agent(...)` wrapped in a named function? Decorator-style Agent-scope guardrails require a factory.
+- **Existing guardrails** — any `@guardrail(...)` decorators above functions, or `*UiPath…Middleware(...)` entries inside `middleware=[...]` in `create_agent(...)`. Note them to avoid duplicating.
+
+### Step 2 — Catalog-Driven Recommendation Analysis
+
+For **each entry** in the catalog (`guardrails[]` array from the cached JSON):
+
+1. Read the entry's `when_to_use`, `use_cases`, `description`, and `security_risk_addressed`.
+2. Compare against agent context (system prompt, schemas, tool docstrings) using semantic reasoning:
+   - Does the agent's purpose align with the `when_to_use` scenario?
+   - Do any `use_cases` items describe what this agent does or the data it handles?
+   - Does the agent face the threat described in `security_risk_addressed`?
+3. Also read `when_not_to_use`. If the agent matches a disqualifying condition, exclude this validator from recommendations (or mention it with an explanation).
+4. Cross-reference with the guardrails list status lookup from Step 0:
+   - `Available` → candidate for recommendation
+   - `Unauthorised` → mention to the user ("this guardrail is not licensed for your tenant") but do NOT add it
+   - Not in the list at all → skip silently (not available on this platform version)
+5. If the validator is a candidate: use the catalog entry's `examples[].config` to determine the appropriate scope, stage, action, and parameters. Translate `validator_parameters` shape to the Python `Validator(...)` / `Middleware(...)` constructor arguments using the SDK docs from Step 0.
+
+Do **not** apply predetermined knowledge about which guardrail maps to which schema field. Let the catalog entry's authored fields drive every recommendation decision.
+
+### 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).
+
+After Step 2 produces the candidate list, group candidates by **(`security_category`, scope, stage)**. For any group with more than one candidate:
+
+1. **Drop deprecated or unavailable entries first.** If the catalog marks an entry deprecated (via its `status`, or a deprecation note in `notes` / `when_not_to_use`), remove it from the group. Never recommend a validator the catalog signals is being retired when an active alternative covers the same category.
+2. **Keep the single best fit** for the agent's context — the one whose `when_to_use` / `use_cases` most closely match. Recommend only that one.
+3. **Mention the alternative(s)** you dropped and why (e.g. "also recommending only User Prompt Attacks, not Prompt Injection — both cover adversarial input at LLM PRE and the catalog marks Prompt Injection deprecated").
+
+Do **not** hardcode validator names or a fixed "prefer X over Y" rule in your reasoning — derive the grouping from each entry's `security_category`, scope, and stage, and derive deprecation from the catalog's own fields. This keeps the behavior correct as the catalog evolves.
+
+### Step 4 — Style Choice
+
+If the user has not specified **middleware** or **decorator**, ask before generating any code. Do not implement both unless explicitly asked.
+
+Use the comparison table from the fetched `langchain/guardrails/` SDK doc (the "Choosing between patterns" section) to help the user decide if they ask.
+
+### Step 5 — Scope and Tool Filtering
+
+In coded agents, scopes map to concrete Python constructs, not selector strings:
+
+| Catalog scope | Coded mapping |
+|---------------|---------------|
+| `Agent` | `GuardrailScope.AGENT` on middleware, or `@guardrail` above a named **agent factory function** that returns `create_agent(...)`. If `create_agent(...)` is called at module level, refactor it into a factory first. |
+| `Llm` | `GuardrailScope.LLM` on middleware, or `@guardrail` above a named **LLM factory function** that returns `UiPathChat(...)`. If the LLM is assigned directly (`llm = UiPathChat(...)`), refactor into a factory first. |
+| `Tool` | `GuardrailScope.TOOL` on middleware with `tools=[<tool_obj>]` (Python object, not string), or `@guardrail` placed directly above a `@tool` function. |
+
+If the user asks for recommendations for a **specific tool** (e.g., "for the lookup_account_info tool"):
+- Tool scope only. Confirm the tool exists as a `@tool` function in the agent code before writing.
+- Pass the Python object (e.g. `lookup_account_info`) into `tools=[...]` — never a string name.
+
+If the user asks for recommendations for a **specific scope** (e.g., "only for Llm"):
+- Keep only candidates whose `allowed_scopes` (from the catalog entry and/or SDK class) include that scope.
+- Discard candidates that do not support that scope.
+
+#### Block as early as possible — default scope selection
+
+When a validator supports **more than one scope** (e.g. `pii_detection` allows Agent / Llm / Tool), pick the scope that stops a violation at the **outermost boundary the validator allows**, so a bad run is halted with the least wasted work:
+
+| Guardrail intent | Prefer | Why |
+|---|---|---|
+| **Input protection** (block bad/sensitive input: PII, jailbreak, injection) | broadest **PRE** scope allowed → **Agent** > Llm > Tool | Agent · PRE fires once, before the agent reaches the LLM or any tool. Catching PII or an attack at Agent · PRE blocks the whole run immediately instead of after the model has already been called. |
+| **Output protection** (block bad output the caller sees: harmful content, IP) | **Agent · POST** when allowed | Agent · POST inspects the agent's final answer — the thing the user actually receives. |
+| **Tool I/O protection** (a specific tool's input/output) | **Tool** scope on that tool | Only narrow to Tool when the concern is genuinely that one tool, or the user scoped it there. |
+
+Concretely: **PII detection meant to stop the agent handling personal data belongs at `GuardrailScope.AGENT` · PRE, not `GuardrailScope.LLM` · PRE** — both are allowed by the catalog, but Agent · PRE blocks the run earlier (before the LLM call) and covers the whole agent, not just one model invocation. Only drop to a narrower scope when the validator does not support the broader one (`prompt_injection` and `user_prompt_attacks` are Llm-only, so Llm · PRE is the earliest available for them) or when the user explicitly asks for a narrower scope.
+
+Always confirm the chosen scope is in the validator's `allowed_scopes` from the guardrails list — never assume a scope the catalog/SDK does not permit.
+
+### Step 6 — Choose the Action
+
+The action (`BlockAction` vs `LogAction`) is **not** a free choice — default to the `action_type` in the catalog entry's representative `examples[].config`. For security-critical guardrails (`adversarial_input` — prompt injection / user prompt attacks; `content_safety` — harmful content / IP) the catalog examples use **Block**, because a logged-but-allowed violation provides no actual protection.
+
+Rules:
+
+1. **Default to the catalog example's `action_type`.** If it is `Block`, generate `BlockAction(...)`. Do not substitute `LogAction` for a security-critical guardrail on your own initiative.
+2. **Never silently downgrade Block → Log.** A guardrail set to log-only when the user expected blocking is the dangerous failure mode — the agent looks protected but isn't. If you use `LogAction` for any guardrail whose catalog default is `Block`, you **must** state it explicitly in the report and give the reason.
+3. **Legitimate reasons to use Log instead of Block** (state which applies):
+   - The user explicitly asked for observe-only / audit / "log first, block later" rollout.
+   - A high false-positive risk where blocking would break normal operation (e.g. PII `PERSON` entity flagging ordinary words) — log so the user can tune thresholds before enforcing.
+4. **When ambiguous, ask once.** If the user gave no action preference and the guardrail is security-critical, you may apply the Block default and report it, or ask "block on violation, or log-only to start?" — but do not quietly pick Log.
+
+### Step 7 — Generate Code
+
+For each recommended guardrail, the catalog entry's `examples[].config` gives the scope/stage/action/parameter intent. Translate it to Python using the writing patterns in [guardrails.md](guardrails.md):
+
+- **Middleware** — spread the class with `*` into `create_agent(middleware=[...])`. For Tool scope, pass `tools=[<tool_obj>]`.
+- **Decorator** — place `@guardrail(validator=..., action=..., stage=...)` above the target (`@tool` function for Tool scope, LLM factory for LLM scope, agent factory for Agent scope).
+
+Use the action chosen in Step 6.
+
+Map catalog parameter shapes to Python:
+
+| Catalog `$parameterType` | Python representation |
+|--------------------------|----------------------|
+| `enum-list` (e.g. `entities`) | List of enum members (e.g. `[PIIDetectionEntityType.EMAIL, PIIDetectionEntityType.PHONE_NUMBER]`) — names taken from SDK docs |
+| `map-enum` (e.g. `entityThresholds`) | Dict from enum member → number (e.g. `{PIIDetectionEntityType.EMAIL: 0.5}`) — keys must exactly match the `enum-list` parameter's values |
+| `number` (e.g. `threshold`) | Plain `float` / `int` constructor argument |
+
+Use `BlockAction(...)`, `LogAction(severity_level=...)`, or other actions exposed by the SDK docs. Never invent action class names.
+
+> Read [guardrails.md](guardrails.md) before writing any Python. The middleware spread, decorator stacking, and factory refactor rules cannot be safely inferred.
+
+### Step 8 — Apply and Verify
+
+Write the recommended guardrails into the Python file using the patterns from [guardrails.md](guardrails.md). Then verify — in two stages, because syntax-valid does **not** mean active:
+
+1. **Syntax** — the file still parses:
+   ```bash
+   python3 -c "import ast; ast.parse(open('graph.py').read())"
+   ```
+2. **Runtime wiring (mandatory)** — the guardrails are actually attached. A guardrail whose symbols were imported from the wrong module parses fine but **silently never fires**. Run the adapter-registration and `_GuardedLLM` / `_GuardedTool` wrap checks from [guardrails.md § Verify Guardrails Are Actually Wired](guardrails.md#verify-guardrails-are-actually-wired-mandatory-after-writing). Do not report the guardrails as added until these pass.
+
+(Replace `graph.py` with the actual entrypoint file from Step 1.)
+
+Report to the user:
+- What was added (by validator name and Python class)
+- Why it was recommended (cite the catalog's `when_to_use` or a specific `use_cases` item that matched the agent's context)
+- Which scope and action were chosen and why. If you dropped an overlapping validator in Step 3, name it and the reason. If you used `LogAction` for a guardrail whose catalog default is `Block` (Step 6), call it out explicitly with the reason.
+- Which parameters were set and their meaning
+- Which style was used (middleware or decorator) and any refactor performed (e.g. wrapped LLM in a factory)
+
+---
+
+## Validate Mode
+
+Use when the agent already has guardrails and the user asks whether they are correctly configured or appropriate.
+
+**Before any validation, run all three Step 0 fetches** (catalog with cache, guardrails list without cache, SDK docs via WebFetch). The SDK docs are the authoritative source for which Python class corresponds to which `validator_id` and which scopes/stages each class supports.
+
+For each existing guardrail discovered in the Python file (Step 1 from Recommend Mode):
+
+### Correctness Check
+
+From the SDK docs and the catalog, look up the validator class referenced in the code:
+
+| Aspect | What to check |
+|--------|---------------|
+| Class import | Class is imported from the path the SDK docs specify (e.g. `from uipath_langchain.guardrails import UiPathPIIDetectionMiddleware`) — typos and stale imports fail at runtime |
+| Entity enums | Every entity/category passed (e.g. `PIIDetectionEntityType.EMAIL`) is a member listed in the SDK doc enum |
+| Threshold keys (`map-enum` parameters) | Every key in the threshold dict matches a member of the corresponding entity list — no extras, no missing |
+| Threshold values | Within the range and step the catalog parameter declares (e.g. harmful content severities must be `0`, `2`, `4`, or `6`) |
+| Action class | Action constructor (`BlockAction`, `LogAction`, ...) is one the SDK docs expose for this validator |
+| Required parameters | Any catalog parameter with `Required: true` is present in the constructor call |
+
+### Actionability Check
+
+1. From the catalog entry, read `allowed_scopes` and the per-scope allowed stages.
+2. Confirm the in-code scope is permitted:
+   - Middleware — every `GuardrailScope` in the `scopes=[...]` argument is in `allowed_scopes`.
+   - Decorator — the function the `@guardrail` decorates matches the implied scope: `@tool` for Tool scope, LLM factory for LLM scope, agent factory for Agent scope.
+3. Confirm the stage is permitted: `GuardrailExecutionStage.PRE` only where catalog allows pre-execution; `POST` only where catalog allows post-execution.
+4. For Tool-scoped middleware: `tools=[...]` must contain the actual `@tool` Python objects discovered in Step 1 — not strings, not undefined names.
+5. For decorator-style LLM/Agent scope: the decorated function must actually return a `UiPathChat(...)` / `create_agent(...)` — decorating an unrelated function silently no-ops.
+
+### Relevance Check
+
+1. Read the catalog entry's `when_not_to_use`.
+2. Compare against the agent's current context (system prompt, schemas, tool docstrings).
+3. If the agent matches a `when_not_to_use` condition, flag the guardrail as potentially misapplied and explain why.
+
+### Report and Fix
+
+Report per guardrail:
+- **OK** — no issues found
+- **Correctness issue** — describe the problem (e.g., "`harmfulContentEntityThresholds` has key `Sexual` but `Sexual` is not in `harmfulContentEntities` — keys must match the entity list") and the fix
+- **Actionability issue** — describe the problem (e.g., "`UserPromptAttacksValidator` is decorating `@tool def lookup_account_info` — the SDK docs say this validator only supports LLM scope; move the `@guardrail` above the LLM factory") and the fix
+- **Relevance issue** — describe why the guardrail may not be appropriate and what to consider instead
+
+If the user asks to fix identified issues: apply corrections to the Python file, then verify:
+
+```bash
+python3 -c "import ast; ast.parse(open('graph.py').read())"
+```
+
+---
+
+## Critical Rules
+
+1. **Always fetch catalog first** (use cache if fresh); **always fetch guardrails list second** (no cache); **always fetch the two SDK doc pages via WebFetch third** (no cache). All three are required before any analysis or code edit.
+2. **If `GuardrailCatalogUnavailable`** → surface the message and stop. Do not fall back to guessing or hardcoded recommendations.
+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.
+6. **Default the action to the catalog example's `action_type`; never silently downgrade Block → Log.** Security-critical guardrails (`adversarial_input`, `content_safety`) default to `Block`. If you use `LogAction` for a guardrail whose catalog default is `Block`, state it and the reason in the report (Step 6).
+7. **Block as early as possible — pick the outermost scope the validator allows.** For input protection (PII, jailbreak, injection) prefer `GuardrailScope.AGENT` · PRE over Llm over Tool, so the run halts before the LLM call. PII meant to stop the agent handling personal data goes at **Agent**, not Llm. Only narrow when the validator is scope-restricted (e.g. `prompt_injection` / `user_prompt_attacks` are Llm-only) or the user asks for a narrower scope. See Step 5.
+8. **For LangChain / LangGraph agents, import guardrail symbols from `uipath_langchain.guardrails`, not `uipath.platform.guardrails`.** Only `uipath_langchain.guardrails` registers the LangChain adapter as an import side effect; the platform module exposes identical names but registers nothing, so guardrails silently no-op. For any other framework (LlamaIndex, OpenAI Agents, plain Python), no UiPath framework adapter is published yet — use `uipath.platform.guardrails` (the framework-agnostic SDK) directly. After writing for LangChain, verify runtime wiring (adapter registered + `_GuardedLLM`/`_GuardedTool` wrap), not just `ast.parse`. See [guardrails.md § Imports Pattern](guardrails.md#imports-pattern) and [§ Verify Guardrails Are Actually Wired](guardrails.md#verify-guardrails-are-actually-wired-mandatory-after-writing).
+9. **For Tool scope**: verify the tool exists as a `@tool` function in the agent code before adding the guardrail. If the agent has no tools, do not add a Tool-scoped guardrail.
+10. **For LLM-scope decorator**: the LLM must be inside a named factory function. If it is assigned directly (`llm = UiPathChat(...)`), refactor into a factory first — never decorate a module-level assignment.
+11. **For Agent-scope decorator**: `create_agent(...)` must be inside a named factory function. If it is called at module level, refactor into a factory first.
+12. **The cache file is `.guardrails-catalog-cache.json`** in the working directory. Add it to `.gitignore` if one exists.
+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.

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

@@ -0,0 +1,250 @@
+# Guardrails for Coded Agents
+
+Add guardrails to a Python coded agent (LangChain/LangGraph) in two styles: **middleware** or **decorator**.
+
+> **The user tells you which guardrail to add. You derive the full list of available guardrails and their configuration from the official documentation — fetch it at the start of every task.**
+
+---
+
+## Step 0 — Fetch Official Documentation
+
+**Do this FIRST — before reading any files, running any commands, or taking any other action.** Call `WebFetch` twice to retrieve current guardrail documentation:
+
+1. **`https://uipath.github.io/uipath-python/langchain/guardrails/`**
+   Extract: middleware classes, their supported scopes, stage support, extra parameters, and correct import paths.
+
+2. **`https://uipath.github.io/uipath-python/core/guardrails/`**
+   Extract: built-in validator names, entity types per validator, available actions, execution stage constraints.
+
+**Use the fetched content as the sole source of truth.** Never rely on memory for:
+- Which middleware classes exist
+- Which scopes or stages a guardrail supports
+- Entity type names or their allowed values
+- Import paths
+
+---
+
+## Check Tenant Availability (mandatory for built-in AI validators)
+
+For built-in AI validators (PII, harmful content, user prompt attacks, IP), confirm the validator is enabled on this tenant **before authoring** — run:
+
+```bash
+uip agent guardrails list --output json
+```
+
+If the requested validator has `Status != "Available"` → tell the user and stop. Actually adding one that is not entitled produces a guardrail that always fails.
+
+**Skip this step only for deterministic guardrails** — they run locally with no backend dependency.
+
+---
+
+## 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.
+
+Use the comparison table from the fetched `langchain/guardrails/` docs (the "Choosing between patterns" section) to help the user decide if they ask.
+
+---
+
+## Step 2 — Read Agent Code
+
+Use `Glob` / `Grep` to find the main Python file (look for `create_agent`, `StateGraph`, or `@entrypoint`). Read it to understand:
+
+- Whether `create_agent()` is called directly or inside a factory function
+- Which `@tool` functions exist (needed for Tool-scoped guardrails)
+- Whether a separate LLM factory function exists (needed for LLM-scope decorator guardrails)
+- Which guardrails are already present (avoid duplicating)
+
+---
+
+## Imports Pattern
+
+### How adapter registration works (read first)
+
+`uipath.platform.guardrails` ships the *low-level* `guardrail` decorator, `*Validator` / `*Middleware` classes, `*Action` classes, entity enums, and `GuardrailExecutionStage`. The decorator on its own only wraps the decorated function if a **framework adapter** is registered for the object the factory returns (a LangChain `UiPathChat`, a LlamaIndex agent, etc.). Without an adapter, the decorated factory returns the plain object, and **every guardrail silently no-ops — no error, no log.**
+
+Today the only published framework adapter is the **LangChain** one. Importing `uipath_langchain.guardrails` registers it as a side effect; the import path is also a re-export of the same names available in `uipath.platform.guardrails`, so consumers see one set of symbols either way.
+
+| Agent framework | Import guardrail symbols from | Detect by |
+|---|---|---|
+| **LangChain / LangGraph** (UiPathChat, `create_agent`) | `uipath_langchain.guardrails` | `uipath-langchain` in `pyproject.toml`, `from langchain...` / `from langgraph...` in source |
+| **Anything else** (LlamaIndex, OpenAI Agents, plain Python, custom orchestration) | `uipath.platform.guardrails` — the framework-agnostic SDK | No `uipath-langchain` dep / no LangChain imports |
+
+For a LangChain agent, **import from `uipath_langchain.guardrails`, not `uipath.platform.guardrails`.** Both modules expose the same names, so platform imports type-check, parse, and run with no error — but they bypass the LangChain adapter and the decorator/middleware never wraps the LLM/tool/agent, so every guardrail silently no-ops. This was the demo2 root cause for a LangGraph agent that imported from `uipath.platform.guardrails`.
+
+For frameworks that have no UiPath adapter yet (LlamaIndex, OpenAI Agents, etc.), the platform module is the correct source for validators, the `guardrail` decorator, action classes, and enums — these are framework-agnostic. Be aware that without a framework adapter, the decorator/middleware mechanism cannot auto-wrap that framework's LLM/tool objects, so guardrails-via-decorator may silently no-op there too; for those frameworks you may need to invoke validators directly rather than rely on factory decoration. Check the platform SDK page for the framework-agnostic usage pattern.
+
+### Detect the framework before writing imports
+
+Before writing the import line, identify the framework by reading the agent code and `pyproject.toml`:
+
+1. Read `pyproject.toml` `dependencies` for `uipath-langchain`, `llama-index*`, `openai-agents`, etc.
+2. Read the entrypoint file's existing imports (`from langchain...`, `from llama_index...`, `from agents...`).
+3. Pick the matching row from the table above. If none match (rare — plain Python with no adapter), use `uipath.platform.guardrails`.
+
+### Worked example — LangChain / LangGraph
+
+```python
+from uipath_langchain.guardrails import (
+    guardrail,
+    BlockAction, LogAction,
+    PIIValidator, PIIDetectionEntity, PIIDetectionEntityType,
+    HarmfulContentValidator, HarmfulContentEntity, HarmfulContentEntityType,
+    UserPromptAttacksValidator,
+    GuardrailExecutionStage,
+    # ...only the names you actually use
+)
+```
+
+❌ `from uipath.platform.guardrails import guardrail, PIIValidator, ...` in a LangChain agent — type-checks but the LangChain adapter never registers; guardrails silently no-op.
+❌ Importing only `from uipath_langchain.chat import UiPathChat` without ever importing `uipath_langchain.guardrails`.
+
+> **Doc-source note:** the `core/guardrails/` SDK page shows `uipath.platform.guardrails.*` paths — that is the canonical *platform* layer, correct only for the no-framework case. For framework agents, use the framework's own SDK guardrails page (`langchain/guardrails/`, `llamaindex/guardrails/`, etc.) as the import source and trust the table above.
+
+Only add the imports you actually use. Merge new names into any existing `from uipath_<framework>.guardrails import (...)` block — do not duplicate the import statement.
+
+---
+
+## Middleware Style — Code Patterns
+
+### Adding to `create_agent()`
+
+Each middleware class is **iterable** — unpack it with `*` into the `middleware=[...]` list:
+
+```python
+agent = create_agent(
+    model=llm,
+    tools=[my_tool],
+    middleware=[
+        *SomeMiddlewareClass(
+            name="...",
+            action=...,
+            # class-specific params from docs
+        ),
+    ],
+)
+```
+
+If `create_agent()` already has a `middleware=[...]` argument, add new entries to the existing list. If there is no `middleware` argument yet, add `middleware=[...]` as a new keyword argument.
+
+### TOOL-scoped middleware
+
+When the fetched docs show a middleware supports TOOL scope, it requires passing `tools=[...]`:
+
+```python
+*SomeMiddlewareClass(
+    name="...",
+    scopes=[GuardrailScope.TOOL],
+    action=...,
+    tools=[my_tool],  # required for TOOL scope — Python object, not string
+),
+```
+
+---
+
+## Decorator Style — Code Patterns
+
+Full documentation and examples: [Core Guardrails](https://uipath.github.io/uipath-python/core/guardrails/)
+
+### Tool scope — decorate the `@tool` function
+
+Place `@guardrail` **above** `@tool`:
+
+```python
+@guardrail(
+    validator=SomeValidator(...),
+    action=...,
+    name="...",
+    stage=GuardrailExecutionStage.PRE,
+)
+@tool
+def my_tool(text: str) -> str:
+    """Tool docstring."""
+    ...
+```
+
+### LLM scope — decorate the LLM factory function
+
+The LLM **must** be created inside a named factory function. Decorate the factory:
+
+```python
+@guardrail(
+    validator=SomeValidator(...),
+    action=...,
+    name="...",
+    stage=GuardrailExecutionStage.PRE,
+)
+def create_llm():
+    return UiPathChat(model="gpt-4o-2024-08-06")
+
+llm = create_llm()
+```
+
+If the code assigns the LLM directly (e.g. `llm = UiPathChat(...)`), refactor it into a factory function first, then decorate.
+
+### Agent scope — decorate the agent factory function
+
+Wrap `create_agent(...)` in a named factory function, then decorate it:
+
+```python
+@guardrail(
+    validator=SomeValidator(...),
+    action=...,
+    name="...",
+    stage=GuardrailExecutionStage.PRE,
+)
+def create_my_agent():
+    return create_agent(model=llm, tools=[my_tool], system_prompt=SYSTEM_PROMPT)
+
+agent = create_my_agent()
+```
+
+If `create_agent()` is called directly at module level (not in a function), wrap it in a factory function first.
+
+---
+
+## Verify Guardrails Are Actually Wired (mandatory after writing)
+
+**Syntactically valid ≠ active.** Because importing from the wrong module bypasses the framework adapter and makes guardrails silently no-op (see [Imports Pattern](#imports-pattern)), `ast.parse` passing tells you nothing about whether a single guardrail will ever fire. After writing, prove the wiring at runtime.
+
+**1. An adapter is registered for the framework.** Each framework's `uipath_<framework>.guardrails` module registers its adapter as an import side effect. After importing the agent module, the registry must be non-empty:
+
+```bash
+uv run python -c "import graph; from uipath.platform.guardrails.decorators._registry import _adapters; assert len(_adapters) >= 1, 'NO ADAPTER REGISTERED — guardrails will silently no-op; import from uipath_<framework>.guardrails (e.g. uipath_langchain.guardrails for LangChain agents)'; print('adapters:', len(_adapters))"
+```
+
+**2. The decorated object is actually wrapped.** For a LangChain agent, a correctly-wired LLM factory returns a `_GuardedLLM`, and a `@tool` decoration returns a `_GuardedTool`:
+
+```bash
+uv run python -c "import graph; n = type(graph.llm).__name__; assert n == '_GuardedLLM', f'LLM is {n}, not _GuardedLLM — guardrail did not wrap it'; print('wrapped:', n)"
+```
+
+If either check fails, the most likely cause is importing guardrail symbols from `uipath.platform.guardrails` instead of `uipath_langchain.guardrails`, or never importing `uipath_langchain.guardrails` at all. Fix the import source and re-verify — do not report the guardrail as added until both checks pass.
+
+For non-LangChain frameworks, there is no published adapter yet, so the decorator/middleware mechanism does not produce a `_Guarded*` wrap. Verify by invoking the validator directly on a known-violating input and confirming it raises / logs.
+
+> A smoke run that deliberately triggers a violation (e.g. feed a PII-bearing input and confirm it blocks) is the strongest verification when the environment is authenticated against the tenant.
+
+---
+
+## Block Action UX
+
+`BlockAction` enforces a violation by **raising** `AgentRuntimeError` (surfaced from the adapter's `_apply_*` hooks). Under local `uipath run` this appears as a Python traceback ending in e.g. `AgentRuntimeError: PII detected: Email: ... (total: 1 detections)`. When deployed, the UiPath runtime renders the same exception as a guardrail-violation error. This is expected behavior, not a bug.
+
+---
+
+## Critical Rules
+
+1. **Always spread middleware with `*`** into the list — never pass the object itself.
+2. **Decorator order matters**: `@guardrail` must be above `@tool`; the **topmost** `@guardrail` (first in source) runs first when the function is called.
+3. **Tool-scoped middleware requires `tools=[<tool_reference>]`** — pass the Python object, not a string.
+4. **LLM-scope decorator**: LLM must be inside a factory function; decorate the factory.
+5. **Agent-scope decorator**: `create_agent()` must be inside a factory function; decorate the factory.
+6. **Respect scope and stage constraints from the docs** — each middleware class has specific allowed scopes and stages; never apply a guardrail at a scope or stage the docs say it doesn't support.
+7. **Only add imports you use** — merge new names into any existing `from uipath_langchain.guardrails import (...)` block (LangChain) or `from uipath.platform.guardrails import (...)` block (every other framework).
+8. **For LangChain / LangGraph agents, import guardrail symbols from `uipath_langchain.guardrails`, not `uipath.platform.guardrails`.** Both expose the same names, but only `uipath_langchain.guardrails` registers the LangChain adapter as an import side effect; without it the decorator/middleware never wraps the LLM/tool/agent and every guardrail silently no-ops with no error or log. For any other framework (LlamaIndex, OpenAI Agents, plain Python), import from `uipath.platform.guardrails` — no framework adapter is published yet. See [Imports Pattern](#imports-pattern).
+9. **Verify wiring at runtime after writing (LangChain only)** — confirm the LangChain adapter is registered (`len(_adapters) >= 1`) and the decorated object is wrapped (`type(llm).__name__ == "_GuardedLLM"`, or `_GuardedTool` for tools). `ast.parse` is not enough; a silently-unwrapped guardrail passes syntax but never fires. For frameworks without an adapter, this wrap-check does not apply — invoke the validator directly to confirm it runs. See [Verify Guardrails Are Actually Wired](#verify-guardrails-are-actually-wired-mandatory-after-writing).
+10. **Entity/threshold values must match the docs exactly** — use enum member names, not raw strings; use only allowed threshold values.
+11. **Deterministic guardrails run locally** — no backend API call, no tenant availability check needed.
+12. **Do not duplicate existing guardrails** — read the agent code first and skip if the same guardrail is already configured.
+13. **Do not delegate the import-source decision (or guardrail authoring) to a subagent.** A dispatched subagent does not carry this skill's context and will report the module where the symbols physically live (`uipath.platform.guardrails`) — the no-op path for LangChain agents (Rule 8). It looks authoritative and silently overrides the correct `uipath_langchain.guardrails` choice. Fetch the docs and write the imports inline, where this skill's import rule still applies.