Cua App-Use 实战指南：用虚拟桌面把 Agent 限制在指定应用中-北京尧图网络

Cua App-Use 实战指南用虚拟桌面把 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/cuaApp-Use 是 Cua 生态中的一项实验性功能它允许你在 macOS 上创建只包含指定应用的虚拟桌面会话从而把 Agent 的视觉与交互范围收窄到 Safari、Notes、iPhone Mirroring 等具体应用上实现更聚焦的任务执行与多 Agent 并行调度。读完本文你将掌握 App-Use 的启用方式、create_desktop_from_apps的核心用法、多 Agent 并行工作流的搭建方法以及它在仓库源码中的底层实现原理。什么是 App-UseApp-Use 的核心思想是不再让 Agent 面对整个屏幕而是只给它看它该看的那几个应用。通过Computer实例上的create_desktop_from_apps()方法你可以创建按应用名白名单过滤的虚拟桌面会话例如只让 Agent 操作 Safari 和 Notes或只允许控制 iPhone Mirroring 应用。在 libs/python/computer/computer/computer.py 中该方法的实现非常简洁——它校验experiments中是否包含app-use然后返回一个基于底层 computer 接口的DioramaComputer代理对象def create_desktop_from_apps(self, apps): assert ( app-use in self.experiments ), App Usage is an experimental feature. Enable it by passing experiments[app-use] to Computer() from .diorama_computer import DioramaComputer return DioramaComputer(self, apps)最小启用示例# Create a macOS VM with App Use experimental feature enabled computer Computer(experiments[app-use]) # Create a desktop limited to specific apps desktop computer.create_desktop_from_apps([Safari, Notes]) # Your agent can now only see and interact with these apps agent ComputerAgent( modelanthropic/claude-sonnet-4-5-20250929, tools[desktop] )实验性功能与平台限制注意App-Use 目前是实验性功能必须显式传入experiments[app-use]特性开关才能使用。仓库源码对这一点做了双重强制校验调用create_desktop_from_apps()时若未启用该实验开关会直接触发assert报错见 computer.py在Computer.__init__中只要启用了app-use实验特性就会断言os_type macos否则报错App use experiment is only supported on macOS见 computer.py。也就是说当前 App-Use 仅支持 macOS这与其底层依赖 Quartz 合成引擎的技术路线直接相关下文工作原理会展开。App-Use 的核心优势1. 轻量快速视觉过滤而非进程隔离App-Use 创建的是视觉过滤器而不是新进程。应用照常运行Cua 只是控制了 Agent能看到什么、能点哪里。这些虚拟桌面是合成视图composited views除了既有的窗口管理器操作外不需要额外的计算资源。从服务端源码看这正是一个纯粹的合成层实现Diorama被定义为 A virtual desktop manager for macOS它负责管理应用窗口并为截图、鼠标交互、键盘输入、坐标变换提供统一接口见 libs/python/computer-server/computer_server/diorama/diorama.py。2. 多 Agent 并行一个桌面部署一支专业化 Agent 团队每个虚拟桌面可以独立分配给一个 Agent多个 Agent 可以针对各自的应用集合并行工作。由于各会话之间保持窗口布局隔离互不干扰。# Create a Computer with App Use enabled computer Computer(experiments[app-use]) # Research agent focuses on browser research_desktop computer.create_desktop_from_apps([Safari]) research_agent ComputerAgent(tools[research_desktop], ...) # Writing agent focuses on documents writing_desktop computer.create_desktop_from_apps([Pages, Notes]) writing_agent ComputerAgent(tools[writing_desktop], ...) async def run_agent(agent, task): async for result in agent.run(task): print(result.get(text, )) # Run both simultaneously await asyncio.gather( run_agent(research_agent, Research AI trends for 2025), run_agent(writing_agent, Draft blog post outline) )这种并行模式在服务端也有对应的设计支撑Diorama为每个app_list计算一个哈希键并据此为每个应用组合独立维护一份光标位置状态见 diorama.py确保不同虚拟桌面之间的输入状态互不串扰。快速上手App-Use 入门环境要求Python 3.11macOS Sequoia (15.0) 或更高版本安装与启动 UI# Install packages and launch UI pip install -U cua-computer[all] cua-agent[all] python -m agent.ui.gradio.app除了命令行/代码方式Cua 还提供了 Gradio 界面。在 libs/python/computer/computer/ui/gradio/app.py 中可以看到UI 层提供了一个应用过滤下拉框当选中应用时界面会以experiments[app-use]初始化 Computer 并调用create_desktop_from_apps(app_list)把整个会话聚焦到所选应用上。最小可用脚本下面是一个完整可运行的示例创建只包含 Notes 的桌面会话截取该桌面的屏幕并让 Agent 执行一个创建笔记的任务。import asyncio from computer import Computer from cua_agent import ComputerAgent async def main(): computer Computer() await computer.run() # Create app-specific desktop sessions desktop computer.create_desktop_from_apps([Notes]) # Initialize an agent agent ComputerAgent( modelanthropic/claude-sonnet-4-5-20250929, tools[desktop] ) # Take a screenshot (returns bytes by default) screenshot await desktop.interface.screenshot() with open(app_screenshot.png, wb) as f: f.write(screenshot) # Run an agent task async for result in agent.run(Create a new note titled Meeting Notes and add todays agenda items): print(fAgent: {result.get(text, )}) if __name__ __main__: asyncio.run(main())注意在 libs/python/computer/computer/diorama_computer.py 中DioramaComputerInterface.screenshot()是通过_send_cmd(screenshot)下发命令的它要求底层 computer 接口已初始化——因此必须先await computer.run()否则会抛出RuntimeError: Computer interface not initialized. Call run() first.。实战场景用 Cua 自动化你的 iPhone通过 iPhone Mirroring 应用App-Use 可以让你直接用自然语言驱动本机 iPhone。⚠️ 重要警告计算机使用类 Agent 是强大的工具能够与你的设备交互。本指南涉及在你自己的 macOS 和 iPhone而非 VM上运行。请自行承担风险。务必做到运行前审查 Agent 的每个动作先从非关键任务开始密切监控 Agent 行为Cua 官方仍然建议为了更好的隔离性Agent 应优先运行在 VM 中。Step 1启动 cua-computer-server要经由 Computer 接口访问 iPhone Mirroring需要先在本地启动 computer-server# Install the server pip install cua-computer-server # Start the server python -m computer_server服务端的 App-Use 能力由diorama模块提供BaseDioramaHandler定义了diorama_cmd接口libs/python/computer-server/computer_server/diorama/base.pymacOS 的MacOSDioramaHandler则将其路由到本地的Diorama实例执行libs/python/computer-server/computer_server/diorama/macos.py。非 macOS 平台会直接返回Diorama is not supported on this OS yet.——这再次印证了 App-Use 的 macOS-only 属性。Step 2连接 iPhone Mirroring在你的 Mac 上打开iPhone Mirroring应用并连接到你的 iPhone。Step 3创建 iPhone 自动化会话import asyncio from computer import Computer from cua_agent import Agent async def automate_iphone(): # Connect to your local computer server my_mac Computer(use_host_computer_serverTrue, os_typemacos, experiments[app-use]) await my_mac.run() # Create a desktop focused on iPhone Mirroring my_iphone my_mac.create_desktop_from_apps([iPhone Mirroring]) # Initialize an agent for iPhone automation agent ComputerAgent( modelanthropic/claude-sonnet-4-5-20250929, tools[my_iphone] ) # Example: Send a message async for result in agent.run(Open Messages and send Hello from Cua! to John): print(fAgent: {result.get(text, )}) # Example: Set a reminder async for result in agent.run(Create a reminder to call mom at 5 PM today): print(fAgent: {result.get(text, )}) if __name__ __main__: asyncio.run(automate_iphone())iPhone 自动化用例自动化消息发送短信、回复消息、管理会话控制应用用自然语言操作任何 iPhone 应用管理设置以编程方式调整 iPhone 设置提取数据从没有 API 的应用中读取信息测试 iOS 应用自动化 iPhone 应用的测试工作流重要说明仅视觉隔离App 之间共享同一套文件、OS 资源和用户会话动态分辨率虚拟桌面会自动缩放以适配应用窗口和菜单栏仅限 macOS当前依赖合成引擎仅支持 macOS不是安全边界这是为了聚焦 Agent而非安全隔离App-Use vs 多个 Cua Container如何选择在同一个 macOS Cua Container 内使用 App-Use当✅ 你需要轻量、快速的 Agent 聚焦仅 macOS✅ 你想在一个桌面上运行多个 Agent✅ 你在自动化个人设备如 iPhone✅ 窗口布局隔离已足够✅ 你想要低计算开销使用多个 Cua Container当✅ 你需要 Agent 之间最大程度的隔离✅ 你需要跨平台支持Mac/Linux/Windows✅ 你需要有保障的资源分配✅ 安全与完全隔离至关重要⚠️ 注意这是计算开销最大的方案工作原理从 API 到 Quartz 的完整调用链当你在客户端调用create_desktop_from_apps()时实际发生的事情如下客户端代理层Computer.create_desktop_from_apps()返回DioramaComputer它包装了一个DioramaComputerInterface。所有交互命令截图、移动光标、点击、滚动、拖拽、输入文本、按键、热键、坐标转换都通过_send_cmd()将app_list注入参数后经底层 computer 接口的diorama_cmd下发见 libs/python/computer/computer/diorama_computer.py。传输与路由macOS 接口将调用封装为diorama_cmd动作请求见 libs/python/computer/computer/interface/macos.py到达 computer-server 后由MacOSDioramaHandler解析并实例化Diorama(app_list)执行见 libs/python/computer-server/computer_server/diorama/macos.py。服务端调度Diorama维护一个全局异步调度队列。每个命令都会根据app_whitelist即你的app_list获取全部窗口、运行中的应用、前台应用并建立AppActivationContext激活上下文再执行截图、鼠标或键盘操作见 diorama.py。Quartz 合成引擎窗口捕获层直接使用 macOS 的 Quartz API——通过Quartz.CGWindowListCopyWindowInfo获取窗口列表支持按 Z 序保留可见窗口的kCGWindowListOptionOnScreenOnly与全量窗口的kCGWindowListOptionAll两种模式并利用kCGWindowLayer、kCGWindowAlpha、kCGWindowOwnerPID、kCGWindowBounds等窗口属性进行过滤与合成见 libs/python/computer-server/computer_server/diorama/draw.py。这正是文档所说Quartz 提供底层窗口管理与渲染能力使多个应用窗口能被合成为隔离的视觉环境的源码证据。综合来看App-Use 的工作机制是过滤视觉输出只展示指定应用的窗口只向这些应用路由输入事件鼠标、键盘事件仅投递给白名单应用保持会话间窗口布局隔离不同虚拟桌面互不影响共享底层文件系统与 OS 资源不做进程级隔离动态调整分辨率自动适配窗口布局与菜单栏高度这种动态分辨率设计确保 Agent 无论面对怎样的应用组合都能完整、清晰地看到它需要交互的整个界面。专业技巧从小处开始先测试单个应用再构建复杂的多应用桌面先截图再行动先用screenshot()验证桌面正确显示了目标应用应用名必须精确使用系统中显示的确切应用名称如iPhone Mirroring而非iphone mirroring考虑性能虽然轻量但过多的并行 Agent 仍可能影响系统性能规划工作流设计 Agent 任务时尽量减少应用切换以获得最佳效果结语App-Use 为计算机自动化带来了一个新维度——轻量、聚焦、可并行。无论你是在构建个人 iPhone 助手还是在编排一支专业化 Agent 团队App-Use 都能在功能与效率之间提供很好的平衡。准备好体验了吗升级到最新版 Cua 并开始聚焦你的 Agentpip install -U cua-computer[all] cua-agent[all]更深入地探索客户端代理实现见 diorama_computer.py服务端虚拟桌面管理器见 libs/python/computer-server/computer_server/diorama/diorama.py窗口捕获与 Quartz 合成逻辑见 libs/python/computer-server/computer_server/diorama/draw.py。【免费下载链接】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），仅供参考

Cua App-Use 实战指南：用虚拟桌面把 Agent 限制在指定应用中

相关推荐

Electrobun 调试排障：5 分钟定位构建失败与运行故障

AI如何解决学术写作痛点：选题到润色全流程解析

一键清掉 Windows 11 内置 AI 功能：RemoveWindowsAI 完整移除指南

更多资讯

蚁群算法在物流调度VRPTW中的Matlab实现与优化

iii 仓库的 AGENTS.md 实战指南：Function / Trigger / Worker 三元组开发规范与 monorepo 协作边界

Text-to-CAD：从工程文本到参数化B-rep的工业建模新范式

从数据到决策：机器学习项目完整流程拆解

Apache Airflow Impala Provider 实战：使用 SQLExecuteQueryOperator 连接与操作 Apache Impala

群晖NAS无公网IP远程访问：cpolar内网穿透固定二级子域名配置教程

今日更新

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？