Skip to content

Commit e62e710

Browse files
feat(uipath-platform): teach agents to write and query trace decisions
Adds references/traces/decisions.md for uip traces decisions create, get and list, links it from SKILL.md, traces.md and uip-commands.md, and adds a smoke task. Addressed review feedback: added a Required column to the list flags table; clarified that decisionId is required in --input files, unlike the flag form which generates one when --id is omitted. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
1 parent a51bda8 commit e62e710

5 files changed

Lines changed: 222 additions & 3 deletions

File tree

‎skills/uipath-platform/SKILL.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
name: uipath-platform
33
description: "UiPath platform ops via the uip CLI — use for ANY task hitting UiPath Cloud / Orchestrator / Studio Web / Integration Service / Data Fabric / LLM Gateway. Load BEFORE writing code that calls a UiPath API. Covers auth, folders, assets, queues, storage buckets, libraries, webhooks, triggers, processes, jobs, machines, users, roles, sessions, calendars, IS connectors/connections/activities, Data Fabric entities/records/files/choice-sets (`uip df`), BYO LLM and BYO guardrail (BYOG) configurations, context grounding, traces (spans + feedback / annotation), licensing. For historical job metrics/trends→uipath-insights. For 'why did X fail' / root-cause→uipath-troubleshoot. For org/tenant audit trail / audit logs / login history→uipath-admin. For `uip solution` lifecycle→uipath-solution. For PDD/SDD design→uipath-planner. For workflow code (.xaml/.cs)→uipath-rpa, .flow (incl. Data Fabric connector nodes)→uipath-maestro-flow, .bpmn→uipath-maestro-bpmn, agents (.py/agent.json)→uipath-agents, Test Manager→uipath-test."
4-
when_to_use: "User mentions UiPath / Orchestrator / Studio Web / Integration Service / Data Fabric / LLM Gateway / 'uip' CLI / asset / queue / bucket / library / webhook / trigger / connector / connection / tenant / folder / robot / package / entity(incl. federated / virtual data object / zero-copy) / record / record / choice set(incl. federated / virtual choice set / zero-copy, entity using connector) / trace / span / trace feedback / BYO LLM / BYO guardrail / BYOG. Also 'upload to UiPath', 'create asset', 'start job', 'list faulted / running jobs', 'list queues', 'set ROI for a process', 'business ROI of a queue', 'deploy a single package to Orchestrator', 'OAuth2 token', 'list trace spans / add trace feedback', 'create entity', 'add field', 'delete field', 'add an entity to my solution', 'local entity', 'entity in my solution', 'list entities', 'insert record', 'update record', 'delete record', 'query Data Fabric', 'search records', 'show every <thing> tagged/where', 'filter records by tag/choice/field', 'count by group', 'unique tag combinations', 'group by field', 'aggregate COUNT/SUM/AVG', 'create choice-set', 'create choiceset', 'add choice set values', 'delete choice set', 'attach file to record', 'upload/download/delete file on entity record', 'swap record attachment', 'import CSV', 'load CSV into entity/list', 'load spreadsheet into entity', 'bulk load records from CSV', 'bulk import from CSV', 'register my own LLM key', 'configure a model substitution', 'my BYO LLM key stopped working / returns errors', 're-probe / audit a BYO configuration', 'list bring-your-own guardrail configurations', 'register/enable/disable/delete a BYOG guardrail configuration', 'who registered this BYOG guardrail', 'uipath.com REST'. For `uip solution` ops or `.uipx` deploys→uipath-solution. For runtime evals of published agents / `uip eval run`→uipath-agents. For Data Fabric connector nodes inside a `.flow`→uipath-maestro-flow. CLI bootstrap: 'install UiPath CLI', 'prepare workstation for UiPath', 'install UiPath skills', `uip` missing / not found, Node or npm missing, Python or .NET SDK missing."
4+
when_to_use: "User mentions UiPath / Orchestrator / Studio Web / Integration Service / Data Fabric / LLM Gateway / 'uip' CLI / asset / queue / bucket / library / webhook / trigger / connector / connection / tenant / folder / robot / package / entity(incl. federated / virtual data object / zero-copy) / record / record / choice set(incl. federated / virtual choice set / zero-copy, entity using connector) / trace / span / trace feedback / BYO LLM / BYO guardrail / BYOG. Also 'upload to UiPath', 'create asset', 'start job', 'list faulted / running jobs', 'list queues', 'set ROI for a process', 'business ROI of a queue', 'deploy a single package to Orchestrator', 'OAuth2 token', 'list trace spans / add trace feedback', 'write / record / query a decision on a trace', 'create entity', 'add field', 'delete field', 'add an entity to my solution', 'local entity', 'entity in my solution', 'list entities', 'insert record', 'update record', 'delete record', 'query Data Fabric', 'search records', 'show every <thing> tagged/where', 'filter records by tag/choice/field', 'count by group', 'unique tag combinations', 'group by field', 'aggregate COUNT/SUM/AVG', 'create choice-set', 'create choiceset', 'add choice set values', 'delete choice set', 'attach file to record', 'upload/download/delete file on entity record', 'swap record attachment', 'import CSV', 'load CSV into entity/list', 'load spreadsheet into entity', 'bulk load records from CSV', 'bulk import from CSV', 'register my own LLM key', 'configure a model substitution', 'my BYO LLM key stopped working / returns errors', 're-probe / audit a BYO configuration', 'list bring-your-own guardrail configurations', 'register/enable/disable/delete a BYOG guardrail configuration', 'who registered this BYOG guardrail', 'uipath.com REST'. For `uip solution` ops or `.uipx` deploys→uipath-solution. For runtime evals of published agents / `uip eval run`→uipath-agents. For Data Fabric connector nodes inside a `.flow`→uipath-maestro-flow. CLI bootstrap: 'install UiPath CLI', 'prepare workstation for UiPath', 'install UiPath skills', `uip` missing / not found, Node or npm missing, Python or .NET SDK missing."
55
allowed-tools: Bash, Read, Write, Glob, Grep, Skill
66
---
77

