★ FEATURED ARTICLE 本文是「Agent 工程实战」系列的第 09 篇属于界面线。系列索引21 篇阅读路线Agent 放权前先补权限、出站、发现这三道口子摘要OpenAI 发布 Agents API 后Agent 会话越来越长你的后台界面正在被当成生产环境。但后台仍是按人眼设计的Agent 靠可访问性树或截图来看页面。本文从感知、操作、反馈三层讲透后台界面如何适配 Agent感知层把 div 换成真 button、补上 label让 Agent 看得准操作层放大命中区到 44px、拉开间距让 Agent 点得准反馈层用 aria-busy、loading 和 toast 让状态可见Agent 才知道做没做成高频写操作再开一条 MCP/HTTP 结构化通道兜底。文末附可直接照抄的检查清单三分钟自检你的后台页面。文章目录从 OpenAI Agents API 说起同一张页面两套读者第一层感知层让 Agent 看得准第二层操作层让 Agent 点得准第三层反馈层让 Agent 知道做完没兜底给 Agent 一条后门这套适配到底值不值从 OpenAI Agents API 说起9月10号 OpenAI 正式发布了 Agents API公开测试一次 API 调用就能建一个生产级的 agent跑的还是 Codex 那套 harness。帖子在 Hacker News 拿了两百多分一路冲到首页前排评论区吵成一团。大家聊的都是Agent 能干什么。多子任务并行、程序化工具调用、还支持 MCP——看着确实猛。我看到的倒是另一件事。官方博客反复强调的能力里有两件事指向同一句潜台词Agent 会话会越来越长要在你的系统里连轴跑好几小时甚至跨几天。一条会话跑小半天意味着它中间要访问你公司的后台、点击你系统的页面、处理真实业务数据。做 Agent 的人已经把你家的内部系统当成生产环境了。但问题是——那个后台还是按给人眼看设计的。上一篇写完AI 都能自己点界面了前端反而机会大了有读者问机会到底在哪这篇就把一件事讲透后台界面凭什么能被 Agent 用以及改起来到底改什么。同一张页面两套读者先说清楚 Agent 是怎么看界面的。市面上做界面操作的 agent 分成两大流派感知和操作各两套感知层一类靠截图喂给视觉模型你让它看什么它就看什么一类靠浏览器渲染出的可访问性树Accessibility Tree拿语义化文本操作层一类是像素坐标点击一类是拿元素定位去触发注意这两条轴是交叉的——截图派多数配坐标点语义树派多数配元素定位但组合不是死的。具体用哪套取决于 Agent 的产品怎么实现。对做界面的人来说这就够了你没法挑 Agent 用哪种方案但只要界面把两套都伺候好来什么 Agent 都能用。给你看同一张订单页两种读者各自看到什么人眼版本 可访问性树版本Agent 视野 ┌────────────────────┐ ┌──────────────────────────────┐ │ 订单后台 │ │ heading 订单后台 │ │ [搜索] [导出] [刷新] │ │ button 搜索 │ │ ┌────────────────┐ │ │ button 导出 │ │ │ 已支付 1000.00 │ │ │ button 刷新 │ │ │ 待支付 250.00 │ │ │ row 已支付 1000.00 │ │ └────────────────┘ │ │ row 待支付 250.00 │ │ 颜色区分状态、布局自然 │ │ role name state │ └────────────────────┘ └──────────────────────────────┘人的眼睛扫的是颜色、位置、留白Agent 拿到的是一棵全是 role、name、state 的树或者是一张像素图。这篇文章讲的适配本质就一句话让第二列列得清楚同时不拆第一列。第一层感知层让 Agent 看得准这层改的是Agent 眼里这张页面长什么样。对语义树派来说它读到的就是树上那些 role 和 label。树列得对不对直接决定它能不能找到按钮。下面示例都可从 Chrome DevTools 的 Accessibility 面板直接验证浏览器自带的不用另装东西。我先说我见过的典型翻车写法后台里特别常见这种假按钮!-- 运行时div 冒充 button看着是按钮 --divclasssubmit-btnonclicksubmitOrder()提交订单/divCSS 一伪装人眼完全看不出来。但在可访问性树里它不是一个按钮身份是 generic可访问性树devtools → Elements → Accessibility 面板 div classsubmit-btn role: generic name: 提交订单 focusable: false ← 键盘和语义工具都拿它当不可点的文本Agent 拿到这棵树能不能猜到这里的提交订单可以点大概率能靠的是猜——猜就有翻车的概率。第一类翻车往往不是 Agent 蠢是你给它的树本身写得含糊。改法很朴素用真正的语义buttontypesubmit提交订单/button!-- 如果样式上必须保留原有视觉效果不冲突 --可访问性树改后 button typesubmit role: button ← 明确是按钮 name: 提交订单 focusable: true ← 可聚焦可激活一行改动树里从疑似可点变成确认可点。再补一个常见的输入框不绑定 label。!-- 坏味道placeholder 当标签用 --inputtypetextplaceholder请输入订单号/可访问性树无 nameAgent 只知道有个输入框不知道填什么 改label fororder-id订单号/label input idorder-id typetext placeholder请输入订单号 / 树变成textbox name:订单号 ← 语义对上了边界说明这层主要对语义树派的 Agent 有效。截图派根本不读这棵树你标不标它都是看像素。反过来截图派要的是对比度、字号够不够清楚。所以这两件事都得做但别指望改了语义截图派也受益。我之前接一个内部项目当时觉得做无障碍是合规需求拖到验收才补。现在回头看那是一棵现成的给 Agent 看的界面分级地图——角色标得越干净的地方Agent 越不会走错。第二层操作层让 Agent 点得准感知层解决看得见操作层解决点得上。坐标点击派的 Agent 有一个很实际的毛病它按像素找目标。按钮太小、两个按钮挨太近它就容易点偏——点错一个后面全乱。我们自己后台之前有个运营功能一排小图标按钮编辑、删除、导出每个命中区域也就二十来像素见方。人肉用没问题让 agent 连续操作的时候编辑和删除之间经常点歪我得盯着回放一路看。改法也不复杂给可点击元素放大命中区域/* 原来只有文字区域可点 */.toolbar .icon-btn{font-size:14px;}/* 改后明面区域 内边距共同组成命中区 */.toolbar .icon-btn{font-size:14px;padding:10px;/* 额外命中空间 */margin-right:8px;/* 相邻按钮拉开间隔 */min-height:40px;display:inline-flex;align-items:center;justify-content:center;}效果实测回放 改前跑一整轮十几步点选平均每轮都偏一两次多半歪到删除 改后同样的一轮动作连着跑了大半天没再点偏过按现在的无障碍最佳实践可交互元素的目标尺寸建议做到 44px 见方这个量级间距至少单边留一点空隙。不是给人用不方便是给手抖的 Agent用方便。边界说明操作层这条只对坐标派有效语义树派不考虑像素它靠元素定位这层的收益是零。同时这个尺寸只是建议起点不是万能解表格里的行内编辑这种高频操作值得做一次性配置弹窗就不必为它折腾。第三层反馈层让 Agent 知道做完没这层是我认为最容易被忽略、出事也最隐蔽的。人在后台点保存点完哪怕只是按钮变灰再变回来也会心里有数成了。Agent 的判断依据要苛刻得多它的成了必须体现在可见状态上——视觉的或者语义树里的。举一个真实排查过的例子。我们有个流程agent 步骤走到点击保存按钮然后紧接着等待结果。结果它一直卡在等待超时之后把整轮操作算作失败重试连着重试了好几轮堆出一批脏数据。回放一看点击明明成功了。问题出在哪保存按钮点击后不到半秒接口就返回了但页面上没有任何状态变化——没有 loading没有成功提示按钮样式也没变。对 Agent 来说点了和没点没有任何可观察的区别。它只能靠猜猜一次两次可能蒙对长任务里必翻车。给操作加反馈状态视觉信号和语义信号一起上buttonidsave-btntypesubmitaria-busyfalse保存/buttonasyncfunctionsaveAndTell(){constbtndocument.getElementById(save-btn);// 1. 立刻进入处理中状态视觉和语义同步btn.setAttribute(aria-busy,true);btn.disabledtrue;btn.textContent保存中…;try{constresawaitapi.save();// 2. 成功状态从 busy 回到 ready并给可感知的结果提示btn.removeAttribute(aria-busy);btn.disabledfalse;btn.textContent保存;showToast(保存成功单号${res.id});}catch(e){// 3. 失败同样要显性化别让它无声失败btn.removeAttribute(aria-busy);btn.disabledfalse;btn.textContent保存;showToast(保存失败${e.message});}}语义树状态流转Agent 视角 点击前 button 保存 busyfalse, disabledfalse 处理中 button 保存中… busytrue, disabledtrue 成功 button 保存 busyfalse, disabledfalse live region 保存成功单号 xxx 失败 button 保存 busyfalse, disabledfalse live region 保存失败xxx把状态有没有变化这件小事做成常态是把接口失败的脏数据风险按回去的最便宜的方式。核心心法一句话Agent 不需要你告诉它我成功了它需要你让它看得到成功。边界说明反馈层对所有 Agent 有效但显性反馈不等于把状态栏写成大字报。异步任务用 live region 播报滚动面板别全屏弹窗别为了 Agent 把操作反馈做成打断式。兜底给 Agent 一条后门三层都做了还有一类场景绕不开老系统没有 API、只有界面。你想让 Agent 在十多年前用 Java 写的老系统里导出报表语义做得再漂亮它也只能靠点击。这时候别硬改界面给高频写操作单独开一条结构化通道——一个 MCP server一个 HTTP 接口把导出报表变成一个工具而不是一段界面操作序列。方案对比 纯界面走通Agent 打开页面 → 点筛选 → 点导出 → 等文件 → 下载 结构化通道Agent 调工具 exportReport(筛选条件) → 拿结果 结构化通道的额外收益可权限校验、可审计、出错可重放官方那篇博客里我注意到一个细节Agents API 支持 MCP 工具把工具跟harness分开编排。这暗示了方向——给 Agent 用结构化通道比界面操作更适合做写路径界面留给读路径和无法改造的场景。边界说明这条路只在接口可控时成立。第三方系统不愿意开接口、或者你只是想快速验证 Agent 能不能跑通业务流程那就返回界面操作别为造接口而造接口。我自己那阵子就干过一回——给一个只有界面的老后台补了个只读导出接口Agent 从十几步界面点选变成一次接口调用回放里点偏造成的错文件再没出现过。成本是一次接口收益是把操作链变成了可审计的调用链。这套适配到底值不值回头看这三层其实都在回答同一个问题怎么让 Agent 在你的系统里用得动。感知层把角色、标签写对Agent 看得准操作层给大目标、留间距Agent 点得准反馈层让状态可见、成功失败显性化Agent 知道做没做成高频写操作再给一条结构化通道兜底。改造成本都不算高大多是改成语义正确级别的改动人眼那一列基本不变。受益的是两套读者。最后给一份可以直接照抄的检查清单按优先级排好★ 越高越优先做性价比也越高层级检查项改法成本对哪类 Agent 有效优先级感知按钮是真 button 不是 div换语义标签别用 divonclick 冒充低语义树派★★★★★感知输入框都有 label / aria-labelplaceholder 不顶用补 label低语义树派★★★★操作高频按钮命中区 ≥44pxpadding 间距低坐标派★★★★操作相邻操作按钮留间距margin 拉开低坐标派★★★反馈保存/提交有 loading 态disabled aria-busy 文案中两派★★★★★反馈成功/失败有可见结果toast / live region中两派★★★★兜底高频写操作有 API/MCP 通道老系统单独开接口高两派★★★看场景拿到这张表你可以顺手做个三分钟自检用 Chrome 打开自己最常用的那个后台页面按 F12 进 Elements 下面的 Accessibility 面板看看那些点起来挺好看的按钮在树里是不是真的 button再找个会保存的表单提交完留意按钮有没有 loading 和结果提示。三项里两项不过关的页面就是这套适配最该先排期的对象。我的判断如下Agent 规模化是真的界面被当成生产环境也是真的。前端在 Agent 时代的新活法之一就是把这些细节做对——既让人的同事用着舒服也让跑你系统的 Agent 别天天翻车。这件事的窗口期不会太长等基建方把语义化界面变成硬性要求再动手就晚了。这里不展开聊 WAI-ARIA 的规范细节了贴两篇官方资料想深挖的可以自己看OpenAIIntroducing the Agents APIW3CWAI-ARIA 1.2「Agent 工程实战」系列路线界面线computer use / Agent UI上一篇08 库存被点没了下一篇10 A 公司数据记到 B 公司系列索引21 篇阅读路线Agent 放权前先补权限、出站、发现这三道口子专栏Agent 工程实战如果这篇对你有用欢迎收藏想追更可以关注「Agent 工程实战」专栏。
阅读完成 · 觉得有帮助？
