一行代码切换模型：CUA Agent 框架多模型智能体集成实战教程

一行代码切换模型CUA 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做智能体Agent开发时最容易踩的一个坑是换个模型prompt 模板、工具声明、响应解析全要跟着重写。CUAcomputer-use 2.0 开源项目的 Agent 框架就是为解决这个问题而生的——ComputerAgent用一套统一接口接住了 OpenAI、Anthropic 和本地部署的模型切换后端只需要改一个model参数业务代码一行不动。本文带你走一遍完整路径三步跑通首个代理、给代理装自定义工具、用预算参数管住成本最后讲多模型组合与轨迹调试。先搞清楚CUA Agent 要解决什么问题想象一下你在维护一个会操作电脑的代理今天用 GPT 的 computer-use 模型明天想试试 Claude后天为了省钱切到本地跑的 UI-TARS。如果没有抽象层每次切换你都要重写工具 schema 的声明格式不同 provider 不一样图像上下文的传递方式computer-use 模型吃截图纯文本模型不吃响应里工具调用字段的解析逻辑。CUA Agent 把这层差异收进了模型适配层。你只管写任务 工具框架负责把消息正确翻译给对应模型再把模型的工具调用翻译成对 Computer云桌面/本地桌面的真实动作。下面这张表是框架开箱即给的能力都是仓库里真实存在的模块能力位置说明模型适配器libs/python/agent/cua_agent/adapters/统一封装 OpenAI、Anthropic、HuggingFace 本地模型、Ollama 等工具系统libs/python/computer/computer/helpers.pysandboxed装饰器函数即工具回调机制libs/python/agent/cua_agent/callbacks/预算管理、轨迹保存、图片保留、PII 匿名化、OTel 遥测等自定义代理注册libs/python/agent/cua_agent/decorators.pyregister_agent按模型名注册完全自实现的代理类轨迹记录ComputerAgent的trajectory_dir参数每步操作留痕供回放与训练数据生成三步跑通首个多模型 Agent第 1 步准备运行环境Agent 依赖两块东西Python 侧的agent包以及一个可操作的目标环境。以云端 Linux 容器为例需要准备两个环境变量CUA_CONTAINER_NAME和CUA_API_KEY分别指向你的 CUA 云容器和 API 密钥。完整可运行的参考代码在 libs/python/agent/example.py建议直接对着它调试。第 2 步创建 Computer 与代理from computer import Computer from cua_agent import ComputerAgent # 云环境一个异步上下文管理器管住容器的生命周期 computer Computer( os_typelinux, provider_typecloud, nameos.getenv(CUA_CONTAINER_NAME), api_keyos.getenv(CUA_API_KEY), ) agent ComputerAgent( modelanthropic/claude-sonnet-4-5-20250929, # 换模型只改这一行 tools[computer], # 代理能操作的计算机 only_n_most_recent_images3, # 上下文最多保留最近 3 张截图 use_prompt_cachingTrue, # 提示词缓存省重复计费 trajectory_dirtrajectories, # 轨迹落盘目录 max_trajectory_budget{ # 预算控制注意是字典 max_budget: 1.0, raise_error: True, reset_after_each_run: False, }, verbositylogging.INFO, )model参数采用提供商/模型名的命名规则官方示例中验证过可用的取值模型家族示例模型 ID特点OpenAIopenai/computer-use-preview原生 computer-use 模型Anthropicanthropic/claude-sonnet-4-5-20250929、anthropic/claude-opus-4-20250514Claude 3.5 以上版本UI-TARShuggingface-local/ByteDance-Seed/UI-TARS-1.5-7B开源 GUI 操作模型Ollama 本地ollama_chat/0000/ui-tars-1.5-7b跑在自己机器上组合前缀omniparser任意模型视觉解析与 LLM 分离见下文第 3 步跑任务循环history [] user_input input( ) # 用户输入任务 history.append({role: user, content: user_input}) async for result in agent.run(history, streamFalse): history result[output] # 把消息、工具调用、执行结果追加回上下文result[output]里的每一项有明确类型message模型回复、computer_call桌面动作、function_call工具调用及其输出。想实时打印的话按item[type]分支处理即可。整个运行过程会在 Gradio 调试界面里同步呈现方便观察每一步代理到底干了什么给代理装上自定义工具除了操作桌面代理还能调用你自己写的函数工具。框架支持两种写法共同点是靠类型注解 docstring 自动生成工具规范不用手写 JSON schema。写法一普通函数直接在进程内执行def calculate(a: int, b: int) - int: Calculate the sum of two integers Parameters ---------- a : int First integer b : int Second integer Returns ------- int Sum of two integers return a b写法二sandboxed装饰器执行被隔离在沙箱环境里适合读文件、跑数据分析这类不想污染主进程的操作from computer.helpers import sandboxed sandboxed() def read_file(location: str) - str: Read contents of a file Parameters ---------- location : str Path to the file to read ... with open(location, r) as f: return f.read()把函数和computer一起塞进tools列表就完成了注册agent ComputerAgent(model..., tools[computer, calculate, read_file])几个实践要点docstring 里写清参数含义和返回类型模型理解工具全靠它想让代理更常调用某个工具就把它的描述写得更具体沙箱函数内部自己捕获异常并返回错误信息字符串比直接抛出崩溃更利于代理自行纠错。用预算和回调管住成本多模型代理最大的隐性成本是跑飞了模型反复截图、反复调用工具账单跟着涨。框架给了两档控制手段。第一档构造参数。上面示例里的三个参数就是最常用组合only_n_most_recent_images3——只保留最近 3 张截图进上下文图像 token 开销直接封顶use_prompt_cachingTrue——系统提示与工具规范命中缓存重复轮次不再全价计费max_trajectory_budget——超过max_budget就按raise_error决定是抛错还是继续reset_after_each_run控制每次运行后是否重置额度。第二档回调模块。libs/python/agent/cua_agent/callbacks/ 下提供了一组可插拔模块覆盖不同生命周期需求回调模块用途budget_manager预算超限处理策略trajectory_saver轨迹落盘供回放与训练image_retention图像上下文保留策略pii_anonymization输出中的 PII 匿名化otel/telemetryOpenTelemetry 指标与遥测上报prompt_instructions注入领域指令更极致的定制用register_agent装饰器按模型名正则匹配注册自定义代理类自己实现predict_step、predict_click、get_capabilities从模型交互的每一行代码开始接管。适合医疗、金融这类需要合规输出格式的场景具体协议见 decorators.py 源码。本地模型与混合组合omniparser 前缀纯 API 模型贵纯本地模型准头差。CUA Agent 的解法是前缀组合omniparser任意模型把看屏幕和做决策拆开——视觉解析Omniparser负责把界面元素结构化后面接的 LLM 负责推理和规划两者可以分别选最合适的实现# 视觉解析 云端大模型 modelomniparseranthropic/claude-sonnet-4-5-20250929 # 视觉解析 本地模型整条链路零 API 费用 modelomniparserollama_chat/0000/ui-tars-1.5-7b这套组合方式对混合部署很实用日常轻量任务走本地 Ollama复杂任务再切回 API 模型切换依旧是改一行model字符串。看代理到底做了什么轨迹调试代理做错了不可怕可怕的是不知道它为什么错。trajectory_dir会把每轮的截图、模型消息、工具调用参数、执行结果全部落盘配合仓库自带的轨迹查看器可以逐步回放一眼看出是定位点错了还是动作参数传错了排查思路可以固定成三步先确认失败那步的截图里元素是否真的可点视觉问题再看工具调用的参数模型理解问题最后看执行结果反馈环境/权限问题。如果失败模式反复出现再把这段轨迹存下来作为回归用例。避坑清单下面这几条是新手最容易卡住的地方来自官方示例代码的约束model的 ID 要写全提供商前缀/模型名一个字符都不能少anthropic和anthropic/claude-sonnet-4-5-20250929是完全不同的东西。max_trajectory_budget是字典不是数字直接传1.0不会生效正确写法见上文示例。Computer是异步上下文管理器要用async with包住否则容器资源不会释放。工具函数必须有 docstring没有参数说明模型拿到的是空 schema调用质量会明显下降。API 密钥走环境变量CUA_API_KEY、CUA_CONTAINER_NAME不要硬编码进代码或轨迹文件。截图数量要有上限长任务里不加only_n_most_recent_images上下文会随轮次线性膨胀。延伸入口想看什么去哪里完整可运行示例libs/python/agent/example.pyAgent 核心源码libs/python/agent/cua_agent/各模型接入说明docs/content/docs/use-cua-with/OpenAI、Anthropic、Ollama 等一篇一个模型什么是 computer usedocs/content/docs/concepts/what-is-computer-use.mdx项目 READMEREADME.md版本说明本文示例代码对照仓库当前libs/python/agent/下的 agent 包libs/python/agent/example.py中列出的模型清单整理不同版本间模型 ID 与参数 API 可能存在差异请以对应版本文档为准。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考