@@ -92,7 +92,7 @@ Load this skill BEFORE writing any code that talks to UiPath. Specific triggers:
9292
- **LLM Gateway — BYO product configurations**: `uip llm-configuration byo-connections` (`list / get / create / update / delete / list-product-configs`). Register tenant-owned OpenAI / Azure OpenAI / AWS Bedrock / Google Vertex / Anthropic / OpenAI-compatible keys against UiPath product features (agents, agenthub, jarvis, IXP, agent builder, ECS). Two input shapes: single-mapping (for `AnyModelWithOwnAdditions` features) and repeated `--mapping` (required for `AllModels` / `AnyModel`). Server-side validation is mandatory.
9393
- **LLM Gateway — diagnose a failing BYO config**: re-probe the underlying IS connection with `byo-connections get <id> --force-refresh`, force a fresh server-side probe with an idempotent `update`, audit the tenant with `list --include-connection-details` filtered on `connectionState != Enabled`, check catalog drift with `list-product-configs`, and cross-reference trace evidence with `uip traces spans get <trace-id>`. The gateway does **not** expose per-request invocation logs via CLI — diagnosis is current-state + trace evidence only. See [`references/llmgateway/byo-connections.md` § Diagnostics](references/llmgateway/byo-connections.md#diagnostics). For tenant-wide AI Trust Layer policy that may be overriding routing, see [uipath-governance](/uipath:uipath-governance).
9494
- **AI Trust Layer — BYO guardrail (BYOG) configurations**: `uip guardrails byo-configurations` (`list / list-validators / probe / create / update / delete`) — manage tenant-registered external guardrail validator providers (e.g. Azure AI Content Safety, Databricks AI Guardrails), each backed by an Integration Service connection. `ValidatorName` is tenant-unique and is the only value agents reference (`ByoValidator(<ValidatorName>)` — the connection resolves server-side). Before creating, `list` (the name must be free) and `uip is connections list` (for `--connection-id`); `create` always probes the connection/validator pair server-side and aborts if the probe fails, with no skip flag, and `update` re-probes whenever `--connection-id` changes. `probe` and `list-validators` test a pairing without saving anything; `update` merges supplied fields and can flip `--enabled`/`--disabled`; `delete` requires `--force`; no `get` verb. See [`references/guardrails/byo-configurations.md`](references/guardrails/byo-configurations.md). For authoring a guardrail against one of these configurations (low-code or coded), see [uipath-agents](/uipath:uipath-agents).
95-
- **Traces**: `uip traces spans get <trace-id>` (LLM/agentic execution observability)
95+
- **Traces**: `uip traces spans get <trace-id>` (LLM/agentic execution observability); `uip traces decisions create|get|list` to write and read decisions on a trace
9696
- **Context grounding**: knowledge indexes for semantic search / RAG — `uip context-grounding` (`list / create` from a bucket or connection `/ ingest / retrieve` to poll ingestion status `/ search / delete`). Agents and flows consume these indexes as tools. See [`references/context-grounding/index-management.md`](references/context-grounding/index-management.md).
9797
- **Platform licensing**: tenant license allocations, user/group bundle assignments, consumables reporting (`uip platform tenants licenses`, `users licenses`, `groups rules`, `licenses consumables get` — the only consumables verb; summary/daily/folders are `--mode` values)
9898
- **CLI tooling itself**: `uip tools list/search/install`, `uip mcp serve`
@@ -227,6 +227,7 @@ Choose the appropriate operation from the Task Navigation table below. For `uip
227227
| **Run runtime evals on a published agent** | [/uipath:uipath-agents](/uipath:uipath-agents) |
228228
| **Debug LLM/agent traces (spans)** | [references/traces/traces.md](references/traces/traces.md) |
229229
| **Annotate traces with feedback** | [references/traces/feedback.md](references/traces/feedback.md) |
230+
| **Write or query decisions on a trace** | [references/traces/decisions.md](references/traces/decisions.md) |
230231
| **Use Integration Service** | [references/integration-service/integration-service.md](references/integration-service/integration-service.md) |
231232
| **Use Data Fabric — entities, records, files, choice sets** | [references/data-fabric/data-fabric.md](references/data-fabric/data-fabric.md) |
232233
| **Build an entity schema / add fields / complex field types** | [references/data-fabric/entity-schema.md](references/data-fabric/entity-schema.md) |
@@ -382,6 +383,7 @@ Every `uip` command accepts:
382383
- **[Planner](/uipath:uipath-planner)** — PDD/SDD design + multi-skill task planning (Process → Solution Design Document → task list)
383384
- **[Traces — Spans](references/traces/traces.md)** — LLM execution trace observability
384385
- **[Traces — Feedback](references/traces/feedback.md)** — Annotate traces with sentiment and comments
386+
- **[Traces — Decisions](references/traces/decisions.md)** — Write and query decisions recorded against a trace
385387
- **[Integration Service](references/integration-service/integration-service.md)** — Connectors, connections, activities, resources
386388
- **[Data Fabric](references/data-fabric/data-fabric.md)** — Entity schemas, records CRUD, query filters and aggregates, choice sets, file attachments, CSV bulk import, folder scoping, [local entities](references/data-fabric/local-entities.md)
387389
- **[LLM Gateway — BYO Connections](references/llmgateway/byo-connections.md)** — Register tenant-owned LLM keys against UiPath products
Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
# Trace Decisions (`uip traces decisions`)
2+
3+
Record who decided what on a trace, field by field, and read it back. A decision holds the accepted outcome, the decided fields (proposed value, final value, disposition, proposer), the actor, and optional process context.
4+
5+
## Commands
6+
7+
| Command | Purpose |
8+
|---------|---------|
9+
| `create` | Write one or more decisions to a trace. Writing an existing `decisionId` replaces it |
10+
| `get <id>` | Read one decision by decision ID |
11+
| `list` | Query decisions by trace, process, instance, element, platform, actor, outcome, origin, or time |
12+
13+
Output keeps the API's camelCase keys, so `get` output is valid `create --input` data.
14+
15+
## Critical rules
16+
17+
1. `create` always needs `--trace-id` (32-char hex or GUID) and `--folder-key`. Take the folder key from the user or from `uip or folders get`; never invent one.
18+
2. Every field in a decision needs `proposedBy` (`identity` + `kind`). Without it the API returns HTTP 400.
19+
3. `decisionId` is 16 lowercase hex characters (an OTEL span ID). Omit `--id` to get a generated one. Any other format returns HTTP 400.
20+
4. Pass `--input <file>` for batches or decisions with `sourceAsset`, `implicitSignals`, or dispositions that differ per field. Use flags only for one decision whose fields share a disposition and proposer. The two forms cannot be mixed.
21+
5. Reuse a `decisionId` only to replace that decision. A second write with the same ID overwrites the first.
22+
6. Read the `create` result: it returns one `{ decisionId, feedbackId }` per decision. Confirm with `get` or `list` before reporting success.
23+
7. On HTTP 500 repeat the identical command once. A write is idempotent per `decisionId`, so a repeat does not duplicate.
24+
8. Use only the logged-in session. Never ask for, paste, or echo a token.
25+
26+
## create
27+
28+
From a file (one decision object or an array; `-` reads stdin):
29+
30+
```bash
31+
uip traces decisions create \
32+
--trace-id <TRACE_ID> \
33+
--input <DECISIONS_FILE> \
34+
--folder-key <FOLDER_KEY> \
35+
--output json
36+
```
37+
38+
From flags (one decision; every `--field` shares the disposition and proposer):
39+
40+
```bash
41+
uip traces decisions create \
42+
--trace-id <TRACE_ID> \
43+
--outcome "<ACCEPTED_OUTCOME>" \
44+
--actor <ACTOR_IDENTITY> \
45+
--field <FIELD_NAME>=<VALUE> \
46+
--folder-key <FOLDER_KEY> \
47+
--output json
48+
```
49+
50+
| Flag | Required | Notes |
51+
|------|----------|-------|
52+
| `--trace-id` | Yes | 32-char hex or GUID |
53+
| `--folder-key` | Yes | |
54+
| `--input` | One of `--input` or flags | JSON file; `-` for stdin |
55+
| `--outcome` | With flags | Accepted outcome |
56+
| `--actor` | With flags | Identity of whoever decided |
57+
| `--field name=value` | With flags, repeatable | Value read as JSON when valid (`1065` is a number), else text |
58+
| `--id` | No | Decision ID, 16 lowercase hex characters. Default: generated |
59+
| `--actor-kind` | No | `Automation`, `Human`, `Rule`, `Agent`. Default `Human` |
60+
| `--platform` | No | `ActionCenter`, `CodedApp`, `VerticalUi`. Default `ActionCenter` |
61+
| `--disposition` | No | `Accepted`, `LightlyEdited`, `Rewritten`, `Rejected`, `Ignored`. Default `Accepted` |
62+
| `--proposed-by` | No | Who proposed the `--field` values. Default: the actor |
63+
| `--proposed-by-kind` | No | `Automation`, `Person`, `Agent`, `Team`. Default `Person` |
64+
| `--rejected-outcome` | No | Repeatable |
65+
| `--evidence` | No | Repeatable explicit evidence line |
66+
| `--timestamp` | No | ISO 8601. Default: now |
67+
| `--process-key` / `--process-version` / `--instance-id` / `--element-id` | No | Process context |
68+
| `--profile <name>` | No | Named login profile |
69+
70+
## Input file shape
71+
72+
```json
73+
[
74+
{
75+
"decisionId": "<DECISION_ID>",
76+
"data": {
77+
"<FIELD_NAME>": {
78+
"proposedValue": "<PROPOSED>",
79+
"finalValue": "<FINAL>",
80+
"disposition": "Rewritten",
81+
"proposedBy": { "identity": "<PROPOSER>", "kind": "Agent" },
82+
"sourceAsset": { "kind": "Process", "id": "<ASSET_ID>", "version": "<VERSION>" }
83+
}
84+
},
85+
"actor": { "identity": "<ACTOR_IDENTITY>", "kind": "Human" },
86+
"acceptedOutcome": "<ACCEPTED_OUTCOME>",
87+
"rejectedOutcomes": ["<REJECTED_OUTCOME>"],
88+
"decisionTimestamp": "<ISO_8601_TIMESTAMP>",
89+
"explicitEvidences": ["<EVIDENCE>"],
90+
"implicitSignals": { "<KEY>": "<VALUE>" },
91+
"processInstanceMetadata": {
92+
"processKey": "<PROCESS_KEY>",
93+
"processVersion": "<PROCESS_VERSION>",
94+
"instanceId": "<INSTANCE_ID>",
95+
"elementId": "<ELEMENT_ID>"
96+
},
97+
"platform": "ActionCenter"
98+
}
99+
]
100+
```
101+
102+
Required per decision: `decisionId`, `data`, `actor`, `acceptedOutcome`, `decisionTimestamp`, `platform`. Required per field: `disposition`, `proposedBy`. `sourceAsset.kind` is one of `Agent`, `Automation`, `Process`, `Rule`, `Ontology`, `Knowledge`.
103+
104+
Unlike the flag form, where omitting `--id` generates one, the JSON input file has no equivalent default: every decision object in it must carry its own `decisionId`.
105+
106+
Field names under `data` are the caller's; the CLI never changes their casing.
107+
108+
## get
109+
110+
```bash
111+
uip traces decisions get <DECISION_ID> --folder-key <FOLDER_KEY> --output json
112+
```
113+
114+
`--include-spans` adds the span that carries the decision. An unknown ID exits 1 with `Decision <id> not found.`.
115+
116+
## list
117+
118+
```bash
119+
uip traces decisions list \
120+
--trace-id <TRACE_ID> \
121+
--folder-key <FOLDER_KEY> \
122+
--output json
123+
```
124+
125+
| Flag | Required | Notes |
126+
|------|----------|-------|
127+
| `--trace-id` | No | 32-char hex or GUID |
128+
| `--process-key` / `--process-version` / `--instance-id` / `--element-id` | No | Process context filters |
129+
| `--platform` | No | `ActionCenter`, `CodedApp`, `VerticalUi` |
130+
| `--actor` / `--actor-kind` | No | Identity and kind (`Automation`, `Human`, `Rule`, `Agent`) |
131+
| `--outcome` | No | Accepted outcome |
132+
| `--origin` | No | Origin value |
133+
| `--from` / `--to` | No | ISO 8601 time bounds |
134+
| `--include-spans` | No | Include the carrying span |
135+
| `--limit` | No | Default 20 |
136+
| `--offset` | No | Row offset, default 0 |
137+
138+
`Data` is an array (empty when nothing matches). `Pagination.Total` is the match count; page with `--offset` while `Pagination.HasMore` is true.
139+
140+
## Error handling
141+
142+
| Symptom | Action |
143+
|---------|--------|
144+
| `--trace-id is required` / `--folder-key is required` | Add the flag. Take the folder key from the user |
145+
| `Invalid trace ID format` | Pass 32 hex characters or a GUID |
146+
| HTTP 400 naming `proposedBy` | Add `proposedBy` to every field in `data` |
147+
| HTTP 400 naming `OTEL SpanId` | Use a 16-char lowercase hex `decisionId` |
148+
| `Not authenticated` | Run `uip login --authority <AUTHORITY> --organization <ORG> --tenant <TENANT>`; never ask for a token |
149+
| `Insufficient permissions` | The user needs Logs permissions on the folder; stop and report |
150+
151+
## Anti-patterns
152+
153+
- Reusing one `decisionId` for different decisions in the same trace; the second replaces the first.
154+
- Building the JSON by string concatenation. Write the file with a JSON-aware tool.
155+
- Putting a token in a command, file, or message.

‎skills/uipath-platform/references/traces/traces.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,4 +42,5 @@ uip traces spans get --job-key <job-key> --output json
4242

4343
- [Run Jobs](../orchestrator/run-jobs.md) — the job lifecycle these traces come from
4444
- [Trace Feedback](feedback.md) — annotate spans with sentiment; includes span selection guidance for nested jobs
45+
- [Trace Decisions](decisions.md) — write and query decisions recorded against a trace
4546
- `uip traces spans get --help` for full option details

0 commit comments

Comments
 (0)