@uipath/skills 1.195.0

package/skills/uipath-agents/references/lowcode/capabilities/built-in-tools/batch-transform/api-reference.md

@@ -0,0 +1,38 @@
+# BatchTransform — API Reference (Debug Only)
+
+> **Stop.** In a low-code agent, the runtime calls these endpoints when the built-in `batch-transform` tool is enabled — see [impl-json.md](impl-json.md). Direct API calls are debug-only.
+
+This file lists endpoints for direct invocation from outside an agent (custom tooling, scripts, debugging). Request body shapes evolve with the SDK — **trust the SDK source, not this file**:
+
+- Request specs: `uipath/platform/context_grounding/_context_grounding_service.py` in the installed venv (look for `_*_creation_spec` and `_*_retrieve_spec` methods)
+- Pydantic models (input + response): `uipath/platform/context_grounding/context_grounding.py`
+- Resume-trigger models: `uipath/platform/common/interrupt_models.py`
+- Public docs: <https://uipath.github.io/uipath-python/>
+
+## Verified Endpoint Paths
+
+| Verb | Path | Purpose |
+|---|---|---|
+| POST | `/ecs_/v2/indexes/createephemeral` | Create an ephemeral index over attachments (`usage`: `DeepRAG` or `BatchRAG`) |
+| GET  | `/ecs_/v2/indexes/{id}` | Read index metadata, including `lastIngestionStatus` |
+| POST | `/ecs_/v2/indexes/{index_id}/createDeepRag` | Start a DeepRAG task |
+| POST | `/ecs_/v2/indexes/{index_id}/createBatchRag` | Start a BatchTransform task (the SDK calls it BatchRag internally) |
+| GET  | `/ecs_/v2/deeprag/{id}` | Read DeepRAG task status + content |
+| GET  | `/ecs_/v2/batchRag/{id}` | Read BatchTransform task status + result-file metadata |
+
+All endpoints require either `x-uipath-folderkey` or `x-uipath-folderpath` header.
+
+## Common Errors
+
+| Status | Body fragment | Cause | Fix |
+|---|---|---|---|
+| 400 | `"A folder is required for this action."` | Missing folder header | Set `UIPATH_FOLDER_KEY` env var; in coded agents, pass `index_folder_key` on the resume-trigger model |
+| 400 | `"Summarization requires a successfully completed ingestion process."` | Index not ingested yet | The runtime waits on the index event when you yield `CreateEphemeralIndex`. Hitting this from direct API calls means you skipped the ingestion poll. |
+| 400 | `"The Prompt field is required."` | Empty `prompt` | Pass non-empty prompt |
+| 400 | `outputColumns` validation | Name regex / length | See `BatchTransformOutputColumn` in `context_grounding.py` |
+| 403 | `"User is missing required index permissions."` | Role lacks index permission in folder | Use a folder where the user / agent identity has rights (personal workspace key is the safe default) |
+| 404 | `"Folder does not exist or the user does not have access..."` | Folder name typo or no access | Verify with `sdk.resource_catalog.search_async` |
+
+## Why Not Document Body Shapes Here
+
+Inline JSON shapes drift the moment the SDK changes a field name (e.g., `enableWebSearchGrounding` vs `useWebSearchGrounding`, `globPattern` vs `targetFileGlobPattern`, `Footnote` citation mode that does not exist). Reading the SDK's `_*_creation_spec` methods gives the exact body the platform accepts at the version you are running against. Any inline copy here will be wrong eventually.

package/skills/uipath-agents/references/lowcode/capabilities/built-in-tools/batch-transform/impl-json.md

