@uipath/skills 1.195.0

package/skills/uipath-agents/references/coded/capabilities/batch-transform/planning.md

@@ -0,0 +1,90 @@
+# BatchTransform in a Coded Agent — Planning
+
+## When to Use
+
+Pick this when:
+
+- Project has `pyproject.toml` with `uipath` / `uipath-langchain`, plus `langgraph.json` or a graph-style `main.py`
+- Source data is tabular (CSV) — one input row should produce one output row plus extra LLM-filled columns
+- Workload is throughput-driven (hundreds to thousands of rows per file)
+- User wants Python control over upstream prep (download, reshape, dedupe) or downstream routing (push results to Data Service, Orchestrator queue, follow-up agent, etc.)
+
+Confirm BatchTransform is the right mode first — see [../../../context-grounding-patterns.md](../../../context-grounding-patterns.md).
+
+For Studio Web Agent Builder → [../../lowcode/capabilities/built-in-tools/batch-transform/planning.md](../../lowcode/capabilities/built-in-tools/batch-transform/planning.md).
+
+## Inputs You Need Before Building
+
+| Input | Why | Where to get it |
+|---|---|---|
+| Source file (CSV) | The data BatchTransform iterates over | Bucket / agent input / upstream node |
+| Prompt | Top-level task framing — sent with every row | User input or static default |
+| `output_columns` | Names + descriptions of new columns the LLM fills per row | User spec; each `description` is the per-column instruction |
+| `enable_web_search_grounding` | Whether each row is augmented with a web search before answering | User flag; default `False` (turn on only when the task needs fresh external data) |
+| Index strategy | Ephemeral (attachments-backed, one-shot) vs existing index | Default ephemeral for CSV-in / CSV-out; existing index when the corpus is stable |
+| `destination_path` | LOCAL filesystem path where the runtime writes the augmented CSV on resume | Include a unique suffix per run (UUID/timestamp) |
+| Target folder for ingestion + BatchTransform | Permission scope | Default to personal workspace key for self-serve |
+
+## Pipeline Shape
+
+Standard ephemeral-attachment flow:
+
+1. `fetch_source` — accept / download the source CSV → local path
+2. `upload_attachment` — `sdk.attachments.upload_async` → attachment uuid
+3. `create_index` — `create_ephemeral_index_async` → check `in_progress_ingestion()` → conditionally `interrupt(WaitEphemeralIndex(...))` → `ContextGroundingIndex`
+4. `run_batch_transform` — `interrupt(CreateBatchTransform(is_ephemeral_index=True, index_id=..., output_columns=[...], destination_path=<local-path>, enable_web_search_grounding=..., ...))` → confirmation string; runtime writes augmented CSV to `destination_path` on disk
+5. `finalize` — return the local `destination_path` (or read the CSV for downstream nodes)
+
+If targeting an existing index instead of attachments, skip steps 2 and 3; pass `index_name=...` and `index_folder_path=...` (without `is_ephemeral_index`) on step 4.
+
+## `BatchTransformOutputColumn` Authoring
+
+Each entry in `output_columns` has `name` and `description`. Treat the description as the prompt-fragment the LLM uses to fill that column for every row.
+
+| Field | Constraint | Tips |
+|---|---|---|
+| `name` | 1–500 chars, regex `^[\w\s\.,!?-]+$` | Friendly column header. No special characters beyond `. , ! ? -`. |
+| `description` | 1–20000 chars | Be specific about what to extract / classify, the format (free text, enum, JSON), and what to output when uncertain. Worked examples improve quality. |
+
+Example (note the import path — `BatchTransformOutputColumn` lives in `context_grounding`, NOT `common`):
+
+```python
+from uipath.platform.context_grounding import BatchTransformOutputColumn
+
+[
+    BatchTransformOutputColumn(
+        name="MCC Code",
+        description=(
+            "Return the 4-digit Merchant Category Code that best fits the merchant. "
+            "If unsure, return UNKNOWN. Output only the code or UNKNOWN, no commentary."
+        ),
+    ),
+    BatchTransformOutputColumn(
+        name="Confidence",
+        description="Confidence in the MCC classification: HIGH, MEDIUM, or LOW.",
+    ),
+]
+```
+
+## Critical Decisions
+
+| Decision | Rule |
+|---|---|
+| Sync vs interrupt | Always use `interrupt()` for `create_index` (conditionally) and `run_batch_transform`. Never poll — runs are long-lived. |
+| Folder for index | Personal workspace key by default for self-serve. Override only when the user has confirmed role permissions in another folder. |
+| Ephemeral vs existing index | Default ephemeral for one-shot runs from a runtime CSV. Use an existing index only if the same data is reused across runs. |
+| Web search grounding | Default `False`. Enable only when prompts depend on fresh external info (address verification, current company status). |
+| `destination_path` collisions | Include a UUID or timestamp suffix (`results/run-{ts}.csv`) so concurrent or repeated runs don't overwrite each other. |
+| Result handling | Augmented CSV lands at the local `destination_path` after resume. Plan whether the agent returns the path, re-uploads to a bucket for RPA, or reads the CSV inline. |
+
+## Bindings
+
+The source bucket (if you download the CSV from one) is bindable. Attachments, ephemeral indexes, and the local `destination_path` are NOT bindable — they are runtime-created or local-only. If the agent re-uploads the augmented CSV to a destination bucket, that destination bucket is also bindable.
+
+## Local-Run Behavior
+
+`uip codedagent run agent '{...}'` exits at the first interrupt. That is correct — the runtime captured suspend state and would resume on the platform event. For end-to-end verification: deploy and invoke from the platform, or use `uip codedagent dev`.
+
+## Hand-off
+
+Once planning is complete, implement per [impl-python.md](impl-python.md).

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

