如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

浏览器和桌面驱动程序

将您管理的环境接入 SDK 的计算机和浏览器辅助类。

驱动程序将获准的工具调用转换为操作,在您控制的浏览器或桌面上执行。如果应用可以报告页面文本、控件和标签页,请使用浏览器驱动程序。如果模型必须根据截图和坐标操作,请使用计算机驱动程序。SDK 负责发送请求和分派调用,您的应用负责管理会话、权限和资源清理。

配置通用控制选项

从 Python 或 Node 的浏览器示例开始。示例提供了完整的驱动程序和确认策略,并演示如何限制一次 Responses 运行的请求数。请保持会话打开,直到运行结束。对于同步驱动程序,Python 还提供同步的 BrowserToolset 和 ResponsesToolRunner 类。

目标 设置位置 预期行为
限制浏览器方法 将 members 传给 BrowserToolset 或 AsyncBrowserToolset 构造函数。 只有选中且已实现的方法会对外开放。要通过示例驱动程序提供只读访问,请只选择 read_page。参阅选择方法。
审批浏览器变更 将 confirm 传给 BrowserToolset 或 AsyncBrowserToolset 构造函数。 只有返回布尔值 true 或 True 才允许执行拟议操作。请检查要调用的成员、操作目标和参数。参阅审批操作。
限制浏览器导航 将 Node 的 urlPolicy 或 Python 的 url_policy 传给 BrowserToolset 或 AsyncBrowserToolset 构造函数。 启用 navigate 或 new_tab 时必须设置。SDK 先检查请求的 URL,再请求确认。参阅限制 URL。
审批原生计算机操作 使用 ResponsesToolRunner 时,在 Node 的运行选项中设置 computerOptions,在 Python 中将 approve_safety_checks 和 before_action 传给 run。 待处理的安全检查必须得到明确批准。可选的操作前回调可以拒绝任一操作。参阅计算机操作审批。
限制运行步数 在 Responses 运行器的运行选项中设置 Node 的 maxSteps 或 Python 的 max_steps。 默认最多发送 20 个请求。最后一个允许发送的请求不能触发新的副作用。
统计用量 将同步回调 onDiagnostic(Node)或 on_diagnostic(Python)传给 ResponsesToolRunner.run。 汇总已完成请求记录中的 Token 用量。如果有已完成的请求缺少用量,请注明总数不完整。参阅查看用量和耗时。

审批操作并管理会话

在受信任的应用代码中创建驱动程序和审批回调。将可执行配置与不受信任的页面数据分开,并通过驱动程序声明的报告字段返回页面数据。

如果选中的浏览器方法会更改状态或读取诊断信息,就必须提供 confirm。只有在 Node 中返回布尔值 true 或在 Python 中返回 True 才能批准操作。navigate 和 new_tab 还要求提供 urlPolicy(Node)或 url_policy(Python)。两个回调都会收到独立的对象副本,其中包含 member、已验证的 arguments、先前的 state 和 call_id。URL 策略回调还会收到请求的 URL。修改这个对象无法改变已经验证的操作。

confirm 批准的是参数已经确定的操作。其中的 state 是先前观测到的状态,不会锁定文档或当前获得焦点的控件。在用户决定是否批准时,页面可能发生跳转或切换焦点。如果用户仅同意对特定页面或控件执行操作,驱动程序必须在执行时核对原始目标。在这种流程中,请禁用 key 并拒绝目标为 null 的 type 操作,因为两者都会使用当前焦点。对于其他依赖当前浏览器状态的操作,也要以同样的方式绑定目标。

要在读取私密页面前请求确认,请在 confirmReads(Node)或 confirm_reads(Python)中列出需要确认的读取方法。对于列出的方法,在驱动程序读取任何状态或内容之前,都会先运行同一个 confirm 回调。此时上下文中的阶段为 phase: "before_read",状态在 Node 中为 state: null,在 Python 中为 None。处理这种情况时不要读取页面元数据。如果拒绝读取,则不会返回任何页面内容或状态。未设置该选项时,现有读取操作保持原有行为,必须审批的操作仍需审批。

对于计算机调用,在辅助类执行任何操作前,必须确认所有待处理的安全检查。Node 的 approveSafetyChecks 和 Python 的 approve_safety_checks 必须返回布尔真值。未提供回调或回调拒绝批准都会终止运行。可选的 beforeAction 或 before_action 会在每个操作执行前立即检查该操作,包括最后的截图操作。如果提供了这个回调,也必须由它明确批准。模型的选择或完成消息均不能代替审批。参阅计算机使用安全指南。

Node 将 { signal } 作为最后一个参数传给两个计算机审批回调。在 Python 中,如果回调接受可选的 cancelled 关键字参数,SDK 就会传入该参数。参数较少的现有回调仍然受支持。运行停止时,可利用此上下文关闭尚在等待用户响应的审批提示。辅助类会等回调结束后再释放会话。

