uipath-tasks

UiPath 任务（Action Center）— Agent 技能

Action Center 是 UiPath 的人在回路平台。任务代表需要人工输入的工作项，包括表单审批、文档验证、数据标注等。

所有操作都通过 uip tasks <verb> --output json 执行。

---

登录与租户设置

默认使用 Production。只有在请求中明确说明时，才切换环境、组织或租户。

• 如果请求未提及环境 → 使用当前会话（默认为生产环境 cloud.uipath.com）
• 如果请求明确指定环境、组织或租户 → 检查 uip login status，并在需要时重新登录

需要切换时：

1. 检查当前登录状态：uip login status --output json — 验证 UIPATH_URL、Organization 和 Tenant
2. 仅在环境不同时，使用 --authority 重新登录：
   • 非默认主机（Automation Suite、专用主机或其他）：uip login --authority "<AUTHORITY_URL>" --tenant <tenant>
   • cloud.uipath.com：uip login --tenant <tenant>（默认，无需 --authority）
3. 如果环境正确但租户不正确：uip login tenant set <tenant-name>

# Check current environment, org, and tenant
uip login status --output json

# Login to a specific environment (production cloud is the default)
uip login --authority https://cloud.uipath.com --tenant MyTenant

# List all available tenants (after login)
uip login tenant list --output json

# Switch tenant within the same environment
uip login tenant set MyTenant

重要： tasks 命令中的 --tenant 标志不会切换当前会话的租户。 环境由身份验证文件中的 UIPATH_URL 决定 — 运行 tasks 命令前，务必通过 login status 确认。

---

适用场景

• 列出或检查各文件夹中的 Action Center 任务
• 将任务分配、重新分配或取消分配给用户
• 使用操作结果和数据负载完成任务
• 查询哪些用户拥有文件夹中的任务权限
• 管理任务目录（列出、获取、创建、更新）及其保留策略
• 读取和添加任务评论
• 设置任务标签
• 编辑任务元数据（标题、优先级、目录关联）
• 获取和保存任务数据
• 获取 Agent 或 Maestro 任务的执行跟踪，并提交关于跟踪或跨度的反馈

不在适用范围内： Orchestrator 队列或队列项目（使用 uip or）、Document Understanding 模型训练或 Action Center 应用开发（使用 uip codedapp）。

---

任务类型

类型	CLI 值	描述
表单任务	FormTask	基于表单的审批／操作任务
外部任务	ExternalTask	通用外部任务
应用任务	AppTask	基于 Action Center 应用的任务
文档验证	DocumentValidationTask	Document Understanding 验证
文档分类	DocumentClassificationTask	Document Understanding 分类
数据标注	DataLabelingTask	数据标注任务

---

任务状态与优先级

状态	含义
Unassigned	已创建，但未分配给任何用户
Pending	已分配，等待完成
Completed	已通过操作／结果完成

优先级	等级
Low	低
Medium	中（默认）
High	高
Critical	紧急

---

快速入门

# Check login and active tenant
uip login status --output json

# Switch tenant if needed
uip login tenant set <tenant-name>

# List all tasks across folders
uip tasks list --output json

# Get details of a specific task
uip tasks get <task-id> --output json

# Assign a task to a user
uip tasks assign <task-id> --user [email protected] --output json

# Complete a task
uip tasks complete <task-id> --type ExternalTask --folder-id <folder-id> --output json

---

关键规则

1. 始终先确定组织和租户。 如果用户指定了组织／环境和租户，请运行 uip login status 检查当前租户，然后根据需要运行 uip login tenant set <tenant> 进行切换。切勿假定当前租户符合用户的意图。

2. 任务 ID 是数字。 与使用 GUID 的其他 UiPath 服务不同，Action Center 使用数字任务 ID。使用 tasks list 查找任务 ID。

3. 文件夹范围有三种可互换的形式。 文件夹范围命令接受 --folder-id <numeric-id>、--folder-path <path> 或 --folder-key <guid>（三者互斥）。路径和键与 uip or folders list 打印的内容完全一致（该命令没有数字 ID 列），因此，如果文件夹是通过文件夹发现找到的，优先使用路径或键；如果任务行提供了 folderId，则仍可使用数字 ID。

4. Complete 必须带上 --type。 API 会根据任务类型路由到不同的端点。完成任务时始终包含 --type。先使用 tasks get 检查任务类型。

5. FormTask 和 AppTask 完成时必须带上 --action 和 --data。 其他任务类型的 action 和 data 可选。

6. Assign 接受 --user-id 或 --user（电子邮件）。 使用 tasks users <folder-id>（或 tasks users --folder-path <path>／--folder-key <guid>）查找可分配的用户及其 ID。

7. 操作前始终先检查。 执行分配／完成操作前，使用 tasks list 或 tasks get 检查任务状态。

8. 不要完成已完成的任务。 检查任务的 status 字段；如果其值为 Completed，请告知用户。

9. Complete/catalogs/comments/labels/metadata/data 需要指定文件夹范围。 这些命令需要一个文件夹。传入 --folder-id／--folder-path／--folder-key 之一；或者在交互式终端中省略这三项，从列表中选择。非交互式运行（Agent、CI）必须指定文件夹选项，否则命令会失败并提示 A folder is required，因此在此类运行中始终要明确传入其中一项。

10. 保留操作为 Delete 或 Archive。 Archive 还需要 --retention-bucket-id。--encrypted 仅可在创建时使用，创建后无法通过更新更改。