@@ -0,0 +1,97 @@
+# BatchTransform in a Low-Code Agent — Implementation
+
+`agent.json` agents enable BatchTransform via a built-in tool resource. Same `resource.json` shape for standalone and inline-in-flow.
+
+## Resource Shape
+
+`resources/<resource-name>/resource.json`:
+
+```json
+{
+  "$resourceType": "tool",
+  "id": "<UUID>",
+  "type": "internal",
+  "referenceKey": null,
+  "isEnabled": true,
+  "properties": {
+    "toolType": "batch-transform"
+  }
+}
+```
+
+| Field | Constraint |
+|---|---|
+| `$resourceType` | `"tool"` |
+| `id` | UUID-shaped string |
+| `type` | `"internal"` (built-in tools) |
+| `referenceKey` | `null` (non-null identifies an external tool) |
+| `isEnabled` | truthy |
+| `properties.toolType` | `"batch-transform"` (others: `analyze-attachments`, `load-attachments`, `deep-rag`) |
+
+Resource directory name is free-form. Validator scans `<agent>/resources/**/resource.json`.
+
+## Tool Configuration
+
+`resource.json` only registers the tool's existence — it does NOT carry per-call inputs (prompt, output columns, destination, web grounding). Those are derived at runtime from the agent's instructions and tool-call output.
+
+What the agent must produce at invocation time (the runtime forwards these to the underlying API):
+
+- A non-empty top-level prompt
+- A list of `BatchTransformOutputColumn` entries (`name` 1–500 chars, regex `^[\w\s\.,!?-]+$`; `description` 1–20000 chars, the per-column LLM instruction)
+- An output destination
+- Whether to enable web grounding
+
+The exact JSON field names the runtime sends to the platform (e.g., `useWebSearchGrounding`, `targetFileGlobPattern`) are SDK-version-specific — see the SDK source `uipath/platform/context_grounding/_context_grounding_service.py` (`_batch_transform_*_creation_spec` methods) for the body shape your version emits. Authoring the agent's system prompt (next section) is what shapes the runtime call, not editing `resource.json`.
+
+## Standalone vs Inline-in-Flow
+
+**Standalone:**
+
+```
+<solution>/<AgentName>/
+├── agent.json                # "type": "lowCode"
+├── project.uiproj
+└── resources/<any>/resource.json
+```
+
+Agent owns its tools directly. Runtime exposes `batch-transform` to the agent's tool-calling loop.
+
+**Inline-in-flow:** flow has a `uipath.agent.autonomous` node and a built-in tool node under the `uipath.agent.resource.tool.*` prefix (canonical: `uipath.agent.resource.tool.builtin`), plus an edge from agent `tool` → tool node `input`. The shared inline-builtin-tool checker (`tests/tasks/uipath-agents/inline_builtin_tool/`) validates by prefix; verify the exact node type at your CLI version with `uip maestro flow registry search "uipath.agent.resource.tool" --output json`.
+
+```text
+[uipath.agent.autonomous] --tool--> [uipath.agent.resource.tool.builtin]
+```
+
+## Output Column Descriptions
+
+Each `description` is the per-column LLM instruction — prompt-fragment, not label.
+
+| Bad | Better |
+|---|---|
+| `"category"` | `"Return the 4-digit MCC code, or UNKNOWN if uncertain. Output only the code."` |
+| `"verified"` | `"YES if the address matches the master list (whitespace, abbreviations OK); NO if it does not; UNKNOWN if undeterminable. Output only YES, NO, or UNKNOWN."` |
+| `"action"` | `"Recommend one of {CALL, EMAIL, ESCALATE, AUTO_APPROVE} from the order amount, status, and customer notes. Output only the chosen value."` |
+
+## Attachment Ingress
+
+Studio Web forwards the user's CSV upload to the tool — no schema wiring. Other channels (flow input, Action Center task): confirm the runtime forwards the file or the tool runs against an empty input set.
+
+## Validation
+
+| Check | How |
+|---|---|
+| Agent project shape (agent.json, resources, bindings) | `uip agent validate --output json` (canonical; auto-runs migrations + writes `.agent-builder/`) |
+| Smoke run | `uip solution upload . --output json`, invoke from Studio Web with a 10–20 row CSV before the full workload |
+
+The repo's coder-eval suite uses a shared static checker at `tests/tasks/uipath-agents/builtin_tool/check_builtin_tool.py` covering all four `toolType` values (`analyze-attachments`, `load-attachments`, `deep-rag`, `batch-transform`). It is shared test tooling, not a runtime requirement for this skill.
+
+## Pack and Publish
+
+```bash
+uip solution upload . --output json
+```
+
+## Resources
+
+- Agent project validator: `uip agent validate --output json`
+- API endpoints (debug): [api-reference.md](api-reference.md)

package/skills/uipath-agents/references/lowcode/capabilities/built-in-tools/batch-transform/planning.md