计算机操作审批针对的是操作的固定参数。在用户决定是否批准时,屏幕和焦点仍可能变化。如果同意仅适用于特定目标,驱动程序必须将操作绑定到该目标,或在状态改变后拒绝操作。请在网络访问受限的隔离环境中执行计算机操作。

限制 URL

仅当任务需要时才启用 navigate 或 new_tab。在 Node 中同时提供 confirm 和 urlPolicy,在 Python 中同时提供 confirm 和 url_policy。URL 回调接收 (context, url),还可接收 Node 中的执行上下文或 Python 中的 cancelled 关键字参数。只有该回调返回布尔真值,SDK 才会继续调用 confirm。新建 URL 为 null 的空白标签页仍需确认,但没有 URL 需要检查。

解析请求的 URL,将其协议、主机名和端口与任务允许访问的目的地址进行比较。不要依赖字符串前缀判断:不能将 https://example.com.evil.test 视为 https://example.com。不支持导航的浏览器驱动程序无需提供 URL 回调。浏览器示例未启用这些方法。

还要在浏览器或环境中实施网络策略。回调会检查请求的导航,但无法限制重定向、弹出窗口、页面脚本或嵌入式资源。多个请求之间应沿用同一个隔离会话。关闭应用自行创建的资源,借用的资源交由其所有者管理。

查看用量和耗时

使用 ResponsesToolRunner 时,将 Node 的 onDiagnostic 或 Python 的 on_diagnostic 传给 run。每完成一个 Responses 请求,回调都会收到一条记录,其中包含 api: "responses"、stage: "request"、reason: "completed" 和 usage。如果 API 提供用量,该用量对象就会包含 input_tokens、output_tokens 和 total_tokens,否则用量在 Node 中为 null,在 Python 中为 None。分别对所有已完成请求的各个 Token 字段求和,即可统计本次运行的用量。只要有一个请求缺少用量,总数就不完整。

ComputerToolset.run 不会通过诊断回调报告请求用量。返回的响应最多只包含最后一个请求的用量。如果需要逐个请求统计用量,请配合使用 ResponsesToolRunner 和 ComputerToolset。

诊断记录还会注明 API、阶段、原因、调用 ID、成员和实测耗时。记录不包含原始错误、页面文本、参数或图像。即使观察器出错,也无法批准操作或改变操作结果。如果您的应用会在调用 ID 和成员名称中加入私密数据,请勿将其写入公开日志。

请使用同步观察器。运行器不会等待诊断工作完成。如果需要异步存储,请在应用中自行调度。

启用提前执行时,接收流的时间可能包含执行操作的时间,因此各阶段的耗时可能重叠。不要将这些耗时相加来计算运行总时长。

关闭辅助类和取消操作

如果前一次调用尚未结束,辅助类会拒绝新的调用并报告忙碌错误。运行器也会拒绝在同一实例上同时启动第二次运行。每个浏览器或桌面会话应只由一个所有者管理。

调用辅助类的 close() 可拒绝新操作。如果已无活动调用,其 status 为 closed。如果先前的调用仍可能产生影响,状态则为 draining。如果状态为 draining,请先等待原执行调用结束,再关闭驱动程序或将会话移交给其他所有者。辅助类不会关闭您的浏览器或桌面。在驱动程序回调内调用 close() 不会等待该回调本身结束。

支持协作式取消的 Node 驱动程序方法和普通函数可以接收第二个参数,即包含 signal 的上下文。Python 方法可以接收 cancelled 关键字参数。在执行导航、截图等耗时操作期间,请检查取消信号。现有的单参数回调仍然有效,但 SDK 无法强制停止这些回调,也无法撤销已产生的影响。

浏览器驱动程序接口约定

实现 state(),并且只实现您打算开放的操作。Node 方法可以返回值或 Promise。Python 分别提供同步类和异步类。每个操作接收一个已经验证的参数对象或字典。对于允许留空的标签页 ID 和目标,请在 Node 中显式使用 null,在 Python 中显式使用 None。

创建辅助类时,如果 Python 能识别出方法的同步或异步类型与辅助类不匹配,就会拒绝创建。请使用 async def 定义供 AsyncBrowserToolset 调用的方法。如果包装方法,请保留装饰器元数据或返回类型注解。对于无法预先识别类型的包装器,SDK 会在调用时检查。可选协议(例如 BrowserReadDriver 和 AsyncBrowserReadDriver)可以为只实现部分操作的驱动程序提供类型标注,无需实现所有操作。Node 导出 BrowserArguments<Member> 和 BrowserResult<Member>,分别描述相应的输入和输出。

