uip traces feedback

Syntax and options for `uip traces feedback`, which creates and manages LLM Observability feedback attached to a trace or span.

uip traces feedback manages LLM Observability feedback — a positive/negative rating, comment, and category tags attached to a trace or span. Use it to record human review of an agent's output, or to pull recorded feedback back out for reporting.

This page is part of the uip traces tool — see that page for spans get.

大纲

uip traces feedback create --trace-id <id> (--positive | --negative) --folder-key <guid> [--span-id <id>] [--comment <text> | --comment-file <path>] [--category <tag>...] [--agent-id <guid>] [--agent-version <str>]
uip traces feedback get <id> [--folder-key <guid>]
uip traces feedback list [--agent-id <guid>] [--agent-version <str>] [--trace-id <id>] [--span-id <id>] [--status <value>...] [--positive | --negative] [--limit <n>] [--offset <n>] [--folder-key <guid>]
uip traces feedback list detailed [--agent-id <guid>] [--agent-version <str>] [--trace-id <id>] [--span-id <id>] [--status <value>...] [--positive | --negative] [--category-id <guid>...] [--after <iso> | --since <duration>] [--before <iso>] [--sort-by <field>] [--sort-order <dir>] [--limit <n>] [--offset <n>] [--folder-key <guid>]
uip traces feedback update <id> (--positive | --negative) --folder-key <guid> [--comment <text> | --comment-file <path>] [--metadata <json> | --metadata-file <path>] [--category <tag>...]
uip traces feedback delete <id> --folder-key <guid> -y

All verbs honor the global options and the standard exit codes.

uip traces feedback create

Create feedback for a trace (or a specific span within it).

选项

标记	描述
--trace-id <id>	Required. Trace ID (32-char hex or GUID).
--positive / --negative	Required — exactly one. Sentiment of the feedback.
--folder-key <guid>	Required. Orchestrator folder key.
--span-id <id>	Span ID. Defaults to the trace's root span when omitted.
--comment <text>	Free-text annotation (max 1,048,576 characters). Mutually exclusive with --comment-file.
--comment-file <path>	Read the comment from a file; pass - to read from stdin. Mutually exclusive with --comment.
--category <tag>	Category tag. Repeatable. The platform recognizes built-in tags like Output, Agent Error, and Agent Plan Execution, but any string is accepted.
--agent-id <guid>	Agent reference ID.
--agent-version <str>	Agent version (max 100 characters).

示例

uip traces feedback create \
  --trace-id 4bf92f3577b34da6a3ce929d0e0e4736 \
  --positive \
  --folder-key a1b2c3d4-0000-0000-0000-000000000001

数据形状

{
  "Code": "FeedbackCreate",
  "Data": { "Id": "a1b2c3d4-0000-0000-0000-000000000002" }
}

Data is an unmodified pass-through of whatever the Feedback API returns — the CLI doesn't project it to a fixed field set, so the real response can carry more fields than shown here.

uip traces feedback get

Get a single feedback record by ID.

参数

• <id> (required) — Feedback record ID (GUID). Fails client-side with "Invalid feedback ID format" if it isn't a GUID.

选项

标记	描述
--folder-key <guid>	Orchestrator folder key. The server generally requires this to authorize the read even though the CLI doesn't hard-fail without it client-side.

示例

uip traces feedback get a1b2c3d4-0000-0000-0000-000000000002 \
  --folder-key a1b2c3d4-0000-0000-0000-000000000001

数据形状

{
  "Code": "FeedbackGet",
  "Data": {
    "Id": "a1b2c3d4-0000-0000-0000-000000000002",
    "IsPositive": true
  }
}

Like create, Data is a raw pass-through — the real response typically carries more fields (comment, metadata, categories, timestamps) than this minimal example shows.

uip traces feedback list

List feedback entries, filtered by trace, span, agent, status, or sentiment.

选项

标记	描述
--agent-id <guid>	Filter by agent ID.
--agent-version <str>	Filter by agent version.
--trace-id <id>	Filter by trace ID.
--span-id <id>	Filter by span ID.
--status <value>	Filter by status: Pending, Approved, Dismissed. Repeatable.
--positive / --negative	Return only positive or only negative feedback. Mutually exclusive.
--limit <n>	Max results. Defaults to 20, capped at 100.
--offset <n>	要跳过的结果。默认为 0。
--folder-key <guid>	Orchestrator folder key.

示例

uip traces feedback list --trace-id 4bf92f3577b34da6a3ce929d0e0e4736

数据形状

{
  "Code": "FeedbackList",
  "Data": [
    {
      "Id": "a1b2c3d4-0000-0000-0000-000000000002",
      "IsPositive": true
    }
  ]
}

An empty result prints "No feedback found. Use 'uip traces feedback create' to add feedback."

uip traces feedback list detailed

List feedback with extended filters (time window, category, sort) and span context. This is a subcommand of list, not a top-level verb — the invocation is uip traces feedback list detailed, with the space, not list-detailed.