@@ -0,0 +1,62 @@
+# BatchTransform in a Low-Code Agent — Planning
+
+## When to Use
+
+Pick this when:
+
+- Project has `agent.json` with `"type": "lowCode"` (standalone) **or** the agent is inline inside a Maestro Flow (`uipath.agent.autonomous` node)
+- User is building in Studio Web Agent Builder, no Python
+- Source data is tabular (CSV) — one input row should produce one output row plus extra LLM-filled columns
+- Output destination is an Orchestrator bucket attachment downstream consumers (RPA, agents) can read
+
+Confirm BatchTransform is the right mode first — see [../../../../context-grounding-patterns.md](../../../../context-grounding-patterns.md).
+
+For coded agents (Python, LangGraph) → [../../../coded/capabilities/batch-transform/planning.md](../../../coded/capabilities/batch-transform/planning.md).
+
+## Inputs You Need Before Building
+
+| Input | Why | Source |
+|---|---|---|
+| Agent project shape | Standalone vs. inline-in-flow — affects where `resource.json` lives | Inspect `agent.json` and the parent solution |
+| Tool resource configuration | Top-level prompt + per-column descriptions + web-grounding default | Author / Studio Web tool config |
+| Attachment ingress | The `batch-transform` tool consumes runtime-uploaded CSV attachments — confirm the agent has an attachment input wired | Studio Web schema / `entry-points.json` |
+| Output destination | Bucket + path where the augmented CSV is written | User config; include unique suffix per run to avoid overwrites |
+| Web grounding default | Whether to enable web search per row by default | User flag; default off (turn on only when the task needs fresh external data) |
+| System prompt | Tells the agent when to invoke `batch-transform` and how to frame the row prompt | Author / Studio Web |
+
+## Tool Resource Shape
+
+Built-in tools are declared in `resources/<name>/resource.json` with `$resourceType: "tool"`, `type: "internal"`, `referenceKey: null`, and `properties.toolType: "batch-transform"`. See [impl-json.md](impl-json.md) for the exact JSON.
+
+Built-in tools accept these `toolType` values: `analyze-attachments`, `load-attachments`, `deep-rag`, `batch-transform`. Anything else fails `uip agent validate`.
+
+### Tool resource vs context-index resource
+
+Two valid shapes for enabling BatchTransform on a low-code agent. This skill documents the **built-in tool** shape (the agent invokes BatchTransform through its tool-calling loop). The alternative is a **context-index resource** that wires BatchTransform as a retrieval mode on a pre-built ECS index — `$resourceType: "context"`, `contextType: "index"`, `retrievalMode: "batchtransform"` (lowercase, no hyphen — `uip agent validate` accepts camelCase but Studio Web silently drops the resource on import), with `webSearchGrounding` and `outputColumns` set on the resource. Use the context-index form when the CSV lives in a stable, pre-built index reused across runs and the agent should query it transparently as context; use the tool form (this skill) when the CSV is a runtime attachment and the agent must decide row-by-row when to invoke it.
+
+## Critical Decisions
+
+| Decision | Rule |
+|---|---|
+| `batch-transform` vs `deep-rag` | Pick by input file type: `.csv` → `batch-transform`; `.pdf` / `.txt` → `deep-rag`. Hard rule, no subjective tiebreaker. |
+| `batch-transform` vs `analyze-attachments` | `analyze-attachments` does single-file, single-shot extraction. `batch-transform` iterates across all rows of a CSV at scale. |
+| Standalone agent vs inline-in-flow | Same `resource.json` shape for both. The flow wiring differs — inline requires an edge from the agent's `tool` port to the tool node's `input` port. See [impl-json.md](impl-json.md). |
+| Output column names | Must match regex `^[\w\s\.,!?-]+$`. No `/`, `:`, `&`, `(`, `)`, or other special chars. |
+| Output column descriptions | Each is the per-column LLM instruction. Be specific about format, enums, and "when uncertain" handling. Worked examples improve quality. |
+| Web grounding default | Off unless the prompt explicitly needs fresh external data. |
+
+## Bindings / Permissions
+
+BatchTransform runs in the folder context of the running agent. The tool requires the index permission and write access to the destination bucket. If the agent is published to a folder where its identity lacks rights, runs fail with 403 (read) or 400 (folder/permission).
+
+## Output Handling
+
+Output is an Orchestrator bucket attachment, not an inline value the agent returns to the chat. Plan for:
+
+- A unique destination path per run (timestamp / UUID suffix)
+- Downstream RPA / agent steps that read the attachment and continue processing
+- A summary message the agent posts back to chat with the bucket location, row count, and any failure summary
+
+## Hand-off
+
+Once planning is complete, implement per [impl-json.md](impl-json.md).