state() 报告 tabs,这是一个对象数组,每个对象包含 id、title、url 和 active。使用稳定的 ID,并标记实际处于活动状态的标签页。标题和 URL 中不得包含凭据或私密信息。常规操作结束后,即使操作失败,SDK 也会返回当前状态。如果拒绝受保护的读取操作,则返回固定的拒绝结果,不会读取或公开状态。如果必需的状态读取失败,运行就会停止。Node 状态读取方法接收 { signal },Python 状态读取方法可以接收 cancelled 关键字参数。当调用方停止运行时,可利用该上下文终止尚未完成的状态读取。现有的无参数读取方法仍然受支持。

标签页状态报告 HTTP 和 HTTPS 源,例如 https://example.com:8443,不包含凭据、路径、查询参数或片段。不含观测元数据的旧版状态会保留 about:blank,对于其他 URL 则仅报告协议方案,例如 data: 或 file:。其 2,048 字节的 UTF-8 限制针对的是报告值,因此页面路径很长也不会妨碍状态读取。对于带 V1 观测元数据的状态,标题会在字符边界处截断,最多保留 1,024 个 UTF-8 字节,必要时会设置 title_truncated。标题和页面内容仍需遵守应用的隐私规则。

选择方法

默认情况下,SDK 会开放下列 18 个方法中驱动程序已实现的方法,其中 list_tabs 由 state() 推导得出。请勿实现 list_tabs。您可以使用 members 列表减少开放的方法,也可以显式启用限定范围的读取和指针操作方法或诊断、脚本和文件方法。列表中的名称不得重复,必须是驱动程序已实现的预定义成员。只有 list_tabs 例外,只需实现 state() 即可。空列表不会开放任何方法。SDK 会在构造时复制所选成员,按自身的工具顺序排列,并在读取状态或征求同意前拒绝对已禁用方法的调用。

如果希望保留已实现的默认方法并添加可选方法,请在 Node 中使用 additionalMembers,在 Python 中使用 additional_members。不要与 members 同时使用。驱动程序必须已实现要添加的方法。BROWSER_MEMBERS 和 DEFAULT_BROWSER_MEMBERS 会列出预定义名称,无需检查驱动程序。

禁用 list_tabs 不会隐藏其他成功操作返回的状态。在 Python 和 Node 中,members 都用于筛选浏览器辅助类提供的方法。普通函数名称可以以 browser_ 开头,但不能与已启用的浏览器工具同名。

方法 参数 结果 是否需要确认
navigate url、tab_id 文本或无结果 是,还需通过 URL 策略检查
read_page filter(“all” 或 “interactive”)、tab_id 文本或结构化读取结果 否
get_page_text tab_id 文本或不含元素的结构化读取结果 否
find query、tab_id 文本或结构化读取结果 否
click target、tab_id 文本或无结果 是
type text、target(可为 null)、tab_id 文本或无结果 是
key keys(字符串)、tab_id 文本或无结果 是
scroll direction、非负的 amount、tab_id 文本或无结果 是
scroll_to target、tab_id 文本或无结果 是
wait_for text、timeout_ms、tab_id 文本或无结果 否
select_option target、values(字符串)、tab_id 文本或无结果 是
hover target、tab_id 文本或无结果 是
screenshot tab_id 原生输入图像 否
zoom region、tab_id 原生输入图像 否
new_tab url(可为 null) 文本或无结果 是,还需通过 URL 策略检查
list_tabs 无 推导得出的当前状态 否
switch_tab 必填的 tab_id 文本或无结果 是
close_tab 必填的 tab_id 文本或无结果 是

除 switch_tab 和 close_tab 外,表中列出的 tab_id 均可为 null。方向可取 up、down、left 或 right。Node 的 BrowserArguments<Member> 描述各方法的参数对象。Python 则提供具名输入类型,例如 TabInput、ReadPageInput 和 ClickInput。

对于 read_page、find 和 get_page_text,如果只需提供更新后的浏览器状态,可在 Node 中返回 null 或不返回值,在 Python 中返回 None。如果读取已完成但没有文本,请返回空字符串。

在 Node 中,表中除 list_tabs 外的每个操作都会接收 { signal } 作为第二个参数。list_tabs 使用前文介绍的状态读取方法。在 Python 中,如果方法接受 cancelled,SDK 就会将其作为关键字参数传入。可利用这个上下文停止尚未完成的导航、输入等操作。现有的单参数方法仍然受支持。

对于 wait_for,文本经空白字符规范化后必须非空,且不超过 256 个 UTF-8 字节。超时时间为 1 至 30,000 毫秒,含两端。执行 scroll_to 后,请重新读取当前页面,再操作控件。

报告结构化读取结果

read_page、find 和 get_page_text 可以返回 BrowserReadV1,其中包含 version: 1、可见的 text、elements 数组和 omitted 数组。每个元素都有唯一的 ref、非空的 label,以及以下七种角色之一:button、textbox、combobox、checkbox、radio、slider 或 listbox。

