@uipath/skills 1.195.0

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

@@ -0,0 +1,350 @@
+# Integration Service Tool
+
+Walkthrough for adding a tool that calls an Integration Service connector activity (e.g., Slack Send Message, Web Search, Jira Create Issue). Integration Service tools connect to external apps via pre-built connectors and authenticated connections.
+
+For Orchestrator process tools (RPA / agent / API / agentic process), see [../process/process.md](../process/process.md).
+
+## When to Use
+
+- Agent needs to call a third-party SaaS / API exposed via UiPath Integration Service (Slack, Salesforce, Jira, ServiceNow, Web Search, etc.)
+- A connection (authenticated link to the target system) already exists or can be created in IS
+
+## Key Difference from Orchestrator Tools
+
+IS tools use **connection** resources (not package/process resources) at the solution level. You only need to create the agent-level `resource.json` — solution-level files are auto-generated by `uip solution resource refresh`.
+
+IS tools differ structurally from Orchestrator-based tools:
+- `type` is `"integration"` (not `"process"`, `"agent"`, etc.)
+- `location` is `"external"`
+- `properties` contains IS-specific fields: `toolPath`, `objectName`, `connection`, `parameters`, `bodyStructure`
+- Additional top-level fields: `iconUrl`, `isPreview`
+- No `referenceKey` or `argumentProperties`
+- Solution-level resources use `connection/` (not `package/` + `process/`)
+- **Connection bindings are exempt from `folderPath` propagation** — they are bound by `connection.id`.
+
+## Agent-Level Resource Shape
+
+**Path:** `<AGENT_NAME>/resources/<ToolName>/resource.json`
+
+```jsonc
+{
+  "$resourceType": "tool",
+  "id": "<uuid>",
+  "type": "integration",
+  "location": "external",
+  "name": "<DisplayName from activity>",
+  "description": "<full Description from activity — do not truncate>",
+  "isEnabled": true,
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "<fieldName>": {
+        "type": "<type from requestField>",
+        "title": "<displayName from requestField>",
+        "description": "<description from requestField>"
+      }
+    },
+    "additionalProperties": false,
+    "required": ["<required field names>"]
+  },
+  "outputSchema": {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "properties": {
+      "<scalarField>": {
+        "title": "<displayName from responseField>",
+        "type": "<type from responseField>",
+        "description": "<description from responseField>"
+      },
+      "results[*]": {                                   // ← literal key, keep the `[*]` suffix
+        "title": "<displayName>",
+        "type": "array",
+        "items": { "$ref": "#/definitions/results[*]" } // ← same literal `[*]` in $ref
+      }
+    },
+    "definitions": {
+      "results[*]": {                                   // ← matches the $ref literally
+        "type": "object",
+        "properties": {
+          "<nestedField>": {
+            "title": "<displayName>",
+            "type": "<type>",
+            "description": "<description>"
+          }
+        }
+      }
+    }
+  },
+  "iconUrl": "<connector image URL — see rules below>",
+  "settings": {},
+  "guardrail": { "policies": [] },     // Must always be present and empty — required for backward-compatible solution loading
+  "isPreview": false,
+  "properties": {
+    "toolPath": "<path from metadata, e.g. /v2/webSearch>",
+    "objectName": "<ObjectName from activity, e.g. v2::webSearch>",
+    "toolDisplayName": "<DisplayName>",
+    "toolDescription": "<full Description from activity — same text as top-level description>",
+    "method": "<method from metadata, e.g. POST>",
+    "bodyStructure": { "contentType": "json" },
+    "connection": {
+      "id": "<connection-id from uip is connections list>",
+      "name": "<connection name>",
+      "elementInstanceId": 0,
+      "apiBaseUri": "",
+      "state": "enabled",
+      "isDefault": false,                    // ← always false on the tool's connection block
+      "connector": {
+        "key": "<connector-key>",
+        "name": "<connector display name>",
+        "image": "<same URL as top-level iconUrl>",
+        "enabled": true,
+        "isPreview": false
+      },
+      "folder": {
+        "key": "<FolderKey from connection>",
+        "path": "<same value as folder.key — NOT empty>"
+      },
+      "solutionProperties": {
+        "resourceKey": "<connection-id>"
+      }
+    },
+    "parameters": [
+      {
+        "name": "<field name>",
+        "displayName": "<field displayName>",
+        "type": "<field type>",
+        "fieldLocation": "body",
+        "value": "{{prompt}}",
+        "description": "<field description>",
+        "position": "primary",
+        "sortOrder": 1,
+        "required": true,
+        "fieldVariant": "dynamic",
+        "isCascading": false,
+        "dynamic": true,
+        "enumValues": null,
+        "loadReferenceOptionsByDefault": null,
+        "dynamicBehavior": [],
+        "reference": null
+      }
+    ]
+  }
+}
+```
+
+### Building `inputSchema` from `requestFields`
+
+- Each request field becomes a property with its `type` and `description`
+- Fields with `enum` → add `enum` and `oneOf` arrays
+- Fields with nested dotted names (e.g., `attachment.title`) → nest as objects in the schema
+- Fields marked `required: true` → add to the `required` array
+- Add `"additionalProperties": false` to the input schema
+
+### Building `outputSchema` from `responseFields`
+
+- Scalar response fields become properties with their `type` and `description` — preserve the metadata description, don't drop it.
+- Fields with `[*]` in the name (e.g., `results[*].title`) become a property keyed **literally** `"results[*]"` (keep the `[*]` in the key) with `type: "array"` and `items: { "$ref": "#/definitions/results[*]" }`. Add a matching `definitions` entry keyed with the same literal `"results[*]"`. Do NOT rename to `results`, `resultItem`, or camelCase — Studio Web matches the literal metadata key and will drop the tool if it's renamed.
+- Add `"$schema": "http://json-schema.org/draft-07/schema#"` to the output schema
+
+**IMPORTANT rules for `outputSchema` (arrays of objects):**
+- Response fields in the metadata named like `results[*].title` indicate an array of objects. Represent this as:
+  - A property keyed **literally** `"results[*]"` (keep the `[*]` suffix in the JSON key) with `type: "array"` and `items: { "$ref": "#/definitions/results[*]" }`.
+  - A `definitions` entry keyed with the exact same literal `"results[*]"` whose `properties` contain the nested fields (`title`, `snippet`, `url`, ...).
+- Do NOT rename to `"results"` / `"resultItem"` / camelCase. Studio Web matches the literal key from the activity metadata — renaming causes the tool to be silently dropped from the agent UI.
+- Preserve each response field's `description` from the metadata (both scalar and nested). Do not drop it.
+
+### Building `properties.parameters` from `requestFields`
+
+- Each `requestField` becomes a parameter with `fieldLocation: "body"` and `value: "{{prompt}}"` (dynamic, filled by the LLM at runtime)
+- Each `parameter` from metadata (query/path params) keeps its original `fieldLocation` (e.g., `"query"`)
+- Fields with `enum` values: set `fieldVariant: "static"`, `dynamic: false`, `value` to the first enum value, and `enumValues` to an **array of `{name, value}` objects** (NOT bare strings) — copy the metadata's `fields.<name>.enum` through verbatim. Bare-string arrays pass `uip agent validate` but make Studio Web drop the tool from the agent UI.
+- Fields with `reference`: include the `reference` object and set `loadReferenceOptionsByDefault: true`
+- Set `position: "primary"` for required fields, `"secondary"` for optional
+- Increment `sortOrder` starting from 1
+
+**Parameter `fieldVariant` values:**
+- `"dynamic"` — value filled by the LLM at runtime (`value: "{{prompt}}"`, `dynamic: true`, `enumValues: null`)
+- `"static"` — pre-configured value (e.g., single-value enum default). Set `dynamic: false`, `value` to the chosen enum value, and `enumValues` to the object-array form below.
+
+**Parameter `enumValues` format — MUST be an array of `{name, value}` objects, never bare strings:**
+```jsonc
+"enumValues": [
+  { "name": "GoogleCustomSearch", "value": "GoogleCustomSearch" }
+]
+```
+The activity metadata's `fields.<name>.enum` already has this exact shape — copy it through verbatim. A bare-string array like `["GoogleCustomSearch"]` passes `uip agent validate` but makes Studio Web silently drop the tool from the agent UI.
+
+**Parameter `fieldLocation` values:**
+- `"body"` — sent in request body (most `requestFields`)
+- `"query"` — sent as query parameter (from metadata `parameters` with `type: "query"`)
+- `"path"` — sent as path parameter
+
+**Parameter `toolDescription` and top-level `description`:** both must be the full description from the activity metadata. Do not abbreviate either.
+
+### `iconUrl` and `connector.image` rules
+
+- Both fields MUST be populated with the same URL in the tenant-scoped form: `{UIPATH_URL}/{organizationName}/{tenantName}/elements_/v3/element/elements/{connectorKey}/image`.
+- Build it directly from the auth env vars (`UIPATH_URL`, `UIPATH_ORGANIZATION_NAME`, `UIPATH_TENANT_NAME`). No discovery call is needed — the tenant route resolves the scale unit server-side.
+- Leaving `iconUrl` as `""` or omitting it does NOT produce a validation error, but Studio Web may silently drop the tool from the agent UI. Always populate it.
+
+### `properties.connection` rules
+
+- `connection.id` MUST be the actual IS connection ID (from `uip is connections list`). Studio Web validates tools by fetching the connection by this ID — a random UUID will cause "Connection is required" errors.
+- `connection.folder.key` AND `connection.folder.path` MUST both be populated. `path` is the folder key string (same value as `key`) — never the empty string.
+- `connection.isDefault` MUST be `false` on the tool's connection block, even if the connection is marked default in `uip is connections list`. The flag here is tool-scoped, not IS-scoped.
+- `solutionProperties.resourceKey` MUST equal `connection.id`. This links the tool to the solution connection resource.
+- All tools sharing the same connector MUST share the same `solutionProperties.resourceKey`.
+
+## Solution-Level Files
+
+**Auto-generated.** Do not create them manually. After creating the agent-level `resource.json`:
+
+1. Run `uip agent validate` — read-only check.
+2. Run `uip agent migrate` — generates `bindings_v2.json` in the agent project directory.
+3. Run `uip solution resource refresh` from the solution root — auto-generates `resources/solution_folder/connection/{connectorKey}/` files and `debug_overwrites.json`.
+
+**`location` and `folderPath`:**
+
+| `location` | `folderPath` | Meaning |
+|------------|-------------|---------|
+| `"solution"` | `"solution_folder"` | Resource is another project within this same solution. Creating this agent-level resource.json is sufficient. |
+| `"external"` | `"solution_folder"` | Resource is already deployed in Orchestrator, outside this solution. Write the agent-level resource.json, then run `uip agent validate` → `uip agent migrate` → `uip solution resource refresh` — refresh auto-generates the solution-level process declaration, package declaration, and `debug_overwrites.json` entry. |
+
+### Connection Definition (refresh fallback)
+
+**Path:** `resources/solution_folder/connection/{connectorKey}/{connectionName}.json`
+
+Provisions an Integration Service connection as part of the solution. Required when an agent has an integration tool (`type: "integration"`). One per connector — all tools using the same connector share this connection resource.
+
+**Auto-generated:** Do not create these files manually. After creating the agent-level integration tool `resource.json`, run `uip agent validate` (read-only check), `uip agent migrate` (generates `bindings_v2.json`), then `uip solution resource refresh` (auto-generates connection resources and `debug_overwrites.json` from `bindings_v2.json`).
+
+**Cross-reference:** The connection resource `key` matches the `solutionProperties.resourceKey` in integration tool resources that use this connector.
+
+```jsonc
+{
+  "docVersion": "1.0.0",
+  "resource": {
+    "name": "my-connection",           // Connection identifier
+    "kind": "connection",
+    "type": "uipath-salesforce-slack", // Connector key from IS
+    "apiVersion": "integrationservice.uipath.com/v1",
+    "isOverridable": true,
+    "spec": {
+      "connectorName": "Slack",
+      "authenticationType": "AuthenticateAfterDeployment",  // credentials provided post-deploy
+      "connectorVersion": "2.13.8",
+      "connectorKey": "uipath-salesforce-slack",
+      "pollingInterval": 5
+    },
+    "key": "<unique-uuid>"
+  }
+}
+```
+
+`authenticationType: "AuthenticateAfterDeployment"` means the connection credentials are provided by the user after deployment (not bundled in the solution).
+
+## Walkthrough
+
+### Step 1 — Scaffold solution and agent (if not already done)
+
+Scaffold per [../../project-lifecycle.md § End-to-End Example](../../project-lifecycle.md#end-to-end-example--new-standalone-agent).
+
+### Step 2 — Find the connector
+
+```bash
+uip is connectors list --output json
+# Or filter: uip is connectors list --filter "slack" --output json
+```
+
+Note the connector `Key` (e.g., `uipath-salesforce-slack`).
+
+### Step 3 — Find a connection
+
+```bash
+uip is connections list "<connector-key>" --output json
+```
+
+Present connections to the user. Recommend the default enabled one but let the user confirm. Note the connection `Id`, `FolderKey`, `Name`. If no connection exists, prompt the user to create one via `uip is connections create "<connector-key>"`.
+
+This command also populates the local cache at `~/.uipath/cache/integrationservice/<connector-key>/connections.json` — used later by `uip solution resource refresh` to generate `debug_overwrites.json`. Running it is mandatory even when you already found the connection via `uip solution resource list --kind Connection`, because refresh reads from the cache this command writes.
+
+### Step 4 — Discover activities
+
+```bash
+uip is activities list "<connector-key>" --output json
+```
+
+Present activities to the user. Note the chosen activity's `DisplayName`, `Description`, `ObjectName`, `MethodName`.
+
+### Step 5 — Get connector details (for iconUrl)
+
+```bash
+uip is connectors get "<connector-key>" --output json
+```
+
+Note the connector `Name` and image URL.
+
+### Step 6 — Get activity metadata
+
+```bash
+uip is resources describe "<connector-key>" "<object-name>" \
+  --connection-id "<connection-id>" --operation Create --output json
+```
+
+The response includes a `metadataFile` path. Read that cached JSON file to get:
+- `requestFields` → build `inputSchema` and `properties.parameters` (body fields)
+- `responseFields` → build `outputSchema`
+- `parameters` → query/path parameters (add to `properties.parameters`)
+- `path` → `properties.toolPath`
+- `method` → `properties.method`
+- `description` → tool description
+
+If no `--connection-id` is available (e.g., the connector auto-provisions connections), omit it — static metadata will be returned. To verify a connection's health beforehand, run `uip is connections ping "<connection-id>" --output json`.
+
+### Step 7 — Build and write the tool resource.json
+
+**File:** `<AGENT_NAME>/resources/<ToolName>/resource.json`
+
+Build the `resource.json` from the metadata. See § Agent-Level Resource Shape above for the full template and field mapping.
+
+### Step 8 — Validate, migrate, and refresh solution resources
+
+```bash
+# Validate — read-only check.
+uip agent validate "<AGENT_NAME>" --output json
+
+# Migrate — generates bindings_v2.json in the agent project directory
+# and regenerates .agent-builder/.
+uip agent migrate "<AGENT_NAME>" --output json
+
+# Refresh solution resources — auto-generates solution-level connection
+# resources and debug_overwrites from bindings_v2.json
+uip solution resource refresh --output json
+```
+
+At this point, the solution can be uploaded to Studio Web and tested:
+
+```bash
+uip solution bundle . -d ./dist --output json
+uip solution upload ./dist/<SOLUTION_NAME>.uis --output json
+```
+
+## Gotchas
+
+See [../../critical-rules.md](../../critical-rules.md):
+- Critical Rules 11, 12 (folderPath / location)
+- Anti-pattern 13 (do NOT pass `--for-low-code-agents` — flag removed)
+
+IS-specific gotchas (each from a real Studio-Web silent-drop bug):
+- `enumValues` MUST be `[{name, value}]` objects, not bare strings.
+- `outputSchema` array properties keyed `"results[*]"` literally — renaming to `results` drops the tool.
+- `iconUrl` and `connector.image` MUST both be set to the tenant-scoped URL `{UIPATH_URL}/{org}/{tenant}/elements_/v3/element/elements/{connectorKey}/image`.
+- `connection.folder.path` MUST equal `connection.folder.key` (never empty).
+- `connection.isDefault` MUST be `false` even if the IS connection is default.
+- `solutionProperties.resourceKey` MUST equal `connection.id` and is shared by all tools using the same connector.
+
+## References
+
+- [../../agent-definition.md](../../agent-definition.md) § Resources Convention
+- [../../solution-resources.md](../../solution-resources.md) § Refresh Mechanics
+- [../../project-lifecycle.md](../../project-lifecycle.md) § Resource Discovery

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

@@ -0,0 +1,186 @@
+# Agent Memory Spaces
+
+Use this when a low-code agent needs an attached UiPath memory space for dynamic few-shot retrieval or seeded memory items.
+
+## Critical Rules
+
+1. **Use `uip agent memory` for memory features.** Do not hand-author `features/{Name}/feature.json` unless recovering from a broken project. The CLI updates both the feature file and `.agent-builder/agent.json`.
+2. **`uip agent memory add` attaches an existing memory space; it does not create the platform memory space.** Always attempt `uip solution resource list --kind MemorySpace` discovery before attaching, even when the user supplied an exact memory space name and folder. Treat provided values as search inputs and fallback values only if discovery is blocked by auth or connectivity.
+3. **Use folder paths, not folder keys.** `--folder-path` must be the literal folder path where the memory space exists, such as `Shared` or `Shared/Sales`.
+4. **Validate, migrate, and refresh after memory changes.** Memory bindings are generated during `uip agent migrate`; do not edit `bindings_v2.json` directly. In a solution, always attempt `uip solution resource refresh --output json` from the solution root after migration so the generated `memorySpace` binding is imported into solution resources.
+5. **Seed only non-sensitive examples.** Memory items become agent project configuration. Do not store secrets, credentials, or raw PII as seed items.
+
+## Workflow
+
+### 1. Discover the memory space
+
+Always attempt discovery first, even when the user already provided the memory space name and folder. Use the provided name as the search term:
+
+```bash
+uip solution resource list --source remote --kind MemorySpace --search "<MEMORY_SPACE_NAME>" --output json
+```
+
+Use the row's `Name` as `--memory-space` and `Folder` as `--folder-path`. If discovery fails because the local session is not authenticated or the network is unavailable, continue only when the user already provided both the memory space name and folder path; use those provided values and report that discovery was attempted.
+
+If the space is external to the solution and should be tracked as a solution resource:
+
+```bash
+uip solution resource add \
+  --source remote \
+  --kind MemorySpace \
+  --name "<MEMORY_SPACE_NAME>" \
+  --folder-path "<FOLDER_PATH>" \
+  --output json
+```
+
+If no memory space exists, stop and ask the user to create or provide one. Do not invent a memory space name and continue silently.
+
+### 2. Attach the memory space to the agent
+
+```bash
+uip agent memory add SupportRecall \
+  --memory-space "<MEMORY_SPACE_NAME>" \
+  --folder-path "<FOLDER_PATH>" \
+  --threshold 0.25 \
+  --result-count 5 \
+  --search-mode hybrid \
+  --field userQuestion=1 \
+  --path "<AGENT_PROJECT_DIR>" \
+  --output json
+```
+
+`SupportRecall` is the feature name inside the agent. Choose a short PascalCase or kebab-free name that describes how the agent will use the memory.
+
+Options:
+
+| Option | Meaning |
+|---|---|
+| `--memory-space` | Tenant memory space name to attach |
+| `--folder-path` | Folder path containing the memory space |
+| `--reference-key` | Optional solution resource key, if already known |
+| `--description` | Human-readable feature description |
+| `--threshold` | Retrieval score threshold; default `0` |
+| `--result-count` | Number of memory results; default `3` |
+| `--search-mode` | `hybrid` or `semantic`; default `hybrid` |
+| `--field name=weight` | Input field weighting; repeat for multiple fields |
+| `--disable-dynamic-few-shot` | Attach the memory space without runtime retrieval |
+| `--path` | Agent project directory; default `.` |
+
+### 3. Seed optional memory items
+
+Add items only when the user explicitly wants seed examples or defaults in the agent project.
+
+```bash
+uip agent memory item add SupportRecall customer-tier gold \
+  --memory-type episodic \
+  --feedback-id "<FEEDBACK_ID>" \
+  --metadata '{"source":"seed"}' \
+  --path "<AGENT_PROJECT_DIR>" \
+  --output json
+```
+
+Valid memory item types are:
+
+| Value | Numeric | Use |
+|---|---:|---|
+| `episodic` | `0` | General recall examples |
+| `escalation` | `1` | Escalation-related memory |
+
+Episodic memory items require `--feedback-id`; use the feedback ID for the conversation, trace, or support example the seed item came from. `--metadata` must be a JSON object, not an array or scalar. Adding an item with an existing key updates that item.
+
+### 4. Verify
+
+```bash
+uip agent memory list --path "<AGENT_PROJECT_DIR>" --output json
+uip agent memory item list SupportRecall --path "<AGENT_PROJECT_DIR>" --output json
+uip agent validate "<AGENT_PROJECT_DIR>" --output json
+uip agent migrate "<AGENT_PROJECT_DIR>" --output json
+uip solution resource refresh --output json
+```
+
+After migration, inspect `<AGENT_PROJECT_DIR>/bindings_v2.json` only to verify that a `memorySpace` binding exists. Do not edit it. Run `uip solution resource refresh` from the solution root so the solution resource catalogue sees the memory binding. Do not skip refresh because the memory space name/folder were provided, because `bindings_v2.json` looks correct, or because publish/deploy is out of scope. If refresh fails due authentication, leave the generated files intact and report the failed refresh command.
+
+## Remove
+
+Remove a feature by feature name or ID:
+
+```bash
+uip agent memory remove SupportRecall --path "<AGENT_PROJECT_DIR>" --output json
+```
+
+Remove by memory space name only when you also pass the folder path:
+
+```bash
+uip agent memory remove "<MEMORY_SPACE_NAME>" \
+  --folder-path "<FOLDER_PATH>" \
+  --path "<AGENT_PROJECT_DIR>" \
+  --output json
+```
+
+Remove a seed item by key or ID:
+
+```bash
+uip agent memory item remove SupportRecall customer-tier \
+  --path "<AGENT_PROJECT_DIR>" \
+  --output json
+```
+
+## Generated Shape
+
+The CLI writes a feature file at:
+
+```text
+<AGENT_PROJECT_DIR>/features/SupportRecall/feature.json
+```
+
+Expected shape, for review only:
+
+```json
+{
+  "$featureType": "memorySpace",
+  "id": "<uuid>",
+  "referenceKey": null,
+  "folderPath": "Shared",
+  "name": "SupportRecall",
+  "memorySpaceName": "support-memory",
+  "description": null,
+  "isEnabled": true,
+  "dynamicFewShotSettings": {
+    "isEnabled": true,
+    "threshold": 0.25,
+    "resultCount": 5,
+    "searchMode": "hybrid",
+    "fieldSettings": [
+      {
+        "id": "<uuid>",
+        "name": "userQuestion",
+        "weight": 1
+      }
+    ]
+  },
+  "items": [
+    {
+      "id": "<uuid>",
+      "key": "customer-tier",
+      "value": "gold",
+      "memoryType": 0,
+      "feedbackId": "<feedback-id>",
+      "description": null,
+      "metadata": {
+        "source": "seed"
+      }
+    }
+  ]
+}
+```
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `required option '--memory-type <type>'` | `item add` always requires a memory type | Add `--memory-type episodic` or `--memory-type escalation` |
+| `required option '--feedback-id <feedbackId>'` | Episodic `item add` requires a source feedback ID | Pass `--feedback-id "<FEEDBACK_ID>"` with `--memory-type episodic` |
+| `Invalid memory-type value` | Unsupported type | Use `episodic`, `escalation`, `0`, or `1` |
+| `Invalid metadata JSON` | Metadata is malformed or not an object | Pass a valid JSON object, e.g. `'{"source":"seed"}'` |
+| `Memory space "<name>" matches by memory space name` | More than one feature references the same memory space name | Pass `--folder-path`, use the feature name, or use the feature ID |
+| No `memorySpace` binding after migration | Migrate was not run after the memory edit | Run `uip agent migrate "<AGENT_PROJECT_DIR>" --output json` |