package/skills/uipath-agents/references/lowcode/capabilities/built-in-tools/built-in-tools.md

@@ -0,0 +1,75 @@
+# Built-In Tools Capability
+
+Built-in tools are pre-built agent tools that ship with the platform. They share a wire shape (`$resourceType: "tool"`, `type: "internal"`) and a fixed input/output schema per tool. Unlike process or Integration Service tools, built-in tools are self-contained at the agent level — no solution-level files, no `uip solution resource refresh`.
+
+For process tools (RPA / agent / API / agentic), see [../process/process.md](../process/process.md). For Integration Service tools, see [../integration-service/integration-service.md](../integration-service/integration-service.md).
+
+## When to Use
+
+- Agent needs file content analysis at runtime → pair a `job-attachment` input field with `analyze-attachments`
+- Agent needs a platform capability that ships pre-built and does not require deployment
+
+## Critical Rules
+
+1. **Built-in tools are not implicit.** Add them as `resources/{Name}/resource.json` with `type: "internal"` to make them callable. Without the resource file, the tool is unavailable.
+2. **`properties.toolType` is the discriminator** — fixed per built-in, kebab-lowercase. Copy from the per-tool walkthrough; do not invent.
+3. **No solution-level files.** Built-in tools need no `uip solution resource refresh`. Validate the agent and bundle.
+4. **Input/output schemas are fixed.** Do not edit them. Each tool's walkthrough lists the canonical schema.
+
+## Resource Shape
+
+```jsonc
+{
+  "$resourceType": "tool",
+  "id": "<UUID>",
+  "referenceKey": null,
+  "name": "<DisplayName>",
+  "type": "internal",
+  "description": "<TOOL_DESCRIPTION>",
+  "isEnabled": true,
+  "inputSchema":  { /* fixed per tool */ },
+  "outputSchema": { /* fixed per tool */ },
+  "settings": {},
+  "guardrail": { "policies": [] },
+  "argumentProperties": {},
+  "properties": {
+    "toolType": "<kebab-lowercase-id>"
+  }
+}
+```
+
+| Field | Notes |
+|---|---|
+| `type` | Always `"internal"` for built-in tools |
+| `properties.toolType` | Fixed discriminator (e.g. `"analyze-attachments"`) |
+| `inputSchema` / `outputSchema` | Fixed per tool — copy from walkthrough |
+| `referenceKey` | Always `null` (no Orchestrator binding) |
+| `guardrail.policies` | Always `[]` — required for backward compatibility |
+| `id` | Fresh UUID per resource — see [../../critical-rules.md](../../critical-rules.md) Anti-pattern 9 |
+
+## Lifecycle
+
+1. **Author** the agent-level `resources/{ToolName}/resource.json` with the canonical shape from the per-tool walkthrough.
+2. **Validate** with `uip agent validate "<AGENT_NAME>" --output json` (read-only check).
+3. **Migrate** with `uip agent migrate "<AGENT_NAME>" --output json` — regenerates `.agent-builder/`.
+4. **Bundle and upload** the solution. No solution-resource refresh needed.
+
+## Tool Registry
+
+| Tool | `toolType` | Walkthrough |
+|---|---|---|
+| Analyze Files | `analyze-attachments` | [analyze-attachments.md](analyze-attachments.md) |
+| Deep RAG | `deep-rag` | [deeprag/impl-json.md](deeprag/impl-json.md) |
+| Batch Transform | `batch-transform` | [batch-transform/impl-json.md](batch-transform/impl-json.md) |
+
+## Gotchas
+
+- See [../../critical-rules.md](../../critical-rules.md) Critical Rules 18–21 and Anti-patterns 21–22 for the canonical rule list.
+- Pairing with file inputs: a `job-attachment` field renders metadata only in `{{input.<field>}}`. The agent reads contents only by calling a file-handling built-in tool. See [../../agent-definition.md](../../agent-definition.md) § File Attachments.
+- Runtime test path: built-in tools cannot be exercised end-to-end through the `uip` CLI. Test from Studio Web or via Orchestrator job invocation.
+
+## References
+
+- [analyze-attachments.md](analyze-attachments.md) — Analyze Files walkthrough
+- [../../agent-definition.md](../../agent-definition.md) § File Attachments — `job-attachment` schema
+- [../../critical-rules.md](../../critical-rules.md) — canonical rules

package/skills/uipath-agents/references/lowcode/capabilities/built-in-tools/deeprag/api-reference.md