11. 标签会替换整个集合。 tasks labels --labels 会覆盖任务的所有标签；要保留标签，请一并传入所有标签；传入 [] 可清除全部标签。

12. data save 不接受类型标记。 该命令会自行解析任务类型；传入任务 ID、一个文件夹选项（--folder-id／--folder-path／--folder-key）以及 --data（一个 JSON 对象）。

---

任务导航

任务	使用的命令
列出所有任务	tasks list
列出文件夹中的任务	tasks list --folder-id <id>
按路径/键列出文件夹中的任务	tasks list --folder-path "<path>" or tasks list --folder-key <guid>
以管理员身份列出任务	tasks list --as-admin
获取任务详情	tasks get <task-id>
获取任务并指定类型提示	tasks get <task-id> --task-type FormTask --folder-id <id>
分配任务	tasks assign <task-id> --user <email>
按用户 ID 分配	tasks assign <task-id> --user-id <id>
重新分配任务	tasks reassign <task-id> --user <email>
取消分配任务	tasks unassign <task-id>
完成任务	tasks complete <task-id> --type <type> --folder-id <id>
使用操作完成任务	tasks complete <task-id> --type FormTask --folder-id <id> --action "Approve" --data '{...}'
列出可分配用户	tasks users <folder-id>、tasks users --folder-path "<path>" 或 tasks users --folder-key <guid>
列出任务目录	tasks catalogs list --folder-id <id>
获取目录	tasks catalogs get <catalog-id> --folder-id <id>
创建目录	tasks catalogs create --name <name> --folder-id <id>
更新目录	tasks catalogs update <catalog-id> --folder-id <id>
列出任务评论	tasks comments list <task-id> --folder-id <id>
添加评论	tasks comments add <task-id> --text <text> --folder-id <id>
设置任务标签	tasks labels <task-id> --labels '[{"name":"region","displayName":"Region","displayValue":"EMEA"}]' --folder-id <id>
编辑任务元数据	tasks metadata <task-id> --folder-id <id> [--title --priority --catalog-id]
获取任务数据	tasks data get <task-id> --folder-id <id>
保存任务数据	tasks data save <task-id> --data '{...}' --folder-id <id>
获取任务的执行轨迹（仅 Agent/Maestro）	tasks get <task-id> --output json 然后运行 traces spans get <trace-id>；参见 references/task-execution-trace.md
对轨迹或跨度提交反馈	traces feedback create --trace-id <id> --folder-key <key> --positive；参见 references/task-execution-trace.md

---

工作流：发现 → 规划 → 执行 → 验证

始终遵循此模式：

1. 发现 — 列出任务、获取详情、查找可分配用户
2. 规划 — 确定操作（分配、完成等）
3. 执行 — 执行操作
4. 验证 — 重新读取任务以确认状态已更改

# 0. Ensure correct tenant
uip login status --output json
uip login tenant set <tenant-name>   # only if needed

# 1. Discover
uip tasks list --output json
uip tasks get <task-id> --output json

# 2. Plan — determine the task type, folder ID, and action needed

# 3. Act — assign a task
uip tasks assign <task-id> --user [email protected] --output json

# 4. Verify
uip tasks get <task-id> --output json

---

故障排除

错误	原因	解决方法
Not logged in	身份验证已过期	uip login
HTTP 401	令牌无效	重新登录
HTTP 403	权限被拒绝	确保帐户在该文件夹中拥有 Action Center 权限
Missing assignee	未提供 --user-id 或 --user	添加 --user <email> 或 --user-id <id>
Task not found	任务 ID 错误	运行 tasks list 获取正确的 ID
完成任务失败	--type 错误	使用 tasks get 检查实际任务类型
完成 FormTask 失败	缺少 --action 或 --data	FormTask 和 AppTask 都需要 --action 和 --data
无法分配	用户在文件夹中没有权限	运行 tasks users <folder-id> 列出符合条件的用户
A folder is required	非交互式运行时未指定文件夹选项	传入 --folder-id、--folder-path 或 --folder-key
Folder not found: '<value>'.	此登录帐号无权访问与该路径/键匹配的文件夹	运行 uip or folders list，并使用列出的 Path 或 Key
Invalid --folder-key: <value>	键不是 UUID	使用 uip or folders list 中 Key 列的 GUID
Error resolving folder path/key '<value>'	文件夹查询本身失败（权限或网络问题）	检查 Instructions 中的错误详情；运行 uip or folders list 验证访问权限

---

参考资料

如需更深入的指导，请仅在需要时阅读以下文件：

• references/task-lifecycle.md — 列出和获取任务、按类型提示路由端点，以及完整的发现→分配→完成工作流
• references/task-completion.md — 完成端点路由，以及各任务类型所需的字段
• references/task-assignment.md — 分配、重新分配、取消分配模式及用户发现
• references/task-catalogs.md — 任务目录的列表、获取、创建、更新及保留策略
• references/task-metadata.md — 编辑任务元数据，以及任务评论和标签
• references/task-data.md — 获取和保存任务数据，以及保存类型路由
• references/task-execution-trace.md — Agent/Maestro 任务的执行跟踪查询和反馈，移植自 Action Center 旧版应用内 Autopilot 工具
• references/action-center-urls.md — 规范的 Action Center URL 模式；构造或分享任何任务深层链接前，请先阅读此文件（门户 UI 会将不含租户的 URL 错误分类为“未启用 Orchestrator”）