只有在应用允许模型查看时,才报告字段的 value 或 options(每个选项包含一对 label 和 value)。复选框或单选按钮可以报告布尔值 checked,listbox 的选项可以报告布尔值 selected。对于其他角色,SDK 会省略这些字段。Node 会省略设为 undefined 的可选字段,不接受这些字段取 null 值。get_page_text 必须返回空的 elements 数组。SDK 不会将普通字符串解析为结构化读取结果。

SDK 不限制元素数、选项数、页面文本大小或完整报告大小。每个引用或标签最多为 256 字节,每个值最多为 512 字节。请使用有效的 Unicode 标量值。如果报告只覆盖部分内容,驱动程序可以使用不重复的 omitted 代码说明省略原因:report_limit、text_limit、target_limit、work_limit、frame_limit、unsupported_root、unsupported_control、remote_action、private、value 或 name_limit。

驱动程序负责判断可见性、保护字段隐私并验证引用。获得批准后、执行操作前,请根据当前页面再次核对引用。能够看到控件标签并不意味着有权读取控件值。仅限制大小无法保证页面内容安全。

返回浏览器图像

screenshot 和 zoom 返回原生 input_image,其中至少包含一个非空的 image_url 或 file_id。两个来源字段可以同时存在,每个非 null 的来源都必须是非空字符串。支持的字段为 type、image_url、file_id、detail 和 prompt_cache_breakpoint。缓存断点必须为 { mode: "explicit" };如果原生内容类型允许,也可以使用 null。SDK 会先验证并复制这些字段,再返回图像。两个 Node 方法都返回 ResponseInputImageContent,其中的 detail 可以省略或设为 null。如果设置该字段,请使用 auto、low、high 或 original。

对于 zoom,region 的格式为 [left, top, right, bottom]。坐标必须是非负安全整数,区域的宽度和高度必须为正。驱动程序负责裁剪并检查边界。后续所有坐标仍以完整可见区域为基准。

启用限定范围的读取和指针操作方法

即使驱动程序实现了以下六个浏览器方法,默认也不会启用。请用 members 选择这些方法,或用 Node 的 additionalMembers 或 Python 的 additional_members 添加。原有 18 个默认方法的名称、参数和结果类型均保持不变。如果使用 members,还要列出仍然需要的默认方法,例如 screenshot 或 read_page。

方法 必填字段 结果 是否需要确认
read_page_scoped tab_id、root、depth、filter BrowserScopedReadV1 否
click_at tab_id、x、y、button、click_count、keys 文本或无结果 是
drag_path tab_id、path、keys 文本或无结果 是
hold_keys tab_id、keys、duration_ms 文本或无结果 是
hover_at tab_id、x、y 文本或无结果 是
set_checked tab_id、target、checked 文本或无结果 是

Node 使用 BrowserArguments<Member>。Python 导出 ReadPageScopedInput、ClickAtInput、DragPathInput、HoldKeysInput、HoverAtInput 和 SetCheckedInput。所有字段均为必填项。要指定活动标签页,可将 tab_id 设为 null 或 None。未知字段会被拒绝,包括路径点中的额外字段。数值必须是有限的安全整数。Python 不接受以 True 和 False 代替数值。

click_at 接受非负的 x 和 y,button 可设为 left、right 或 middle,click_count 可设为 1、2 或 3。drag_path 接受 2 至 100 个严格符合 {x, y} 格式的路径点,坐标必须非负。两种方法都以页面完整可见区域为基准,以 CSS 像素为单位,缩放后也一样。驱动程序必须检查当前边界。两种方法的 keys 字段均为修饰键列表,可包含 Control、Alt、Meta 或 Shift,不能重复。列表可以为空。

hover_at 将指针移至当前页面上指定的 CSS 坐标,不按住任何鼠标按钮。set_checked 按请求的布尔值设置复选框状态。连续两次设为 true 后,复选框必须保持选中。即使无需改变状态,也必须使用原目标,核实它仍是当前目标,并取得确认。不得接受已失效或已被替换的控件。

hold_keys 接受 1 至 8 个互不重复的非空按键名称。每个名称最多为 64 个 UTF-8 字节,并且必须由有效的 Unicode 标量值组成。duration_ms 的取值范围为 1 至 3000,含两端。会改变状态的方法要求 confirm 返回布尔真值。支持协作式取消的方法会接收本次调用的取消上下文:Node 将 { signal } 作为第二个参数传入,Python 则在方法接受 cancelled 时传入该关键字参数。现有的单参数方法仍然有效。

在指定区域内读取