@@ -0,0 +1,38 @@
+# DeepRAG — API Reference (Debug Only)
+
+> **Stop.** In a low-code agent, the runtime calls these endpoints when the built-in `deep-rag` tool is enabled — see [impl-json.md](impl-json.md). Direct API calls are debug-only.
+
+This file lists endpoints for direct invocation from outside an agent (custom tooling, scripts, debugging). Request body shapes evolve with the SDK — **trust the SDK source, not this file**:
+
+- Request specs: `uipath/platform/context_grounding/_context_grounding_service.py` in the installed venv (look for `_*_creation_spec` and `_*_retrieve_spec` methods)
+- Pydantic models (input + response): `uipath/platform/context_grounding/context_grounding.py`
+- Resume-trigger models: `uipath/platform/common/interrupt_models.py`
+- Public docs: <https://uipath.github.io/uipath-python/>
+
+## Verified Endpoint Paths
+
+| Verb | Path | Purpose |
+|---|---|---|
+| POST | `/ecs_/v2/indexes/createephemeral` | Create an ephemeral index over attachments (`usage`: `DeepRAG` or `BatchRAG`) |
+| GET  | `/ecs_/v2/indexes/{id}` | Read index metadata, including `lastIngestionStatus` |
+| POST | `/ecs_/v2/indexes/{index_id}/createDeepRag` | Start a DeepRAG task |
+| POST | `/ecs_/v2/indexes/{index_id}/createBatchRag` | Start a BatchTransform task (the SDK calls it BatchRag internally) |
+| GET  | `/ecs_/v2/deeprag/{id}` | Read DeepRAG task status + content |
+| GET  | `/ecs_/v2/batchRag/{id}` | Read BatchTransform task status + result-file metadata |
+
+All endpoints require either `x-uipath-folderkey` or `x-uipath-folderpath` header.
+
+## Common Errors
+
+| Status | Body fragment | Cause | Fix |
+|---|---|---|---|
+| 400 | `"A folder is required for this action."` | Missing folder header | Set `UIPATH_FOLDER_KEY` env var; in coded agents, pass `index_folder_key` on the resume-trigger model |
+| 400 | `"Summarization requires a successfully completed ingestion process."` | Index not ingested yet | The runtime waits on the index event when you yield `CreateEphemeralIndex`. Hitting this from direct API calls means you skipped the ingestion poll. |
+| 400 | `"The Prompt field is required."` | Empty `prompt` | Pass non-empty prompt |
+| 400 | `outputColumns` validation | Name regex / length | See `BatchTransformOutputColumn` in `context_grounding.py` |
+| 403 | `"User is missing required index permissions."` | Role lacks index permission in folder | Use a folder where the user / agent identity has rights (personal workspace key is the safe default) |
+| 404 | `"Folder does not exist or the user does not have access..."` | Folder name typo or no access | Verify with `sdk.resource_catalog.search_async` |
+
+## Why Not Document Body Shapes Here
+
+Inline JSON shapes drift the moment the SDK changes a field name (e.g., `enableWebSearchGrounding` vs `useWebSearchGrounding`, `globPattern` vs `targetFileGlobPattern`, `Footnote` citation mode that does not exist). Reading the SDK's `_*_creation_spec` methods gives the exact body the platform accepts at the version you are running against. Any inline copy here will be wrong eventually.

package/skills/uipath-agents/references/lowcode/capabilities/built-in-tools/deeprag/impl-json.md

