Computer Use Agent（简称 CUA）是面向 AI Agent 场景的用户专属云端运行环境，为 Agent 提供可见、可操作的 Windows 云桌面。Agent 可在远端桌面中完成网页浏览、原生应用操作、终端执行、文件处理和多步骤工作流，并通过任务状态、上下文、产物与可观测链路将执行结果返回调用方。本文将介绍购买 Agent Plan 套餐后，如何在 AI 工具中通过 Skill 接入并使用 Computer Use Agent。 # 能力介绍 CUA 是一套"本地操作、远端运行"的 Windows 云桌面系统。支持的核心能力如下： |能力 |说明 | |---|---| |**Windows 云桌面** |通过 ark\-cua skill 获取私有的 URL，随时通过电脑、手机访问你的云桌面，并且支持移动端、PC 端的整体适配。

**桌面端交互：**

**移动端交互：**

| |**浏览器自动化** |通过浏览器结构化能力完成 URL 访问、DOM 读取、网页表单和下载等 Web 任务。

**分析股票行情走势：**

| |**视觉自动化** |结合截图、鼠标键盘和 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）。套餐说明参见 [套餐概览](https://ark.volcengine.com/region:cn-beijing/docs/82379/2366394?lang=zh)。 2. 确认使用地域、账号实名认证和套餐状态符合要求。 ## 步骤二：开启 Computer Use Agent Harness 1. 在 Agent Plan 控制台单击 **Harness**。 ![图片](https://arkdocs.tos-cn-beijing.volces.com/images/CodingPlan/image-20260908-205313-739.png) 2. 在 **Harness** 区域找到 **Computer Use Agent**，开启抵扣开关。 ![图片](https://arkdoc.tos-cn-beijing.volces.com/images/cua/cua/open-cua-harness.png) 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 分钟，过期后重新获取指令即可。 ![图片](https://arkdoc.tos-cn-beijing.volces.com/images/cua/cua-return-url.png) 2. 使用返回的 URL 登录后，可以在左侧的聊天框内发布指令，也可以直接在右侧图形化界面中操作 CUA。 ![图片](https://arkdoc.tos-cn-beijing.volces.com/images/cua/cua-open.png) 3. **通过配置使用连接器和外设。** CUA 预装了多种软件连接器（Office CLI 等），选择最左侧连接器标签，跟随引导补充配置信息，即可通过 Skill 使用对应能力。当场景需要摄像头或麦克风输入时，也可将本地外设连接至 CUA。 ![图片](https://arkdoc.tos-cn-beijing.volces.com/images/cua/cua-switch-tool.png) ## 关闭 CUA 停止计费 CUA 是按照使用时长计费的，计费频率为小时，因此当确认不再需要使用时，可以通过 Skill 请求关闭 CUA，同步停止计费，以节约使用成本。关闭 CUA 后，之前签发的云桌面的访问地址同步失效，机器无法使用。

注意

关闭后机器仅保留 7 天，超过 7 天关闭的 CUA 会被销毁。此时重新运行机器，平台会为你创建全新机器，而不是恢复之前的机器！

![图片](https://arkdoc.tos-cn-beijing.volces.com/images/cua/cua-close.png) # 最佳实践 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 能力说明和产品专用条款](https://ark.volcengine.com/region:cn-beijing/docs/82379/2516291?lang=zh) * [Computer Use Agent 服务规则](https://ark.volcengine.com/region:cn-beijing/docs/82379/2672395?lang=zh)

火山方舟