@uipath/skills 1.201.0-preview.621 → 1.202.0-preview.635

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

@@ -0,0 +1,465 @@
+# Data Fabric Integration for Coded Agents
+
+How to query and manage UiPath Data Fabric entities from coded agents. Two integration paths exist — choose based on the use case.
+
+## Step 1: Discover Available Entities
+
+Before choosing a path, discover what entities exist. Start with folder-scoped listing — most entities live in a specific folder (commonly `Shared`):
+
+```bash
+# List entities in the default Shared folder
+uip df entities list --folder-path "Shared" --output table
+
+# If the user specifies a different folder
+uip df entities list --folder-path "<FolderName>" --output table
+
+# Get full details for a specific entity (fields, types, IDs)
+uip df entities get --name "<EntityName>" --folder-path "Shared"
+```
+
+Only fall back to `--include-folders` if the entity isn't found in the expected folder:
+
+```bash
+# Search across all folders (can return many results)
+uip df entities list --include-folders --output table
+```
+
+Each entity in the output has:
+- **`Id`** (UUID) — the entity identifier needed for `DataFabricEntityItem`
+- **`Name`** — the entity name used in SDK calls (`entity_key`)
+- **`FolderId`** (UUID) — the folder key needed for `DataFabricEntityItem`
+- **`Fields`** — column names, types, and relationships
+
+**Recommend an entity to the user** based on their use case. For example, if they ask about "customer orders," look for entities with names like `Orders`, `SalesOrder`, or similar. Show them the matching entities and their fields before proceeding.
+
+## Step 2: Choose the Integration Path
+
+| Path | Best for | Trade-off |
+|------|----------|-----------|
+| **SDK direct** (`sdk.entities`) | The query shape is known at build time — same filter, same fields every time | Reliable, no LLM cost, but you code every query |
+| **`create_datafabric_tool`** | Users ask freeform questions the agent can't anticipate | Flexible, but adds an inner LLM call for SQL generation |
+
+**Rule of thumb:** If the user describes a fixed operation (e.g. "look up orders by customer name"), use the SDK. If they say "users can ask anything" or "I can't predict the questions," use `create_datafabric_tool`.
+
+**CRITICAL: For freeform/unpredictable queries, always use `create_datafabric_tool` from `uipath_langchain.agent.tools`.** Do NOT build a custom NL-to-SQL solution, do NOT use internal functions like `create_datafabric_query_tool`, and do NOT wrap raw SDK calls to handle freeform questions. The `create_datafabric_tool` factory handles schema resolution, SQL generation, error correction, and caching — reimplementing this is fragile and unsupported.
+
+Both paths can coexist in a single agent — use SDK for known operations and `create_datafabric_tool` for open-ended exploration.
+
+---
+
+## Path 1: SDK Direct Access (`sdk.entities`)
+
+Use the Python SDK's `EntitiesService` for deterministic CRUD operations. No LLM intermediary — the agent code specifies exactly what to fetch or write.
+
+**Fixed-shape does not mean inline.** Even when the query is always the same, expose each SDK call as a `@tool`-decorated function and hand it to the agent (see § Wiring into a LangGraph Agent). Do NOT call `sdk.entities.*` directly inside a plain graph node — a tool keeps the SDK call bindable, testable, and invocable by the agent.
+
+### Setup
+
+```python
+from uipath.platform import UiPath
+
+# CRITICAL: Never instantiate at module level — always inside a function/node.
+# Module-level UiPath() fails during `uip codedagent init` introspection.
+sdk = UiPath()
+```
+
+### Reading Records
+
+`list_records` supports pagination only — it has NO `filter`/`select`/`orderby` parameters. To filter, sort, or project, use `retrieve_records` (see Structured Query with Filters below).
+
+```python
+# List with pagination
+records = await sdk.entities.list_records_async(
+    entity_key="Orders",
+    start=0,
+    limit=50,
+)
+
+# Single record by ID
+record = await sdk.entities.get_record_async(
+    entity_key="Orders",
+    record_id="abc-123",
+)
+```
+
+### Structured Query with Filters
+
+For complex filters, aggregations, and joins — use `retrieve_records` with typed filter objects:
+
+```python
+from uipath.platform.entities import (
+    EntityQueryFilter,
+    EntityQueryFilterGroup,
+    EntityQuerySortOption,
+    EntityAggregate,
+    EntityAggregateFunction,
+    LogicalOperator,
+    QueryFilterOperator,
+)
+
+filter_group = EntityQueryFilterGroup(
+    logical_operator=LogicalOperator.And,
+    query_filters=[
+        EntityQueryFilter(
+            field_name="Status",
+            operator=QueryFilterOperator.Equals,
+            value="Open",
+        ),
+        EntityQueryFilter(
+            field_name="Total",
+            operator=QueryFilterOperator.GreaterThan,
+            value="1000",
+        ),
+    ],
+)
+
+result = await sdk.entities.retrieve_records_async(
+    entity_key="Orders",
+    filter_group=filter_group,
+    sort_options=[EntityQuerySortOption(field_name="Total", is_descending=True)],
+    selected_fields=["OrderId", "CustomerName", "Total"],
+    limit=20,
+)
+
+for record in result.items:
+    print(record.id, record.model_extra)
+```
+
+### Aggregation
+
+```python
+result = await sdk.entities.retrieve_records_async(
+    entity_key="Orders",
+    aggregates=[
+        EntityAggregate(
+            function=EntityAggregateFunction.Sum,
+            field="Total",
+            alias="total_revenue",
+        ),
+        EntityAggregate(
+            function=EntityAggregateFunction.Count,
+            field="Id",
+            alias="order_count",
+        ),
+    ],
+    group_by=["Status"],
+)
+```
+
+### Writing Records
+
+```python
+# Single insert (fires triggers)
+record = await sdk.entities.insert_record_async(
+    entity_key="Orders",
+    data={"CustomerName": "Acme Corp", "Total": 5000, "Status": "Open"},
+)
+
+# Single update (fires triggers)
+updated = await sdk.entities.update_record_async(
+    entity_key="Orders",
+    record_id=record.id,
+    data={"Status": "Closed"},
+)
+
+# Single delete (fires triggers)
+await sdk.entities.delete_record_async(entity_key="Orders", record_id=record.id)
+
+# Batch insert (does NOT fire triggers)
+batch_result = await sdk.entities.insert_records_async(
+    entity_key="Orders",
+    records=[
+        {"CustomerName": "Acme", "Total": 5000},
+        {"CustomerName": "Globex", "Total": 3000},
+    ],
+)
+# Check batch_result.failure_records for errors
+```
+
+### File Attachments
+
+```python
+# Upload
+await sdk.entities.upload_attachment(
+    entity_id="<entity-uuid>",
+    record_id="<record-uuid>",
+    field_name="Invoice",
+    file_path="/path/to/invoice.pdf",
+)
+
+# Download
+content: bytes = await sdk.entities.download_attachment_async(
+    entity_id="<entity-uuid>",
+    record_id="<record-uuid>",
+    field_name="Invoice",
+)
+```
+
+### Wiring into a LangGraph Agent
+
+Wrap every SDK call as a LangChain `@tool` so the agent can invoke it. This applies to fixed-shape queries too — the deterministic query lives inside the tool body; the agent decides when to call it. Never place `sdk.entities.*` calls in a plain graph node.
+
+```python
+from langchain_core.tools import tool
+from uipath.platform import UiPath
+from uipath.platform.entities import (
+    EntityQueryFilter,
+    EntityQueryFilterGroup,
+    LogicalOperator,
+    QueryFilterOperator,
+)
+
+
+@tool
+async def get_open_orders(customer_name: str) -> str:
+    """Get all open orders for a specific customer.
+
+    Args:
+        customer_name: The customer name to look up.
+    """
+    sdk = UiPath()
+    result = await sdk.entities.retrieve_records_async(
+        entity_key="Orders",
+        filter_group=EntityQueryFilterGroup(
+            logical_operator=LogicalOperator.And,
+            query_filters=[
+                EntityQueryFilter(
+                    field_name="CustomerName",
+                    operator=QueryFilterOperator.Equals,
+                    value=customer_name,
+                ),
+                EntityQueryFilter(
+                    field_name="Status",
+                    operator=QueryFilterOperator.Equals,
+                    value="Open",
+                ),
+            ],
+        ),
+        selected_fields=["OrderId", "Total", "CreatedTime"],
+        limit=50,
+    )
+    if not result.items:
+        return f"No open orders found for {customer_name}."
+    lines = [f"- {r.model_extra['OrderId']}: ${r.model_extra['Total']}" for r in result.items]
+    return f"Open orders for {customer_name}:\n" + "\n".join(lines)
+
+
+@tool
+async def close_order(order_id: str) -> str:
+    """Mark an order as closed.
+
+    Args:
+        order_id: The record ID of the order to close.
+    """
+    sdk = UiPath()
+    await sdk.entities.update_record_async(
+        entity_key="Orders",
+        record_id=order_id,
+        data={"Status": "Closed"},
+    )
+    return f"Order {order_id} closed."
+```
+
+Then add to your agent graph:
+
+```python
+from langchain_core.messages import SystemMessage
+from uipath_langchain.agent.react.agent import create_agent
+from uipath_langchain.chat import UiPathChat
+
+def _make_llm():
+    """Lazy LLM factory — never call at module level."""
+    return UiPathChat(model="gpt-4.1-mini-2025-04-14")
+
+graph = create_agent(_make_llm(), tools=[get_open_orders, close_order], messages=[SystemMessage("...")])
+```
+
+---
+
+## Path 2: DataFabric Tool (`create_datafabric_tool`)
+
+Use `create_datafabric_tool` when end-users ask freeform questions that the agent can't anticipate at build time. This is the **only supported way** to add NL-to-SQL querying to a coded agent. The tool runs an inner LLM sub-graph that translates natural language to SQL, executes it against Data Fabric, and returns results.
+
+### Required Import
+
+```python
+# This is the ONLY correct import. Do NOT use create_datafabric_query_tool
+# or any other function from internal submodules.
+from uipath_langchain.agent.tools import create_datafabric_tool
+```
+
+### Setup
+
+Use the entity ID, name, and folder key from Step 1 discovery.
+
+### Usage
+
+```python
+from langchain_core.messages import SystemMessage
+from uipath.platform.entities import DataFabricEntityItem
+from uipath_langchain.agent.react.agent import create_agent
+from uipath_langchain.agent.tools import create_datafabric_tool
+from uipath_langchain.chat import UiPathChat
+
+
+def _make_llm():
+    """Lazy LLM factory — never call at module level."""
+    return UiPathChat(model="gpt-4.1-mini-2025-04-14")
+
+
+system_prompt = "Answer questions using only the configured Data Fabric entities."
+
+llm = _make_llm()
+datafabric_tool = create_datafabric_tool(
+    llm=llm,
+    name="query_orders",
+    description="Query order and customer data from Data Fabric.",
+    base_system_prompt=system_prompt,
+    entities=[
+        DataFabricEntityItem(
+            id="1312e893-8295-f111-9b33-0022482a9eea",
+            name="Orders",
+            folder_key="379fec63-62b1-41ec-b2fc-718f8f7dda3c",
+        ),
+        DataFabricEntityItem(
+            id="a1b2c3d4-5678-90ab-cdef-1234567890ab",
+            name="Customers",
+            folder_key="379fec63-62b1-41ec-b2fc-718f8f7dda3c",
+        ),
+    ],
+)
+
+graph = create_agent(llm, tools=[datafabric_tool], messages=[SystemMessage(system_prompt)])
+```
+
+### Key Design Constraint
+
+**The same instruction string must reach both levels: pass it as `messages=[SystemMessage(...)]` to `create_agent` and as `base_system_prompt` to `create_datafabric_tool`.** The tool forwards it to the inner SQL-generation sub-graph so the agent's instructions apply consistently at both levels.
+
+### How It Works Internally
+
+1. Agent receives a freeform user question
+2. Agent calls the `datafabric_tool` with a `user_query` string
+3. Inner LLM sub-graph resolves entity schemas (lazy, cached after first call)
+4. Inner LLM generates a SQL SELECT against the entity schemas
+5. SQL executes against Data Fabric; errors loop back to the LLM for self-correction
+6. Results return to the outer agent as text
+
+### `create_datafabric_tool` Signature
+
+```python
+def create_datafabric_tool(
+    *,
+    llm: BaseChatModel,        # LLM for the inner SQL generation loop
+    name: str,                  # Tool name exposed to the outer agent
+    description: str,           # Tool description for agent tool selection
+    entities: Sequence[DataFabricEntityItem],  # Entities available to query
+    base_system_prompt: str,    # Forwarded to inner sub-graph
+) -> BaseTool
+```
+
+### `DataFabricEntityItem` Fields
+
+| Field | Type | Required | Source |
+|-------|------|----------|--------|
+| `id` | `str` (UUID) | Yes | `uip df entities list` |
+| `name` | `str` | Yes | Entity display name |
+| `folder_key` | `str` (UUID) | Yes | `uip df entities list` or Orchestrator folder ID. Tenant-level entities: pass the discovered all-zeros `FolderId` (`00000000-0000-0000-0000-000000000000`) as-is |
+| `entity_key` | `str` | No | Technical entity identifier |
+| `description` | `str` | No | Helps the LLM understand the entity's purpose |
+
+---
+
+## Combining Both Paths
+
+A single agent can use both paths. Use SDK tools for known operations and the DataFabric tool for open-ended exploration:
+
+```python
+from langchain_core.messages import SystemMessage
+from langchain_core.tools import tool
+from uipath.platform import UiPath
+from uipath.platform.entities import DataFabricEntityItem
+from uipath_langchain.agent.react.agent import create_agent
+from uipath_langchain.agent.tools import create_datafabric_tool
+from uipath_langchain.chat import UiPathChat
+
+
+# Deterministic tool — known query shape
+@tool
+async def close_order(order_id: str) -> str:
+    """Mark an order as closed. Use when the user asks to close a specific order.
+
+    Args:
+        order_id: The record ID of the order.
+    """
+    sdk = UiPath()
+    await sdk.entities.update_record_async(
+        entity_key="Orders", record_id=order_id, data={"Status": "Closed"}
+    )
+    return f"Order {order_id} closed."
+
+
+def _make_llm():
+    """Lazy LLM factory — never call at module level."""
+    return UiPathChat(model="gpt-4.1-mini-2025-04-14")
+
+
+system_prompt = (
+    "You are an order management assistant. "
+    "Use query_orders for data questions. Use close_order to close orders."
+)
+
+llm = _make_llm()
+# NL-to-SQL tool — freeform queries
+query_tool = create_datafabric_tool(
+    llm=llm,
+    name="query_orders",
+    description="Query order and customer data using natural language.",
+    base_system_prompt=system_prompt,
+    entities=[
+        DataFabricEntityItem(
+            id="1312e893-8295-f111-9b33-0022482a9eea",
+            name="Orders",
+            folder_key="379fec63-62b1-41ec-b2fc-718f8f7dda3c",
+        ),
+    ],
+)
+
+graph = create_agent(llm, tools=[query_tool, close_order], messages=[SystemMessage(system_prompt)])
+```
+
+---
+
+## Gotchas
+
+1. **Never instantiate `UiPath()` or `UiPathChat()` at module level** — they read auth credentials at construction time. `uip codedagent init` imports your module to introspect it, and module-level construction will fail. Wrap in a lazy factory function.
+
+2. **For freeform queries, use `create_datafabric_tool` — not a custom solution.** Import it from `uipath_langchain.agent.tools`. Do NOT use `create_datafabric_query_tool` or any other internal function — those are implementation details and may change without notice.
+
+3. **SDK-direct calls are always `@tool`-wrapped — even fixed-shape ones.** "Same query every time" describes the tool's body, not a reason to skip the tool. An `sdk.entities.*` call inline in a graph node is not invocable by the agent and is the most common shape mistake on this path.
+
+4. **Single vs. batch trigger behavior** — `insert_record` / `update_record` / `delete_record` fire entity triggers. Batch variants (`insert_records`, `update_records`, `delete_records`) do **not**.
+
+5. **SQL query constraints** — `query_entity_records` only accepts SELECT statements. Queries without WHERE must include LIMIT. Subqueries, UNION, WITH, and DML/DDL are forbidden.
+
+6. **Entity schemas resolve lazily** in `create_datafabric_tool` — the first invocation fetches schemas from Data Fabric and caches them. Subsequent calls reuse the cache.
+
+7. **Reserved field names** — `Id`, `CreatedBy`, `CreateTime`, `UpdatedBy`, `UpdateTime` are system fields and cannot be used as user field names.
+
+## Comparison with Low-Code DataFabric Context
+
+Low-code agents use `contextType: "datafabricentityset"` in `resource.json` — see [../../lowcode/capabilities/context/datafabric.md](../../lowcode/capabilities/context/datafabric.md). The coded agent paths above are the programmatic equivalent. The key differences:
+
+| | Low-code | Coded (SDK) | Coded (Tool) |
+|-|----------|-------------|--------------|
+| Configuration | `resource.json` | Python code | `create_datafabric_tool()` call |
+| Query flexibility | NL-to-SQL via built-in tool | Full programmatic control | NL-to-SQL via inner sub-graph |
+| Write support | No | Yes (single + batch) | No (read-only SQL) |
+| LLM cost per query | Yes | No | Yes |
+
+## References
+
+- [sdk-services.md](sdk-services.md) — Full SDK services reference
+- [context-grounding.md](context-grounding.md) — Context Grounding (RAG over documents, separate from Data Fabric)
+- [../../lowcode/capabilities/context/datafabric.md](../../lowcode/capabilities/context/datafabric.md) — Low-code DataFabric context
+- Sample: `uipath-langchain-python/samples/datafabric-coded-agent/` — Working coded agent example

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