@@ -0,0 +1,253 @@
+# Context Grounding Guide
+
+How to use UiPath's Context Grounding Service to ground LLM responses in your organization's specific information through semantic document search.
+
+## Overview
+
+**Context Grounding** enables you to search through indexed documents using natural language queries and ground LLM responses in your organization's specific knowledge. This is essential for building accurate, information-rich agents that reference real organizational data.
+
+## Index Creation
+
+Before using context grounding, you must first create an index in your Orchestrator organization:
+
+1. Navigate to the desired folder in Orchestrator
+2. Select **Indexes** from the sidebar
+3. Create a **new index** from a storage bucket containing your documents
+4. Documents will be indexed and made searchable via semantic search
+
+Once indexed, you can reference the index by name in your agent code.
+
+## 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`.
+
+```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
+
+### ContextGroundingRetriever
+
+A document retrieval system using vector search to find relevant information based on natural language queries.
+
+```python
+from uipath_langchain.retrievers import ContextGroundingRetriever
+
+retriever = ContextGroundingRetriever(index_name="my_index")
+documents = await retriever.ainvoke("What is our return policy?")
+```
+
+**Features:**
+- Vector search for semantic relevance
+- Async operations for performance
+- Integration with LangChain chains and agents
+- Returns document results with relevance scores
+
+### ContextGroundingVectorStore
+
+A vector store enabling semantic searches and retrieval chains with language models.
+
+```python
+from uipath_langchain.vectorstores import ContextGroundingVectorStore
+
+vector_store = ContextGroundingVectorStore(index_name="my_index")
+results = await vector_store.asimilarity_search(query="company policies", k=5)
+```
+
+**Search Methods:**
+- `similarity_search()` - Find similar documents
+- `similarity_search_with_score()` - Get documents with similarity scores
+- `asimilarity_search()` - Async similarity search
+
+## LangGraph Integration
+
+### Using Retriever as an Agent Tool
+
+Incorporate context grounding into your LangGraph agent by adding it as a tool that nodes can invoke:
+
+```python
+from langgraph.graph import START, END, StateGraph, MessagesState
+from langgraph.types import Command
+from langchain_core.messages import HumanMessage, SystemMessage, ToolMessage
+from uipath_langchain.chat.models import UiPathAzureChatOpenAI
+from uipath_langchain.retrievers import ContextGroundingRetriever
+
+class GraphState(MessagesState):
+    query: str
+    answer: str | None = None
+
+async def retrieve_context(state: GraphState) -> Command:
+    """Retrieve relevant documents from context grounding."""
+    retriever = ContextGroundingRetriever(index_name="company_docs", folder_path="Shared")
+    documents = await retriever.ainvoke(state["query"])
+    context = "\n".join([doc.page_content for doc in documents])
+    return Command(update={
+        "messages": state["messages"] + [
+            ToolMessage(content=f"Retrieved context: {context}", tool_call_id="retrieve")
+        ]
+    })
+
+async def respond_with_context(state: GraphState) -> Command:
+    """Generate response using retrieved context."""
+    llm = UiPathAzureChatOpenAI()
+    messages = [
+        SystemMessage(content="Answer based on the provided context."),
+        *state["messages"],
+    ]
+    response = await llm.ainvoke(messages)
+    return Command(update={"answer": response.content})
+
+builder = StateGraph(GraphState)
+builder.add_node("retrieve", retrieve_context)
+builder.add_node("respond", respond_with_context)
+builder.add_edge(START, "retrieve")
+builder.add_edge("retrieve", "respond")
+builder.add_edge("respond", END)
+
+graph = builder.compile()
+```
+
+### Retrieval-Augmented Generation (RAG) Pattern
+
+Combine context grounding with an LLM for more accurate responses:
+
+```python
+from langchain.chains import RetrievalQA
+from uipath_langchain.chat.models import UiPathAzureChatOpenAI
+from uipath_langchain.vectorstores import ContextGroundingVectorStore
+
+llm = UiPathAzureChatOpenAI()
+vector_store = ContextGroundingVectorStore(index_name="company_docs")
+retriever = vector_store.as_retriever(search_kwargs={"k": 5})
+
+rag_chain = RetrievalQA.from_chain_type(
+    llm=llm,
+    chain_type="stuff",
+    retriever=retriever
+)
+
+result = await rag_chain.ainvoke("What are our current policies?")
+```
+
+## Agent Integration
+
+Add context grounding as a tool to agents for autonomous document-based reasoning:
+
+```python
+from uipath_langchain.retrievers import ContextGroundingRetriever
+from langchain_core.tools import tool
+
+@tool
+async def search_company_docs(query: str) -> str:
+    """Search company documentation for relevant information.
+
+    Args:
+        query: Natural language question to search for in company docs
+
+    Returns:
+        Relevant documents matching the query
+    """
+    retriever = ContextGroundingRetriever(index_name="company_docs", folder_path="Shared")
+    documents = await retriever.ainvoke(query)
+    return "\n".join([doc.page_content for doc in documents])
+
+# Use with agent tools
+tools = [search_company_docs]
+```
+
+## Best Practices
+
+### Document Preparation
+
+- **Clear Structure**: Organize documents with clear titles, sections, and metadata
+- **Chunking**: Keep document chunks focused on single topics for better relevance
+- **Metadata**: Add metadata fields to help with filtering and relevance scoring
+- **Updates**: Regularly update indexes when documents change
+
+### Query Optimization
+
+- **Specific Queries**: Use specific, natural language questions for better results
+- **Context Setting**: Include context in your query ("according to company policy...")
+- **Multiple Searches**: Use multiple queries to cover different aspects
+
+### Response Grounding
+
+- **Include Sources**: Always mention which documents the response references
+- **Confidence Scores**: Check similarity scores to gauge result confidence
+- **Fallback Handling**: Handle cases where no relevant documents are found
+
+## Common Patterns
+
+### Question-Answer System
+
+```python
+async def qa_system(question: str) -> dict:
+    retriever = ContextGroundingRetriever(index_name="faq_docs", folder_path="Shared")
+    docs = await retriever.ainvoke(question)
+
+    if not docs:
+        return {"answer": "No relevant documents found.", "sources": []}
+
+    context = "\n".join([doc.page_content for doc in docs])
+
+    llm = UiPathAzureChatOpenAI()
+    response = await llm.ainvoke([
+        SystemMessage(content=f"Answer this question using the provided context: {context}"),
+        HumanMessage(content=question)
+    ])
+
+    return {
+        "answer": response.content,
+        "sources": [doc.metadata.get("source", "Unknown") for doc in docs]
+    }
+```
+
+### Document Summarization
+
+```python
+async def summarize_documents(topic: str) -> str:
+    vector_store = ContextGroundingVectorStore(index_name="docs")
+    results = await vector_store.asimilarity_search(topic, k=10)
+
+    combined_content = "\n\n".join([doc.page_content for doc in results])
+
+    llm = UiPathAzureChatOpenAI()
+    summary = await llm.ainvoke([
+        SystemMessage(content="Summarize these documents concisely."),
+        HumanMessage(content=combined_content)
+    ])
+
+    return summary.content
+```
+
+## Performance Considerations
+
+- **Async Operations**: Use async methods (`asimilarity_search`, `ainvoke`) for better performance
+- **Result Limit**: Set appropriate `k` values to limit returned documents
+- **Caching**: Cache retriever results when the same query is used multiple times
+- **Index Selection**: Use specific index names to avoid unnecessary searches across all data
+
+## Troubleshooting
+
+**"Index not found" errors:**
+- Verify the index name matches exactly what's in Orchestrator
+- Ensure the index has been fully indexed (check Orchestrator UI)
+- Confirm you have access to the index in your organization
+
+**"No results found":**
+- Try rephrasing your query with different keywords
+- Check if documents are properly uploaded and indexed
+- Verify document content is searchable (not just images/binary)
+
+**Low relevance results:**
+- Use more specific, natural language queries
+- Check document chunking and quality
+- Consider using multiple search queries to broaden coverage
+- Review metadata to ensure proper categorization
+
+## Reference
+
+For detailed API documentation, see the [UiPath Context Grounding documentation](https://uipath.github.io/uipath-python/langchain/context_grounding/).

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

@@ -0,0 +1,86 @@
+# Conversational Agents
+
+Chat-style coded agents where the UiPath runtime feeds **one message per turn** and threads history across turns.
+
+Supported on **LangGraph** and **LlamaIndex**. Coded Function and OpenAI Agents are not conversational.
+
+## Contract (framework-agnostic)
+
+Two requirements:
+
+1. **Flag the agent as conversational** — set `runtimeOptions.isConversational: true` in `uipath.json`:
+
+   ```json
+   {
+     "runtimeOptions": {
+       "isConversational": true
+     }
+   }
+   ```
+
+   Without it, Studio Web / Orchestrator render a single-shot input form and history is not threaded.
+
+2. **Type the graph/workflow input as the framework's message envelope.** The runtime fills it with one new message per turn; prior turns are threaded in by the runtime. The exact shape is framework-specific — see the framework reference below.
+
+Set `isConversational: true` in `uipath.json` **before** running `uip codedagent init` so the emitted `entry-points.json` reflects the chat shape.
+
+### Wire Envelope (`--input-file` payload)
+
+The minimal payload accepted by `uip codedagent run --input-file <file>.json`:
+
+```json
+{
+  "messages": [
+    {
+      "role": "user",
+      "contentParts": [
+        {
+          "mimeType": "text/plain",
+          "data": {"inline": "your message text"}
+        }
+      ]
+    }
+  ]
+}
+```
+
+- `role` is `"user"` for client input.
+- `data.inline` carries the text content; `mimeType` describes its format.
+- `messageId` and `contentPartId` may be supplied as GUIDs to address specific entities in the conversation hierarchy; if omitted the runtime fills them with fresh UUIDs.
+
+The same envelope is used for both LangGraph and LlamaIndex on the wire. Each framework's runtime converts it to the in-process shape its graph/workflow expects (`HumanMessage` for LangGraph, `user_msg: str` for LlamaIndex). `uip codedagent dev` builds this envelope automatically.
+
+## Framework-Specific Implementation
+
+| Framework | Reference |
+|---|---|
+| LangGraph | `../frameworks/langgraph-integration.md` § Conversational Agents |
+| LlamaIndex | `../frameworks/llamaindex-integration.md` § Conversational Agents |
+
+## Running Locally
+
+Inline JSON payloads on the CLI are fragile across shells (single vs. double quotes, brace escaping on cmd.exe / PowerShell). Two cleaner options:
+
+- **`--input-file`** on `uip codedagent run` — pass a `.json` file:
+
+  ```bash
+  uip codedagent run agent --input-file turn1.json --keep-state-file
+  ```
+
+- **`uip codedagent dev`** — opens a local chat window that wires up the runtime, lets you send turns interactively, and preserves thread state between messages. Preferred for iterative chat development.
+
+### Preserving State Across Turns
+
+Local CLI runs lose conversation state between invocations unless you keep the runtime's checkpoint / state file. Pass `--keep-state-file` on **every** turn (including the first) — without it, each `uip codedagent run` starts from scratch and history is dropped.
+
+```bash
+uip codedagent run agent --input-file turn1.json --keep-state-file
+uip codedagent run agent --input-file turn2.json --keep-state-file
+```
+
+The state file is per-project; deleting it resets the conversation. `uip codedagent dev` handles this automatically — the flag is only needed for the headless `uip codedagent run` path.
+
+## Gotchas
+
+- `isConversational` lives under `runtimeOptions` in `uipath.json` — not in `langgraph.json` / `llama_index.json` / `pyproject.toml`.
+- LangGraph and LlamaIndex per-message shapes differ — do not transplant a payload from one framework to the other.

package/skills/uipath-agents/references/coded/capabilities/deeprag/api-reference.md

@@ -0,0 +1,38 @@
+# DeepRAG — API Reference (Debug Only)
+
+> **Stop.** In a coded agent, use the resume-trigger models (`Create*` / `Wait*` from `uipath.platform.common`) with plain `interrupt()` — see [impl-python.md](impl-python.md). The runtime calls these endpoints for you with the correct headers, body shape, and folder context.
+
+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/coded/capabilities/deeprag/impl-python.md

@@ -0,0 +1,117 @@
+# DeepRAG in a Coded Agent — Implementation
+
+LangGraph + `interrupt()` pattern. **No polling** — runtime suspends on `Create*` resume-trigger models and resumes on the DeepRAG completion event.
+
+
+## Dependencies
+
+```toml
+[project]
+dependencies = ["uipath", "uipath-langchain"]
+```
+
+## Flavour A — Ephemeral index (attachment-backed, one-shot)
+
+### Node: create_index
+
+```python
+from uipath.platform import UiPath
+from uipath.platform.common import UiPathConfig, WaitEphemeralIndex
+from uipath.platform.context_grounding import EphemeralIndexUsage
+from langgraph.types import interrupt
+
+sdk = UiPath()
+if not (folder_key := UiPathConfig.folder_key):
+    folder_key = (await sdk.folders.get_personal_workspace_async()).key
+
+ephemeral_index = await sdk.context_grounding.create_ephemeral_index_async(
+    usage=EphemeralIndexUsage.DEEP_RAG,
+    attachments=[attachment_id],
+    folder_key=folder_key,
+)
+if ephemeral_index.in_progress_ingestion():
+    ephemeral_index = interrupt(WaitEphemeralIndex(index=ephemeral_index))  # → ContextGroundingIndex (ingested)
+```
+
+### Node: run_deep_rag
+
+```python
+from uipath.platform.common import CreateDeepRag
+from langgraph.types import interrupt
+
+content = interrupt(CreateDeepRag(
+    name=task_name,
+    index_id=ephemeral_index_id,        # from state, set by create_index node
+    is_ephemeral_index=True,
+    prompt=prompt,
+    index_folder_key=index_folder_key,  # from state, set by create_index node
+))  # → DeepRagContent — has .text, .citations
+```
+
+`is_ephemeral_index=True` is required when `index_id` came from an ephemeral index — missing it surfaces server-side at execution.
+
+## Flavour B — Existing named index
+
+Skip the `fetch_file`, `upload_attachment`, and `create_index` nodes entirely.
+
+### Node: run_deep_rag
+
+```python
+from uipath.platform.common import CreateDeepRag
+from langgraph.types import interrupt
+
+content = interrupt(CreateDeepRag(
+    name=task_name,
+    index_name="<INDEX_NAME>",
+    index_folder_path="<INDEX_FOLDER_PATH>",
+    prompt=prompt,
+))  # → DeepRagContent — has .text, .citations
+```
+
+## Procedure (Flavour A)
+
+1. **fetch_file** — accept / download the PDF/TXT → local path
+2. **upload_attachment** — `await sdk.attachments.upload_async(name=..., source_path=local, folder_key=folder_key)` → attachment uuid
+3. **create_index** — `create_ephemeral_index_async` → check `in_progress_ingestion()` → conditionally `interrupt(WaitEphemeralIndex(...))` → `ContextGroundingIndex`
+4. **run_deep_rag** — `interrupt(CreateDeepRag(... is_ephemeral_index=True, index_id=..., prompt=..., index_folder_key=...))` → `DeepRagContent` (`text`, `citations`)
+5. **finalize** — shape the agent's `GraphOutput`
+
+Instantiate `UiPath()` inside nodes only — never at module level.
+
+## Resume Values
+
+| Yielded model | Resume value | Useful fields |
+|---|---|---|
+| `WaitEphemeralIndex` | `ContextGroundingIndex` | `id`, `folder_key` (ingested) |
+| `CreateDeepRag` | `DeepRagContent` (validated) or `dict` | `text`, `citations` |
+| `CreateDeepRagRaw` | `DeepRagResponse` raw | full response, no status validation |
+
+Runtime raises `UiPathFaultedTriggerError` (imported as `from uipath.core.errors import UiPathFaultedTriggerError`) on terminal `Failed`. Use `*Raw` variants only to inspect a failed status without raising.
+
+## Defensive Resume-Value Access
+
+Resume value may be the typed model or a dict depending on SDK version. Read both shapes:
+
+```python
+text = content.get("text", "") if isinstance(content, dict) else getattr(content, "text", "")
+raw_citations = content.get("citations") if isinstance(content, dict) else getattr(content, "citations", [])
+citations = [c if isinstance(c, dict) else c.model_dump() for c in (raw_citations or [])]
+```
+
+## Citation Modes
+
+Pass `citation_mode=CitationMode.SKIP | INLINE` on `CreateDeepRag`. Default `SKIP` (lowest latency, no citations). `INLINE` interleaves citations in `content.text`. Verify the available enum values at your SDK version: `from uipath.platform.context_grounding import CitationMode; list(CitationMode)`.
+
+## Local-Run Verification
+
+```bash
+uip codedagent run agent '{"instructions":"<PROMPT>"}' --output-file out.json
+```
+
+Runtime executes pre-interrupt nodes synchronously, then suspends at `create_index` with the `WaitEphemeralIndex` model captured as the suspend value (Flavour A) or at `run_deep_rag` with `CreateDeepRag` (Flavour B). That output is correct — not a failure. End-to-end completion happens only on a deployed agent or via `uip codedagent dev`.
+
+## Resources
+
+- UiPath Python SDK: <https://uipath.github.io/uipath-python/>
+- Built-in tool reference (BT/DR/etc.): `uipath_langchain.agent.tools.context_tool` in the installed venv
+- API endpoints (debug): [api-reference.md](api-reference.md)

package/skills/uipath-agents/references/coded/capabilities/deeprag/planning.md

@@ -0,0 +1,58 @@
+# DeepRAG in a Coded Agent — Planning
+
+## When to Use
+
+Pick this when:
+
+- Project has `pyproject.toml` with `uipath` / `uipath-langchain`, plus `langgraph.json` or a graph-style `main.py`
+- User wants Python / programmatic control over the pipeline
+- Agent needs to combine DeepRAG with custom pre/post-processing (download from bucket, validate, route, etc.)
+- Agent must run unattended (scheduled, queue-triggered, or invoked from another agent)
+
+Confirm DeepRAG is the right mode first — see [../../../context-grounding-patterns.md](../../../context-grounding-patterns.md).
+
+For Studio Web Agent Builder → [../../lowcode/capabilities/built-in-tools/deeprag/planning.md](../../lowcode/capabilities/built-in-tools/deeprag/planning.md).
+
+## Inputs You Need Before Building
+
+| Input | Why | Where to get it |
+|---|---|---|
+| File source | Determines the first node | Bucket / queue payload / attachment id from upstream |
+| Bucket name + folder path (if downloading) | `sdk.buckets.download_async` arguments | User config or hardcoded constant |
+| Prompt | DeepRAG `prompt` body field — required, non-empty | User input or static default |
+| Target folder for ingestion + DeepRAG | Permission scope | Default to personal workspace key for self-serve |
+| Citation mode | Per `CitationMode` enum in the SDK (currently `SKIP`, `INLINE` — verify at your version) | User preference; default `SKIP` |
+
+## Pipeline Shape
+
+Standard 5-node graph:
+
+1. `fetch_file` — download / accept input file → local path
+2. `upload_attachment` — `sdk.attachments.upload_async` → attachment uuid
+3. `create_index` — `create_ephemeral_index_async` → check `in_progress_ingestion()` → conditionally `interrupt(WaitEphemeralIndex(...))` → `ContextGroundingIndex`
+4. `run_deep_rag` — `interrupt(CreateDeepRag(is_ephemeral_index=True, ...))` → `DeepRagContent`
+5. `finalize` — shape `GraphOutput`
+
+Steps 3 and 4 use plain `interrupt()` so the agent suspends and resumes on platform completion events. Polling kills the serverless 15-min job timeout — see [impl-python.md](impl-python.md) for the implementation.
+
+## Critical Decisions
+
+| Decision | Rule |
+|---|---|
+| Sync vs interrupt | Always use `interrupt()` for create-index (conditionally) and run-deep-rag. Never poll. |
+| Folder for index | Personal workspace key by default. Only override when the user has confirmed role permissions in another folder. |
+| Citation mode | Default `SKIP` for summarization. Use `INLINE` when the user asks for inline source references. Verify available values via the SDK's `CitationMode` enum. |
+| `is_ephemeral_index` | Always `True` on `CreateDeepRag` when `index_id` came from `CreateEphemeralIndex`. Runtime requires the flag to route as ephemeral; missing it fails server-side. The Pydantic validator only catches the inverse case (`is_ephemeral_index=True` with `index_id=None`). |
+| Mock-friendly outputs | Return shapes that work whether the resume value is the typed model or a dict — see the defensive accessor in [impl-python.md](impl-python.md). |
+
+## Bindings
+
+The bucket counts as a bindable resource. Attachments and ephemeral indexes do NOT — they are runtime-created.
+
+## Local-Run Behavior
+
+`uip codedagent run agent '{...}'` exits at the first interrupt. That is correct — the runtime has captured suspend state and would resume on the platform event. For end-to-end verification: deploy the agent (or `uip codedagent dev`) and invoke from the platform.
+
+## Hand-off
+
+Once planning is complete, implement per [impl-python.md](impl-python.md).