选项

标记	描述
--agent-id <guid>	Filter by agent ID.
--agent-version <str>	Filter by agent version.
--trace-id <id>	Filter by trace ID.
--span-id <id>	Filter by span ID.
--status <value>	Filter by status: Pending, Approved, Dismissed. Repeatable.
--positive / --negative	Return only positive or only negative feedback. Mutually exclusive.
--category-id <guid>	Filter by category ID. Repeatable.
--after <iso>	Created after this ISO 8601 timestamp.
--before <iso>	Created before this ISO 8601 timestamp.
--since <duration>	Relative lookback shorthand for --after — for example 1h, 24h, 7d. Only h (hours) and d (days) units are accepted.
--sort-by <field>	Sort field: createdAt or updatedAt. Defaults to createdAt.
--sort-order <dir>	Sort direction: asc or desc. Defaults to desc.
--limit <n>	Max results. Defaults to 20, capped at 200 (higher than plain list's cap of 100).
--offset <n>	要跳过的结果。默认为 0。
--folder-key <guid>	Orchestrator folder key.

备注：

--since and --after both set the same underlying start-time filter — --since is evaluated relative to "now" at the moment the command runs.

示例

uip traces feedback list detailed --since 24h

数据形状

{
  "Code": "FeedbackListDetailed",
  "Data": [
    {
      "Id": "a1b2c3d4-0000-0000-0000-000000000002",
      "IsPositive": true,
      "TraceId": "4bf92f3577b34da6a3ce929d0e0e4736"
    }
  ]
}

The underlying API response is paginated ({ items, totalCount }), but the CLI only emits the items array as Data — the total match count (totalCount) is not surfaced. To know whether more results exist beyond --limit, compare the returned count to --limit rather than relying on a total.

uip traces feedback update

Update an existing feedback record's sentiment, comment, metadata, or categories.

重要提示：

The API replaces the whole record rather than patching it, so the CLI reads the existing record first and carries over any field you didn't pass — except --category: omitting it leaves existing categories untouched, but this read-then-write is not atomic. A concurrent edit landing between the read and the write is silently lost.

参数

• <id> (required) — Feedback record ID (GUID).

选项

标记	描述
--positive / --negative	Required — exactly one. New sentiment.
--folder-key <guid>	Required. Orchestrator folder key.
--comment <text>	Updated comment (max 1,048,576 characters). Mutually exclusive with --comment-file. Omit to keep the existing comment.
--comment-file <path>	Read the updated comment from a file; pass - for stdin. Mutually exclusive with --comment.
--metadata <json>	Updated metadata; must be valid JSON (max 1,048,576 characters). Mutually exclusive with --metadata-file. Omit to keep the existing metadata.
--metadata-file <path>	Read updated metadata from a file; pass - for stdin. Mutually exclusive with --metadata.
--category <tag>	Replacement category tags. Repeatable. Omit entirely to leave existing categories as they are — passing it replaces the full set, it doesn't merge.

示例

# change sentiment and add a comment
uip traces feedback update a1b2c3d4-0000-0000-0000-000000000002 \
  --negative \
  --comment "Wrong output" \
  --folder-key a1b2c3d4-0000-0000-0000-000000000001

# attach metadata read from a file
uip traces feedback update a1b2c3d4-0000-0000-0000-000000000002 \
  --positive \
  --metadata-file review.json \
  --folder-key a1b2c3d4-0000-0000-0000-000000000001

数据形状

{
  "Code": "FeedbackUpdate",
  "Data": {
    "Id": "a1b2c3d4-0000-0000-0000-000000000002",
    "IsPositive": false
  }
}

uip traces feedback delete

Delete a feedback record by ID. This is a destructive operation — it requires -y, --yes; the CLI never prompts.

参数

• <id> (required) — Feedback record ID (GUID).

选项

标记	描述
--folder-key <guid>	Required. Orchestrator folder key.
-y, --yes	Confirm this irreversible operation. Required — the CLI never prompts.

示例

uip traces feedback delete a1b2c3d4-0000-0000-0000-000000000002 \
  --folder-key a1b2c3d4-0000-0000-0000-000000000001 \
  --yes

数据形状

{
  "Code": "FeedbackDelete",
  "Data": { "Id": "a1b2c3d4-0000-0000-0000-000000000002" }
}

错误行为

• 401 from the Feedback API: Failure: "Not authenticated. Run 'uip auth login' first.".
• 403：Failure: "Insufficient permissions. Ensure you have Logs.View / Logs.Create / Logs.Delete on this folder."。
• 404: Failure naming the missing feedback ID.
• An id that isn't a GUID (get, update, delete): Failure: "Invalid feedback ID format: <id>", checked client-side before any network call.

相关内容

• uip traces spans get — source of the --trace-id/--span-id values used above.
• 工具（插件） — 安装、更新、卸载traces-tool包。
• uip login — session used to authenticate every verb on this page.

另请参阅

• uip traces