对于 read_page_scoped,将 root 设为 null 可以查找可见区域。非 null 的根必须是驱动程序签发的范围引用,不能使用选择器。引用必须非空、由有效 Unicode 字符组成,且不超过 256 个 UTF-8 字节。将 depth 设为 1 至 32,将 filter 设为 all 或 interactive。深度按根范围内的 DOM 遍历层数计算,与框架或影子 DOM 的限制分别计算。

返回 BrowserScopedReadV1,它在现有读取结果的基础上增加了 scopes: [{ref, label}]。引用和标签必须非空、由有效 Unicode 字符组成,且各不超过 256 个 UTF-8 字节。范围引用不得重复,也不得与任何元素引用相同。此方法不接受字符串或 null 结果。SDK 会先复制已知字段,再请求最终状态。

范围引用只能用来选择下一次读取的根。修改元素的操作必须拒绝范围引用。当所属标签页、文档、代次或可见性发生变化时,应同时使范围引用和元素引用失效。继续遵守现有的字段隐私规则、总工作量限制和读取限制。

启用诊断、脚本和文件传输方法

以下四个方法默认也不会启用。请在 members 中逐一选择,或通过 additionalMembers 或 additional_members 添加。必须提供 confirm,诊断读取也需要确认。仅在驱动程序中实现这些方法,并不会让模型获得调用权限。

方法 必填参数 结果
read_diagnostics tab_id、source、limit 仅含文本的结构化读取结果
run_script tab_id、source、timeout_ms 文本
upload_file grant_id BrowserFileOutcome
download_file grant_id BrowserFileOutcome

对于 read_diagnostics,选择 console 或 network 作为来源,并将条数上限设为 1 至 100。返回结构化读取结果,其中的 elements 数组必须为空。在 Node 中使用 BrowserTextReadV1 结果类型。驱动程序必须过滤私密数据,并限制保留的历史记录。不要返回原始标头、Cookie、凭据或未经筛选的控制台消息。

run_script 接受由有效 Unicode 字符组成的非空源代码,以及 1 至 30000 毫秒的超时时间。SDK 会保留完整源代码。返回的文本必须由有效 Unicode 字符组成。空字符串有效,null 结果无效。SDK 会完整保留较大的结果。脚本以页面的权限运行。请使用不含凭据的新会话,限制其网络访问,并在无法确定执行状态时停用该会话。停止本地等待并不能证明页面脚本已经停止。

文件方法只接受调用方签发的 grant_id,它必须非空、由有效 Unicode 字符组成,且不超过 256 个 UTF-8 字节。该授权标识一个已获批准且仅限本任务使用的文件,不能使用路径或 URL 代替。文件所有者必须为该文件单独取得批准,还必须重新检查授权是否过期以及所有权是否正确,实施大小限制,并确保授权只能使用一次。浏览器操作确认不能代替文件审批。

返回结果必须恰好包含 version、status、effect 和 cleanup。将 version 设为 1。cleanup 可取 not_started、pending 或 completed。状态和效果的有效组合如下:

status effect
completed completed
refused none
unknown unknown
interrupted none 或 unknown

SDK 会先复制并验证此结果,再请求最终浏览器状态。只有 completed 会将工具输出中的 ok 设为 true。其他情况会保留结构化结果,并将 ok 设为 false,因此运行器会跳过该响应中依赖这一结果的浏览器调用。如果传输结果未知,请先检查实际文件和应用状态,再重试。文件操作的结果不能证明后续表单提交或业务操作已经成功。

run_script、upload_file 和 download_file 会接收本次调用的取消信息:Node 将 { signal } 作为第二个参数传入,Python 则传入 cancelled 关键字参数。Python 导出 ReadDiagnosticsInput、RunScriptInput 和 BrowserFileInput。

计算机驱动程序接口约定

计算机驱动程序接收原生计算机操作并返回截图。它必须实现以下方法。在 Node 中,ComputerDriver 从 openai 导入。在 Python 中,ComputerDriver 或 AsyncComputerDriver 从 openai 导入。配套的 ComputerToolset 或 Python 的 AsyncComputerToolset 也从 openai 导入。

方法 驱动程序接收的操作信息
click 坐标、鼠标按钮和按住的键
double_click 坐标和按住的键
drag 路径和按住的键
keypress 组合键
move 指针坐标
scroll 坐标、scroll_x 和 scroll_y
type 要输入当前焦点控件的文本
wait 等待环境稳定的请求
screenshot 无参数,返回当前屏幕画面

操作方法接收已生成的计算机操作对象,保留其中以小写字母和下划线命名的字段,不返回任何值。如果无法执行操作,必须抛出错误,不要静默忽略不支持的输入。Node 支持同步结果或 Promise。在 Python 中请等待异步方法执行完毕。