@@ -14,6 +14,11 @@ Both workflows are driven by live data — the catalog (`uip agent guardrails ca
 
 > Full three-fetch mandate applies to **Recommend mode**. In **Validate mode** of an existing guardrail the SDK docs are the authoritative, sufficient source for a validator's scope/stage — `catalog` (relevance metadata) and `list` (tenant entitlement) are recommended cross-checks, not a hard prerequisite for a scope/placement fix. See [Validate Mode](#validate-mode).
 
+> **The SDK docs are authoritative for shape, never for availability.** They carry `Platform Availability`
+> notes for features still rolling out (BYOG, LLM-as-judge). Those are product-wide statements, not facts
+> about this tenant — only `uip agent guardrails list` decides that. Never withhold or down-rank a
+> recommendation because a fetched page called the feature "not enabled on every tenant yet".
+
 **Required first operation in both modes:** use `WebFetch` on
 `https://uipath.github.io/uipath-python/core/guardrails/` before catalog calls,
 project inspection, analysis, or edits. A coded guardrail recommendation or

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

@@ -24,6 +24,8 @@ Add guardrails to a Python coded agent (LangChain/LangGraph) in two styles: **mi
 - Entity type names or their allowed values
 - Import paths
 
+> **That authority covers shape, not availability.** These pages carry `Platform Availability` notes for features still rolling out (BYOG, LLM-as-judge). Those notes are product-wide, never a statement about the tenant in front of you — [Check Tenant Availability](#check-tenant-availability-mandatory-for-built-in-ai-validators) below is the only authority for that. A validator the docs describe as "not enabled on every tenant yet" can still be `Available` here; author it.
+
 When available, the `langchain/guardrails/` page documents three actions — **`LogAction`**, **`BlockAction`**, and
 **`EscalateAction`** (human-in-the-loop). Treat the fetched page as the source of truth for `EscalateAction`'s
 parameters, supported scopes, and stages; the operational wiring it doesn't cover (the suspend->resume UX, the

package/skills/uipath-agents/references/coded/capabilities/human-in-the-loop.md

@@ -13,12 +13,14 @@ If the user has not named one, your ENTIRE response must be a question that list
 | Pattern | When | LangGraph | LlamaIndex |
 |---|---|---|---|
 | API trigger | Resumed via an Orchestrator inbox URL; no Action Center involved | `interrupt({...})` | `InputRequiredEvent(...)` |
-| Action Center task | Structured form for a human reviewer | `interrupt(CreateTask(...))` | `CreateTaskEvent(...)` |
-| Escalation task | Task flagged as escalation | `interrupt(CreateEscalation(...))` | use `CreateTaskEvent` (no event-level distinction) |
-| Wait for existing task | A task was already created elsewhere; resume when it completes | `interrupt(WaitTask(...))` | `WaitTaskEvent(...)` |
+| Action Center task | Structured form for a human reviewer, described as a normal review / sign-off task. Resume delivers only the task `data` | `interrupt(CreateTask(...))` | `CreateTaskEvent(...)` |
+| Escalation task | The request calls the hand-off an escalation (`escalate`, `escalation`, "needs sign-off above a limit"), or the agent must branch on the reviewer's approve/reject outcome. Resume delivers the full `Task` (incl. `action`) | `interrupt(CreateEscalation(...))` | use `CreateTaskEvent` (no event-level distinction) |
+| Wait for existing task | A task was already created elsewhere; resume when it completes. Same split as above: `WaitTask` resumes with the task `data`; `WaitEscalation` resumes with the full `Task` (incl. `action`) | `interrupt(WaitTask(...))` / `interrupt(WaitEscalation(...))` | `WaitTaskEvent(...)` |
 | Invoke a process | Trigger an RPA process; resume on completion | `interrupt(InvokeProcess(...))` | `InvokeProcessEvent(...)` |
 | Wait for existing job | A job is running elsewhere; resume on its completion | `interrupt(WaitJob(...))` | `WaitJobEvent(...)` |
 
+**Task vs Escalation is decided by the request's wording, not by preference — for both the create pair and the wait pair.** "Escalate" / "escalation" / must act on the approve-reject decision → `CreateEscalation` / `WaitEscalation`. "Review task" / "sign-off" / "not an escalation" / only carry the reviewer's input forward → `CreateTask` / `WaitTask`. Never substitute one for the other: they resume with different payloads (see § Escalation Variant).
+
 OpenAI Agents has no first-class HITL support. Coded Function (no framework) has no checkpoint/resume — call `sdk.tasks.create()` then `sdk.tasks.retrieve()` synchronously if a synchronous human step is needed.
 
 LangGraph models live in `uipath.platform.common`; LlamaIndex events live in `uipath_llamaindex.models.events`.
@@ -56,7 +58,7 @@ class GraphState(MessagesState):
     request: str
     approval_status: str | None = None
 
-async def escalate_to_human(state: GraphState) -> Command:
+async def request_review(state: GraphState) -> Command:
     task_output = interrupt(CreateTask(
         app_name="RequestReview",
         app_folder_path="MyFolderPath",
@@ -86,7 +88,7 @@ async def escalate_to_human(state: GraphState) -> Command:
 
 ### Escalation Variant
 
-Swap `CreateTask` for `CreateEscalation` when the task is an escalation. It is the same task shape: `CreateEscalation` extends `CreateTask` with the same fields. Difference is the resume return value: escalation returns the full `Task`; normal task returns `task.data`.
+Use `CreateEscalation` whenever the request describes the hand-off as an escalation (a threshold breach routed to a manager / director, "escalate to a reviewer"), or when the agent must act on whether the reviewer approved or rejected. It is the same task shape: `CreateEscalation` extends `CreateTask` with the same fields. Difference is the resume return value: escalation returns the full `Task` (so `task_output.action` / `task_output.data` are both available); normal task returns only `task.data`. Do not use `CreateTask` for an escalation — its resume payload has no `action`, so approve/reject cannot be read back.
 
 ```python
 from uipath.platform.common import CreateEscalation
@@ -113,6 +115,8 @@ async def monitor_task(state: GraphState) -> Command:
     return Command(update={"task_result": task_output})
 ```
 
+`WaitTask` resumes with the task's `data` only. Swap in `WaitEscalation` (same fields, `from uipath.platform.common import WaitEscalation`) when the existing task is an escalation, or the agent must branch on the reviewer's approve/reject `action` — it resumes with the full `Task`. Same rule as `CreateTask` vs `CreateEscalation`.
+
 **LlamaIndex equivalent:** `ctx.write_event_to_stream(WaitTaskEvent(action=...))`
 
 ## InvokeProcess — Call RPA Automation
@@ -143,10 +147,12 @@ output = interrupt(WaitJob(job=background_job, process_folder_path="Workflows"))
 
 ### Conditional Interrupt
 
+Threshold breach routed to a director is an escalation → `CreateEscalation`.
+
 ```python
 async def conditional_workflow(state: GraphState) -> Command:
     if state["amount"] > 10000:
-        result = interrupt(CreateTask(
+        result = interrupt(CreateEscalation(
             assignee="finance-director@example.com",
             title="Approve Large Request",
             app_name="ApprovalProcess",

package/skills/uipath-agents/references/coded/flow-integration.md

@@ -36,7 +36,7 @@ Fallback discovery paths if the deploy output is unavailable or unparseable, **t
 
 If all paths return empty / 404, the deploy command's stdout JSON is authoritative — re-run the deploy and capture its output rather than chasing post-hoc discovery endpoints.
 
-For the flow node JSON shape, see the uipath-maestro-flow skill agent-plugin reference (Published variant). `model.section` is `"Published"`.
+For the flow node JSON shape, see the uipath-maestro-flow skill agent-plugin reference (Published variant). Registry output marks the published variant with `category: "agent.published"` and omits `model.section`.
 
 ---
 
@@ -75,7 +75,7 @@ Coded agents use `location: "external"`.
 | Node type | `uipath.core.agent.<resourceKey>` (local, from `project add`) | `uipath.core.agent.<resourceKey>` (Orchestrator-assigned) | `uipath.agent.resource.tool.agent` |
 | Lifecycle | `uip solution upload` (single pass) | `uip codedagent deploy` | `uip codedagent deploy` |
 | Runtime lookup | Studio Web projects API | Orchestrator Releases API | Orchestrator (via parent agent) |
-| `model.section` | `"In this solution"` | `"Published"` or absent | n/a |
+| `model.section` | `"In this solution"` | absent (`category: "agent.published"`) | n/a |
 | Cross-flow reuse | No | Yes | Yes |
 
 ---

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

@@ -283,6 +283,54 @@ Or have the terminal node compute the full aggregate and emit it.
 
 ---
 
+## Available Tools
+
+The `uipath-langchain` package provides UiPath-specific LangChain tools:
+
+| Tool | Import | Purpose |
+|------|--------|---------|
+| Process invocation | `uipath_langchain.agent.tools import create_process_tool` | Trigger UiPath processes |
+| Escalation (HITL) | `uipath_langchain.agent.tools import create_escalation_tool` | Send to human reviewer |
+| Context search | `uipath_langchain.retrievers import ContextGroundingRetriever` | Search Context Grounding indexes |
+| MCP tools | `uipath_langchain.agent.tools import open_mcp_tools` | Connect to MCP servers |
+
+> **Context Grounding retrieval in LangGraph:** always use `ContextGroundingRetriever` from `uipath_langchain.retrievers` — not `sdk.context_grounding.search()` / `search_async()`. The LangChain retriever integrates natively with the graph pipeline and declares `index_name` + `folder_path` at one call site — the exact shape the `index` binding entry needs (see [../lifecycle/bindings-reference.md](../lifecycle/bindings-reference.md)). See [../capabilities/context-grounding.md](../capabilities/context-grounding.md) for usage examples.
+
+### Context Grounding RAG Example
+
+Minimal RAG shape: retrieval node + answer node.
+
+```python
+from typing import TypedDict
+
+from langchain_core.messages import HumanMessage, SystemMessage
+from uipath_langchain.chat.models import UiPathAzureChatOpenAI
+from uipath_langchain.retrievers import ContextGroundingRetriever
+
+class GraphState(TypedDict):
+    question: str
+    snippets: list[str]
+    answer: str
+
+async def retrieve(state: GraphState) -> dict:
+    retriever = ContextGroundingRetriever(index_name="company_docs", folder_path="Shared")
+    documents = await retriever.ainvoke(state["question"])
+    return {"snippets": [doc.page_content for doc in documents]}
+
+async def answer(state: GraphState) -> dict:
+    context = "\n\n".join(state["snippets"])
+    llm = UiPathAzureChatOpenAI(temperature=0)
+    response = await llm.ainvoke([
+        SystemMessage(content="Answer only from the provided context."),
+        HumanMessage(content=f"Context:\n{context}\n\nQuestion: {state['question']}"),
+    ])
+    return {"answer": response.content}
+```
+
+Wire `retrieve → answer` as in § Building the Graph.
+
+---
+
 ## Tracing
 
 LangGraph agents get **automatic tracing** — you do NOT need `@traced()` on graph nodes. The UiPath LangGraph runtime instruments all node executions, LLM calls, and tool invocations automatically.
@@ -393,19 +441,3 @@ Both are valid — pick based on the agent's needs:
 See `../capabilities/conversational-agents.md` § Running Locally for the `--keep-state-file` flag (required on every turn) and § Wire Envelope for the `turn1.json` shape.
 
 ---
-
-## Available Tools
-
-The `uipath-langchain` package provides UiPath-specific LangChain tools:
-
-| Tool | Import | Purpose |
-|------|--------|---------|
-| Process invocation | `uipath_langchain.agent.tools import create_process_tool` | Trigger UiPath processes |
-| Escalation (HITL) | `uipath_langchain.agent.tools import create_escalation_tool` | Send to human reviewer |
-| Context search | `uipath_langchain.retrievers import ContextGroundingRetriever` | Search Context Grounding indexes |
-| MCP tools | `uipath_langchain.agent.tools import open_mcp_tools` | Connect to MCP servers |
-
-> **Context Grounding retrieval in LangGraph:** always use `ContextGroundingRetriever` from `uipath_langchain.retrievers` — not `sdk.context_grounding.search()` / `search_async()`. The LangChain retriever integrates natively with the graph pipeline and auto-generates the correct `index` binding. See [../capabilities/context-grounding.md](../capabilities/context-grounding.md) for usage examples.
-
----
-

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

@@ -4,7 +4,7 @@ A lightweight integration for running OpenAI Agents SDK agents on the UiPath pla
 
 > **Note:** This is a streamlined integration focused on agent execution and streaming. It does **not** support Human-in-the-Loop (HITL), state persistence/checkpointing, or UiPath process invocation from within agents. For workflows that need those features, use the [LangGraph](langgraph-integration.md) or [LlamaIndex](llamaindex-integration.md) integrations instead.
 
-> **STOP — input shape decides framework fit.** OpenAI Agents accept **only** a `messages` conversation input ([Input](#input) § CONSTRAINT). When the requested input is not a conversation, do NOT map it onto `messages` and proceed — STOP before scaffolding, tell the user, and let them choose another framework (e.g. [LangGraph](langgraph-integration.md)).
+> **STOP — input shape decides framework fit.** The OpenAI Agents SDK runner accepts **only** a `messages` conversation input ([Input](#input) § CONSTRAINT) — an SDK constraint, not a UiPath one; UiPath merely surfaces it as the required `messages` field in the generated schema. When the requested input is not a conversation, do NOT map it onto `messages` and proceed — STOP before scaffolding, tell the user, and let them choose another framework (e.g. [LangGraph](langgraph-integration.md)).
 
 ## Scaffolding a New Project
 

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

@@ -67,7 +67,17 @@ content/
 └── uv.lock
 ```
 
-Control file inclusion via `packOptions` in `uipath.json`:
+Control file inclusion and exclusion via `packOptions` in `uipath.json`:
+
+| Property | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `fileExtensionsIncluded` | `string[]` | No | `[".py", ".mermaid", ".json", ".yaml", ".yml", ".md"]` | File extensions to include in the package |
+| `filesIncluded` | `string[]` | No | `["pyproject.toml"]` | Specific files to always include |
+| `filesExcluded` | `string[]` | No | `[]` | Specific files to exclude |
+| `directoriesExcluded` | `string[]` | No | `[]` | Directories to exclude from packaging |
+| `includeUvLock` | `boolean` | No | `false` | Whether to include `uv.lock` file |
+
+**Example:**
 
 ```json
 {