一行代碼切換模型CUA Agent 框架多模型智能體集成實戰(zhàn)教程【免費下載鏈接】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開發(fā)時最容易踩的一個坑是換個模型prompt 模板、工具聲明、響應解析全要跟著重寫。CUAcomputer-use 2.0 開源項目的 Agent 框架就是為解決這個問題而生的——ComputerAgent用一套統(tǒng)一接口接住了 OpenAI、Anthropic 和本地部署的模型切換后端只需要改一個model參數(shù)業(yè)務代碼一行不動。本文帶你走一遍完整路徑三步跑通首個代理、給代理裝自定義工具、用預算參數(shù)管住成本最后講多模型組合與軌跡調(diào)試。先搞清楚CUA Agent 要解決什么問題想象一下你在維護一個會操作電腦的代理今天用 GPT 的 computer-use 模型明天想試試 Claude后天為了省錢切到本地跑的 UI-TARS。如果沒有抽象層每次切換你都要重寫工具 schema 的聲明格式不同 provider 不一樣圖像上下文的傳遞方式computer-use 模型吃截圖純文本模型不吃響應里工具調(diào)用字段的解析邏輯。CUA Agent 把這層差異收進了模型適配層。你只管寫任務 工具框架負責把消息正確翻譯給對應模型再把模型的工具調(diào)用翻譯成對 Computer云桌面/本地桌面的真實動作。下面這張表是框架開箱即給的能力都是倉庫里真實存在的模塊能力位置說明模型適配器libs/python/agent/cua_agent/adapters/統(tǒng)一封裝 OpenAI、Anthropic、HuggingFace 本地模型、Ollama 等工具系統(tǒng)libs/python/computer/computer/helpers.pysandboxed裝飾器函數(shù)即工具回調(diào)機制libs/python/agent/cua_agent/callbacks/預算管理、軌跡保存、圖片保留、PII 匿名化、OTel 遙測等自定義代理注冊libs/python/agent/cua_agent/decorators.pyregister_agent按模型名注冊完全自實現(xiàn)的代理類軌跡記錄ComputerAgent的trajectory_dir參數(shù)每步操作留痕供回放與訓練數(shù)據(jù)生成三步跑通首個多模型 Agent第 1 步準備運行環(huán)境Agent 依賴兩塊東西Python 側(cè)的agent包以及一個可操作的目標環(huán)境。以云端 Linux 容器為例需要準備兩個環(huán)境變量CUA_CONTAINER_NAME和CUA_API_KEY分別指向你的 CUA 云容器和 API 密鑰。完整可運行的參考代碼在 libs/python/agent/example.py建議直接對著它調(diào)試。第 2 步創(chuàng)建 Computer 與代理from computer import Computer from cua_agent import ComputerAgent # 云環(huán)境一個異步上下文管理器管住容器的生命周期 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參數(shù)采用提供商/模型名的命名規(guī)則官方示例中驗證過可用的取值模型家族示例模型 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 步跑任務循環(huán)history [] user_input input( ) # 用戶輸入任務 history.append({role: user, content: user_input}) async for result in agent.run(history, streamFalse): history result[output] # 把消息、工具調(diào)用、執(zhí)行結(jié)果追加回上下文result[output]里的每一項有明確類型message模型回復、computer_call桌面動作、function_call工具調(diào)用及其輸出。想實時打印的話按item[type]分支處理即可。整個運行過程會在 Gradio 調(diào)試界面里同步呈現(xiàn)方便觀察每一步代理到底干了什么給代理裝上自定義工具除了操作桌面代理還能調(diào)用你自己寫的函數(shù)工具?？蚣苤С謨煞N寫法共同點是靠類型注解 docstring 自動生成工具規(guī)范不用手寫 JSON schema。寫法一普通函數(shù)直接在進程內(nèi)執(zhí)行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裝飾器執(zhí)行被隔離在沙箱環(huán)境里適合讀文件、跑數(shù)據(jù)分析這類不想污染主進程的操作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()把函數(shù)和computer一起塞進tools列表就完成了注冊agent ComputerAgent(model..., tools[computer, calculate, read_file])幾個實踐要點docstring 里寫清參數(shù)含義和返回類型模型理解工具全靠它想讓代理更常調(diào)用某個工具就把它的描述寫得更具體沙箱函數(shù)內(nèi)部自己捕獲異常并返回錯誤信息字符串比直接拋出崩潰更利于代理自行糾錯。用預算和回調(diào)管住成本多模型代理最大的隱性成本是跑飛了模型反復截圖、反復調(diào)用工具賬單跟著漲?？蚣芙o了兩檔控制手段。第一檔構(gòu)造參數(shù)。上面示例里的三個參數(shù)就是最常用組合only_n_most_recent_images3——只保留最近 3 張截圖進上下文圖像 token 開銷直接封頂use_prompt_cachingTrue——系統(tǒng)提示與工具規(guī)范命中緩存重復輪次不再全價計費max_trajectory_budget——超過max_budget就按raise_error決定是拋錯還是繼續(xù)reset_after_each_run控制每次運行后是否重置額度。第二檔回調(diào)模塊。libs/python/agent/cua_agent/callbacks/ 下提供了一組可插拔模塊覆蓋不同生命周期需求回調(diào)模塊用途budget_manager預算超限處理策略trajectory_saver軌跡落盤供回放與訓練image_retention圖像上下文保留策略pii_anonymization輸出中的 PII 匿名化otel/telemetryOpenTelemetry 指標與遙測上報prompt_instructions注入領域指令更極致的定制用register_agent裝飾器按模型名正則匹配注冊自定義代理類自己實現(xiàn)predict_step、predict_click、get_capabilities從模型交互的每一行代碼開始接管。適合醫(yī)療、金融這類需要合規(guī)輸出格式的場景具體協(xié)議見 decorators.py 源碼。本地模型與混合組合omniparser 前綴純 API 模型貴純本地模型準頭差。CUA Agent 的解法是前綴組合omniparser任意模型把看屏幕和做決策拆開——視覺解析Omniparser負責把界面元素結(jié)構(gòu)化后面接的 LLM 負責推理和規(guī)劃兩者可以分別選最合適的實現(xiàn)# 視覺解析 云端大模型 modelomniparseranthropic/claude-sonnet-4-5-20250929 # 視覺解析 本地模型整條鏈路零 API 費用 modelomniparserollama_chat/0000/ui-tars-1.5-7b這套組合方式對混合部署很實用日常輕量任務走本地 Ollama復雜任務再切回 API 模型切換依舊是改一行model字符串?？创淼降鬃隽耸裁窜壽E調(diào)試代理做錯了不可怕可怕的是不知道它為什么錯。trajectory_dir會把每輪的截圖、模型消息、工具調(diào)用參數(shù)、執(zhí)行結(jié)果全部落盤配合倉庫自帶的軌跡查看器可以逐步回放一眼看出是定位點錯了還是動作參數(shù)傳錯了排查思路可以固定成三步先確認失敗那步的截圖里元素是否真的可點視覺問題再看工具調(diào)用的參數(shù)模型理解問題最后看執(zhí)行結(jié)果反饋環(huán)境/權(quán)限問題。如果失敗模式反復出現(xiàn)再把這段軌跡存下來作為回歸用例。避坑清單下面這幾條是新手最容易卡住的地方來自官方示例代碼的約束model的 ID 要寫全提供商前綴/模型名一個字符都不能少anthropic和anthropic/claude-sonnet-4-5-20250929是完全不同的東西。max_trajectory_budget是字典不是數(shù)字直接傳1.0不會生效正確寫法見上文示例。Computer是異步上下文管理器要用async with包住否則容器資源不會釋放。工具函數(shù)必須有 docstring沒有參數(shù)說明模型拿到的是空 schema調(diào)用質(zhì)量會明顯下降。API 密鑰走環(huán)境變量CUA_API_KEY、CUA_CONTAINER_NAME不要硬編碼進代碼或軌跡文件。截圖數(shù)量要有上限長任務里不加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版本說明本文示例代碼對照倉庫當前l(fā)ibs/python/agent/下的 agent 包libs/python/agent/example.py中列出的模型清單整理不同版本間模型 ID 與參數(shù) API 可能存在差異請以對應版本文檔為準?！久赓M下載鏈接】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創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考