在 Python 中,为 ComputerToolset 使用同步方法,用 async def 定义供 AsyncComputerToolset 调用的方法。创建辅助类时,它会拒绝能够识别的同步或异步类型不匹配。包装方法时,请保留装饰器元数据或返回类型注解。对于无法预先识别类型的包装器,辅助类会在调用时检查,因此包装器自身的代码可能在辅助类发现类型不匹配之前就已执行。

在 Node 中,使用 ComputerCallInput 表示传给 ComputerToolset.execute() 的调用。它接受原生调用,也接受包含 actions 数组但省略 pending_safety_checks 的新版调用。对于这种合法的省略形式,审批回调收到的是独立的调用副本,其中的检查列表为空。重放调用时保留原始字段。

screenshot() 返回 computer_screenshot,其中包含 image_url(可以是 data URL)或 file_id。计算机辅助类要求至少提供一个图像来源,也允许同时提供两个来源字段。辅助类不会读取本地文件。每个操作按顺序执行一次,全部结束后辅助类再截取最终画面。它不会重试驱动程序操作。

对于仅使用计算机工具的 Responses 循环,请使用 ComputerToolset.run 或 Python 的 AsyncComputerToolset.run。选择您的项目可用且支持计算机工具的模型。对于混合运行,请将计算机辅助类传给 Responses 运行器的 computer 选项。Node 通过运行选项 computerOptions 接收计算机回调。Python 直接通过运行方法的关键字参数接收 approve_safety_checks 和 before_action。浏览器示例仅控制浏览器,不实现或验证原生桌面环境。

计算机辅助类和 ResponsesToolRunner 都支持通过 Responses 的 context_management 压缩上下文。两者都会检查各条目的必填字段,并原样重放加密内容。使用 ResponsesToolRunner 时,请在这个原生选项与本地 contextBudget 或 context_budget 选项之间择一使用,不要组合使用。

运行基于截图的任务

运行您的第一个任务提供了完整示例,您可以选择 Python 或 Node。示例使用 Responses 计算机工具在本地浏览器中查看取件详情。

使用隔离桌面

要控制操作系统桌面,请参阅完整的 Python 或 Node 桌面示例。两者均使用隔离的 Linux 客体环境。在搭载 Apple 芯片的 Mac 上,该环境运行在虚拟机中;在 x86-64 Linux 上,则运行在 Docker 中。每个示例都包含无需 API 密钥的本地练习。实际运行的任务会同时检查浏览器记录和已保存的文件。如果使用自己的环境,请从 Docker 配置示例开始,按上述接口约定调整驱动程序。

将浏览器操作与其他工具配合使用

Responses 运行器可以将浏览器和计算机辅助类与普通函数、网页搜索、文件搜索、代码解释器、图像生成和远程 MCP 工具配合使用。当下一个请求重放响应时,服务器端工具结果会保留其原生内容和容器 ID。如果服务器端结果显示失败、不完整或尚未完成,本轮会在执行本地操作之前停止。

如果一次运行声明了服务器端工具,即使启用了 eager,本地调用也会等待完整响应。运行器必须先检查后续的服务器端结果和审批请求,才能安全执行操作。

本轮完成时,如果普通函数在注册时允许覆盖结果,Node 的 supplyOutputs 或 Python 的 supply_outputs 就可以替换尚未尝试执行的普通函数的结果。即使未显式指定提前执行策略,也可以这样做。替换结果不能用于答复浏览器调用、计算机调用或 MCP 审批请求。

图像生成完成后,运行器需要使用已存储的响应才能继续。运行器会拒绝 Node 的 store: false 或 Python 的 store=False 配置,条件是本次运行声明了 image_generation。适用时请将存储选项设为 true,或者使用 client.responses.create 发送单个无状态请求。运行器不会代您启用存储。

复用带类型的函数工具,无需重复编写验证逻辑。在 Node 中,将 zodResponsesFunction 或 standardResponsesFunction 工具传给 runnerFunction 进行包装,该函数由 openai/helpers/responses-tool-runner 导出。工具必须包含自己的回调。在 Python 中,将 RegisteredFunction.from_tool 或 AsyncRegisteredFunction.from_tool 与现有的 pydantic_responses_function_tool 及显式指定的带类型执行器配合使用。参数无效时,流程会在执行器启动前停止。回调输出无效时,运行会停止,不会重复执行已产生影响的操作。直接注册 RunnerFunction 和 RegisteredFunction 时,参数处理方式保持不变。

对于 MCP,请在 Node 中提供 approveMcp,在 Python 中提供 approve_mcp。回调接收实际审批请求的独立副本,并返回 true 或 false。运行器将答复绑定到该请求的 ID 和声明的服务器。它不能自行批准请求,也不能将最终消息视为同意。

声明了 MCP 工具的请求会禁用 SDK 自动重试,无论是否使用运行日志。如果请求失败,请先检查 MCP 服务器实际执行了哪些操作,再启动新的运行。

处理失败