@@ -0,0 +1,84 @@
+# DeepRAG in a Low-Code Agent — Implementation
+
+`agent.json` agents enable DeepRAG via a built-in tool resource. Same `resource.json` shape for standalone and inline-in-flow.
+
+## Resource Shape
+
+`resources/<resource-name>/resource.json`:
+
+```json
+{
+  "$resourceType": "tool",
+  "id": "<UUID>",
+  "type": "internal",
+  "referenceKey": null,
+  "isEnabled": true,
+  "properties": {
+    "toolType": "deep-rag"
+  }
+}
+```
+
+| Field | Constraint |
+|---|---|
+| `$resourceType` | `"tool"` |
+| `id` | UUID-shaped string |
+| `type` | `"internal"` (built-in tools) |
+| `referenceKey` | `null` (non-null identifies an external tool) |
+| `isEnabled` | truthy |
+| `properties.toolType` | `"deep-rag"` (others: `analyze-attachments`, `load-attachments`, `batch-transform`) |
+
+Resource directory name is free-form. Validator scans `<agent>/resources/**/resource.json`.
+
+## Standalone vs Inline-in-Flow
+
+**Standalone:**
+
+```
+<solution>/<AgentName>/
+├── agent.json                # "type": "lowCode"
+├── project.uiproj
+└── resources/<any>/resource.json
+```
+
+Agent owns its tools directly. Runtime exposes `deep-rag` to the agent's tool-calling loop.
+
+**Inline-in-flow:** flow has a `uipath.agent.autonomous` node and a built-in tool node under the `uipath.agent.resource.tool.*` prefix (canonical: `uipath.agent.resource.tool.builtin`), plus an edge from agent `tool` → tool node `input`. The shared inline-builtin-tool checker (`tests/tasks/uipath-agents/inline_builtin_tool/`) validates by prefix; verify the exact node type at your CLI version with `uip maestro flow registry search "uipath.agent.resource.tool" --output json`.
+
+```text
+[uipath.agent.autonomous] --tool--> [uipath.agent.resource.tool.builtin]
+```
+
+## Authoring the System Prompt
+
+The agent's instructions determine effectiveness. Cover:
+
+- When to call `deep-rag` (e.g., "When the user asks to summarize or research uploaded documents")
+- What to pass as `prompt` (e.g., "Pass the user's question verbatim; ask for citations when sources matter")
+- How to combine results (e.g., "Treat tool output as ground truth; do not paraphrase citations")
+
+Without explicit guidance, the agent under-uses DeepRAG or invokes it for tasks that don't need it.
+
+## Attachment Ingress
+
+Studio Web forwards conversation attachments to the tool — no schema wiring. Other channels (flow input, Action Center task): confirm the runtime forwards attachments or the tool runs against an empty set.
+
+## Validation
+
+| Check | How |
+|---|---|
+| Agent project shape (agent.json, resources, bindings) | `uip agent validate --output json` (canonical; auto-runs migrations + writes `.agent-builder/`) |
+| Smoke run | `uip solution upload . --output json`, invoke from Studio Web with a test PDF/TXT attachment |
+
+The repo's coder-eval suite uses a shared static checker at `tests/tasks/uipath-agents/builtin_tool/check_builtin_tool.py` covering all four `toolType` values (`analyze-attachments`, `load-attachments`, `deep-rag`, `batch-transform`). It is shared test tooling, not a runtime requirement for this skill.
+
+## Pack and Publish
+
+```bash
+uip solution upload . --output json
+```
+
+## Resources
+
+- Agent project validator: `uip agent validate --output json`
+- API endpoints (debug): [api-reference.md](api-reference.md)

package/skills/uipath-agents/references/lowcode/capabilities/built-in-tools/deeprag/planning.md

