Computer Use Agent（CUA）是一款运行在云端沙箱桌面、基于多模态大模型的企业级 AI 智能体，专为交付「浏览器 + 桌面 OS / App」任务而设计。它通过视觉理解屏幕、自主规划步骤、稳定执行鼠标键盘动作，在真实桌面环境中代替用户完成端到端任务，让企业用户获得「对话即办事」的全新体验。 ## 前提条件 * 已完成 [火山引擎账号注册](https://www.volcengine.com/docs/6261/64925) 和 [实名认证](https://www.volcengine.com/docs/6261/64935)。 * 已 [完成跨服务授权](https://console.volcengine.com/iam/service/attach_role/?ServiceName=ipaas)。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_e4e6d9594f0a4df698b92a73c1b1bf43.png) * 已 [开通 CUA 服务](https://console.volcengine.com/ACEP/cua/new-task)。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_82214989a0b7e33ed006e6a7f6cd5abf.png) ## 限时免费体验平台为您提供了 **30 分钟免费体验活动**，您可以在此期间方便、快捷的体验 CUA 功能，确认其是否满足您的业务需求。

注意

请在免费体验有效期内完成体验，超时后沙箱将自动回收，其中的数据均会删除且无法找回。

1. 登录 [CUA 体验中心](https://console.volcengine.com/ACEP/computer-use-agent/experience-center)。 2. 按需选择沙箱操作系统类型，并单击“立即启动”按钮。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_fbc19cfbf1178236e3344df8c718feba.png) 3. 待沙箱创建成功后，即可开始体验。 * **基础功能** 发起任务您可以在左侧通过对话，为 CUA 安排网页信息搜集、沙箱桌面操作等任务。

说明

若您安排的任务存在人机验证、密码输入等操作，可根据提示在右侧沙箱桌面中完成相应操作，CUA 将自动继续任务。

* **示例 Prompt：** 使用豆包网页版生成几张Q版的白色小狗在蓝天、白云的草地玩耍的图片，并且将图片下载下来。 * **示例效果：**

管理对话 * 创建新对话单击“新对话”按钮，即可创建新对话。

说明

首次新建的对话默认命名为 “新对话”，完成首轮对话后，系统将自动把该默认名称更新为首条对话内容（超出 60 字符仅截取前 60 字符）。

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_347d8d87abc092bb0f5cb73eff18808f.png) * 切换/删除历史对话 1. 单击列表图标 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_17c64e52be1d378f26db53924f90e7df.png) 2. 单击目标历史对话，即可切换至对应对话。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_419cf2971200cab2ffbc08df2abc9c2a.png) 3. 若您不再使用历史对话，可单击目标对话右侧删除图标，并在弹窗中单击“删除”按钮进行删除。

注意

对话删除后无法恢复，请谨慎操作。

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_591e813a2a960466045903d29b315575.png) 管理沙箱 * 查看沙箱系统信息单击“系统信息”按钮，即可在弹窗中了解当前 CUA 沙箱的 ID、运行沙箱的主机类型等信息。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_a2905c91ff04cb31cdae561a5e615e21.png) * 切换/删除沙箱 1. 若您创建了多个 CUA 沙箱，可在下拉列表中进行切换。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_5b418719c28d0a7147e1d7967778ca2b.png) 2. 若存在您不再使用的沙箱，可在列表中单击其右侧的删除图标，并在弹窗中单击“删除沙箱”按钮进行删除。

注意

沙箱删除后无法恢复，其中的数据也无法找回，请谨慎操作。

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_ac48888d1233f240e466140d70dbfc20.png) * **高级功能** CUA 还为您提供了任务提示词一键优化、视频转提示词等高级功能，您可以在体验过程中逐一试用，获得更好的任务执行效果。任务提示词优化一键将您输入的口语化指令自动改写为结构清晰的提示词，提升任务成功率。 1. 请在对话框中输入任务提示词。 2. 单击任务提示词优化图标。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_c7921d87c418f69a54e9a4f564742996.png) 3. 若优化结果满足要求，您可以单击“应用”按钮将其添加至对话框，按需调整后即可发送给 CUA 执行。否则，也可单击“重新生成”按钮再次进行优化。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_a4aa9dfb6df95aa813da50c5e8f9dfe6.png) 录制生成提示词您可以录制一段人工操作演示，CUA 将根据录制的视频自动反推出对应操作的任务提示词，适合复杂或多步骤任务。 1. 单击“录制生成提示词”按钮。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_03e49d851dcf247a8f46cc502d2cf6ed.png) 2. 单击“开始录制”按钮。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_7ce9a7eeddc4a86262893393b69a1406.png) 3. 按需在沙箱桌面中进行操作，并在操作完成后，单击“结束录制”按钮。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_9be51e9c8002b66d66b611faea075f04.png) 4. 确认录制信息后，单击“开始生成提示词”按钮。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_91d0657980100a5f92c29abcdc232be7.png) 5. CUA 将根据录屏自动生成提示词，请耐心等待。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_cc9e882c00ed23ac101b2adf52bcae2e.png) 6. 成功生成提示词后，您可以单击“编辑”按钮按需调整，再单击“立即执行”按钮让 CUA 自动执行。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_e2a4b39b9fd2df2288e7c4a651e3b4d4.png) Agent 会话设置为当前会话配置其单会话最大推理步数、截图策略及省流模式，平衡执行深度与 Token 消耗。

