# Computer Use Agent
> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。
Computer Use Agent（简称 CUA）是面向 AI Agent 场景的用户专属云端运行环境，为 Agent 提供可见、可操作的 Windows 云桌面。Agent 可在远端桌面中完成网页浏览、原生应用操作、终端执行、文件处理和多步骤工作流，并通过任务状态、上下文、产物与可观测链路将执行结果返回调用方。
本文将介绍购买 Agent Plan 套餐后，如何在 AI 工具中通过 Skill 接入并使用 Computer Use Agent。
# 能力介绍
CUA 是一套"本地操作、远端运行"的 Windows 云桌面系统。支持的核心能力如下：
| 能力 | 说明 |
| --- | --- |
| **Windows 云桌面** | 通过 ark-cua skill 获取私有的 URL，随时通过电脑、手机访问你的云桌面，并且支持移动端、PC 端的整体适配。
**桌面端交互：**
[视频](https://arkdocs.tos-cn-beijing.volces.com/videos/CodingPlan/cua-app-desktop.webm)
**移动端交互：**
[视频](https://arkdocs.tos-cn-beijing.volces.com/videos/CodingPlan/cua-app-mobile.webm) |
| **浏览器自动化** | 通过浏览器结构化能力完成 URL 访问、DOM 读取、网页表单和下载等 Web 任务。
**分析股票行情走势：**
[视频](https://arkdocs.tos-cn-beijing.volces.com/videos/CodingPlan/cua-stock-analysis.webm) |
| **视觉自动化** | 结合截图、鼠标键盘和 Windows UI Automation 操作原生桌面应用（如微信、豆包），以及无法通过 DOM 完成的图形交互。 |
| **长程任务** | 支持任务状态跟踪、需要用户输入时暂停、上下文复用、时间线、定时或周期任务。 |
| **虚拟外设** | 支持浏览器连接本地外设工具（摄像头、麦克风）。 |
**典型场景：**
- 登录业务系统并完成跨页面数据录入、查询和下载。
- 操作仅提供 Windows 客户端的办公、研发或行业软件。
- 组合浏览器、终端、桌面应用和文件工具完成端到端流程。
- 执行需要等待、追踪进度、人工补充信息或导出文件的长程任务。
- 按指定时间执行一次性或周期性桌面工作流。
- 通过连接器远程连接本地麦克风和摄像头完成交互。
# 使用限制
- 需订购 Agent Plan **Medium 及以上**套餐，并由平台为当前用户分配或绑定可用的 CUA 桌面。
- 根据管理需要，使用本能力前需在 [火山平台](https://console.volcengine.com/user/authentication/detail/) 预先完成实名认证，否则可能会导致无法正常分配机器。
- 同一桌面同一时间只运行一个活动任务。
- 云桌面临时访问 URL 属于敏感凭证，不应写入公开文档、日志或群聊；使用完毕或疑似泄露时应立即撤销。
- Agent Plan API Key 仅在用户本地终端输入并缓存，禁止粘贴到对话、任务目标、命令参数日志、仓库文件或截图中。
- 桌面重置会重建桌面，必须显式确认；任务取消仅在用户明确要求停止时执行。
# 接入方法
## 步骤一：订阅 Agent Plan
1. 进入 [开通管理-Agent Plan](https://ark.volcengine.com/region:cn-beijing/subscription/agent-plan?agentMode=close) 页面，选择并订购 **Medium 及以上**级别套餐（目前仅 Medium 及以上套餐支持购买 Computer Use Agent）。套餐说明参见 [套餐概览](/docs/agent-plan-personal-plan-overview)。
2. 确认使用地域、账号实名认证和套餐状态符合要求。
## 步骤二：开启 Computer Use Agent Harness
1. 在 Agent Plan 控制台单击 **Harness**。
2. 在 **Harness** 区域找到 **Computer Use Agent**，开启抵扣开关。
3. 确认当前用户已分配或绑定 CUA。若控制台尚未展示 CUA 服务项，表示能力尚未对当前账号开放，请先检查套餐等级是否为 Medium 及以上；如仍有问题请联系管理员或业务支持。
## 步骤三：安装或更新 CUA Skill
### 方式一：使用 arkcli 安装（推荐）
1. 安装 arkcli。
```Bash
npm i @volcengine/ark-cli -g --registry https://registry.npmjs.org
```
> **提示**：如果之前有安装过，可以先移除再重装。
2. 通过 arkcli 配置 agentplan 并安装 cua（以 codex 为例）。
```Bash
arkcli helper mcp codex --capability cua
```
### 方式二：通过 Skill 安装器安装
以下以 Codex 为例；其他受支持的 AI 工具可替换 `--agent` 参数。
```Bash
# 安装 ark-cua Skill
npx skills add https://skills.volces.com/skills/volcengine/ark -s byted-util-ark-cua --agent codex
```
# 使用方法
## Skill 方式
在已安装 ark-cua 的 AI 工具中，直接用自然语言描述任务即可。例如：`使用 ark-cua 打开浏览器，登录测试环境，查询今天创建的订单并导出 CSV。导出后告诉我记录数，并把文件作为产物返回；如遇验证码或需要业务确认，先向我提问。`
AI 工具会依次检查登录状态、提交原始目标、记录任务 ID，并根据返回状态继续处理：
| outcome | 含义 | 下一步 |
| --- | --- | --- |
| `in_progress` | 任务仍在运行 | 继续执行返回的 `next.command` 或 `watch`。 |
| `needs_input` | 需要用户补充信息 | 原样转达 `input_request.question`，收到答复后执行 `answer`。 |
| `completed` | 任务完成 | 以 `result.text` 为最终结果，并处理产物。 |
| `failed` | 任务失败 | 报告错误码、请求 ID 和安全诊断；不要盲目重试。 |
| `cancelled` | 任务已取消 | 告知用户任务已停止。 |
## 登录 CUA 操作
1. 通过 Skill 让 Agent 返回临时 URL 访问 Computer Use Agent。URL 有效期约 30 分钟，过期后重新获取指令即可。
2. 使用返回的 URL 登录后，可以在左侧的聊天框内发布指令，也可以直接在右侧图形化界面中操作 CUA。
3. **通过配置使用连接器和外设。** CUA 预装了多种软件连接器（Office CLI 等），选择最左侧连接器标签，跟随引导补充配置信息，即可通过 Skill 使用对应能力。当场景需要摄像头或麦克风输入时，也可将本地外设连接至 CUA。
## 关闭 CUA 停止计费
CUA 是按照使用时长计费的，计费频率为小时，因此当确认不再需要使用时，可以通过 Skill 请求关闭 CUA，同步停止计费，以节约使用成本。
关闭 CUA 后，之前签发的云桌面的访问地址同步失效，机器无法使用。
> **注意**
>
> 关闭后机器仅保留 7 天，超过 7 天关闭的 CUA 会被销毁。此时重新运行机器，平台会为你创建全新机器，而不是恢复之前的机器！
# 最佳实践
1. **把目标写成可验收的任务。** 说明目标系统、环境、数据范围、交付物、成功标准和禁止动作。例如"在测试环境创建一条草稿，保存但不要提交审批，并返回草稿编号"比"帮我操作一下系统"更稳定。
2. **优先使用确定性证据。** 同一目标可由多种工具完成时，优先选能产生结构化、可验证结果的路径：Terminal 适合命令和状态检查，Browser 适合网页 DOM 与表单，Computer / UIA 用于原生应用、拖拽和系统级弹窗。不要用坐标点击替代可以通过终端或 DOM 完成的操作。
3. **一个请求只创建一次任务。** 保存首次返回的 `invocation_id` 或 task ID。等待超时不等于任务失败，继续 `watch` 即可；重复 `delegate` 既可能触发冲突，也可能造成重复业务操作和额外消耗。
4. **正确处理人工介入。** 遇到验证码、登录确认、业务审批、不可逆操作或信息不足时，允许任务向调用方转达问题，由调用方将问题原样交给用户后再继续。
5. **将进度、观察和结果分开。** 进度摘要、截图与观察日志只用于了解任务正在发生什么。完成判定必须基于 `outcome == completed`，文件交付必须确认 Artifact 存在可下载内容。
6. **管好凭证和临时访问链接。** API Key 只在本地终端输入并妥善保管；临时桌面票据不进入仓库和群聊，使用完毕或疑似泄露时应立即撤销。
7. **对外部副作用设置边界。** 生产环境写入、发送消息、提交审批、购买、删除和桌面重置等动作，应在目标中明确是否允许，并在不可逆步骤前要求确认。失败时根据稳定错误码处理，不通过盲目重试扩大影响。
# 计费说明
CUA 作为 Agent Plan Harness，计费遵循 Agent Plan Harness 的统一原则：按小时计算费用，抵扣用户积分。
| 场景 | 规则 |
| --- | --- |
| **套餐额度未用尽** | 优先消耗 Agent Plan 套餐额度 / AFP。目前折扣费率为312.5 AFP/CU/小时，活动期内限时2折优惠，费率低至62.5 AFP/CU/小时。套餐内用量通常不再就该 Harness 能力单独推送后付费账单；在 CUA 内的 agent也会消耗token，这部分token消耗是自动通过用户的agent plan结算。 |
| **超额后场景** | 当用户的套餐积分在周期内耗尽，默认关闭 CUA 使用入口，同时机器为用户保留 7 天，用户需要尽快补充积分。 |
| **计量口径** | 平台按照实际占用和使用情况结算费用，结算粒度为小时级别。 |
# 常见问题
- **为什么返回 AUTH_REQUIRED？**
本地没有有效的 Agent Plan API Key，或 Key 已失效。请在自己的本地终端按提示完成配置后重试。不要把 Key 发到对话中。
- **为什么返回 DESKTOP_NOT_BOUND？**
当前账号尚未分配 CUA 桌面。请确认已开通 CUA Harness，并联系管理员或业务支持完成资源分配。
- **为什么返回 ACTIVE_RUN_CONFLICT？**
绑定桌面已有活动任务，新任务未启动。等待现有任务结束；除非用户明确要求，不要取消现有任务或重复提交。
- **watch 超时是否代表任务失败？**
不是。超时只是本次等待窗口结束；只要 outcome 仍为 `in_progress`，继续执行 `watch`。
- **桌面访问链接失效怎么办？**
通过 Skill 让 Agent 重新获取新链接。旧链接不应长期保存或转发。
# 服务协议
- [Harness 能力说明和产品专用条款](/docs/harness-rules)
- [Computer Use Agent 服务规则](/docs/cua-service-rules)