2026/9/15 15:10:44
FEATURED · 精选文章 
page-agent customTools完全指南5分钟为AI操作员添加自定义工具【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agentPageAgent是一个住在网页里的 GUI Agent一段 JavaScript 脚本就能让任意页面拥有自己的 AI 操作员用自然语言点击、输入、滚动。而customTools正是它的能力扩展接口——5 分钟内你就能给这个 AI 操作员加上加入购物车搜索知识库等业务专属工具也能一键移除它不需要的内置工具。 一句话理解内置工具让 AI 会点页面customTools 让 AI 会干你的业务。为什么需要 customToolsPageAgent 自带的工具都是通用的页面操作比如内置工具作用click_element_by_index点击页面元素input_text在输入框里打字scroll上下滚动页面wait等待页面加载ask_user向用户提问done结束任务并返回结果这些工具定义在 tools/index.ts 中。但你的产品往往需要 AI 直接调用业务接口——下单、查库存、查知识库。customTools就是为这类场景设计的用 Zod 定义输入参数让 AI 安全地调用你的业务逻辑。⚠️ 小提示页面信息通过 packages/core/src/prompts/system_prompt.md 中的系统提示词驱动customTools 的description会被直接喂给大模型所以描述写得越清楚AI 用得越准。customTools 的三大属性一个工具长什么样每个自定义工具都由 tool() 辅助函数定义包含三个属性description—— 工具的说明书AI 靠它决定何时调用inputSchema—— 用 Zod 定义的输入参数结构execute—— 真正的执行逻辑返回一个字符串结果工具类型定义可以见 types.tscustomTools的配置结构是Recordstring, PageAgentTool | null键是工具名值是工具对象也可以是null后面会讲。5分钟上手给AI操作员加一个加入购物车工具先确认 Zod 版本PageAgent 支持 Zod 33.25.0和 Zod 4统一从zod/v4子路径导入即可。下面是一个完整的购物车示例灵感来自官方文档 custom-tools 页面import { z } from zod/v4 import { PageAgent, tool } from page-agent const pageAgent new PageAgent({ // ...你的模型配置 customTools: { add_to_cart: tool({ description: Add a product to the shopping cart by its product ID., inputSchema: z.object({ productId: z.string(), quantity: z.number().min(1).default(1), }), execute: async function (input, { signal }) { await fetch(/api/cart, { method: POST, body: JSON.stringify(input), signal, // 关键尊重取消信号 }) return Added ${input.quantity}x ${input.productId} to cart. }, }), }, })就这么多。现在用户说一句把商品 P-1024 加两件购物车AI 就会自己调用add_to_cart把参数通过 Zod 校验后打到你的/api/cart接口上。 命名建议工具名用snake_case英文如search_knowledge_basedescription用英文写清做什么 何时用AI 的调用准确率会更高。进阶覆盖与移除内置工具customTools 有个隐藏但强大的用法——同名覆盖用与内置工具相同的名字可以覆盖它的行为设置为null则彻底移除该工具比如做一个无干扰模式的 Agentconst pageAgent new PageAgent({ customTools: { scroll: null, // 禁止滚动 execute_javascript: null, // 禁止执行脚本 }, })这对权限收敛非常有用把不需要的危险能力直接关掉AI 只能在你允许的范围内活动。移除逻辑在 PageAgentCore.ts 中完成——customTools 会最后合入工具表同名的自然覆盖内置项。异步工具必读尊重 signal 中断信号注意上面示例里的execute: async function (input, { signal })。每次工具执行都会收到一个 ToolContext其中包含AbortSignal。为什么必须用它用户在任务进行中点停止时框架要靠这个信号中断你的异步代码。正确姿势调fetch时把signal传进去fetch(url, { signal })写循环时检查signal.aborted或调用signal.throwIfAborted()不做这一步任务停不下来用户只能眼睁睁看它跑完。项目内的实战参考Chrome扩展如何用 customTools别觉得 customTools 只是玩具——PageAgent 自己的Chrome 扩展就是靠它实现多标签页操作的。在 tabTools.ts 中createTabTools()工厂函数生成了三个标签页工具open_new_tab—— 打开新标签页并设为当前页switch_to_tab—— 切换到指定标签页close_tab—— 关闭标签页然后在 MultiPageAgent.ts 里通过customTools注入 PageAgentCore。这个工厂函数 注入的模式值得抄作业先把工具做成独立模块再在构造 Agent 时注入代码干净又可测试。常见问题速查问题解答工具不触发检查description是否清晰AI 是读说明书选工具的参数经常传错用 Zod 加.describe()、.default()、.min()等约束支持哪些 Zod 版本Zod 33.25.0或 Zod 4从zod/v4导入不支持 Zod Mini返回值有要求吗返回字符串它会作为工具执行结果进入 AI 的上下文配置项标记为 experimental见 types.ts接口未来可能微调升级前看一眼 CHANGELOG参考资料官方文档仓库内置docs/ 目录下的 README-zh.md自定义工具文档页源码custom-tools/page.tsx配置项类型定义types.ts内置工具实现tools/index.ts扩展包多页 Agent 示例MultiPageAgent.ts变更记录CHANGELOG.md小结customTools让 PageAgent 从通用页面操作员进化为懂你业务的操作员——三个属性定义一个工具一个null移除一个能力五分钟即可上手。去给你的 AI 操作员加第一个专属工具吧【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
page-agent customTools完全指南：5分钟为AI操作员添加自定义工具
page-agent customTools完全指南5分钟为AI操作员添加自定义工具【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agentPageAgent是一个住在网页里的 GUI Agent一段 JavaScript 脚本就能让任意页面拥有自己的 AI 操作员用自然语言点击、输入、滚动。而customTools正是它的能力扩展接口——5 分钟内你就能给这个 AI 操作员加上加入购物车搜索知识库等业务专属工具也能一键移除它不需要的内置工具。 一句话理解内置工具让 AI 会点页面customTools 让 AI 会干你的业务。为什么需要 customToolsPageAgent 自带的工具都是通用的页面操作比如内置工具作用click_element_by_index点击页面元素input_text在输入框里打字scroll上下滚动页面wait等待页面加载ask_user向用户提问done结束任务并返回结果这些工具定义在 tools/index.ts 中。但你的产品往往需要 AI 直接调用业务接口——下单、查库存、查知识库。customTools就是为这类场景设计的用 Zod 定义输入参数让 AI 安全地调用你的业务逻辑。⚠️ 小提示页面信息通过 packages/core/src/prompts/system_prompt.md 中的系统提示词驱动customTools 的description会被直接喂给大模型所以描述写得越清楚AI 用得越准。customTools 的三大属性一个工具长什么样每个自定义工具都由 tool() 辅助函数定义包含三个属性description—— 工具的说明书AI 靠它决定何时调用inputSchema—— 用 Zod 定义的输入参数结构execute—— 真正的执行逻辑返回一个字符串结果工具类型定义可以见 types.tscustomTools的配置结构是Recordstring, PageAgentTool | null键是工具名值是工具对象也可以是null后面会讲。5分钟上手给AI操作员加一个加入购物车工具先确认 Zod 版本PageAgent 支持 Zod 33.25.0和 Zod 4统一从zod/v4子路径导入即可。下面是一个完整的购物车示例灵感来自官方文档 custom-tools 页面import { z } from zod/v4 import { PageAgent, tool } from page-agent const pageAgent new PageAgent({ // ...你的模型配置 customTools: { add_to_cart: tool({ description: Add a product to the shopping cart by its product ID., inputSchema: z.object({ productId: z.string(), quantity: z.number().min(1).default(1), }), execute: async function (input, { signal }) { await fetch(/api/cart, { method: POST, body: JSON.stringify(input), signal, // 关键尊重取消信号 }) return Added ${input.quantity}x ${input.productId} to cart. }, }), }, })就这么多。现在用户说一句把商品 P-1024 加两件购物车AI 就会自己调用add_to_cart把参数通过 Zod 校验后打到你的/api/cart接口上。 命名建议工具名用snake_case英文如search_knowledge_basedescription用英文写清做什么 何时用AI 的调用准确率会更高。进阶覆盖与移除内置工具customTools 有个隐藏但强大的用法——同名覆盖用与内置工具相同的名字可以覆盖它的行为设置为null则彻底移除该工具比如做一个无干扰模式的 Agentconst pageAgent new PageAgent({ customTools: { scroll: null, // 禁止滚动 execute_javascript: null, // 禁止执行脚本 }, })这对权限收敛非常有用把不需要的危险能力直接关掉AI 只能在你允许的范围内活动。移除逻辑在 PageAgentCore.ts 中完成——customTools 会最后合入工具表同名的自然覆盖内置项。异步工具必读尊重 signal 中断信号注意上面示例里的execute: async function (input, { signal })。每次工具执行都会收到一个 ToolContext其中包含AbortSignal。为什么必须用它用户在任务进行中点停止时框架要靠这个信号中断你的异步代码。正确姿势调fetch时把signal传进去fetch(url, { signal })写循环时检查signal.aborted或调用signal.throwIfAborted()不做这一步任务停不下来用户只能眼睁睁看它跑完。项目内的实战参考Chrome扩展如何用 customTools别觉得 customTools 只是玩具——PageAgent 自己的Chrome 扩展就是靠它实现多标签页操作的。在 tabTools.ts 中createTabTools()工厂函数生成了三个标签页工具open_new_tab—— 打开新标签页并设为当前页switch_to_tab—— 切换到指定标签页close_tab—— 关闭标签页然后在 MultiPageAgent.ts 里通过customTools注入 PageAgentCore。这个工厂函数 注入的模式值得抄作业先把工具做成独立模块再在构造 Agent 时注入代码干净又可测试。常见问题速查问题解答工具不触发检查description是否清晰AI 是读说明书选工具的参数经常传错用 Zod 加.describe()、.default()、.min()等约束支持哪些 Zod 版本Zod 33.25.0或 Zod 4从zod/v4导入不支持 Zod Mini返回值有要求吗返回字符串它会作为工具执行结果进入 AI 的上下文配置项标记为 experimental见 types.ts接口未来可能微调升级前看一眼 CHANGELOG参考资料官方文档仓库内置docs/ 目录下的 README-zh.md自定义工具文档页源码custom-tools/page.tsx配置项类型定义types.ts内置工具实现tools/index.ts扩展包多页 Agent 示例MultiPageAgent.ts变更记录CHANGELOG.md小结customTools让 PageAgent 从通用页面操作员进化为懂你业务的操作员——三个属性定义一个工具一个null移除一个能力五分钟即可上手。去给你的 AI 操作员加第一个专属工具吧【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