注意

该配置仅对当前对话有效，不会影响您创建的新对话或其他历史对话。

1. 单击对话框中的设置图标并选择“Agent 会话设置”。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_0cbd69fb3c7a711f050cb49b623d969b.png) 2. 按需调整如下参数。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_f2d105b19b1a85f92083fabaca0c32f2.png) 系统提示词设置通过系统提示词，您可以指定 CUA 在当前对话中的行为准则、工作流程等要求，决定 CUA 如何响应和处理您输入的 Prompt。

注意

该配置仅对当前对话有效，不会影响您创建的新对话或其他历史对话。

修改提示词可能影响系统行为和输出质量。

1. 单击对话框中的设置图标并选择“系统提示词设置”。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_bd22a20727a624ec0316d636838c19a4.png) 2. 单击“修改提示词”按钮，并在输入框中按需填写要求。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_a47c19860df334b61239bd69df25c9e2.png) 3. **（可选）** 单击“Prompt 优化”按钮，可一键将输入的口语化信息自动修改为结构清晰的提示词。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_4662aa295223c6b94426022bcc832abd.png) * 若优化结果满足要求，您可以单击“应用”按钮将其添加至输入框并保存。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_c0aaeb56fcb3d9ebc2f41350fa895f27.png) * 若优化结果满足要求，也可单击“重新生成”按钮再次进行优化。 4. 完成修改后，单击“保存修改”按钮即可。 * **通用设置** 您可以将不同平台的登录账号及密码，知识库内容等上传至 CUA，所有 CUA 沙箱在执行任务时都可以按需使用其中内容，无需每次手动输入。密钥管理 CUA 为您提供了基于火山引擎 Jeddak AICC 的密钥管理功能，您可以在其中安全的托管不同网站登录凭据，CUA 在需要登录时可自动使用托管的凭证完成登录认证。 1. 单击“全局设置”按钮。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_0f3ce34aea5f38f21125e57c439f446b.png) 2. 在左侧目录树选择“通用设置 \> 密钥管理”。 3. 单击“添加密钥”按钮，填写您希望托管的网站地址、登录账号及密码信息。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_6e62a449127590fef0f281420d58c9ca.png) 4. 单击“确定”按钮完成操作。知识库管理您可以将业务背景、操作规范等资料上传至 CUA 作为知识库，Agent 在执行任务时可将知识库内容作为上下文进行参考。 1. 单击“全局设置”按钮。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_0f3ce34aea5f38f21125e57c439f446b.png) 2. 在左侧目录树选择“通用设置 \> 知识库管理”。 3. 单击“添加知识库”按钮，填写知识库名称与备注信息，并导入本地文件。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_fbba8fddfab1246522643224f1092ead.png) 4. 待知识库构建完成后，您可以在需要使用知识库内容作为上下文的对话中，单击知识库图标并勾选目标知识库即可。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_376afa4d6930b633dc6c6bd0dcb75c1c.png) ## 使用 ECS 实例部署 CUA 如需在自有环境中正式、长期的使用 CUA，您可以将已订购的火山引擎云服务器实例添加为 CUA 的设备节点资源，CUA 将部署并运行在您指定的 ECS 中。 ### 步骤一：准备资源 1. 登录 [火山引擎云服务器控制台](https://console.volcengine.com/ecs/region:ecs+cn-beijing/instance?projectName=default)。 2. **（可选）** 若您还未创建作为 CUA 设备的云服务器，可根据 [通过向导购买实例](https://www.volcengine.com/docs/6396/67743) 指引，购买符合如下要求的云服务器实例。 |**配置项** |**推荐配置** | |---|---| |**基础配置** || |地域和可用区 |暂仅支持选择 **华北2（北京）** 地域下任意可用区中的实例。 | |计算规格 |不限制实例规格族，仅需选择 2 vCPU、4 GiB 内存及以上规格即可。

说明

建议您购买 4 vCPU、8 GiB 内存及以上规格实例，获得更好的体验。

