e2e自定义executor完全指南：替换内置智能体执行器

e2e自定义executor完全指南替换内置智能体执行器【免费下载链接】e2eNext generation e2e testing framework for web and mobile apps.项目地址: https://gitcode.com/GitHub_Trending/e2e6/e2ee2e 是面向 Web 和移动端的下一代端到端测试框架它内置了一个 AI 智能体执行器agent executor让测试用自然语言驱动界面。当内置智能体不够用——你想换一套工具词表、接入自己的大脑、甚至完全不用大模型时就可以通过e2e 自定义 executor替换内置智能体执行器。本文用通俗的方式讲清楚为什么要换、怎么换、以及替换后你能拿到什么。先搞懂executor 是什么为什么要替换e2e 的智能体步骤agent.act()/agent.assert()由两部分协作完成理解这个分工是理解自定义 executor 的关键角色职责是否可替换运行器runner脱敏、动作授权、预算、超时、录制、报告❌ 固定执行器executor思考读屏幕、决定做哪个动作、给出结论✅ 可替换源码注释里有一句点睛之笔Swapping executors changes the thinking, never safety, budgets, or the report——换执行器只换思考安全、预算和报告永远由运行器把关见 executor.ts。所以替换内置智能体执行器是安全的你的自定义 executor 拿到的是已脱敏的屏幕观察和受检查的动作方法无论里面跑的是哪家大模型、还是纯脚本逻辑预算、死线和判定规则都不变。什么情况下需要替换常见场景有三类️ 内置动作词表不合用比如只允许读屏幕 点节点的最小工具集 想接入自己的模型或决策逻辑含非 AI SDK 的模型 根本不需要模型用确定性脚本代替 AI 决策两条官方路线保留循环 或 完全接管官方文档 executors.mdx 给出了两条路线按需选择路线一createToolLoopExecutor—— 保留内置循环只换工具词表如果你还想要大模型驱动但想控制它能说什么话选这条路。它会原样保留内置循环的全部纪律预算模型调用次数、动作次数重复调用检测防死循环见 tool-loop.ts 中的 loop guards结论工具complete_step、用量记账、调试转录你只需要提供三样东西system提示词、buildPrompt开场提示、tools工具集。循环会自动补上complete_step结论工具。路线二StepExecutor—— 完全自定义模型可选自己实现runStep(ctx)方法一个步骤进、一个结论出。模型和 AI SDK 都是可选的——不装ai包类型照样能编译。适合确定性脚本只处理特定的assert断言其他指令直接返回blocked用自己的模型、自己的推理框架需要把历史/记忆作为事实来源的执行器此时把cache设为off每个步骤都真实执行三步把自定义 executor 挂进配置替换内置智能体执行器只需在e2e.config.ts的agents条目里加一个executor字段。以路线二为例最小可用写法import type { E2EConfig, StepExecutor } from e2e; import { web } from e2e-dev/web; const scripted: StepExecutor { name: scripted, version: 1, cache: off, async runStep(ctx) { const screen await ctx.observe(); const ready screen.text.includes(Ready); return ready ? { status: passed, summary: The screen says Ready. } : { status: failed, summary: Ready is absent. }; }, }; export default { targets: [{ engine: web(), app: { url: http://localhost:3000 } }], agents: { default: { executor: scripted } }, } satisfies E2EConfig;配置规则详见 config.mdxexecutor与其他字段互斥同一条目里再写system或tools会报INVALID_CONFIG——执行器自带提示词和工具把它们传给createToolLoopExecutor即可仍然生效的选项model、judge、context和各类预算照常工作模型一致性条目和 executor 各自带了model时必须指向同一模型否则配置加载失败被测试的应用长这样——智能体内置或自定义都在这类界面上工作替换后你能拿到什么执行器上下文与结论自定义 executor 的runStep(ctx)会收到一个内容丰富的上下文完整定义见 StepExecutorContext核心成员成员用途ctx.step步骤指令、参数、序号秘密值只会以secret:name占位符出现ctx.observe({ tree, pixels })脱敏后的屏幕文本可选节点树和打码截图ctx.actions受检查、受记账的动作tap、type、scrollUntil、upload等二十多个动词ctx.target目标平台与它支持的动词集合——只给模型提供它能做到的ctx.signal取消、死线或其他硬停止时触发收到就该立刻停ctx.budgets动作/模型调用记账自定义工具包在runTool里执行ctx.replayedPrefix缓存重放已执行过的动作继续时别重做ctx.attachScreenshot/attachTurns把截图、模型回合附到步骤报告上步骤结束时返回三态结论StepVerdict✅passed目标达成不携带错误码❌failed应用行为不符合要求blocked环境/凭据/预算阻断了判断必须携带可阻断的错误码注意STEP_TIMEOUT、CANCELLED这类运行器专属错误码不能由执行器发明乱返回会被以MODEL_OUTPUT_INVALID拒收见 agent-steps.mdx。缓存、预算与常见坑重放缓存cache决定act步骤如何参与缓存——inherit默认跟随配置模式off永不重放、每步都进runStep。assert步骤从不缓存。条目按agent 上下文为键一个 agent 录制的条目不会在另一个 agent 上重放记账要用ctx.budgets.runTool自定义工具要占动作槽、被记录就包在runTool里但不要在runTool内部再调ctx.actions或ctx.observe会死锁直连页面 API 要谨慎用surfaceOf(handle)拿到 Playwright 页面直接操作会绕过动作授权和重放缓存运行器仍会执行死线和记录结论工具体保持短小并支持取消步骤死线无法取消一个无视信号的底层操作模型缺失会明确报错路线一要求有模型条目没配model时抛MODEL_UNAVAILABLE错误信息会告诉你去配哪里选型清单我该选哪条路你的需求推荐方案仍用大模型但想收紧工具词表、自定义提示词createToolLoopExecutor零模型、确定性脚本断言手写StepExecutorcache: off用自己的模型/推理框架驱动界面StepExecutor自带model直接操控浏览器Playwright 风格StepExecutorsurfaceOf换执行器 换大脑不换安全底线。想动手的话从官方示例页 executors.mdx 的两个完整例子起步再对照 executor 接口源码 逐字段阅读半小时内就能跑起第一个自定义 executor。延伸阅读内置智能体步骤机制、agents 配置参考、引擎编写指南、项目工具 defineTool【免费下载链接】e2eNext generation e2e testing framework for web and mobile apps.项目地址: https://gitcode.com/GitHub_Trending/e2e6/e2e创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考