企业官网建设流程全解析

CUA ComputerAgent 实操：一行 model 切换 OpenAI、Claude 与本地 UI-TARS 跑同一个桌面任务

【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua

写桌面 Agent 最磨人的，往往不是模型本身，而是切换模型：OpenAI 的 computer-use-preview 一套 API 形态，Anthropic 的 Claude 另一套，本地 UI-TARS 还得自己拼请求。CUA 的 ComputerAgent 把这件事压成了一个model字符串——同一套任务循环、工具集和轨迹记录，改一行模型名就换后端，不用动业务代码。🧩

三种写法切换模型：一条 model 字符串的路由规则

ComputerAgent 底层走 litellm，框架内部注册了一批适配器，运行时按模型名匹配对应的 agent loop 再分发请求。也就是说，模型选择是「字符串路由」，不需要为每个模型写实例化代码。

官方示例 libs/python/agent/example.py 中确认过这些写法：

• openai/computer-use-preview：OpenAI 的 computer-use 模型
• anthropic/claude-3-7-sonnet-20250219等：Claude 系列
• huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B：HuggingFace 本地部署
• ollama_chat/0000/ui-tars-1.5-7b：本地 Ollama 服务
• omniparser+<任意模型>：前缀叠加 OmniParser，把 UI 解析能力和任意 LLM 组合起来

匹配逻辑（正则 + 优先级）在 libs/python/agent/cua_agent/decorators.py 里，读一遍就能明白「为什么换模型不改代码」。

十行代码把 Agent 接到云端桌面上

Agent 需要一个操作对象，Computer来自 computer 包，支持本地系统与云容器两种接法，示例里用的是云端 Linux 容器：

from computer import Computer from cua_agent import ComputerAgent async with Computer(os_type="linux", provider_type="cloud", name=os.getenv("CUA_CONTAINER_NAME"), api_key=os.getenv("CUA_API_KEY")) as computer: agent = ComputerAgent( model="openai/computer-use-preview", tools=[computer], trajectory_dir="trajectories", max_trajectory_budget={"max_budget": 1.0, "raise_error": True}, ) history = [{"role": "user", "content": "打开浏览器查一下天气"}] async for result in agent.run(history, stream=False): history += result["output"]

几个参数值得留意：

• tools=[computer]：桌面本身就是第一件工具，点击、输入、截图都由它承担
• trajectory_dir：每一步落盘成轨迹文件，供回放与评估
• max_trajectory_budget：dict 形式设单次预算上限，raise_error=True超支即抛错
• use_prompt_caching/only_n_most_recent_images：提示词缓存、限制上下文图片数量，控制成本

给 Agent 加工具：函数工具和 computer 处理器两条路

函数工具最轻。普通 Python 函数加上类型注解和 docstring，再用@sandboxed()装饰，执行就落在沙箱里：

from computer.helpers import sandboxed @sandboxed() def read_file(location: str) -> str: """Read contents of a file 读取文件内容，返回文本或错误信息""" with open(location) as f: return f.read()

把read_file直接塞进tools即可，框架依据注解与 docstring 自动生成工具调用规范交给模型，@sandboxed的实现在 libs/python/computer/computer/helpers.py。

第二条路是computer 处理器：需要长驻进程或独立 UI 的工具（编辑器、可视化面板之类），实现AsyncComputerHandler协议后挂到 computer 上。协议定义在 libs/python/agent/cua_agent/computers.py。

预算与轨迹：上生产前必开的两个开关

💰预算：max_trajectory_budget是最粗也最稳的一档，更细的控制交给回调——BudgetManagerCallback、TrajectorySaverCallback之外，回调模块还提供了消息预处理、工具调用拦截、OTel 遥测、图片留存等生命周期钩子，全集见 libs/python/agent/cua_agent/callbacks/。

📊轨迹：跑完一轮任务，trajectory_dir下就有完整轨迹，配合仓库自带的轨迹查看器可以逐步回放整个执行过程，排查「模型为什么点错了」这类问题。查看器介绍见 blog/trajectory-viewer.md。

用 register_agent 注册自己的 agent loop

想接自家模型、或换一套提示词策略？@register_agent把「模型 → agent loop」的映射变成一张注册表：

from cua_agent.decorators import register_agent @register_agent(models=r"^ollama_chat/.*ui-tars.*", priority=10) class MyUITarsLoop: async def predict_step(self, *args, **kwargs): ... async def predict_click(self, *args, **kwargs): ... def get_capabilities(self): return ["step", "click"]

• models是正则，模型名命中即生效
• priority决定多条规则命中时的先后，tool_type可声明绑定 browser/mobile 工具类型
• 类必须实现predict_step、predict_click、get_capabilities，装饰器注册时就会校验

现成的 loop 实现都在 libs/python/agent/cua_agent/loops/，openai、anthropic、gemini、uitars、omniparser 等可以直接抄。

接下来做三件事

✅ 先用 Ollama 的 UI-TARS 在本地把 libs/python/agent/example.py 跑通，验证工具与桌面链路没问题，再切到 API 模型。

✅ 上生产前把max_trajectory_budget与trajectory_dir两个开关打开，超支和回放都有兜底。

✅ 换模型后别只看单次成败，用轨迹查看器对比不同模型的步数与点击质量，再决定默认模型。

想继续深入，从 docs/content/docs/how-to-guides/agent-context/ 的 Agent 接入指南开始读即可。

【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua