@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-agents/references/coded/capabilities/integration-service.md

@@ -34,7 +34,7 @@ Then, as needed:
 Coded-specific layers:
 
 1. **Reuse before discover** — grep cwd for existing `ActivityMetadata` constants before re-running describe.
-2. **Present concrete options, then echo every pick.** At each stop point call `AskUserQuestion` with the actual candidates as selectable options (one per candidate: short label + one-line description, per the option-label format in the `uipath-platform` skill's `connectors.md`). Recommend the safest default; let the user choose. Never ask open-ended — derive options from the discovery output. After the pick, echo the chosen option back before the next call. Ambiguous answer or "other" → follow up to narrow; do not infer.
+2. **Present concrete options, then echo every pick.** At each stop point ask the user, presenting the actual candidates as concrete options (one per candidate: short label + one-line description, per the option-label format in the `uipath-platform` skill's `connectors.md`). Recommend the safest default; let the user choose. Never ask open-ended — derive options from the discovery output. After the pick, echo the chosen option back before the next step. Ambiguous answer or "other" → follow up to narrow; do not infer.
    - **Stop points:** connector (multi-hit on `connectors list --filter`), curated-vs-raw object, ambiguous operation verb (`Update` vs `Replace`), parent-field `-f` values, custom-field-by-name with >1 candidate.
    - Silent inference produces wrong-connector / wrong-form / wrong-customfield writes.
 
@@ -139,10 +139,10 @@ from uipath.platform.connections import ActivityMetadata, ActivityParameterLocat
 
 def post_to_slack(channel: str, message: str) -> dict:
     sdk = UiPath()
-    # Binding key, NOT a UUID. Locally this 400s unless resourceOverwrites
-    # is set — see § Local runtime binding. Do NOT add a try/except or a
-    # state health-check around it; gate any deployed-only probe on env.
-    connection = sdk.connections.retrieve("slack-triage")
+    # The connection id (the `Id` from `uip is connections list`) — the same
+    # value as bindings.json `ConnectionId.defaultValue`. Let it raise; don't
+    # wrap in try/except.
+    connection = sdk.connections.retrieve("<connection_id>")
     return sdk.connections.invoke_activity(
         activity_metadata=SLACK_SEND_MESSAGE,
         connection_id=connection.id,
@@ -151,7 +151,7 @@ def post_to_slack(channel: str, message: str) -> dict:
 ```
 
 - **`activity_input` is the single bucket** for query, path, header, multipart, and body values. SDK routes by `parameter_location_info`. No `query=`/`path=`/`header=` kwarg exists.
-- **`invoke_activity` calls `retrieve()` internally** (`_connections_service.py:675`), so `connection_id` can be a UUID or a binding-key string — the `@resource_override` decorator on `retrieve` resolves it. The pattern above (explicit retrieve, then pass `connection.id`) is preferred because it gives the agent a typed `Connection` for `metadata()` / `retrieve_token()`; one-shots can use `invoke_activity(connection_id="slack-triage", ...)` directly.
+- **`invoke_activity` calls `retrieve()` internally** (`_connections_service.py:675`). The pattern above (explicit retrieve, then pass `connection.id`) is preferred because it gives the agent a typed `Connection` for `metadata()` / `retrieve_token()`; one-shots can pass the connection id straight to `invoke_activity(connection_id="<connection_id>", ...)`.
 - **Return value** is `response.json()` — keys mirror `responseFields[].name`. Flat connectors return top-level; some wrap in `Data` / `result`. Auto-traced via `@traced`; see [tracing.md](tracing.md).
 - **Silent drops** — `None` values and any key not in `parameter_location_info` are skipped (`_connections_service.py:753-770`). Mistyped keys never surface as errors; echo-check writes per Error Handling § "Silent rename / typo".
 
@@ -198,7 +198,7 @@ Wrap `invoke_activity_async` in the framework's tool primitive — runtime body
 
 ## Connection Resolution — `bindings.json`
 
-Invocation URL is `/elements_/v3/element/instances/<UUID>/…`, so the SDK ultimately needs a UUID. To let admins rebind per environment, write code against a binding key string; `@resource_override("connection", resource_identifier="key")` (`_connections_service.py:51`) on `retrieve` maps it to the deployed UUID. `uip codedagent init` writes `resources: []` — author the connection entry after picking the connection.
+Write the connection's id (the `Id` from `uip is connections list`, a GUID) as the `retrieve()` argument in code AND as `ConnectionId.defaultValue` in `bindings.json` — the two must match. That way it resolves locally (no override) and `bindings.json` lets users rebind the resource per environment when deployed. `uip codedagent init` writes `resources: []` — author the connection entry after picking the connection.
 
 Minimal connection entry (`uip codedagent init` writes `resources: []`; add this). The entry-type field is **`resource`** (NOT `type`) — the CLI bindings schema is `{ resource, key, value, metadata }`:
 
@@ -220,42 +220,28 @@ Full JSON schema lives in [`../lifecycle/bindings-reference.md`](../lifecycle/bi
 
 - Entry type field is `resource` (`"resource": "connection"`), never `type` — matches every other binding entry.
 - `key` is just `<CONNECTION_KEY>` (no `<NAME>.<FOLDER>` dot suffix used by other resources). Same string passed positionally to `retrieve()`.
-- `value.ConnectionId.defaultValue` is the binding key string, NOT a UUID. Capital-C `ConnectionId` (other resources use `name`); no `folderPath`.
+- `value.ConnectionId.defaultValue` is the connection id — the same value passed to `retrieve()` in code (and the binding `key`). Capital-C `ConnectionId` (other resources use `name`); no `folderPath`.
 - `metadata.UseConnectionService: "True"` is mandatory; `Connector: ""` (empty); `BindingsVersion: "2.2"` is the per-resource rev and is independent of the top-level envelope `version: "2.0"`.
 - `uip codedagent deploy` repackages as `content/bindings_v2.json` — never hand-author that path.
 
-### Required artifact — `__uipath/uipath.json` (local-run binding)
+### Connection value: code and bindings must match
 
-Every coded IS agent MUST write `__uipath/uipath.json`. It is the file `uipath run` reads for connection overwrites: `cli_run.py` → `read_resource_overwrites_from_file(ctx.runtime_dir)`, `runtime_dir` defaults to `__uipath` (`runtime/context.py`), config name `uipath.json` (`UIPATH_CONFIG_FILE`). Without it, local `retrieve("<KEY>")` 400s with `CNS1026 The value '<KEY>' is not valid` — `bindings.json` is deploy-time only (packed into `content/bindings_v2.json`) and ignored by local run. This is distinct from `./uipath.json` (pack/deploy config). Write both:
+Write the **same connection id** in code and in `bindings.json`:
 
-```jsonc
-{
-  "functions": { "main": "main.py:main" },
-  "runtime": {
-    "internalArguments": {
-      "resourceOverwrites": {
-        "connection.slack-triage": {
-          "connectionId": "<Id from `uip is connections list`>",
-          "folderKey":    "<FolderKey from `uip is connections list`>"
-        }
-      }
-    }
-  }
-}
-```
+- In code, pass it to `retrieve()` — `sdk.connections.retrieve("<connection_id>")`.
+- In `bindings.json`, use it as the connection's `ConnectionId.defaultValue` (and the binding `key`).
 
-`ConnectionResourceOverwrite` (`uipath/platform/common/_bindings.py:100`, **NOT** `uipath/_utils/_bindings.py`) requires exactly two fields — `connectionId` (alias accepts `ConnectionId`) and `folderKey` — and has `extra="ignore"`, so `elementInstanceId` and any other extras are silently dropped (see anti-pattern #1). Key format is `connection.<BINDING_KEY>` matching the `bindings.json` `key`. After override, `Connection.element_instance_id` (for `sdk.connections.metadata()` calls) comes from the live IS API response — never write it locally.
+Because they match, the agent resolves the connection both **locally** (run uses the code value directly, no override) and **when deployed** (`bindings.json` lets Studio Web / Orchestrator override the resource per environment). Get the connection id from the `Id` field of `uip is connections list --output json` (a GUID).
 
-**Required outputs — every coded IS agent ships all four:**
+`Connection.element_instance_id` (needed for `sdk.connections.metadata()` calls) comes from the live IS API response after `retrieve()` — never hardcode it.
+
+**Required outputs — every coded IS agent ships these three:**
 
 | File | Read by | Must contain |
 |---|---|---|
-| `main.py` | runtime | lazy `UiPath()` (not module-scope), inline `ActivityMetadata` literal, `retrieve(<KEY>)` + `invoke_activity` |
-| `bindings.json` | `uip codedagent deploy` | connection resource, `key`, `ConnectionId.defaultValue`=binding key, `UseConnectionService: "True"` |
+| `main.py` | runtime | lazy `UiPath()` (not module-scope), inline `ActivityMetadata` literal, `retrieve("<connection_id>")` + `invoke_activity` |
+| `bindings.json` | `uip codedagent deploy` | connection resource, `key` + `ConnectionId.defaultValue` = the same connection id, `UseConnectionService: "True"` |
 | `uipath.json` | `uip` pack/deploy | `functions`, `packOptions` |
-| `__uipath/uipath.json` | `uipath run` (local) | `runtime.internalArguments.resourceOverwrites["connection.<KEY>"]` = `connectionId` + `folderKey` |
-
-Omitting `__uipath/uipath.json` means the agent cannot run locally — incomplete, not optional. Personal-workspace connections also need `UIPATH_FOLDER_KEY=<KEY>` (`FolderKey` from `uip is connections list`) in the environment at local run.
 
 ## Error Handling
 
@@ -274,7 +260,7 @@ Network / 5xx are retried with exponential backoff by `BaseService.request`; onl
 
 These six are the ones the SDK / IS / vendor will NOT tell you about. Positive guidance for everything else lives in the relevant section above; do not pad this list.
 
-1. **Adding `elementInstanceId` to `resourceOverwrites`.** `ConnectionResourceOverwrite` (`_bindings.py:100`) defines only `connectionId` + `folderKey` with `extra="ignore"` — extras are silently dropped. The `element_instance_id` you need for `sdk.connections.metadata()` comes from the live `Connection.element_instance_id` after `retrieve()`, never from local config.
+1. **Hardcoding `element_instance_id`.** The `element_instance_id` needed for `sdk.connections.metadata()` comes from the live `Connection.element_instance_id` after `retrieve()` — never hardcode it.
 2. **Hand-authoring `object_path` / `method_name` / `body_fields`.** Curated activities rename fields silently between connector versions. Always source from `uip is resources describe` and re-run after upgrades. Sidecar-JSON literals also drift — keep `ActivityMetadata` literals inline in a `.py` file; `pack` bundles them and mypy / pyright catch shape errors at edit time.
 3. **Typos and unknown keys in `activity_input`.** Anything not in `parameter_location_info` is silently dropped (`_connections_service.py:753-770`); the request goes out missing the field, vendor returns 2xx, the data is just gone. Echo-check writes by reading back the created object (see Error Handling § "Silent rename / typo").
 4. **`invoke_activity` for trigger payloads.** IS-triggered jobs receive `EventArguments` as input — unwrap with `sdk.connections.retrieve_event_payload(event_args)` (`_connections_service.py:421`). Calling `invoke_activity` to "receive" anything is a category error.

package/skills/uipath-agents/references/coded/lifecycle/bindings-reference.md

@@ -51,11 +51,12 @@ Bindable resource types:
 | `.context_grounding.*` (all methods: `retrieve`, `search`, `add_to_index`, `create_index`, etc.) | `(name="name", folder_path="folder")` | `index` | `name` or `index_name` |
 | `.connections.retrieve` / `.retrieve_async` | `("connection_key")` | `connection` | `key` (positional) |
 | `.mcp.retrieve` / `.retrieve_async` | `(slug="slug", folder_path="folder")` | `mcpServer` | `slug` |
+| `EscalateAction(...)` (guardrail HITL action) | `(app_name="name", app_folder_path="folder", recipient=...)` | `app` | `app_name` |
 | `interrupt(InvokeProcess(...))` (LangGraph HITL) | `(name="name", process_folder_path="folder", input_arguments={...})` | `process` | `name` |
 | `interrupt(CreateTask(...))` (LangGraph HITL) | `(app_name="name", app_folder_path="folder", title="...", data={...})` | `app` | `app_name` |
 | `interrupt(CreateEscalation(...))` (LangGraph HITL) | `(app_name="name", app_folder_path="folder", title="...", data={...})` | `app` | `app_name` |
 
-> **Interrupt-based patterns also produce bindings.** LangGraph agents pause and delegate work via `interrupt(InvokeProcess|CreateTask|CreateEscalation(...))` imported from `uipath.platform.common`. These produce the **same binding entries** as their `sdk.processes.invoke` / `sdk.tasks.create` counterparts — same `resource` type, same key format, same `ActivityName`. Scan for the class names (`InvokeProcess`, `CreateTask`, `CreateEscalation`) in addition to the `sdk.*` method calls. Note: `InvokeProcess` uses `process_folder_path` (not `folder_path`).
+> **Guardrail and interrupt-based patterns also produce bindings.** Guardrail HITL escalation uses `EscalateAction(app_name=..., app_folder_path=...)`; LangGraph agents pause and delegate work via `interrupt(InvokeProcess|CreateTask|CreateEscalation(...))` imported from `uipath.platform.common`. These produce the **same binding entries** as their `sdk.processes.invoke` / `sdk.tasks.create` counterparts — same `resource` type, same key format, same `ActivityName`. Scan for the class/action names (`EscalateAction`, `InvokeProcess`, `CreateTask`, `CreateEscalation`) in addition to the `sdk.*` method calls. Note: `InvokeProcess` uses `process_folder_path` (not `folder_path`).
 
 Use Grep to find calls matching these patterns across all project Python files. Then read the surrounding code to extract the literal string values for resource name and folder path.
 
@@ -65,7 +66,7 @@ Use Grep to find calls matching these patterns across all project Python files.
 
 First check the project's pinned `uipath` version (see **SubType Metadata → Version-detection rule**). If `uipath < 2.10.58`, **skip SubType entirely** — emit no `SubType` for any binding, including `retrieve_credential*`.
 
-If `uipath >= 2.10.58`, then for `retrieve_credential` / `retrieve_credential_async` calls always emit `"SubType": "credentialAsset"` — the method name is definitive. For all other calls, follow the full lookup procedure in the **SubType Metadata** section below: fetch metadata → filter by kind → disambiguate from code → fall back to `AskUserQuestion` → omit `SubType` if the user skips. Omitting `SubType` is always safe — `uipath push` still creates a virtual placeholder for supported kinds, just with the base `kind` only.
+If `uipath >= 2.10.58`, then for `retrieve_credential` / `retrieve_credential_async` calls always emit `"SubType": "credentialAsset"` — the method name is definitive. For all other calls, follow the full lookup procedure in the **SubType Metadata** section below: fetch metadata → filter by kind → disambiguate from code → ask the user → omit `SubType` if the user skips or can't be asked. Omitting `SubType` is always safe — `uip codedagent push` still creates a virtual placeholder for supported kinds, just with the base `kind` only.
 
 ### Step 3: Compare with Existing Bindings
 
@@ -89,7 +90,7 @@ Each resource can optionally be linked to an entrypoint from `entry-points.json`
 
 **Workflow:**
 1. **Single entrypoint** — If `entry-points.json` contains exactly one entrypoint, automatically bind all resources to it. Add `EntryPointUniqueId` (preferred) or `EntryPointPath` (fallback). No need to ask the user.
-2. **Multiple entrypoints** — Call `AskUserQuestion` once with all detected resources and the entrypoint choices. Exact phrasing:
+2. **Multiple entrypoints** — Ask the user once, presenting all detected resources and the entrypoint choices. Suggested phrasing:
 
    > Which entrypoint should each of these resources be bound to? Choose one per resource, or `None` to leave it unbound.
    > Resources: `<list: name + type>`
@@ -114,7 +115,7 @@ For the exact JSON structure of each resource type, see § bindings.json Referen
 - Each resource entry has `resource`, `key`, `value`, and `metadata` fields
 - The `key` is `<name>.<folder_path>` for most types, just `<connection_key>` for connections. When `folder_path` is empty, omit the dot separator — the key is just `<name>`
 - `ActivityName` in metadata always uses the `_async` variant name
-- Connection entries use a `ConnectionId` field in their binding `value` (other resource types use `name`) and have no `folderPath`. The `ConnectionId`'s `defaultValue` is the connection key — the same string passed as the positional argument to `sdk.connections.retrieve()` / `retrieve_async()`.
+- Connection entries use a `ConnectionId` field in their binding `value` (other resource types use `name`) and have no `folderPath`. The `ConnectionId`'s `defaultValue` is the connection's **id**.
 - The `app` resource type uses the app name as `DisplayLabel`; all others use `"FullName"`
 - `SubType` is an optional metadata field — see the **SubType Metadata** section for the full lookup procedure and the `retrieve_credential*` shortcut.
 - Entrypoint fields (`EntryPointUniqueId`, `EntryPointPath`) are optional in any resource's `value` block, but when present must include a `displayName` set to the entrypoint's `filePath` from `entry-points.json`
@@ -149,8 +150,8 @@ After writing the updated `bindings.json`:
 | Duplicate key in resources array | Same resource scanned from multiple code paths | Deduplicate — keep one entry per unique key |
 | Missing project root | No `pyproject.toml` or `uipath.json` found | Verify the working directory is a UiPath agent project |
 | Stale entries after refactor | Old resource calls removed but bindings.json not updated | Run the full sync workflow to detect and remove orphaned entries |
-| Push creates wrong asset type as virtual resource | Missing `SubType` in metadata for a `retrieve_credential*` call | Add `"SubType": "credentialAsset"` to the asset's metadata and re-run `uipath push` |
-| Push warns "was not found" for connection/mcpServer/index | These kinds do not support virtual-resource fallback | Create the resource in Orchestrator / Integration Service before running `uipath push` |
+| Push creates wrong asset type as virtual resource | Missing `SubType` in metadata for a `retrieve_credential*` call | Add `"SubType": "credentialAsset"` to the asset's metadata and re-run `uip codedagent push` |
+| Push warns "was not found" for connection/mcpServer/index | These kinds do not support virtual-resource fallback | Create the resource in Orchestrator / Integration Service before running `uip codedagent push` |
 
 ## Additional Instructions
 
@@ -253,7 +254,7 @@ When the SDK call is `retrieve_credential` or `retrieve_credential_async`, add `
 }
 ```
 
-This SubType is required for `uipath push` to create a credential-asset placeholder (rather than a plain string asset) when the asset doesn't yet exist in Orchestrator.
+This SubType is required for `uip codedagent push` to create a credential-asset placeholder (rather than a plain string asset) when the asset doesn't yet exist in Orchestrator.
 
 ---
 
@@ -456,7 +457,27 @@ task = sdk.tasks.create(title="...", data={...}, app_name="app_name", app_folder
 - `app_name` — keyword argument `app_name=`
 - `app_folder_path` — keyword argument `app_folder_path=`
 
-**Note:** The `DisplayLabel` in metadata uses the literal app name value, not `"FullName"`. Both Action Center tasks and escalations use this resource type — `CreateEscalation` extends `CreateTask` with the same `app_name`/`app_folder_path` fields.
+**Note:** The `DisplayLabel` in metadata uses the literal app name value, not `"FullName"`. Action Center tasks, manual escalations, and guardrail `EscalateAction` use this resource type — `CreateEscalation` extends `CreateTask` with the same `app_name`/`app_folder_path` fields, and `EscalateAction` references the same deployed Action App.
+
+**Guardrail-action variant — `EscalateAction(...)`:**
+
+Guardrail HITL escalation references an Action Center app directly from the guardrail action:
+
+```python
+from uipath_langchain.guardrails import EscalateAction
+
+action = EscalateAction(
+    app_name="Guardrail.Escalation.Action.App",
+    app_folder_path="Shared",
+    recipient=recipient,
+)
+```
+
+Binding entry is **identical** to `sdk.tasks.create` — same `resource: "app"`, same `key` (`<app_name>.<app_folder_path>`), same `ActivityName: "create_async"`, same `DisplayLabel: <app_name>`.
+
+**Parameter extraction:**
+- `app_name` — keyword argument `app_name=` to `EscalateAction(...)`
+- `app_folder_path` — keyword argument `app_folder_path=`
 
 **Interrupt-based variant — `interrupt(CreateTask(...))` / `interrupt(CreateEscalation(...))`:**
 
@@ -569,7 +590,7 @@ connection = sdk.connections.retrieve("connection_key")
 **Key construction:** Just `<connection_key>` (no folder path, no dot).
 
 **Parameter extraction:**
-- `connection_key` — first positional argument to `retrieve_async()` / `retrieve()`
+- The connection id is the first positional argument to `retrieve_async()` / `retrieve()`, and the same value is used as the binding `key` and `ConnectionId.defaultValue` — all three match.
 
 **Differences from other resource types:**
 - No `folderPath` in `value`
@@ -625,15 +646,15 @@ server = sdk.mcp.retrieve(slug="mcp_server_slug", folder_path="folder_path")
 
 ## SubType Metadata
 
-The `SubType` field in a resource's `metadata` block specifies a sub-classification of the resource `kind`. It is **optional** but should be emitted when determinable, so `uipath push` can create the correct virtual-resource placeholder when the resource isn't found in the catalog (see `Virtual Resource Fallback on uipath push` below).
+The `SubType` field in a resource's `metadata` block specifies a sub-classification of the resource `kind`. It is **optional** but should be emitted when determinable, so `uip codedagent push` can create the correct virtual-resource placeholder when the resource isn't found in the catalog (see `Virtual Resource Fallback on uip codedagent push` below).
 
-> **Minimum `uipath` version: 2.10.58 ([PyPI](https://pypi.org/project/uipath/)).** Below that version, **omit `SubType` entirely** — older `uipath push` releases ignore the field, so emitting it gives no benefit and just adds noise to `bindings.json`.
+> **Minimum `uipath` version: 2.10.58 ([PyPI](https://pypi.org/project/uipath/)).** Below that version, **omit `SubType` entirely** — older `uip codedagent push` releases ignore the field, so emitting it gives no benefit and just adds noise to `bindings.json`.
 >
 > **Version-detection rule (run before the lookup procedure):**
 >
 > 1. Read the project's `pyproject.toml` (or `requirements.txt` / `uv.lock`) and extract the resolved `uipath` version.
 > 2. If the version is **`>= 2.10.58`**, follow the full lookup procedure.
-> 3. If the version is **`< 2.10.58`** (or unspecified / unresolvable), **ask the user** before falling back. Do **not** run the upgrade command yourself. Call `AskUserQuestion` with the warning prefix and two options:
+> 3. If the version is **`< 2.10.58`** (or unspecified / unresolvable), **ask the user** before falling back. Do **not** run the upgrade command yourself. Ask with the warning prefix and two options:
 >
 >    - **Question:** `⚠️ uipath is pinned to <version>. SubType support requires uipath >= 2.10.58 — without it every binding will be written with no SubType. Do you want to upgrade?`
 >    - **Option A — Yes, upgrade `uipath`** — print the upgrade command for the user to run themselves and stop the workflow. Tell them to re-run the bindings task after the upgrade lands. Suggested commands (do **not** execute them):
@@ -642,7 +663,7 @@ The `SubType` field in a resource's `metadata` block specifies a sub-classificat
 >      # Poetry: poetry add 'uipath@^2.10.58'
 >      # pip:    pip install --upgrade 'uipath>=2.10.58'
 >      ```
->    - **Option B — No, continue with current version** — skip the entire SubType lookup, do **not** call `AskUserQuestion` for sub-types, and write every binding with no `SubType` in `metadata` (including `retrieve_credential*`). Tell the user once: *"`uipath` is pinned to `<version>`; SubType emission is disabled."*
+>    - **Option B — No, continue with current version** — skip the entire SubType lookup, do **not** ask about sub-types, and write every binding with no `SubType` in `metadata` (including `retrieve_credential*`). Tell the user once: *"`uipath` is pinned to `<version>`; SubType emission is disabled."*
 
 ### Authoritative source for valid SubType values
 
@@ -701,10 +722,7 @@ For each binding, follow these steps:
 4. **Choose a SubType:**
    - **No candidates** (all entries lack `type`) → omit `SubType`.
    - **One candidate** → emit it as `SubType`.
-   - **Multiple candidates** → try code-based disambiguation first (see rules below). If no rule matches, ask the user. Use the path that fits the candidate count:
-     - **≤ 3 candidates** → call `AskUserQuestion` with each candidate as an `option` (`label` = the `type` string). `AskUserQuestion`'s `options` array is capped at 4 entries, and one slot is reserved for the trailing `skip`. The harness presents a picker UI and returns the chosen `label` directly — no numbered list needed in the prompt body.
-     - **≥ 4 candidates** → emit a plain-text **numbered list** (one per line, `N. <type>`) ending with a final numbered `skip` line. The user replies with just the number; map it back to the `type` string. Do not use `AskUserQuestion` here — the list won't fit.
-     Either way, include the resource name and folder in the prompt for context. If the user picks `skip` (or its number), omit `SubType`.
+   - **Multiple candidates** → try code-based disambiguation first (see rules below). If no rule matches, ask the user — present each candidate `type` as a concrete option plus a `skip` option. Include the resource name and folder for context. If the user picks `skip` or cannot be asked (non-interactive), omit `SubType`.
 
    **Numbered-list rules** (plain-text path only):
    - One candidate per line, prefixed with `N. ` (1-indexed).
@@ -728,7 +746,7 @@ curl -s -H "Authorization: Bearer <TOKEN>" \
 
 ### Known code-based disambiguation rules
 
-Apply these rules in order. Only fall through to the `AskUserQuestion` prompt if none of them produces a confident match.
+Apply these rules in order. Only fall through to asking the user if none of them produces a confident match.
 
 | Kind | Rule | SubType | Confidence |
 |------|------|---------|------------|
@@ -747,7 +765,7 @@ Apply these rules in order. Only fall through to the `AskUserQuestion` prompt if
    - Used in arithmetic, compared numerically → `integerAsset`.
    - Used in `if x:` as a truth check where Orchestrator stores it as boolean → `booleanAsset`.
 4. Check the variable name and surrounding context against sensitive patterns (`password`, `pwd`, `api_key`, `secret`, `token`, `credential`). If a match is found, prompt the user to choose between `credentialAsset` and `secretAsset` (they differ in how Orchestrator exposes the value).
-5. If the heuristic is inconclusive or produces only medium confidence, fall through to the `AskUserQuestion` prompt with the heuristic's best guess pre-highlighted.
+5. If the heuristic is inconclusive or produces only medium confidence, fall through to asking the user with the heuristic's best guess pre-highlighted.
 
 ### Asking the user (example prompts)
 
@@ -821,9 +839,23 @@ Always include a final `skip` option — it means "I don't know, emit no SubType
 
 ---
 
-## Virtual Resource Fallback on uipath push
+## What `uip codedagent push` does with bindings
+
+`uip codedagent push` uploads the source files, then (unless `--ignore-resources`) resolves every `bindings.json` entry against the Resource Catalog. It searches by the binding's identity: most kinds by **`name` + `folderPath`** (both must match an existing resource in that folder — a wrong/missing `folderPath` causes a miss), `connection` by its **`ConnectionId`** (the connection id) — a value that doesn't match a real connection is a common miss.
+
+Each binding: **found** → imported as a reference; **not found, virtual-capable kind** → placeholder created, project still deploys; **not found, non-virtual kind** (`connection`, `mcpServer`, `index`) → warned and **skipped entirely**.
+
+> ⚠️ **A "was not found" warning is NEVER "expected".** For a non-virtual kind the binding is dropped from the deployed project. The agent may still run (it can resolve to in-code defaults), but the resource is **not overridable from Studio Web** — so the solution cannot be cleanly promoted/deployed to another tenant. Treat every "not found" as a defect to resolve before reporting push successful.
+
+### When push reports a resource was not found
+
+1. **Diagnose the miss** — the binding's identity matched no catalog resource. Check: wrong `folderPath` (resource exists in another folder), wrong `name`/`ConnectionId` (typo or stale value), or resource genuinely doesn't exist.
+2. **Resolve, then re-push** — fix the binding's `name`/`folderPath`/`ConnectionId`, or have the user create the missing resource, then re-run `uip codedagent push` and confirm the warning is gone.
+3. **If unresolvable, state it plainly** — e.g. *"Code uploaded, but connection `<key>` was not imported (no IS connection with that key/folder; connections cannot be auto-created), so it cannot be overridden in Studio Web."* Do not report push as done.
+
+## Virtual Resource Fallback on uip codedagent push
 
-Starting with `uipath` 2.10.52, `uipath push` creates a virtual resource placeholder when a binding's resource isn't found in the Resource Catalog — the project can be deployed before its dependencies exist. The fallback only works for a subset of kinds.
+Starting with `uipath` 2.10.52, `uip codedagent push` creates a virtual resource placeholder when a binding's resource isn't found in the Resource Catalog — the project can be deployed before its dependencies exist. The fallback only works for a subset of kinds.
 
 The push command fetches the supported-kinds list from `/studio_/backend/api/resourcebuilder/metadata` at push time. The static fallback (used when that endpoint is unreachable) is `app, asset, bucket, process, queue, taskCatalog, trigger`.
 
@@ -836,7 +868,7 @@ The push command fetches the supported-kinds list from `/studio_/backend/api/res
 ### Implications for binding generation
 
 1. **Emit `SubType` only when `uipath >= 2.10.58`.** Below that version, omit `SubType` from every binding — see **SubType Metadata → Version-detection rule**. When the version gate is met, always emit `"SubType": "credentialAsset"` for `retrieve_credential*` asset calls; without it the virtual-resource fallback creates a plain string asset placeholder, causing runtime failures when the agent expects a credential.
-2. **Warn the user about non-fallback kinds.** For `connection`, `mcpServer`, and `index` bindings, the referenced resource must exist in Orchestrator before `uipath push`. If it doesn't, the binding is skipped with a warning and the agent will fail at runtime. Flag this to the user when generating such bindings.
+2. **Warn the user about non-fallback kinds.** For `connection`, `mcpServer`, and `index` bindings, the referenced resource must exist in Orchestrator before `uip codedagent push`. If it doesn't, the binding is skipped with a warning and the agent will fail at runtime. Flag this to the user when generating such bindings.
 3. **Optional `SubType` for bucket.** The bucket's backing storage is not inferable from code. Consider asking the user which storage type their buckets use, so virtual-resource fallback creates the correct kind.
 
 ---

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

@@ -45,6 +45,7 @@ Load capability references **only if the task requires them** — do not preload
 
 ## Additional Instructions
 
+- **File/document input → `Attachment`, never a filesystem path string.** If the prompt says the agent "takes a CSV/PDF/file as input" (or similar), read `../capabilities/file-attachments.md` before defining the `Input` model. A `str` path field runs locally with `uip codedagent run` but breaks on Studio Web/Orchestrator, where no such path exists in the container.
 - **Select a framework before writing any code.** Infer from the prompt if possible (tools/orchestration → LangGraph, RAG → LlamaIndex, simple LLM → OpenAI Agents, no LLM → Coded Function). If ambiguous, ask the user to choose.
 - **Structured input contract → not OpenAI Agents.** OpenAI Agents always require a `messages` input field and cannot express an input contract without it (see `../frameworks/openai-agents-integration.md` § Input). When the user needs a strict typed/structured input (e.g. a single named field, no `messages`), choose LangGraph (custom `StateGraph` with arbitrary input state) instead. Do NOT silently fall back to a Coded Function to satisfy the input shape — a Coded Function produces `ProjectType: Function`, not a coded agent, so it does not fulfill a request for an agent.
 - **Read ONLY the single framework reference** for the selected framework before writing code. Do NOT read other framework references or capability references unless the task explicitly requires that capability.

package/skills/uipath-agents/references/coded/lifecycle/evaluations/evaluation-sets.md

@@ -126,7 +126,7 @@ evaluations/eval-sets/
 ```json
 "mockingStrategy": {
   "type": "mockito",
-  "behaviors": [
+  "config": [
     {
       "function": "external_api_call",
       "arguments": {
@@ -144,6 +144,10 @@ evaluations/eval-sets/
 }
 ```
 
+- Behaviors key is `config` (SDK alias; `behaviors` also accepted).
+- `function` matches the `@mockable`-decorated function's `__name__` (bare name, not qualified). Decorate the target in `main.py` with `@mockable` for the mock to bind.
+- `arguments` optional — omit to match any call.
+
 **Mock Behavior Types:**
 - `type: "return"` - Return a value
 - `type: "raise"` - Throw an exception

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

@@ -44,6 +44,8 @@ uip codedagent init
 
 `uipath-dev` is added to the dev dependency group during scaffold so `uip codedagent dev` works later without a second install pass. Skipping it causes `uip codedagent dev` to fail with *"The 'uipath-dev' package is required to use the dev command"*.
 
+**What `uip codedagent setup` does:** locates a Python that has `uipath` installed and caches its path, so later commands (`init`/`run`/`eval`/`pack`) can invoke the Python SDK. It searches PATH (`python3.x`, `python3`, `python`) and uses your `.venv` only when activated. So when using uv, always `uv sync` then activate the venv before the `setup` command.
+
 ## Coded Function Agents
 
 `uipath.json` carries the entrypoint mapping:
@@ -92,7 +94,7 @@ Edit the scaffolded `main.py`'s `Input` / `Output` models and `async def main` t
 ```
 
 **Key fields:**
-- **`runtimeOptions.isConversational`** - Set `true` for conversational/chat agents
+- **`runtimeOptions.isConversational`** - scaffold defaults to `false` (single-shot). Building a chat/conversational agent? Flip to `true` BEFORE `uip codedagent init` so `entry-points.json` gets the chat shape. See [conversational-agents](../capabilities/conversational-agents.md).
 - **`packOptions`** - Control which files are included when packaging for deployment
 - **`functions`** - Entrypoint mappings (format: `"file_path:function_name"`)
 

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

@@ -78,7 +78,7 @@ When the user asks to create and deploy an agent end-to-end, follow these steps
 
 **IMPORTANT: Do NOT stop between steps to ask "would you like me to continue?" or list next steps. Execute the entire flow automatically.** Pause only when (a) you hit an **architectural fork** — a step with multiple valid implementations (framework choice, HITL pattern, evaluator type, deploy target, conversational vs not, etc.) — or (b) you need data only the user has (credentials, project ID). At a fork, apply **infer-or-ask**: if the prompt or context names the choice, infer it and continue; otherwise output ONLY the choice question as your entire response, then STOP and wait. For missing data, output ONLY the data request. After getting the answer, resume immediately. Forks for each step are documented in that step's referenced file — read the reference when you reach the step; do not guess.
 
-Steps 8 and 9 are mandatory stops **for greenfield**: always ask, even if the user only said "build". Use `AskUserQuestion` (or platform equivalent); fall back to plain text only when no UI tool exists. They are **automatically resolved** for `local-workspace` (auto-sync) and for `existing-coded` with `has_project_id == true` (push) — see steps 8 and 9 for the branch logic.
+Steps 8 and 9 are mandatory stops **for greenfield**: always ask the user, even if the user only said "build". They are **automatically resolved** for `local-workspace` (auto-sync) and for `existing-coded` with `has_project_id == true` (push) — see steps 8 and 9 for the branch logic.
 
 1. **Framework** — **Skip if `framework != none`** (already chosen — verify the right `<framework>.json` is present and continue). Else select per the [Framework Selection](#framework-selection) section below.
 2. **Setup** — Idempotent by `project_state` and `has_venv`:
@@ -165,7 +165,7 @@ Then STOP and wait. On reply, run the matching one-shot login from [../authentic
    **Finally**, run `uip codedagent eval <ENTRYPOINT> evaluations/eval-sets/smoke-test.json --no-report` (use the entrypoint name from `entry-points.json`).
 8. **Delivery target.** Single branch point. **Evaluate branches in order — Local Workspace projects also have `UIPATH_PROJECT_ID` set in `.env`, so the `local-workspace` check MUST come before the `has_project_id` check, or Local Workspace will incorrectly fall into the push branch:**
 
-   - **(1) `project_state == local-workspace`** → Studio Web auto-syncs saves to the remote SW project, so options A and B (manual push / solution upload) are skipped — they would be redundant or break sync identity. The user may still want a local dev console. Stop and ask via `AskUserQuestion` (header `"Delivery"`, `multiSelect: false`):
+   - **(1) `project_state == local-workspace`** → Studio Web auto-syncs saves to the remote SW project, so options A and B (manual push / solution upload) are skipped — they would be redundant or break sync identity. The user may still want a local dev console. Stop and ask the user (single choice, "Delivery"):
 
      **Question:** *Studio Web is auto-syncing this workspace. Do you want a local dev console too?*
 
@@ -180,7 +180,7 @@ Then STOP and wait. On reply, run the matching one-shot login from [../authentic
 
      Do **not** run `uip codedagent push` for this branch (that's recovery only — see [lifecycle/local-workspace.md](lifecycle/local-workspace.md) § Studio-Web-Auto-Sync). Do **not** present options A or B.
    - **(2) `has_project_id == true` (cloud workspace, project ID already set)** → Run `uip codedagent push` to upload local edits, then continue to step 9. No fork question — the delivery choice was made in a prior session.
-   - **(3) Else (greenfield / cloud workspace not yet wired)** → Stop and ask via `AskUserQuestion` (header `"Delivery"`, `multiSelect: false`).
+   - **(3) Else (greenfield / cloud workspace not yet wired)** → Stop and ask the user (single choice, "Delivery").
 
      **Question:** *How do you want to use the agent next?*
 
@@ -206,7 +206,7 @@ Then STOP and wait. On reply, run the matching one-shot login from [../authentic
      - **C** → run `uip codedagent dev` in the background; surface the URL (default `http://localhost:8080`). Prereq: `uipath-dev` (added during scaffold). **STOP — do NOT proceed to step 9.** Local dev is a terminal choice.
      - **Skip** → continue to step 9.
 
-9. **Deploy.** Reachable from any `project_state` after option **Skip** at step 8 (greenfield or local-workspace), after the auto-push in branch (2), or after options **A** / **B** in greenfield. After option **C** at step 8, the run ends — do not ask. Stop and ask via `AskUserQuestion` (header `"Deploy target"`, `multiSelect: false`).
+9. **Deploy.** Reachable from any `project_state` after option **Skip** at step 8 (greenfield or local-workspace), after the auto-push in branch (2), or after options **A** / **B** in greenfield. After option **C** at step 8, the run ends — do not ask. Stop and ask the user (single choice, "Deploy target").
 
    **Question:** *Do you want to deploy the agent? If yes, which target?*
 
@@ -313,14 +313,15 @@ Execute the following in order, end-to-end, in one pass — do not pause for con
 
 ## Framework Selection
 
-Infer the framework from the user's prompt when possible. If ambiguous, ask them to choose:
+> **First — is this an agent at all?** If the task is deterministic logic with no LLM reasoning (validate data, call an API with custom auth, transform records, upload/download files), it's a **Python Coded Function** — not an agent. Use the [`uipath-functions`](/uipath:uipath-functions) skill instead of this one. Coded Functions use typed I/O (`@dataclass`, Pydantic `BaseModel`, or a thin Python class with typed annotations) and a `functions` map in `uipath.json`; what distinguishes an agent is LLM reasoning and a framework graph.
 
-1. **Coded Function** — Plain Python with `Input`/`Output` models. No LLM. Best for deterministic logic.
-2. **LangGraph** — StateGraph with conditional routing, tool use, interrupts. Best for complex LLM agents.
-3. **LlamaIndex** — Workflow with events and RAG support. Best for knowledge retrieval.
-4. **OpenAI Agents** — Lightweight agent with tools and handoffs. Best for simple LLM agents; lacks HITL, process invocation, and state persistence.
+If the task needs LLM reasoning, infer the framework from the user's prompt when possible. If ambiguous, ask them to choose:
 
-**Inference hints:** mentions of tools/tool calling, multi-step, or orchestration → LangGraph. RAG or knowledge retrieval → LlamaIndex. Simple handoffs or lightweight LLM → OpenAI Agents. No LLM needed → Coded Function. Summarize / research / synthesize over PDF or TXT (incl. bucket files, attachments) → not a framework choice — see [capabilities/deeprag/planning.md](capabilities/deeprag/planning.md). Per-row CSV extraction → see [capabilities/batch-transform/planning.md](capabilities/batch-transform/planning.md). When in doubt, ask.
+1. **LangGraph** (recommended — best integrated with the UiPath ecosystem) — StateGraph with conditional routing, tool use, interrupts. Best for complex LLM agents.
+2. **LlamaIndex** — Workflow with events and RAG support. Most complete LangGraph alternative.
+3. **OpenAI Agents** — Lightweight agent with tools and handoffs. Best for simple LLM agents; lacks HITL, process invocation, and state persistence.
+
+**Inference hints:** mentions of tools/tool calling, multi-step, or orchestration → LangGraph. Simple handoffs or lightweight LLM → OpenAI Agents. No LLM needed → not an agent — use [`uipath-functions`](/uipath:uipath-functions). Summarize / research / synthesize over PDF or TXT (incl. bucket files, attachments) → not a framework choice — see [capabilities/deeprag/planning.md](capabilities/deeprag/planning.md). Per-row CSV extraction → see [capabilities/batch-transform/planning.md](capabilities/batch-transform/planning.md). When in doubt, ask.
 
 **Always tell the user which framework you selected and why** before proceeding to build. Example: "I'll use **LangGraph** for this agent since it involves tool calling and multi-step orchestration."
 

package/skills/uipath-agents/references/coded-vs-lowcode-guide.md

@@ -19,6 +19,7 @@ Reference for comparing **coded** (Python) and **low-code** (agent.json) agents.
 | Full runtime control over LLM prompts | ❌ | ✅ |
 | Multi-model / multi-framework strategies | ❌ | ✅ |
 | Fastest path to first working agent | ✅ | ❌ |
+| Conversational (chat-style, multi-turn) use-cases | ✅ | currently not recommended for production, use low-code |
 | Embed inline in a flow project | ✅ | ❌ |
 | Embed as sibling project in same solution | ✅ | ✅ |
 | Invoke as published agent node in a flow | ✅ | ✅ |

package/skills/uipath-agents/references/context-grounding-patterns.md

@@ -27,7 +27,7 @@ Route by file type first, signal second:
 |---|---|---|---|
 | `.csv` | "add columns" / "classify every row" / "enrich vendor addresses" / "MCC categorization" / "1000 rows of structured output" | **BatchTransform** | Coded: [coded/capabilities/batch-transform/planning.md](coded/capabilities/batch-transform/planning.md). Low-code: [lowcode/capabilities/built-in-tools/batch-transform/planning.md](lowcode/capabilities/built-in-tools/batch-transform/planning.md). |
 | `.pdf` / `.txt` | "summarize" / "research across these docs" / "one narrative answer" | **DeepRAG** | Coded: [coded/capabilities/deeprag/planning.md](coded/capabilities/deeprag/planning.md). Low-code: [lowcode/capabilities/built-in-tools/deeprag/planning.md](lowcode/capabilities/built-in-tools/deeprag/planning.md). |
-| pre-built index, no file upload | "search the policy KB" / "look up X in our docs" | **Index search** | `sdk.context_grounding.unified_search_async` or low-code Context tool — see [coded/capabilities/context-grounding.md](coded/capabilities/context-grounding.md). |
+| pre-built index, no file upload | "search the policy KB" / "look up X in our docs" | **Index search** | Consume: `sdk.context_grounding.unified_search_async` or low-code Context tool — see [coded/capabilities/context-grounding.md](coded/capabilities/context-grounding.md). Create / ingest / inspect the index from the CLI: [uipath-platform/references/context-grounding/index-management.md](../../uipath-platform/references/context-grounding/index-management.md). |
 
 ## Surface Selection