对于引用已失效等可恢复问题,可以抛出 BrowserError,但其中的文本必须可以安全地提供给模型。浏览器操作抛出的其他错误只会产生通用失败消息。遇到这类操作失败时,运行器仍会为每个浏览器调用提供输出,跳过该响应中剩余的浏览器操作,并让模型在下一轮重新选择。返回结果或状态无效会导致运行停止。无法报告状态、普通函数执行失败或原生计算机安全检查未获批准也会导致运行停止。

设置 maxSteps 或 max_steps 可限制 API 请求数,默认上限为 20。最后一个允许发送的请求不能触发新的副作用。SDK 重试 HTTP 请求时,不会重试驱动程序操作。在 Node 中使用 signal,在 Python 中使用 cancelled,可在两个操作之间停止执行。对于正在进行的驱动程序调用,不能保证可以撤销。

ResponsesToolRunner 会在每个请求中保留 tool_choice。如果所选策略始终要求调用本地工具,运行就无法结束,因此运行器会在执行任何工作之前拒绝该策略。对于循环,请使用 auto;对于单次强制调用工具的请求,请使用 responses.create。如果策略要求使用工具,同时也允许选择已声明的服务器端工具,则仍然有效。

排查运行问题

现象 检查和处理方法
无法导入 ComputerToolset 或浏览器辅助类 检查运行脚本的环境中安装的软件包。请使用 Python 的 openai==3.31.0 或 Node 的 openai@7.33.0,也可以使用包含这些辅助类的更高版本。
Chromium 无法启动 在运行脚本的同一环境中执行 Playwright 安装命令。如果使用 Linux 容器,请安装所需的系统库,并以非 root 用户身份运行。不要通过关闭沙盒来掩盖错误。
API 拒绝模型或工具 检查项目的模型访问权限,并查看该模型的工具部分,详见模型目录。原生 computer 工具和浏览器函数工具对模型的要求不同。
操作或待处理的安全检查被拒绝 检查应用的审批策略,并对照当前状态核对操作的固定参数。需要时请求审批,不要为了让运行通过而批准所有请求。
模型达到步数上限 先核实实际页面或文件,检查任务是否需要驱动程序拒绝提供的能力。在提高 maxSteps 或 max_steps 前,先简化任务。
模型未读取页面就作答 启用驱动程序已经实现的读取方法,例如示例中的 read_page。要求模型读取当前页面,然后重新运行任务。接受答案之前,请验证页面或文件中的实际结果。
点击未命中可见目标 检查截图和坐标。

修正点击位置偏差

重新截图,确认画面中显示的是目标窗口。截图和操作应使用同一坐标系。如果发送的是 800 × 600 的截图,而显示屏分辨率为 1600 × 1200,请在点击前将返回的两个坐标值均乘以 2。如果计算机驱动程序发送的是裁剪后的截图,请在缩放坐标后加上裁剪区域的偏移量。浏览器驱动程序的指针方法以完整可见页面区域中的 CSS 像素为单位,缩放后也一样。不要将其与显示屏像素混淆。

截图尺寸会影响输入 Token 数量和费用。有关图像尺寸和模型限制,请参阅截取屏幕截图。

流式运行与恢复

Responses 默认以非流式方式运行。如果同时使用 stream 和 onEvent(Node)或 on_event(Python),运行器会提供流事件的独立副本,并等响应结束后再执行操作。启用 eager 时,运行器可以按顺序提前执行已经完整接收的输出项。它绝不会根据尚在增量传输的参数执行操作。

只有在运行器验证完整响应之前就能安全执行已完成的输出项时,才应启用提前执行。如果后续事件更改或移除了该项,运行器会停止并保留执行记录,无法撤销已执行的操作。如果所有操作都必须等完整响应通过验证后再执行,请关闭提前执行,或使用空的提前执行策略。

如果已完成的输出项到达顺序有误,或索引不连续,运行器会等待完整响应,再执行序列中的这一部分。如果流传输失败,已经执行并产生影响的操作仍会保留记录。

earlyExecution 或 early_execution 可以按协议中的函数名称限制哪些函数可以提前执行,也可以通过单独的布尔值控制原生计算机操作的分派。传入空对象会推迟所有本地工具调用。省略此选项时,提前执行模式仍按常规方式对所有工具生效。为保留调用顺序,从第一个被推迟的工具开始,后续所有工具也会推迟。使用 iterate() 时,请先检查已完成的一轮,再继续推进。如果在这个轮次边界关闭迭代,则不会执行任何已推迟的工具。这些选项只改变执行时机,不改变审批要求。

对于单个已完整接收的调用,beforeEarlyCall 或 before_early_call 可以在分派前返回 defer。这个回调无法让提前执行允许列表之外的调用提前运行。只有普通函数可以独立运行、不依赖其他操作时,才将其标记为 independent: true。未使用运行日志时,独立函数可以在流继续传输时执行。可持久恢复的运行、浏览器操作和计算机操作仍按顺序执行。即使其他调用失败,已启动的操作也会保留执行记录。

