openai-agents-python 计算机操作接口指南深入解析 Computer 与 AsyncComputer 抽象基类【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python导读在 openai-agents-python 这一多智能体框架中Computer与AsyncComputer是驱动计算机操作Computer Use能力的两大核心抽象接口Agent 通过它们获得截图、点击、键入、拖拽等 GUI/浏览器自动化能力而 SDK 则负责把这些本地实现映射到 OpenAI Responses API 的计算机工具表面。本文将完整拆解这两个抽象基类的接口契约、ComputerTool的挂载方式与生命周期管理、GA 与 preview 两代 wire 格式的选择逻辑并结合仓库源码与可运行示例给出从零实现一个可用计算机操作 Agent 的完整路径。一、接口定位什么是 Computer 抽象层在 docs/ref/computer.md 的 API 参考中agents.computer模块暴露了两个抽象基类Computer以同步操作实现的计算机抽象AsyncComputer以异步操作实现的计算机抽象。两者的职责完全一致——封装一台可以被程序化操作的计算机的最小动作集合。它们本身不包含任何业务逻辑而是作为契约存在子类提供本地运行时如 Playwright 浏览器、PyAutoGUI 桌面自动化等ComputerTool再把这个契约映射到 OpenAI Responses API 的计算机接口上。这正是 docs/tools.md 中本地运行时工具定位的体现ComputerTool与ApplyPatchTool一样始终在你的环境中执行模型只负责决策调用实际动作由你提供的实现完成。从源码结构看两个基类均继承自abc.ABC除screenshot外的所有方法都是抽象方法这保证了 SDK 在运行时可以无差别地驱动任意实现。二、接口契约逐项解析2.1 类型别名Environment 与 Button模块顶部定义了两个Literal类型别名见 src/agents/computer.pyEnvironment Literal[mac, windows, ubuntu, browser] Button Literal[left, right, wheel, back, forward]Environment声明计算机的运行环境类型。preview 时代的 wire 负载需要它在序列化时随请求发送详见第五节而 GA 负载则不再需要。Button声明鼠标按键类型左键、右键、滚轮、后退、前进。2.2 可选属性environment 与 dimensions两个基类都提供了两个属性property默认返回Noneproperty def environment(self) - Environment | None: Return preview tool metadata when the preview computer payload is required. return None property def dimensions(self) - tuple[int, int] | None: Return preview display dimensions when the preview computer payload is required. return None其语义在 docstring 中写得很清楚仅在需要 preview 计算机负载时才提供预览元数据。也就是说environment与dimensions不是强制要求——子类可以在 preview 流程下覆写它们例如返回(browser, (1024, 768))而在 GA 流程下保持默认None即可这正是 GA 负载不需要预序列化元数据特性的来源见 tests/models/test_openai_responses.py 中test_ga_computer_tool_does_not_require_preview_metadata的验证。2.3 必需实现的 8 个抽象方法Computer同步版与AsyncComputer异步版的抽象方法签名一一对应仅async修饰不同。以同步版为例方法签名语义screenshotscreenshot(self) - str返回当前屏幕的base64 编码 PNG截图clickclick(self, x: int, y: int, button: Button) - None在(x, y)屏幕坐标处点击指定按键double_clickdouble_click(self, x: int, y: int) - None在(x, y)处双击scrollscroll(self, x, y, scroll_x, scroll_y) - None在(x, y)处以(scroll_x, scroll_y)为单位滚动typetype(self, text: str) - None向当前焦点目标键入文本waitwait(self) - None等待计算机准备好下一次动作movemove(self, x: int, y: int) - None移动鼠标光标到(x, y)keypresskeypress(self, keys: list[str]) - None按下指定组合键如[ctrl, c]dragdrag(self, path: list[tuple[int, int]]) - None沿给定的(x, y)路径点序列点击并拖拽值得注意的是类文档中的一句说明鼠标动作方法在驱动程序支持时还可以接收一个关键字专用参数keys用于携带按住状态的修饰键例如按住Shift再点击。这一点在 Playwright 示例中被实际使用见下文第六节属于支持即用的可选能力并非强制签名。wait方法的语义值得单独强调它不同于固定的sleep而是等待计算机就绪——例如等待页面渲染完成、光标动画结束等是保证截图时序正确性的关键环节。在仓库示例中examples/tools/computer_use.py 的 Playwright 实现用asyncio.sleep(1)作为简化实现。三、ComputerTool本地 harness 的挂载点3.1 数据结构ComputerTool是一个泛型数据类三个字段构成其核心dataclass(eqFalse) class ComputerTool(Generic[ComputerT]): computer: ComputerT | ComputerCreate[ComputerT] | ComputerProvider[ComputerT] on_safety_check: Callable[[ComputerToolSafetyCheckData], MaybeAwaitable[bool]] | None None custom_data_extractor: ComputerToolCustomDataExtractor | None field(defaultNone, kw_onlyTrue)computer计算机实现本身或按次运行产生实现的工厂。其类型并集被定义为ComputerConfig ComputerLike | ComputerCreate[Any] | ComputerProvider[Any]src/agents/tool.py其中ComputerLike Computer | AsyncComputer。on_safety_check可选回调用于确认计算机工具的安全检查safety check。回调入参ComputerToolSafetyCheckData包含运行上下文、执行动作的 Agent、原始的ResponseComputerToolCall以及待确认的PendingSafetyChecksrc/agents/tool.py。返回bool表示是否放行。custom_data_extractor可选回调把 SDK 专属的自定义数据附加到工具输出条目上用于扩展computer_call_output的元信息。ComputerTool还有两个与命名相关的属性值得注意src/agents/tool.pyname返回computer_use_preview——这是为了保持 hooks 与持久化RunState的向后兼容保留 preview 时代的运行时命名trace_name返回computer——tracing 展示时使用 GA 别名即使运行时命名仍保持兼容。这解释了为什么在 docs/guardrails.md 中ComputerTool被归入不使用工具守卫管线的内置执行工具它走的是 Responses API 计算机接口而非普通 function-tool 管线。3.2 工厂与生命周期ComputerProvider当多个并发 Agent 需要隔离的计算机实例时可以直接传入实例但更推荐使用工厂模式。ComputerProvider定义了 per-run 生命周期钩子dataclass class ComputerProvider(Generic[ComputerT]): create: ComputerCreate[ComputerT] dispose: ComputerDispose[ComputerT] | None None其中ComputerCreate(*, run_context: RunContextWrapper[Any]) - MaybeAwaitable[ComputerT]针对当前运行上下文初始化计算机src/agents/tool.pyComputerDispose(*, run_context, computer) - MaybeAwaitable[None]清理某个运行上下文创建的计算机src/agents/tool.py。从源码实现看src/agents/tool.pyresolve_computer的处理逻辑如下通过weakref.WeakKeyDictionary按(tool, run_context)缓存已解析实例避免重复创建依次尝试ComputerProvider的create→ 可调用工厂 →tool.computer直接实例若create返回 awaitable则先await再使用校验结果必须是Computer或AsyncComputer实例否则抛出UserError(The computer tool did not provide a computer instance.)。对应的dispose_resolved_computerssrc/agents/tool.py在运行上下文结束时清理缓存、恢复工厂原值并逐个调用dispose即使 dispose 抛异常也只记录警告日志而不中断流程。四、从接口到 APIwire 格式的 GA 与 preview 之辨ComputerTool的负载格式取决于实际 Responses 请求上的生效模型这一转换发生在 src/agents/models/openai_responses.py 中。核心结论与 docs/tools.md 所述一致显式gpt-5.5请求 → GA 内置工具负载{type: computer}旧版computer-use-preview模型请求 → preview 负载{type: computer_use_preview, environment: ..., display_width: ..., display_height: ...}。迁移对照如下维度preview 路径GA 路径模型computer-use-previewgpt-5.5工具选择器computer_use_previewcomputer调用形状每个computer_call一个actioncomputer_call上批量的actions[]截断必须ModelSettings(truncationauto)不需要源码中的选择函数_convert_builtin_computer_tool_choicesrc/agents/models/openai_responses.py体现了三条规则preview 模型优先即使调用方强制传入 GA 别名computer或computer_use只要模型是 preview 系列仍然输出{type: computer_use_preview}prompt 管理调用默认走 preview当使用 prompt 模板、请求中省略model由 prompt 拥有模型时SDK 保持 preview 兼容负载除非显式传modelgpt-5.5或用ModelSettings(tool_choicecomputer)/tool_choicecomputer_use强制 GA 选择器否则输出 GAcomputer_use只是兼容别名GA 内置工具表面统一为computer。另外两条重要约束一个 Agent 只能挂一个ComputerToolconvert_tools中会检查computer_tools数量多于一个直接抛UserErrorsrc/agents/models/openai_responses.pytool_choice归一化当ComputerTool存在时computer、computer_use、computer_use_preview三种字符串都被接受并归一化为与生效模型匹配的内置选择器没有ComputerTool时这些字符串仍按普通函数名处理。这一区别对ComputerProvider工厂模式尤其关键GA 负载序列化时不需要environment与尺寸因此可以在工厂产出实例之前完成序列化而 preview 兼容序列化必须拿到已解析的Computer/AsyncComputer实例以获取environment、display_width、display_height对应源码中display_width: dimensions[0], display_height: dimensions[1]的填充逻辑见 src/agents/models/openai_responses.py。在运行时两条路径共用同一套本地 harnesspreview 响应输出单action的computer_call条目gpt-5.5可输出批量actions[]SDK 按顺序执行后生成computer_call_output截图条目。流式场景下两者都仍以tool_called事件名暴露、截图结果以tool_output返回见 docs/ja/streaming.md 对应说明。五、实战基于 Playwright 的完整实现仓库提供了开箱即用的可运行实现 examples/tools/computer_use.py它把AsyncComputer契约映射到本地 Playwright 浏览器上。运行方式uv run python -m playwright install chromium uv run -m examples.tools.computer_use通过环境变量可调整行为COMPUTER_USE_HEADLESS0关闭无头模式、COMPUTER_USE_START_URL指定起始页面、COMPUTER_USE_BROWSER_CHANNEL切换浏览器通道。5.1 核心实现要点LocalPlaywrightComputer继承AsyncComputerexamples/tools/computer_use.py其关键设计dimensions返回(1024, 768)同时用于 Playwright 启动窗口与 viewport 设置screenshot仅截取视口full_pageFalse并将 PNG 字节做 base64 编码返回——与接口契约base64-encoded PNG严格对应按键归一化CUA_KEY_TO_PLAYWRIGHT_KEY映射表把模型侧按键名如cmd、ctrl、arrowdown转换为 Playwright 按键名Meta、Control、ArrowDown修饰键支持click、double_click、scroll、move、drag都接受关键字参数keys通过_hold_keys上下文管理器实现按键按下—动作—释放drag实现先移动鼠标到路径起点并按下再沿剩余路径点移动最后释放资源管理同时提供上下文管理器__aenter__/__aexit__与显式的open()/close()分别服务于两种挂载方式。5.2 两种挂载方式singleton 与 per-request示例末尾展示了两种生命周期策略方式一共享单例singleton_computer——适用于不期望多 Agent 并发共享状态的场景async with LocalPlaywrightComputer() as computer: await run_agent(computer)方式二按请求创建computer_per_request——每次运行创建独立实例避免状态串扰配合ComputerProvider的create/dispose钩子async def create_computer(*, run_context: RunContextWrapper[Any]) - LocalPlaywrightComputer: return await LocalPlaywrightComputer().open() async def dispose_computer(*, run_context, computer) - None: await computer.close() await run_agent( ComputerProviderLocalPlaywrightComputer )Agent 的装配方式run_agent也很有代表性agent Agent( nameBrowser user, instructionsAGENT_INSTRUCTIONS, tools[ComputerTool(computercomputer_config)], modelgpt-5.5, # GA 内置 computer 工具 model_settingsModelSettings(tool_choicerequired), ) result await Runner.run(agent, WEATHER_PROMPT)在gpt-5.5模型下SDK 自动选择 GA 的{type: computer}负载模型读取截图后发出computer_call动作序列SDK 依次驱动你的实现执行直至完成点击Refresh forecast并总结天气的任务。六、最小实现模板与测试验证如果只想快速验证链路可以像 docs/tools.md 中的示例那样实现一个空操作计算机这里给出带类型标注的同步版最小模板from agents.computer import Computer, Button class NoopComputer(Computer): environment browser dimensions (1024, 768) def screenshot(self) - str: return def click(self, x: int, y: int, button: Button) - None: ... def double_click(self, x: int, y: int) - None: ... def scroll(self, x: int, y: int, scroll_x: int, scroll_y: int) - None: ... def type(self, text: str) - None: ... def wait(self) - None: ... def move(self, x: int, y: int) - None: ... def keypress(self, keys: list[str]) - None: ... def drag(self, path: list[tuple[int, int]]) - None: ...仓库测试对接口契约给出了直接佐证。例如 tests/models/test_openai_responses.py 的test_ga_computer_tool_does_not_require_preview_metadata一个不覆写environment/dimensions的AsyncComputer子类在显式模型请求下最终序列化结果精确等于[{type: computer}]——证实了GA 负载不需要预览元数据而test_prompt_id_uses_preview_computer_payload_when_prompt_owns_modeltests/models/test_openai_responses.py则验证了prompt 拥有模型时回退 preview 负载的行为。此外tests/test_agent_runner.py 还覆盖了ComputerTool在审批流程中的行为边界。七、选择与注意事项小结综合文档与源码落地 Computer Use 功能时的要点如下同步还是异步同步场景实现Computer异步场景实现AsyncComputer两者方法签名一一对应选择取决于你的底层驱动 API。实例还是工厂单 Agent 简单场景直接传实例多 Agent 并发或需要隔离状态时用ComputerProvider(create..., dispose...)按运行上下文管理生命周期SDK 的弱引用缓存会按(tool, run_context)去重并自动清理。模型与负载匹配显式指定gpt-5.5获得 GA 负载无需environment/尺寸、支持批量actions[]prompt 模板管理模型时必须显式传模型或用tool_choice强制 GA 选择器否则保持 preview 兼容负载。单例约束每个 Agent 至多一个ComputerTool多余会抛UserError。安全检查高权限动作可通过on_safety_check回调在 SDK 侧确认PendingSafetyCheck实现人机共治的安全闸门。可运行范例完整的 Playwright 实现与两种生命周期模式见 examples/tools/computer_use.py是理解接口契约与生产实践的最佳起点。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考