| |镜像 |* Debian 11、12 及以上版本

* Ubuntu 24.04 及以上版本

说明

使用公共镜像时，请勾选启动时安装云助手 Agent，该工具是火山引擎提供的原生自动化运维工具。支持通过云助手Agent，以免密码、免登录、无需使用跳板机的形式，在云服务器实例中批量执行运维命令。

使用非公共镜像时，请在实例创建后自行安装与助手 Agent。

| |**网络配置** || |公网IP |勾选“分配弹性公网IP”。 | 3. 登录 [云助手客户端管理控制台](https://console.volcengine.com/ecs/region:ecs+cn-beijing/invocations?tab=instanceList)，确认您的实例已 [安装云助手 Agent](https://www.volcengine.com/docs/6396/147514) 且 Agent 处于 **运行中** 状态。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_df3f771d7e4d1cc8a3140953078bcb5c.png) 4. 修改实例安全组配置，在其“入方向”放通“8910”端口，CUA 服务将通过该端口与 ECS 进行的通信。 1. 登录 [实例控制台](https://console.volcengine.com/ecs/region:ecs+cn-shanghai/instance)，单击目标实例名称进入其详情页。 2. 选择“安全组”页签，单击目标安全组（本文以Default为例）右侧“配置规则”按钮。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_63f7949e9eef47049d3e49505b340219.png) 3. 选择“访问控制 \> 入向规则”页签，单击“添加规则”按钮。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_d5107065812fa948b83e1f8a8e09601f.png) 4. 允许通过TCP协议访问“8910”端口。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_232c284831f2c7fbde7ffd2afc8ca8cb.png) ### 步骤二：添加设备资源 1. 登录 [CUA 设备资源控制台](https://console.volcengine.com/ACEP/computer-use-agent/node-resource)。 2. 单击“添加设备”按钮。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_2f7c6e471fcc1372c7f6e692dd5b3f8d.png) 3. 在列表页中按需勾选目标实例，单击“下一步：组件配置”按钮。

注意

请确认待添加的实例处于 运行中 状态，添加停机状态的云服务器可能导致添加节点失败。

4. 确认待安装的平台功能组件，单击“下一步：配置确认”按钮。 5. 确认实例与组件信息无误后，单击“完成”按钮提交添加设备申请。 ### 步骤三：发起任务 1. 待设备创建完成后，在左侧目录树选择“新任务”。 2. 在对话框中选择您添加的目标设备，即可通过对话发起 CUA 任务。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_d11d5e89f5ddad050b58c2aacf7b5e7b.png) ## OpenAPI 快速接入除控制台操作外，CUA 还为您提供了 OpenAPI，您可以通过 OpenAPI 将任务下发、状态查询等能力嵌入自有业务系统。 1. [获取 AccessKey、SecretKey](https://www.volcengine.com/docs/6291/65568)，并将其配置为环境变量 `VOLC_ACCESSKEY` 、`VOLC_SECRETKEY`。 2. 在您的本地环境中执行如下命令，安装火山引擎 Python SDK。 ```Python pip install volcengine-python-sdk ``` 3. 参考如下示例代码进行接入。 ```Python import os import time import uuid import volcenginesdkcore from volcenginesdkcore.rest import ApiException if __name__ == '__main__': # 从环境变量获取 AK/SK ak = os.environ.get("VOLC_ACCESSKEY") sk = os.environ.get("VOLC_SECRETKEY") # 配置 SDK configuration = volcenginesdkcore.Configuration() configuration.ak = ak configuration.sk = sk configuration.region = "cn-beijing" # 创建 API 客户端 api_instance = volcenginesdkcore.UniversalApi( volcenginesdkcore.ApiClient(configuration) ) # ----------------------------- # 请替换为实际参数 # ----------------------------- ecs_id = "" # CUA 节点对应的 ECS 实例 ID cua_node_id = 123 # 节点 ID tos_bucket = "" # TOS 桶名称 tos_endpoint = "" # TOS endpoint，例如：https://tos-cn-beijing.volces.com tos_region = "" # TOS region，例如：cn-beijing user_prompt = "打开浏览器并搜索火山引擎" try: # ========================================================= # 1. 创建 noVNC 拉流会话 # 接口：CreateCuaNodeNoVNCSession # 服务：cua 版本：2024-01-01 # ========================================================= novnc_body = {} if cua_node_id is not None: novnc_body["Id"] = cua_node_id if ecs_id: novnc_body["Ecsid"] = ecs_id if not novnc_body: raise ValueError("Id 和 Ecsid 需要二选一传入，不能都为空") novnc_resp = api_instance.do_call( volcenginesdkcore.UniversalInfo( method="POST", action="CreateCuaNodeNoVNCSession", service="cua", version="2024-01-01", content_type="application/json" ), volcenginesdkcore.Flatten(novnc_body).flat() ) print("\nCreateCuaNodeNoVNCSession response:") print(novnc_resp) novnc_result = novnc_resp.get("Result", novnc_resp) print("\nnoVNC 会话信息：") print("ViewerUrl :", novnc_result.get("ViewerUrl")) print("WebsocketUrl:", novnc_result.get("WebsocketUrl")) print("ExpiresAt :", novnc_result.get("ExpiresAt")) # ========================================================= # 2. 运行 Agent 任务 # 接口：RunAgentTaskOneStep # 服务：ipaas 版本：2023-08-01 # ========================================================= run_body = volcenginesdkcore.Flatten({ "RunName": "computer-use 测试 demo", "ThreadId": str(uuid.uuid4()), "AgentType": "cua", "Ecsid": ecs_id, "UserPrompt": user_prompt, "TosBucket": tos_bucket, "TosEndpoint": tos_endpoint, "TosRegion": tos_region }).flat() run_resp = api_instance.do_call( volcenginesdkcore.UniversalInfo( method="POST", action="RunAgentTaskOneStep", service="ipaas", version="2023-08-01", content_type="application/json" ), run_body ) print("\nRunAgentTaskOneStep response:") print(run_resp) run_info = run_resp.get("Result", run_resp) run_id = run_info["RunId"] print("\nRunId:", run_id) # ========================================================= # 3. 轮询 Agent 当前步骤 # 接口：ListAgentRunCurrentStep # 服务：ipaas 版本：2023-08-01 # 状态 3/5/6/7 表示任务结束 # ========================================================= time.sleep(5) # 等待任务开始执行 while True: step_resp = api_instance.do_call( volcenginesdkcore.UniversalInfo( method="GET", action="ListAgentRunCurrentStep", service="ipaas", version="2023-08-01", content_type="application/json" ), volcenginesdkcore.Flatten({"RunId": run_id}).flat() ) print("\nListAgentRunCurrentStep response:") print(step_resp) step_info = step_resp.get("Result", step_resp) if step_info.get("Status") in [3, 5, 6, 7]: print("\n任务已结束，最终状态:", step_info.get("Status")) break time.sleep(2) # 继续轮询 # ========================================================= # 4. 获取 Agent 任务结果 # 接口：GetAgentResult # 服务：ipaas 版本：2023-08-01 # ========================================================= result_resp = api_instance.do_call( volcenginesdkcore.UniversalInfo( method="GET", action="GetAgentResult", service="ipaas", version="2023-08-01", content_type="application/json" ), volcenginesdkcore.Flatten({"RunId": run_id}).flat() ) print("\nGetAgentResult response:") print(result_resp) except ApiException as e: print(f"API Exception: {e}") except Exception as e: print(f"General Exception: {e}") ``` * **调用流程说明** 1. 调用 CreateCuaNodeNoVNCSession 接口，创建 noVNC 可视化会话。 2. 调用 RunAgentTaskOneStep 接口，传入 UserPrompt（自然语言指令）、目标节点 EcsId 等参数下发任务，返回 RunId。 3. 调用 ListAgentRunCurrentStep 接口，通过 RunId 轮询任务当前执行步骤，配合回调地址获取最终结果。 4. 调用 GetAgentResult 接口，通过 RunId 查看任务执行结果。 * **参数说明** 下表为您汇总了示例代码中需要您自行填写的参数信息。 |参数 |说明 | |---|---| |cua_node_id |请填写 CUA 节点 ID。 | |ecs_id |请填写作为 CUA 设备的云服务器实例 ID，您可以登录 [火山引擎云服务器控制台](https://console.volcengine.com/ecs/region:ecs+cn-beijing/instance?projectName=default) 获取。

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_4229b00a658ca3875dea2e2d9be04935.png)

说明

若您还未创建作为 CUA 设备的云服务器，请根据准备资源指引创建实例。

| |tos_bucket |请填写用于结果回流的 TOS 桶名称，您可以登录 [对象存储控制台](https://console.volcengine.com/tos/bucket?projectName=default) 获取。 | |tos_endpoint |请填写用于结果回流的 TOS 桶 Endpoint，您可以登录 [对象存储控制台](https://console.volcengine.com/tos/bucket?projectName=default) 获取。 | |tos_region |请填写用于结果回流的 TOS 桶所属地域的 Region ID，您可以登录 [对象存储控制台](https://console.volcengine.com/tos/bucket?projectName=default) 查看其所属地域，并参考 [地域和访问域名（Endpoint）](https://www.volcengine.com/docs/6349/107356) 获取该地域的 Region ID。 |

云手机