@@ -0,0 +1,49 @@
+# DeepRAG in a Low-Code Agent — Planning
+
+## When to Use
+
+Pick this when:
+
+- Project has `agent.json` with `"type": "lowCode"` (standalone) **or** the agent is inline inside a Maestro Flow (`uipath.agent.autonomous` node)
+- User is building in Studio Web Agent Builder, no Python
+- Agent receives runtime attachments (files uploaded in chat) and must research / synthesize across them
+- Expected output is a single grounded narrative answer
+
+Confirm DeepRAG is the right mode first — see [../../../../context-grounding-patterns.md](../../../../context-grounding-patterns.md).
+
+For coded agents (Python, LangGraph) → [../../../coded/capabilities/deeprag/planning.md](../../../coded/capabilities/deeprag/planning.md).
+
+## Inputs You Need Before Building
+
+| Input | Why | Source |
+|---|---|---|
+| Agent project shape | Standalone vs. inline-in-flow — affects where `resource.json` lives | Inspect `agent.json` and the parent solution |
+| Attachment ingress | The `deep-rag` tool consumes runtime-uploaded attachments — confirm the agent has an attachment input wired | Studio Web schema / `entry-points.json` |
+| Prompt wiring | The agent's system prompt or per-call prompt must mention when to invoke the tool | Author / Studio Web |
+| Other built-in tools | Do not enable `deep-rag` AND `analyze-attachments` if a single research pass suffices — pick one | User intent |
+
+## Tool Resource Shape
+
+Built-in tools are declared in `resources/<name>/resource.json` with `$resourceType: "tool"`, `type: "internal"`, `referenceKey: null`, and `properties.toolType: "deep-rag"`. See [impl-json.md](impl-json.md) for the exact JSON.
+
+Built-in tools accept these `toolType` values: `analyze-attachments`, `load-attachments`, `deep-rag`, `batch-transform`. Anything else fails `uip agent validate`.
+
+### Tool resource vs context-index resource
+
+Two valid shapes for enabling DeepRAG on a low-code agent. This skill documents the **built-in tool** shape (the agent invokes DeepRAG through its tool-calling loop on runtime attachments). The alternative is a **context-index resource** that wires DeepRAG as a retrieval mode on a pre-built ECS index — `$resourceType: "context"`, `contextType: "index"`, `retrievalMode: "deeprag"` (lowercase, no hyphen — `uip agent validate` accepts camelCase but Studio Web silently drops the resource on import), with `citationMode` (`"Inline"` or `"Skip"`) set on the resource. Use the context-index form when the documents live in a stable, pre-built index reused across runs and the agent should query it transparently as context; use the tool form (this skill) when the documents are runtime attachments uploaded per conversation.
+
+## Critical Decisions
+
+| Decision | Rule |
+|---|---|
+| `deep-rag` vs `analyze-attachments` | Prefer `deep-rag`. It handles larger files, returns citations (with optional bounding-box anchors), and produces denser output. `analyze-attachments` is one-shot synthesis with lower page limits — reach for it only when the document is small and the task is a single-shot extraction. |
+| `deep-rag` vs `load-attachments` | `load-attachments` only makes attachment text available to the agent; `deep-rag` runs an iterative synthesis pass. Use `load-attachments` when the agent will reason directly over short contents; use `deep-rag` for long / multiple docs. |
+| Standalone agent vs inline-in-flow | Same `resource.json` shape for both. The flow wiring differs — inline requires an edge from the agent's `tool` port to the tool node's `input` port. See [impl-json.md](impl-json.md). |
+
+## Bindings / Permissions
+
+DeepRAG runs in the folder context of the running agent. The tool requires the index permission in that folder — same rule as the coded surface. If the agent is published to a folder where the user lacks rights, DeepRAG calls fail with 403. Use the personal workspace (or a folder the agent's runtime identity has rights in) for self-serve.
+
+## Hand-off
+
+Once planning is complete, implement per [impl-json.md](impl-json.md).

package/skills/uipath-agents/references/lowcode/capabilities/context/attachments.md

@@ -0,0 +1,54 @@
+# Attachments Context
+
+Walkthrough for adding a **context resource** (`$resourceType: "context"`, `contextType: "attachments"`) that takes runtime files passed to the agent. No backing index — files are uploaded with each agent invocation.
+
+For other context variants, see [context.md](context.md).
+
+> **Not what you want?** To accept a file as a plain agent input field and read its contents via a built-in tool, see [../built-in-tools/built-in-tools.md](../built-in-tools/built-in-tools.md) and [../../agent-definition.md](../../agent-definition.md) § File Attachments. That pattern uses `$resourceType: "tool"` (not context) and pairs a `job-attachment` input with `analyze-attachments`.
+
+## When to Use
+
+- Caller uploads files (PDFs, images, documents) at runtime
+- No persistent index needed — files are processed per-invocation
+- No solution-level resource binding (attachments are runtime-only)
+
+## Agent-Level Resource Shape
+
+**Path:** `<AgentName>/resources/<ContextName>/resource.json`
+
+```jsonc
+{
+  "$resourceType": "context",
+  "id": "<uuid>",
+  "referenceKey": null,
+  "name": "<ContextName>",
+  "description": "",
+  "contextType": "attachments",
+  "indexName": "<ContextName>",          // same as name for attachments
+  "attachments": {
+    "description": "Array of files, documents, images to process."
+  },
+  "settings": {
+    "retrievalMode": "semantic",
+    "query": { "variant": "dynamic" },
+    "folderPathPrefix": { "variant": "static" },
+    "fileExtension": { "value": "All" },
+    "threshold": 0,
+    "resultCount": 3
+  }
+}
+```
+
+## Solution-Level Files
+
+None. No solution-level file is produced — attachments are runtime-only.
+
+## Gotchas
+
+`contextType` value MUST be `"attachments"` (all lowercase) — see [../../critical-rules.md](../../critical-rules.md) Anti-pattern 12.
+
+## References
+
+- [context.md](context.md) — capability overview
+- [index.md](index.md) — Context Grounding RAG
+- [datafabric.md](datafabric.md) — DataFabric entity-set context

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

@@ -0,0 +1,40 @@
+# Context Capability
+
+Contexts feed retrievable information into an agent at runtime. Three variants exist, discriminated by `contextType`. All use `$resourceType: "context"`.
+
+## When to Use
+
+- Agent needs to retrieve from a knowledge base (RAG / Context Grounding)
+- Agent needs runtime file attachments (uploaded by the caller)
+- Agent needs to query DataFabric entity sets
+
+## Variants
+
+| `contextType` | Backing | Solution-level auto-gen by `uip solution resource refresh`? | Walkthrough |
+|---|---|---|---|
+| `"index"` | ECS Context Grounding index (StorageBucket-backed) | Yes — auto-writes `index/<Name>.json` + `bucket/orchestratorBucket/<Bucket>.json` + 2 debug entries | [index.md](index.md) |
+| `"attachments"` | Runtime files passed to the agent | No (no solution resource needed) | [attachments.md](attachments.md) |
+| `"datafabricentityset"` | DataFabric entity sets | No (not yet auto-generated; hand-author solution files) | [datafabric.md](datafabric.md) |
+
+## Decision
+
+- **RAG / semantic search across documents indexed in Context Grounding** → `index` ([index.md](index.md))
+- **Files attached at runtime by the caller (uploaded with each request)** → `attachments` ([attachments.md](attachments.md))
+- **Queries against DataFabric entity sets** → `datafabricentityset` ([datafabric.md](datafabric.md))
+
+> **File-as-input ≠ attachments context.** If the agent should accept a file as a plain input field and read its contents via a built-in tool (no semantic retrieval), use `job-attachment` + `analyze-attachments` instead — see [../built-in-tools/built-in-tools.md](../built-in-tools/built-in-tools.md) and [../../agent-definition.md](../../agent-definition.md) § File Attachments.
+
+## Casing Rule
+
+`contextType` and `retrievalMode` values are lowercase. See [../../critical-rules.md](../../critical-rules.md) § What NOT to Do — Anti-pattern 12.
+
+## Sibling Files
+
+- [index.md](index.md) — Context Grounding RAG index walkthrough (most common variant)
+- [attachments.md](attachments.md) — Runtime file attachments
+- [datafabric.md](datafabric.md) — DataFabric entity-set context
+
+## References
+
+- [../../agent-definition.md](../../agent-definition.md) § Resources Convention
+- [../../solution-resources.md](../../solution-resources.md) § Refresh Mechanics

package/skills/uipath-agents/references/lowcode/capabilities/context/datafabric.md

@@ -0,0 +1,52 @@
+# DataFabric Entity Set Context
+
+Walkthrough for adding a context resource backed by one or more DataFabric entity sets.
+
+For other context variants, see [context.md](context.md).
+
+## When to Use
+
+- Agent needs to query against UiPath DataFabric entity sets
+- The entity sets already exist in DataFabric
+
+## Agent-Level Resource Shape
+
+**Path:** `<AgentName>/resources/<ContextName>/resource.json`
+
+```jsonc
+{
+  "$resourceType": "context",
+  "id": "<uuid>",
+  "referenceKey": null,
+  "name": "<ContextName>",
+  "description": "",
+  "contextType": "datafabricentityset",
+  "entitySet": [
+    {
+      "id": "<uuid>",
+      "referenceKey": "<entity-key>",
+      "name": "<EntityName>",
+      "folderId": "<folder-uuid>",
+      "folderDisplayName": "Shared",
+      "description": null
+    }
+    // ...more entities
+  ]
+}
+```
+
+No `indexName` and no `settings` for DataFabric contexts. The shape is entirely different from index/attachments.
+
+## Solution-Level Files
+
+**Not auto-generated.** Solution-level resource generation for DataFabric contexts is not yet supported by `uip solution resource refresh` — the agent-level `resource.json` is written, but you must hand-author any solution manifests needed.
+
+## Gotchas
+
+`contextType` value MUST be `"datafabricentityset"` (all lowercase) — see [../../critical-rules.md](../../critical-rules.md) Anti-pattern 12.
+
+## References
+
+- [context.md](context.md) — capability overview
+- [index.md](index.md) — Context Grounding RAG
+- [attachments.md](attachments.md) — runtime file attachments