@uipath/skills 1.195.0

package/skills/uipath-agents/references/lowcode/evaluations/orchestrator-eval-run.md

@@ -0,0 +1,210 @@
+# Orchestrator Package Offline Eval Run
+
+Submit offline evaluation runs for low-code agents published as Orchestrator packages.
+
+Use this when the agent has been published to Orchestrator (via `uip solution deploy` or Studio) and you want to trigger an eval run against the published package rather than using the Agent Runtime.
+
+## Command
+
+```bash
+uip or eval run-offline-evals \
+  --package-name <processKey> \
+  --package-version <version> \
+  [--eval-set-id <guid>] \
+  [--items <json>] \
+  [--evaluators <json>] \
+  [--is-low-code-agent] \
+  [--batch-size <n>] \
+  [--folder-key <folder-guid>] \
+  [--tenant <tenant-name>] \
+  --output json
+```
+
+The folder resolves from your personal workspace automatically. Pass `--folder-key` to target a specific folder instead.
+
+`--eval-set-id` defaults to `00000000-0000-0000-0000-000000000000` when `--items` and `--evaluators` are provided inline.
+
+## Options
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--package-name` | Yes | Orchestrator package name (processKey, e.g. `MyAutomation.Agent.agent`) |
+| `--package-version` | Yes | Package version (e.g. `1.0.2`) |
+| `--eval-set-id` | No | Eval set ID to run; mutually exclusive with `--items`/`--evaluators` |
+| `--items` | No | JSON array of eval items to override those from the package |
+| `--evaluators` | No | JSON array of evaluator configs to override those from the package |
+| `--is-low-code-agent` | No | Auto-transform items/evaluators from the raw package format (flat JSON with `type`/`category` fields) to the API wire format. Use this when pasting directly from the package or portal. |
+| `--batch-size` | No | Max concurrent evaluation pipelines (default: `5`) |
+| `--folder-key` | No | Folder key GUID; defaults to personal workspace. Use `uip or folders list` to find available keys. |
+| `--tenant` | No | UiPath tenant name |
+
+## Examples
+
+```bash
+# Minimal — items/evaluators loaded from the published package
+uip or eval run-offline-evals \
+  --package-name "MyAutomation.Agent.agent" \
+  --package-version "1.0.2" \
+  --eval-set-id "9e4b2f17-7c3a-4d81-b592-3f6e8a1d5c09" \
+  --output json
+
+# Inline override — paste evaluator and item JSON directly from the package/portal.
+# Use --is-low-code-agent to auto-transform: wraps evaluator as { evaluatorTypeId, evaluatorConfig }
+# and renames expectedAgentBehavior → expectedBehavior on items.
+# Replace "model" with the actual model ID used by the agent (not "same-as-agent").
+uip or eval run-offline-evals \
+  --package-name "MyAutomation.Agent.agent" \
+  --package-version "1.0.2" \
+  --is-low-code-agent \
+  --output json \
+  --evaluators '[{
+    "id": "8f3a1c72-bd4e-4f91-a832-9e5d2b7c04f6",
+    "name": "Default Evaluator",
+    "type": 5,
+    "category": 1,
+    "prompt": "As an expert evaluator, analyze the semantic similarity...",
+    "model": "anthropic.claude-3-5-sonnet-20240620-v1:0",
+    "targetOutputKey": "*",
+    "createdAt": "2026-05-31T19:36:35.382Z",
+    "updatedAt": "2026-05-31T19:36:35.382Z"
+  }]' \
+  --items '[{
+    "id": "7b2e9f48-c3a1-4d85-b6f2-1e8c5a9d3b70",
+    "name": "Test Case 1",
+    "inputs": {},
+    "expectedOutput": { "content": "The current date is 2026-05-31." },
+    "expectedAgentBehavior": ""
+  }]'
+
+# Explicit folder key instead of personal workspace
+uip or eval run-offline-evals \
+  --package-name "MyAutomation.Agent.agent" \
+  --package-version "1.0.2" \
+  --eval-set-id "9e4b2f17-7c3a-4d81-b592-3f6e8a1d5c09" \
+  --folder-key "a9f3b2c1-7d4e-4a8b-9c2f-5e1d3b6a8f7e" \
+  --output json
+```
+
+## Output
+
+```json
+{
+  "Result": "Success",
+  "Code": "EvalRunSubmitted",
+  "Data": {
+    "Package": "MyAutomation.Agent.agent v1.0.2",
+    "Folder": "user@uipath.com's workspace",
+    "EvalSetId": "9e4b2f17-7c3a-4d81-b592-3f6e8a1d5c09",
+    "EvalSetRunId": "f3a7d219-8b4c-4e62-a951-7d3f6e2c8b04"
+  }
+}
+```
+
+Use the `EvalSetRunId` to track results in the UiPath portal.
+
+## Items and Evaluators Format
+
+### Without `--is-low-code-agent` (API wire format)
+
+Pass the data already in the format the API expects:
+
+**Evaluators** — each item must have `id`, `evaluatorTypeId` (string), and `evaluatorConfig`:
+
+```json
+[
+  {
+    "id": "8f3a1c72-bd4e-4f91-a832-9e5d2b7c04f6",
+    "version": "",
+    "evaluatorTypeId": "5",
+    "evaluatorConfig": {
+      "id": "8f3a1c72-bd4e-4f91-a832-9e5d2b7c04f6",
+      "name": "Default Evaluator",
+      "type": 5,
+      "category": 1,
+      "prompt": "As an expert evaluator...",
+      "model": "anthropic.claude-3-5-sonnet-20240620-v1:0",
+      "targetOutputKey": "*",
+      "createdAt": "2026-05-31T19:36:35.382Z",
+      "updatedAt": "2026-05-31T19:36:35.382Z"
+    }
+  }
+]
+```
+
+**Items** — each item must include `id`, `name`, `inputs`, and `expectedOutput`:
+
+```json
+[
+  {
+    "id": "7b2e9f48-c3a1-4d85-b6f2-1e8c5a9d3b70",
+    "name": "Test Case 1",
+    "inputs": {},
+    "expectedOutput": { "content": "Expected agent response here." },
+    "expectedBehavior": ""
+  }
+]
+```
+
+### With `--is-low-code-agent` (raw package format)
+
+Paste the evaluator JSON directly from the package file (flat, with `type` and `category` at the top level). The CLI will auto-transform to the wire format.
+
+> **Note:** Replace `"model": "same-as-agent"` with the actual model ID (e.g. `"anthropic.claude-3-5-sonnet-20240620-v1:0"`). The `same-as-agent` value requires loading `agent.json` from the package, which is not available in inline mode.
+
+```json
+[
+  {
+    "id": "8f3a1c72-bd4e-4f91-a832-9e5d2b7c04f6",
+    "name": "Default Evaluator",
+    "type": 5,
+    "category": 1,
+    "prompt": "As an expert evaluator...",
+    "model": "anthropic.claude-3-5-sonnet-20240620-v1:0",
+    "targetOutputKey": "*",
+    "createdAt": "2026-05-31T19:36:35.382Z",
+    "updatedAt": "2026-05-31T19:36:35.382Z"
+  }
+]
+```
+
+Items use `expectedAgentBehavior` (renamed to `expectedBehavior` automatically):
+
+```json
+[
+  {
+    "id": "7b2e9f48-c3a1-4d85-b6f2-1e8c5a9d3b70",
+    "name": "Test Case 1",
+    "inputs": {},
+    "expectedOutput": { "content": "Expected agent response here." },
+    "expectedAgentBehavior": ""
+  }
+]
+```
+
+## Troubleshooting
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `401 Unauthorized` | Auth expired or not configured | Run `uip login` |
+| `Authentication failed` | No active session | Run `uip login` first |
+| `Package not found` | Package not published or wrong name/version | Verify with `uip or packages list`; re-publish with `uip solution deploy` |
+| `Eval set not found` | Invalid `--eval-set-id` GUID | Verify the eval set exists in the portal; use `--items` and `--evaluators` inline instead |
+| `'same-as-agent' model option requires agent settings` | Inline evaluator has `"model": "same-as-agent"` — agent.json not available in inline mode | Replace with explicit model ID (e.g. `anthropic.claude-3-5-sonnet-20240620-v1:0`) |
+| `personal workspace not found` | Account has no personal workspace | Pass `--folder-key` explicitly |
+| `Folder not found` | `--folder-key` GUID invalid or inaccessible | Run `uip or folders list` to find valid keys |
+
+## Validation Rules
+
+The CLI enforces these rules before making any network calls:
+
+1. **Must provide `--eval-set-id` OR both `--items` and `--evaluators`.** Omitting all three is an error.
+2. **`--eval-set-id` and `--items`/`--evaluators` are mutually exclusive.** Providing both is an error.
+3. **`--items` and `--evaluators` must be provided together.** Providing one without the other is an error.
+4. **`--batch-size` must be a positive integer.** Non-numeric values are rejected with an error.
+
+## Anti-patterns
+
+- **Don't run against an unpublished package version.** The command targets the package already in Orchestrator. Bump `--package-version` after each publish; stale versions return results from old agent logic.
+- **Don't mix `--eval-set-id` with `--items`/`--evaluators`.** They are mutually exclusive. Use `--eval-set-id` to load from a saved eval set, or `--items`/`--evaluators` to provide inline. Not both.
+- **Don't pass `--items`/`--evaluators` in the wrong schema for your mode.** Field names differ: legacy format (from package/portal) uses `expectedAgentBehavior`; wire format uses `expectedBehavior`. Add `--is-low-code-agent` when pasting directly from the package or portal; omit it when you've already transformed to wire format.
+- **Don't pass `"model": "same-as-agent"` with inline `--evaluators`.** Inline mode has no access to `agent.json`; the CLI cannot resolve `same-as-agent` and will error at runtime.

package/skills/uipath-agents/references/lowcode/evaluations/running-evaluations.md

@@ -0,0 +1,207 @@
+# Running Evaluations
+
+Execute evaluations against the Agent Runtime, check status, view results, and compare runs.
+
+All run commands require the agent to be pushed to Studio Web first (`uip agent push`). The Agent Runtime executes test cases in the cloud using the pushed agent definition.
+
+## Start an Eval Run
+
+```bash
+uip agent eval run start --set "<eval_set_name>" --path <agent_dir> --wait --output json
+```
+
+**Options:**
+
+| Flag | Required | Description | Default |
+|------|----------|-------------|---------|
+| `--set <name>` | Yes | Eval set name or ID | — |
+| `--path <path>` | No | Agent project directory | `.` |
+| `--wait` | No | Block until the run completes, then print results | `false` |
+| `--timeout <seconds>` | No | Maximum time to block when `--wait` is set | `600` (10 min) |
+| `--solution-id <id>` | No | Override solution ID for this run | Auto-resolved from the pushed-agent state |
+
+Without `--wait`, the command returns immediately with `Code: AgentEvalRunStarted`:
+
+```json
+{
+  "Code": "AgentEvalRunStarted",
+  "Data": {
+    "EvalSetRunId": "a1b2c3d4-...",
+    "EvalSetName": "Default Evaluation Set",
+    "TestCases": 5,
+    "Evaluators": 2
+  }
+}
+```
+
+With `--wait`, the CLI polls every 5 seconds (hardcoded interval) until the run reaches a terminal state (`completed` or `failed`) or `--timeout` elapses, then emits `AgentEvalRunCompleted` plus per-test `AgentEvalRunResults`. If `--timeout` elapses first, the run continues server-side; query progress with `eval run status <run_id>`.
+
+### Output codes
+
+| Subcommand | `Code` |
+|------------|--------|
+| `run start` (no `--wait`) | `AgentEvalRunStarted` |
+| `run start --wait` (summary) | `AgentEvalRunCompleted` |
+| `run start --wait` (per-case detail) | `AgentEvalRunResults` |
+| `run status` | `AgentEvalRunStatus` |
+| `run results` | `AgentEvalRunResults` |
+| `run results --export-format` | `AgentEvalRunExported` |
+| `run list` | `AgentEvalRunList` |
+| `run compare` | `AgentEvalRunComparison` |
+
+## Check Run Status
+
+```bash
+uip agent eval run status <eval_set_run_id> --set "<eval_set_name>" --path <agent_dir> --output json
+```
+
+**Output:**
+```json
+{
+  "Code": "AgentEvalRunStatus",
+  "Data": {
+    "EvalSetRunId": "a1b2c3d4-...",
+    "Status": "completed",
+    "Score": 0.86,
+    "Duration": "42.5s",
+    "EvaluatorScores": "semantic: 0.9, trajectory: 0.82"
+  }
+}
+```
+
+Terminal states: `completed` or `failed`.
+
+## View Results
+
+```bash
+uip agent eval run results <eval_set_run_id> \
+  --set "<eval_set_name>" \
+  --path <agent_dir> \
+  --output json
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--only-failed` | Show only failed or errored test cases |
+| `--verbose` | Include evaluator justifications in output |
+| `--export-format <json\|csv>` | Export results to file (`eval-results-{timestamp}.json` or `.csv`) |
+
+**Per-test-case output fields:** `TestCase`, `Status`, `Score`, `EvaluatorScores`, `Tokens`, `Duration`, `Error` (plus `Justifications` when `--verbose`).
+
+### Filtering results with `--output-filter`
+
+`--output-filter` takes a JMESPath expression and applies it to the JSON payload before printing. Useful for triage:
+
+```bash
+# Print only test cases with a specific name
+uip agent eval run results <run_id> --set "Default Evaluation Set" --path ./my-agent \
+  --output json --output-filter 'Data.Results[?TestCase==`greeting-test`]'
+
+# Print only the score field for each test case
+uip agent eval run results <run_id> --set "Default Evaluation Set" --path ./my-agent \
+  --output json --output-filter 'Data.Results[*].{name: TestCase, score: Score}'
+```
+
+### Failure detection
+
+`--only-failed` filters to test cases where any of these are true (`isFailedRun()` in the CLI):
+
+1. `status === "failed"` (or numeric `"3"`)
+2. `errorMessage` is non-null
+3. `result.score.type === "error"` (or numeric `"2"`)
+4. Any `assertionRuns[*].result.score.type === "error"` (or numeric `"2"`)
+5. Any `assertionRuns[*].result.score.value === false` (exact-match evaluators that returned a false boolean)
+
+Status enum values from the SDK: `0 = pending`, `1 = running`, `2 = completed`, `3 = failed`. The CLI normalizes string and numeric forms.
+
+## List Past Runs
+
+```bash
+uip agent eval run list --set "<eval_set_name>" --path <agent_dir> --output json
+```
+
+**Per-row output:** `EvalSetRunId`, `Status`, `Score`, `TestCases`, `Duration`, `EvaluatorScores`, `CreatedAt`.
+
+## Compare Runs
+
+Compare two eval runs side by side to see score changes:
+
+```bash
+uip agent eval run compare <run_id_a> \
+  --compare-to <run_id_b> \
+  --set "<eval_set_name>" \
+  --path <agent_dir> \
+  --output json
+```
+
+**Output:**
+```json
+{
+  "Code": "AgentEvalRunComparison",
+  "Data": {
+    "RunA": { "Id": "...", "Score": 0.86, "Status": "completed" },
+    "RunB": { "Id": "...", "Score": 0.80, "Status": "completed" },
+    "ScoreDelta": 0.06,
+    "TestCases": [
+      {
+        "TestCase": "happy-path",
+        "ScoreA": 1.0,
+        "ScoreB": 0.9,
+        "Delta": "+0.1",
+        "StatusA": "completed",
+        "StatusB": "completed"
+      }
+    ]
+  }
+}
+```
+
+Use `compare` after prompt changes to verify improvements without regressions.
+
+## Workflow Example
+
+```bash
+# 1. Add test cases
+uip agent eval add greeting-test \
+  --set "Default Evaluation Set" \
+  --inputs '{"input":"hi there"}' \
+  --expected '{"content":"Hello! How can I help you?"}' \
+  --expected-agent-behavior "Agent should respond with a friendly greeting" \
+  --path ./my-agent --output json
+
+# 2. Validate (catches schema drift, missing evaluator refs, broken eval JSON)
+uip agent validate --path ./my-agent --output json
+
+# 3. Push agent to Studio Web (required before running evals)
+uip agent push --path ./my-agent --output json
+
+# 4. Run and wait
+uip agent eval run start \
+  --set "Default Evaluation Set" \
+  --path ./my-agent \
+  --wait --timeout 600 --output json
+
+# 5. Review failures
+uip agent eval run results <run_id> \
+  --set "Default Evaluation Set" \
+  --only-failed --verbose \
+  --path ./my-agent --output json
+
+# 6. Make changes, validate, push, re-run, compare
+uip agent validate --path ./my-agent --output json
+uip agent push --path ./my-agent --output json
+uip agent eval run start --set "Default Evaluation Set" --path ./my-agent --wait --output json
+uip agent eval run compare <new_run_id> --compare-to <old_run_id> \
+  --set "Default Evaluation Set" --path ./my-agent --output json
+```
+
+## Anti-patterns
+
+- **Don't run `eval run start` without `uip agent push` first.** The Agent Runtime executes against the pushed agent, not local files. Local edits made after the last push will not affect results.
+- **Don't assume `--timeout` cancels the server-side run.** It only stops the local CLI from blocking. The run continues and can be inspected with `run status`.
+- **Don't skip `uip agent validate` between edits and push.** Validate catches eval-set / evaluator drift that push will accept silently and the runtime will reject.
+- **Don't compare runs from different eval sets.** `compare` aligns by test case `name` within the eval set; cross-set deltas are meaningless.
+- **Don't rely on `Score` alone — inspect `EvaluatorScores`.** A 0.86 aggregate can mask a faithful-but-wrong agent (high semantic, low trajectory). Use `--verbose` to read justifications when scores look surprising.
+- **Don't mix score scales across evaluators in the same eval set.** Defaults written by `uip agent init` use 0–100 prompts; defaults written by `evaluator add` use 0–1 prompts. The runtime DTO normalizes to 0–100, but mixed-scale prompts produce confusing per-evaluator scores. Decide on one scale per eval set and edit prompts to match.

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

@@ -0,0 +1,101 @@
+# UiPath Low-Code Agent Authoring
+
+Entry point for low-code agent work. Read this first after low-code mode is detected.
+
+## When to Use
+
+- Create a new low-code agent project (standalone or inline in a flow)
+- Edit `agent.json` — prompts, model, schemas, settings
+- Add tools, contexts, or escalations as files in `resources/{Name}/resource.json`
+- Add memory spaces or seed memory items with `uip agent memory`
+- Wire agent-to-agent calls within a solution or to an external deployed agent
+- Design input/output schemas and sync with `entry-points.json`
+- Validate agent project structure
+- Publish agent to Studio Web, pack and deploy to Orchestrator
+
+## Critical Rules
+
+[critical-rules.md](critical-rules.md) is the canonical source for low-code agent rules and anti-patterns. Read it every session. The rules below are the operational must-knows; the rest live in the canonical file.
+
+1. **Edit JSON files directly, except CLI-managed memory features.** The CLI provides `init` (scaffold), `validate` (read-only check), `migrate` (apply writes + regenerate `.agent-builder/`), and `memory` (writes memory feature files). Resources live in `resources/{Name}/resource.json`; memory features live in `features/{Name}/feature.json`.
+2. **Use `--output json`** on every `uip` command.
+3. **Validate and migrate after every bulk of related edits**, not after each line. Run `uip agent validate --output json` to check, then `uip agent migrate --output json` to apply pending migrations and regenerate `.agent-builder/`.
+4. **Keep `agent.json` ↔ `entry-points.json` schemas in sync.** `inputSchema`/`outputSchema` must mirror `input`/`output` field-for-field.
+5. **Never edit `.agent-builder/` by hand.** It is generated by `uip agent migrate` and managed by Studio Web.
+6. **Do not publish or deploy without user consent.** Ask before `uip solution upload`, `publish`, or `deploy`.
+7. **Never invoke other skills automatically.** For Orchestrator setup, tell the user to use the `uipath-platform` skill; for flow wiring, tell them to use the `uipath-maestro-flow` skill.
+
+## Quick Start
+
+Standard workflow for any low-code agent task:
+
+1. **Scaffold** — `uip solution init` (if no solution exists), then `uip agent init "<AgentName>" --output json`. Full walkthrough in [project-lifecycle.md](project-lifecycle.md) § End-to-End Example.
+2. **Edit** — open `agent.json` and `entry-points.json`. Schema reference in [agent-definition.md](agent-definition.md). **Override the scaffold model** (`gpt-4o-2024-11-20`) per [model-selection-guide.md](model-selection-guide.md) and write robust prompts per [agent-prompting-guide.md](agent-prompting-guide.md) — the scaffold ships a stale model and toy prompts.
+3. **Add capabilities** — pick from the Capability Registry below. Most add `resources/{Name}/resource.json`; memory uses `uip agent memory` and writes `features/{Name}/feature.json`.
+4. **Validate** — `uip agent validate --output json`. Confirm `MigrationPending`, `Validated`. Read-only — never writes.
+5. **Migrate** — `uip agent migrate --output json`. Applies pending writes and regenerates `.agent-builder/`. Confirm `MigrationApplied`, `StorageVersion`.
+6. **Refresh solution resources** — `uip solution resource refresh --output json` if any capability needs solution-level files (external tools, IS tools, index contexts, memory spaces, escalations).
+7. **Bundle and upload** — `uip solution bundle` then `uip solution upload --output json` (with user consent per Rule 6).
+
+Capabilities are **orthogonal**: there is no ordering requirement among them. Adding a tool and an escalation in parallel is safe — they do not interact at the file level. Validate and refresh once after all capability edits are complete, not after each one.
+
+## Reference Navigation
+
+### Read on demand
+
+| Read when... | File |
+|---|---|
+| Scaffolding, validating, or running solution lifecycle commands | [project-lifecycle.md](project-lifecycle.md) |
+| Editing `agent.json` (prompts, schemas, model, contentTokens) or `entry-points.json` | [agent-definition.md](agent-definition.md) |
+| Choosing the LLM (`settings.model`) — discover tenant models, override the scaffold default | [model-selection-guide.md](model-selection-guide.md) |
+| Writing a robust system/user prompt — skeleton, tool-call criteria, output contract, production checklist | [agent-prompting-guide.md](agent-prompting-guide.md) |
+| External tools / IS tools / index contexts / memory spaces / escalations behave unexpectedly after `uip solution resource refresh` | [solution-resources.md](solution-resources.md) |
+| Running evaluations, adding test cases, managing evaluators | [evaluations/evaluate.md](evaluations/evaluate.md) |
+
+### Capability Registry
+
+| I need to... | Read first | Then |
+|--------------|------------|------|
+| Understand agent.json schema | [agent-definition.md](agent-definition.md) | |
+| Edit system prompt or user message | [agent-prompting-guide.md](agent-prompting-guide.md) (quality) | [agent-definition.md](agent-definition.md) § Messages, § contentTokens (mechanics) |
+| Choose or change the model | [model-selection-guide.md](model-selection-guide.md) | [agent-definition.md](agent-definition.md) § Change Model Settings |
+| Add/remove input or output fields | [agent-definition.md](agent-definition.md) § entry-points.json | |
+| Scaffold a new agent project | [project-lifecycle.md](project-lifecycle.md) § End-to-End Example | [agent-definition.md](agent-definition.md) |
+| Validate, upload, pack, publish, or deploy | [project-lifecycle.md](project-lifecycle.md) | |
+| Discover solution resources (processes/apps/indexes/buckets/connections) | [project-lifecycle.md](project-lifecycle.md) § Resource Discovery | |
+| Add a tool — pick the right kind | [capabilities/process/process.md](capabilities/process/process.md) | applicable sibling |
+| Add a process tool (RPA / agent / API / agentic) — local or external | [capabilities/process/process.md](capabilities/process/process.md) | [capabilities/process/solution-files.md](capabilities/process/solution-files.md) |
+| Wire a multi-agent solution (parent + tool agents) | [capabilities/process/process.md](capabilities/process/process.md) § Multi-Agent Solution Example | |
+| Add an Integration Service tool | [capabilities/integration-service/integration-service.md](capabilities/integration-service/integration-service.md) | |
+| Add a built-in tool (Analyze Files) | [capabilities/built-in-tools/built-in-tools.md](capabilities/built-in-tools/built-in-tools.md) | [capabilities/built-in-tools/analyze-attachments.md](capabilities/built-in-tools/analyze-attachments.md) |
+| Accept a file as agent input or return a file as output | [agent-definition.md](agent-definition.md) § File Attachments | [capabilities/built-in-tools/built-in-tools.md](capabilities/built-in-tools/built-in-tools.md) |
+| Add a context (Context Grounding / attachments / DataFabric) | [capabilities/context/context.md](capabilities/context/context.md) | applicable sibling |
+| Add an index-backed context (RAG) | [capabilities/context/index.md](capabilities/context/index.md) | |
+| Add attachments context | [capabilities/context/attachments.md](capabilities/context/attachments.md) | |
+| Add DataFabric entity-set context | [capabilities/context/datafabric.md](capabilities/context/datafabric.md) | |
+| Add a memory space or seed memory items | [capabilities/memory/memory.md](capabilities/memory/memory.md) | |
+| Add an Action Center escalation (HITL) | [capabilities/escalation/escalation.md](capabilities/escalation/escalation.md) | |
+| Add guardrails (PII, harmful content, custom rules) | [capabilities/guardrails/guardrails.md](capabilities/guardrails/guardrails.md) | |
+| Embed an agent inline in a flow | [capabilities/inline-in-flow/inline-in-flow.md](capabilities/inline-in-flow/inline-in-flow.md) | |
+| Set up Orchestrator resources | Tell the user to use the `uipath-platform` skill | |
+| Wire agent into a flow | Tell the user to use the `uipath-maestro-flow` skill | |
+
+## Anti-patterns
+
+See [critical-rules.md](critical-rules.md) § What NOT to Do for the canonical list. Most expensive to get wrong:
+
+- Editing `content` without updating `contentTokens` (causes silent rendering failures)
+- Skipping `uip solution resource refresh` after adding external tools (`bindings_v2.json` never reaches the solution)
+- Hand-editing memory feature JSON instead of using `uip agent memory`
+- camelCasing `contextType` / `retrievalMode` enum values (validate accepts it, Studio Web silently drops the resource)
+- Copy-pasting UUIDs across resources (every resource needs its own)
+
+## Completion Output
+
+After completing a task, report:
+
+1. **File paths** — which files were created or modified
+2. **What was configured** — summary of agent settings and schemas
+3. **Validation result** — output of `uip agent validate --output json` (`MigrationPending`, `Validated` counts) followed by `uip agent migrate --output json` (`MigrationApplied`, `StorageVersion`)
+4. **Schema sync status** — confirm agent.json and entry-points.json match
+5. **Next steps** — suggest what the user should do next (publish, test in Studio Web, add resources)

package/skills/uipath-agents/references/lowcode/model-selection-guide.md

@@ -0,0 +1,69 @@
+# Model Selection Guide
+
+How to pick the LLM for a low-code agent's `settings.model`. The tenant is the source of truth — discover at runtime, then select; never ship the scaffold default.
+
+> `uip agent init` scaffolds `settings.model: "gpt-4o-2024-11-20"` — a 2024-era GA model with a 16384 output cap. **Always override it** with a discovered current model before validating.
+
+## 1. Discover (primary path)
+
+List the models the authenticated tenant actually offers:
+
+```bash
+uip agent model list --output json
+```
+
+`Data` is a **flat array of PascalCase objects** — not nested, not lowercase:
+
+| Field | Meaning |
+|-------|---------|
+| `Provider` | `OpenAi` \| `AwsBedrock` \| `VertexAi` |
+| `Name` | The exact string for `settings.model` (e.g. `anthropic.claude-sonnet-4-6`, `gpt-5.4`) |
+| `IsByo` | `true` = bring-your-own key registered for this tenant |
+| `IsPreview` | `true` = preview/non-GA — avoid by default |
+| `MaxTokens` | Output-token ceiling for this model — caps `settings.maxTokens` |
+
+Filter to selectable GA models with `--output-filter` (a global flag applied to `Data` — write the JMESPath starting at `Data`, no `Data.` prefix):
+
+```bash
+uip agent model list --output json \
+  --output-filter "[?IsByo==\`false\` && IsPreview==\`false\`].{Name:Name,Provider:Provider,MaxTokens:MaxTokens}"
+```
+
+Run discovery **before** choosing a model. Do not pick from this doc's examples without confirming the name appears in the live list — model availability differs per tenant and changes over time.
+
+## 2. Select
+
+1. Start from the GA-filtered list above (`IsByo=false`, `IsPreview=false`).
+2. **Preview models are opt-in only.** Use an `IsPreview: true` model (e.g. `gpt-5.5-2026-04-23`, `gemini-3.1-pro-preview`, `anthropic.claude-opus-4-7`) **only when the user explicitly asks** for the bleeding edge — preview models can change behavior or availability without notice.
+3. Pick the **newest GA model matching the task class** (§3).
+4. Set `settings.maxTokens` from the chosen model's `MaxTokens` — never exceed the cap. Example: `gpt-4o-2024-11-20` caps at 16384, so `maxTokens: 32768` is invalid for it; `anthropic.claude-sonnet-4-6` caps at 64000; `gpt-5.4` at 128000.
+
+## 3. Task → model mapping
+
+Express the choice as **selection criteria over the discovered list**, not a fixed ID:
+
+| Task class | Selection criterion | Why |
+|------------|---------------------|-----|
+| Reasoning / judgment / multi-step tool use | Newest GA Anthropic Sonnet or Opus, or newest GA flagship OpenAI | Strongest instruction-following + tool-call discipline |
+| Fast / cheap / high-volume classification or extraction | Newest GA `*-mini` (e.g. an OpenAI `*-mini`) or GA Haiku | Lower latency + cost; sufficient for narrow deterministic tasks |
+| Long-context (large documents, big tool outputs) | GA model with the highest `MaxTokens` | Avoids truncated output |
+
+Concrete GA examples observed on a live tenant — **illustrative only; verify against `uip agent model list`**:
+
+- Reasoning: `anthropic.claude-sonnet-4-6`, `anthropic.claude-opus-4-6-v1`, `gpt-5.4`, `gpt-4.1-2025-04-14`
+- Fast/cheap: `gpt-5.4-mini-2026-03-17`, `gpt-4.1-mini-2025-04-14`, `anthropic.claude-haiku-4-5-20251001-v1:0`
+
+## 4. Fallback (discovery unavailable)
+
+If `uip agent model list` fails (not logged in, offline, command unavailable), pick a curated GA default — currently `anthropic.claude-sonnet-4-6` for reasoning tasks — and **tell the user it was not tenant-verified** and may not exist on their tenant. This is the only situation where a hardcoded name is the operative choice; everywhere else, discover first.
+
+## 5. Apply the choice
+
+Edit `settings.model` (and `settings.maxTokens`) in `agent.json`, then validate and migrate:
+
+1. Set `settings.model` to the discovered `Name`.
+2. Set `settings.maxTokens` ≤ the model's `MaxTokens`.
+3. `uip agent validate --output json`
+4. `uip agent migrate --output json`
+
+For inline-in-flow agents add `--inline-in-flow` to both commands. Full field reference: [agent-definition.md](agent-definition.md#change-model-settings).