默认最多可同时执行两个独立的提前调用。要更改上限,请将 Node 的 maxConcurrentCalls 或 Python 的 max_concurrent_calls 设为正整数。运行器会等待当前一组调用结束,再读取流中的更多调用。此选项仅适用于未使用运行日志且允许独立函数提前执行的运行。每个函数还必须自行限制它所启动的工作量。

如果启用了提前执行的运行中断,请检查 Node 中的 ResponsesToolRunnerError.attemptedCallIds 和 completedCallIds,或 Python 中的 attempted_call_ids 和 completed_call_ids。它们只包含调用 ID,不包含结果、参数或驱动程序消息。操作可能已经产生影响。重试已尝试或结果不确定的操作之前,请先读取应用中可作为判断依据的实际状态。

使用 contextBudget 或 context_budget 可以限制下一个请求的输入字节数和图像数,无论是否使用持久化存储都适用。筛选出的输入会保留当前观测结果和必需的工具关联。仅在内存中设置限制,无法让运行在进程退出后恢复。

一轮完成时,可以使用 appendUserText 或 append_user_text 将用户指导加入队列。运行器会在记录待处理输出后追加这段指导。此方法接收文本,不接受任意工具输出或审批对象,也不会重置请求预算。

可以使用此方法澄清当前任务,例如让智能体检查另一个日期。如果用户更换了任务,请停止当前运行,等待其结束,再启动新的运行。重新读取应用状态,并为新的操作重新取得批准。请保留旧运行的记录,更改指令不会撤销它已产生的影响。

要实现持久化恢复,请提供 ledger,在独占本次运行的前提下保存每个检查点。只能从已完成轮次的边界恢复。如果存在待处理或结果不确定的操作,必须先核对记录与实际状态。恢复后会保留剩余请求预算和已完成的历史记录。按本地上下文预算进行压缩时,完整证据仍保存在运行日志中,当前观测结果、安全检查、消息和推理内容也会固定保留。压缩不会批准任何操作。

每次保存都会收到独立且完整的检查点副本,包括在本地操作产生影响之前和之后的保存。检查点包含整个批次和累积历史。批次较大时,复制和存储这些记录所需的总工作量可能随批次大小呈平方增长。请选择适合这一数据量的存储方式。contextBudget 和 context_budget 限制的是请求输入,不限制运行日志的存储量。

运行中断时,处于待处理状态的检查点包含截至上次保存时的内容,可能没有包含后续文本和尚未尝试的拟议操作。这个检查点绝不能作为重放操作的授权依据。在操作产生影响前后保存的检查点,均包含截至当时观测到的全部内容及执行记录。

对于包含 MCP 工具的运行,运行器会在每个请求之前保存待处理检查点。如果连接失败,请先检查 MCP 服务器实际执行了哪些操作,再启动另一次运行。待处理检查点不能自动恢复。

保存 MCP 工具声明时,会省略授权信息和自定义标头,并以 SHA-256 指纹替换服务器 URL。原生请求仍使用原始 URL。需要轮换的凭据应放在授权信息或标头中。更改 URL 路径或无法识别的查询参数值会改变服务器标识,此时必须开始新的运行。包含原始 MCP URL 的检查点无法用于恢复。Node 需要使用 crypto.subtle.digest 才能保存 MCP URL 的指纹。检查点中的其他输入和输出仍属于应用私密数据。

恢复时,请提供当前有效的凭据,并确认凭据对应预期的服务器和账户。

保存代码解释器声明时,会保留凭据名称和域名,但会清除凭据的秘密值。恢复时,请在工具配置中提供当前有效的值。对于 MCP 审批,空的 always: {} 或 never: {} 筛选器适用于所有工具。

如果初始输入或已保存的运行日志包含已获批准的 MCP 请求,请在 Node 中提供 approveMcp,在 Python 中提供 approve_mcp。在首次保存或发送 API 请求之前,对于每项没有对应已完成 MCP 调用的审批,运行器都会重新请求批准。无论是否使用运行日志或上下文预算,这条规则都适用。已完成的调用和先前的拒绝决定保持不变。如果需要重新审批但没有提供回调,运行会停止。

在本地检查自定义驱动程序

在调整示例前,请先运行预订演示或隔离桌面示例中的本地练习。添加检查,验证驱动程序所操作页面的实际状态、输入产生的效果和资源清理情况。SDK 验证通过并不能证明环境正确执行了操作。

可运行的 SDK 工作流程请参阅运行您的第一个任务,环境设置请参阅集成示例。每次更改后,请先核实已保存的表单、文件或其他应用记录,再报告成功。