Mastra Tools 冒烟测试指南从 Studio 页面到/api/tools执行链路的完整验证【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra导读Tools工具是 Mastra 中 Agent 能力调用的核心载体工具能否被正确注册、渲染和执行直接决定 Agent 应用的质量。本文基于 Mastra 仓库中--test tools冒烟测试的官方参考文档系统讲解如何在 Studio 界面与 API 两个层面完整验证工具功能并结合仓库源码tools.ts、validation.ts、weather-tool.ts剖析/api/tools路由、工具查找链与输入校验管线的底层实现。读完本文你将掌握一套可复制的 Tools 冒烟测试清单、curl 验证命令与常见故障排查方法。一、冒烟测试定位Tools 是发布前必检项在 Mastra 的发布冒烟流程中Tools 测试是强制测试清单Mandatory Test Checklist中的第 3 项命令为smoke test --test tools在本地--env local、staging 与 production 三个环境均需执行。完整的执行约定见 SKILL.md默认需要同时完成API/curl 检查证明运行时端点可用与Studio 浏览器检查证明 Playground/Studio UI 能加载、提交表单并展示结果只有显式传入--skip-browser或浏览器访问确实被阻断时才允许跳过浏览器检查部分测试--test tools仍会先运行 Setup 步骤确保项目可启动、pnpm dev后的开发服务器监听在localhost:4111。Tools 冒烟测试的核心目的是回答三个问题工具列表能否加载、工具能否被选中并展示详情、工具能否真正执行并返回结构化结果。二、Studio 页面验证五步走清单对应参考文档 tools.md 中的 5 个步骤每一步都应当有明确的观察记录1. 导航到 Tools 页面在 Studio 中打开/tools记录工具列表是否加载、页面是否显示错误记录出现的工具清单例如get-weather。2. 选择一个工具点击某个工具例如get-weather记录工具详情面板是否打开记录可见的输入字段例如 city / location 输入框。3. 执行工具在输入字段填入测试值例如城市填London点击 Submit 或 Run 按钮等待执行完成。4. 观察输出记录输出格式JSON、文本等记录输出内容天气字段、数值等记录是否出现错误信息。5. 测试错误处理输入非法值空字符串、特殊字符等记录页面展示的错误信息记录工具是崩溃还是优雅降级。观察记录表检查项记录内容工具列表出现哪些工具、是否报错工具详情展示了哪些输入字段执行结果输出格式与内容输出数据返回的数据错误处理错误信息内容与行为浏览器操作可以用 Playwright / 浏览器工具自动化复现典型动作序列Navigate to: /tools Click: First tool in list (e.g., get-weather) Type in input field: London Click: Submit button Wait: For output Verify: JSON output appears提示浏览器冒烟测试中若无障碍快照未能暴露足够文本应检查document.body.innerText或截图取证不能只依赖 API 输出判断 UI 通过。三、curl / API 验证--skip-browser模式当跳过浏览器时直接用 curl 验证工具端点。Mastra 开发服务器默认监听http://localhost:4111冒烟项目可先用curl -s -o /dev/null -w %{http_code}\n http://localhost:4111确认存活。1. 列出全部工具curl -s http://localhost:4111/api/tools2. 执行一个工具curl -s -X POST http://localhost:4111/api/tools/toolId/execute \ -H Content-Type: application/json \ -d {data:{location:San Francisco}}关键约定data包裹层toolId是工具的.id属性而不是导出名。例如一个weatherTool导出、id: get-weather的工具必须请求/api/tools/get-weather/execute而不是/api/tools/weatherTool/execute。同时注意请求体中有一个data包裹层工具的输入 schema 字段必须放在data内部而不是顶层{ data: { location: San Francisco } }从源码看服务端处理器正是通过const { data } bodyParams;解构出输入再调用tool.execute(data, { mastra, requestContext, tracingContext })完成执行见 tools.ts。通过标准Pass Criteria检查项期望结果GET /api/tools返回按工具 id 组织的 JSON 对象POST /api/tools/toolId/execute合法输入HTTP 200 工具结果对象POST /api/tools/toolId/execute非法输入HTTP 200 { error: true, validationErrors: { ... } }常见错误Common Mistakes错误后果说明用导出名如weatherTool代替工具id如get-weather404 Tool not found路由参数取的是tool.id输入字段放在顶层而非data内每个字段都报校验错误服务端只从bodyParams.data读取输入外部 API 失败HTTP 500 上游错误内容先换一个已知正常的输入重试再判断工具本身是否损坏四、源码纵深/api/tools路由与工具查找链tools.md 文档断言的行为在 packages/server/src/server/handlers/tools.ts 中有完整实现对应冒烟测试者可以借此理解为什么会 404 / 为什么列表里有这个工具。路由清单方法路径说明GET/api/tools列出全部工具含序列化的 input/output schemaGET/api/tools/:toolId按 id 获取工具详情POST/api/tools/:toolId/execute执行工具GET/api/agents/:agentId/tools/:toolId获取某 Agent 绑定的工具详情POST/api/agents/:agentId/tools/:toolId/execute执行某 Agent 绑定的工具对应源码定义位于 tools.ts全局工具路由与 tools.tsAgent 工具路由。工具查找链为什么是 404 Tool not found执行与详情路由遵循一致的解析顺序见 tools.ts优先在 CLI 打包器发现的registeredTools中按tool.id匹配未命中则回退到mastra.getToolById(toolId)全局注册表仍未命中则回退到findToolInAgents遍历各 Agent 的listTools()覆盖toolsResolver动态解析的工具全部未命中抛出HTTPException(404, { message: Tool not found })。这正是文档中用导出名请求会 404的根因路由参数toolId在解析时始终按tool.id去匹配与文件导出名无关。列表接口tools.ts则会把registeredTools与mastra.listTools()两路工具合并并按tool.id去重保证同一工具只出现一次。一个可验证的工具实例get-weatherMastra 默认模板 weather-agent 提供了冒烟测试最常用的参照工具export const weatherTool createTool({ id: get-weather, description: Get current weather for a location, inputSchema: z.object({ location: z.string().describe(City name), }), outputSchema: z.object({ temperature: z.number(), feelsLike: z.number(), humidity: z.number(), windSpeed: z.number(), windGust: z.number(), conditions: z.string(), location: z.string(), }), execute: async inputData { return await getWeather(inputData.location); }, });注意这里导出名是weatherTool工具 id 是get-weather——正是文档强调的最典型易错点。执行时传入{data:{location:Paris}}返回的 JSON 应包含temperature、feelsLike、humidity、windSpeed、windGust、conditions、location等字段符合outputSchema声明。五、源码纵深输入校验管线与validationErrors文档要求非法输入返回 HTTP 200 { error: true, validationErrors: {...} }这背后是 packages/core/src/tools/validation.ts 中的validateToolInput实现。错误对象结构interface ValidationErrorT unknown { error: true; message: string; validationErrors: FormattedValidationErrorsT; }其中FormattedValidationErrors包含当前层级的errors: string[]与嵌套的fields结构见 validation.ts因此嵌套对象字段的校验错误也会以路径形式逐层呈现。多层容错校验管线validateToolInputvalidation.ts并非简单的一次性校验而是一条逐步重试的容错管线normalizeNullishInput顶层null/undefined按 schema 类型归一化为{}或[]处理 LLM 在全部参数可选时发送空值的问题convertUndefinedToNull将对象属性中的undefined转为null兼容 OpenAI 兼容层把.optional()转成.nullable()的场景首次校验保留null兼容.nullable()schema失败后尝试coerceStringifiedJsonValues把 LLM 返回的字符串化 JSON如args: [\file.py\]还原为真正的数组/对象再失败则stripNullishValuesAtPaths仅剥离导致校验失败的路径上的null/undefined兼容 Gemini 等向.optional()字段发null的行为最后尝试 prompt 别名归一化当 schema 声明prompt字段而模型发送了query/message/input时自动映射重试。校验失败时返回的message形如Tool input validation failed for test-tool. Please fix the following errors and try again: - name: Invalid input: expected string, received undefined - age: Invalid input: expected number, received undefined这一格式被 validation.test.ts 的集成测试以快照方式锁定冒烟测试中遇到的任何字段级校验错误都可以对照此格式定位。六、已知不一致200 vs 4xx 的语义差异参照 errors.md 中的错误语义表Tools 接口存在一个已知的不一致工具非法输入返回HTTP 200并在响应体内携带error: truevalidationErrors而 Agent / Workflow 的同类校验失败通常映射为 4xx/5xx。冒烟测试时应记录该行为用于横向对比但不应把它当作通过而忽视服务端 API 的错误码映射仍有改进空间。同时注意两点额外断言未知工具 id → HTTP 404响应体为{ error: Tool not found }非法 JSON 请求体 → HTTP 400Hono body 解析失败。无论哪种错误路径通过标准都要求响应体包含可读的error或工具的validationErrors字段、不泄漏堆栈、HTTP 状态码符合上表。七、常见问题排查表问题原因修复方向No tools found工具未注册检查src/mastra/tools/的导出确认在src/mastra/index.ts的Mastra实例中挂载工具执行失败缺少依赖检查工具实现体execute内部与外部 API 可达性非法 JSON 输出工具内部错误查看服务端日志定位堆栈404 Tool not found用了导出名而非tool.id使用get-weather这类 id而非weatherTool每个字段都报校验错误输入未包在data内按{data:{...}}结构提交外部 API 500上游接口异常换成已知正常城市如 London重试排除工具自身问题八、结果报告规范冒烟测试完成后按 SKILL.md 的报告模板输出结果例如## Smoke Test Results **Environment**: local **Project**: smoke-project | Test | Status | Notes | | ----- | ------ | ------------------------------ | | Setup | ✅ | tsc --noEmit 通过 | | Tools | ✅ | get-weather 执行返回天气 JSON | **Issues Found**: (无) **Skipped Tests**: 无浏览器检查结果应单独成节如## Studio Browser Smoke Results逐区域记录 PASS/FAIL 与证据页面加载、工具列表、get-weather表单提交返回巴黎天气 JSON 等并注明是本地 Studio 还是云端 Studio / 已部署服务器。小结Mastra 的 Tools 冒烟测试覆盖注册 → 展示 → 执行 → 错误处理全链路Studio 页面五步检查验证 UI 可用性/api/tools与/api/tools/toolId/execute验证运行时端点正确性而源码层面的查找链与多层校验管线则解释了 404、data包裹、validationErrors结构等一切表象背后的实现逻辑。把本文的清单、curl 命令与通过标准固化到发布流程中即可对工具功能回归形成稳定、可断言的质量闸门。详细步骤仍以官方参考文档 tools.md 为准配合 setup.md 完成项目准备、errors.md 对照错误语义即可跑通完整冒烟。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考