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