在 Mastra Studio 中测试自定义工具与 Agent从 Transactions Tool 到端到端验证【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra在 Mastra 中完成一个自定义工具如获取 Google Sheets 交易数据的getTransactions工具并将其挂载到 Agent 之后下一步关键工作就是验证它是否真正可用。本文以 Mastra 官方入门课程中测试你的工具一课对应仓库文档 docs/src/course/01-first-agent/13-testing-your-tool.md为骨架讲解如何借助Mastra Studio在浏览器里直接执行工具、向 Agent 提问验证工具调用链路并结合仓库中 Studioplayground的前端实现与端到端测试深入说明工具测试背后的执行原理。读完本文你将掌握一套工具先行验证、Agent 链路复验的完整调试流程。为什么要在 Studio 里测试工具在 docs/src/course/01-first-agent/12-connecting-tool-to-agent.md 中我们把getTransactionsTool通过tools: { getTransactionsTool }挂载到了financialAgent上并在系统指令里补充了工具的用法说明。此时 Agent 已经知道有这样一个工具但工具本身是否工作正常还未知——例如 Google Sheets 的公开 CSV 地址是否可访问、返回的csvData是否为空、fetch是否被网络策略拦截这些都属于工具自身的问题。原文档给出了一个非常务实的调试策略在把工具接入 Agent 之前先在 Studio 中直接测试工具本身这能帮你先把工具层的问题定位并修复再排查 Agent 调用工具时可能出现的问题。也就是说把工具层和Agent 编排层两个变量分开排查。如果工具直接在 Studio 中执行成功说明数据获取逻辑正确之后 Agent 回答不了问题时就可以把排查范围收敛到提示词、工具描述或调用策略上而不是重新怀疑数据源。启动开发服务器并打开 Mastra StudioMastra Studio 是随项目一起启动的本地调试界面。按课程前序步骤先确保开发服务器处于运行状态npm run dev随后在浏览器中访问http://localhost:4111/正如 docs/src/course/01-first-agent/05-running-playground.md 所介绍的Studio 提供了一整套交互能力向 Agent 发送消息并查看响应查看 Agent 的思考过程thought process直接测试工具调试运行中出现的各类问题。值得注意的是Studio 默认端口为4111这与 Mastra 服务器端口是两回事如果你的配置修改过端口请以实际启动日志中打印的地址为准。在 Tools 标签页直接执行工具打开 Studio 后找到Tools标签页。这里会列出当前 Mastra 实例注册的全部工具——既包括你通过createTool自定义的工具也包括挂载的 MCP 工具。选中getTransactions工具后你会看到工具名称与描述来自 ToolInformation 组件Input Data表单区域由于getTransactionsTool的inputSchema定义为z.object({})没有输入参数Studio 会显示提示信息 No input is required to run this tool.该提示逻辑可见 ToolExecutor.tsx点击Submit / Execute后右侧会以 JSON 形式展示工具执行的返回结果。对于本课程中的工具预期返回的是类似下面结构的 JSONcsvData字段里包含 Google Sheets 导出的 CSV 原文{ csvData: date,merchant,amount\n... }如果工具报错右侧展示区则会显示错误信息方便你直接定位是网络请求失败、解析失败还是返回结构不匹配。底层执行链路从源码看Studio 的 Tools 页面并不是模拟执行而是真实调用了 Mastra 客户端注册的工具。其执行入口在 use-execute-tool.ts通过client.getTool(toolId)拿到已注册的工具实例构造一个RequestContext将表单里填写的输入与上下文一并传入调用tool.execute({ data: input, requestContext })真正触发工具的执行逻辑执行成功则返回结果失败则通过 toast 提示 Error executing dev tool 并在控制台输出错误详情。因此你在 Studio 里点下的每一次执行走的就是与 Agent 内部调用工具时相同的execute通道——这就是它能作为工具层验收标准的根本原因。表单与 Schema 的联动Tools 页面会根据工具的inputSchema自动生成表单控件核心逻辑在 ToolExecutor.tsx使用isEmptyZodObject(zodInputSchema)判断工具是否需要输入有输入字段时渲染DynamicForm基于 Zod schema 动态生成的表单无输入字段时展示提示并允许直接执行若工具还声明了requestContextSchema则额外提供Request Context标签页用于在上下文中注入凭证等运行时信息。这解释了为什么getTransactionsTool空输入 schema在 Studio 里看起来没有表单也能跑——它确实不需要任何输入。通过 Agent 提问验证工具调用工具在 Tools 标签页验证通过后回到 Agent 的聊天界面。选择你的 Financial Assistant Agent直接尝试原文档给出的三组问题Can you show me my recent transactions?How much did I spend on Amazon?What was my largest transaction this month?如果一切正常Agent 会根据系统指令判断获取交易数据需要调用getTransactions工具调用工具拿到 CSV 数据对 CSV 内容进行分析、筛选例如按 merchant 过滤 Amazon 的交易、聚合例如统计本月最大单笔金额后给出自然语言回答。这正是 docs/src/course/01-first-agent/12-connecting-tool-to-agent.md 中在系统指令里写清工具用途的回报模型只有在理解何时用、怎么用的前提下才会在合适的时机发起工具调用。常见失败模式与排查方向根据工具层/编排层分离的思路可以按下面的表格快速定位问题现象可能原因排查动作Tools 标签页执行即报错数据源不可访问、fetch失败、返回结构不符直接在 Studio 的 Tools 页看错误详情必要时单独用 curl 验证 Google Sheets CSV 地址Tools 标签页执行成功但 Agent 不调用工具工具未挂载、系统指令未提及工具用法检查tools: { getTransactionsTool }配置参考 12-connecting-tool-to-agent.md 补充指令Agent 调用了工具但回答内容空洞工具描述不够具体模型不理解数据含义完善createTool中的description让描述覆盖数据来源、字段含义与适用场景Agent 回答时忘了之前的对话尚未配置 memory这是课程下一步要解决的问题详见 docs/src/course/01-first-agent/14-understanding-memory.md原文档特别提醒当前 Agent 还没有记忆能力因此不会记住之前的对话每次提问都是独立的。这个限制会在下一课14-understanding-memory.md 及后续 15-installing-memory.md、16-adding-memory-to-agent.md中通过为 Agent 接入 memory 来解决。从端到端测试看 Studio 工具页的验证逻辑仓库中的 Studio 前端位于 packages/playground配套了完整的 Playwright 端到端测试可以用来说明工具详情页执行在工程上被验证的行为。以 packages/playground/e2e/tests/tools/$toolId/page.spec.ts 为例await page.goto(/tools/simpleMcpTool); // 页面应展示工具名与空的 JSON 初始输出 await expect(page.locator(h2)).toHaveText(simpleMcpTool); await expect(page.locator([data-languagejson])).toHaveText({}); // 填写输入字段并提交 await page.getByLabel(The name of the person).fill(John Doe); await page.getByRole(button, { name: Submit }).click(); // 右侧 JSON 输出应展示工具返回结果 await expect(page.locator([data-languagejson])).toHaveText( { hello: world, thisIsA: fixture}, );这段测试验证的正是你手动操作所经历的完整流程进入工具详情页 → 填写输入 → 提交执行 → 在 JSON 面板查看返回结果。同一文件还验证了从工具详情页可以通过面包屑导航header nav中的Tools链接返回工具列表说明 Studio 工具页的导航结构也保持可用。由此可以看出在 Studio 中直接执行工具不只是一个调试技巧它对应着产品化界面中稳定、可回归验证的标准交互。你在 13-testing-your-tool.md 中手动做的每步操作都有自动化测试在守护其行为不回归。工具测试的完整工作流小结把整个课程串联起来测试环节的完整工作流如下准备确保开发服务器运行npm run dev访问http://localhost:4111/工具层验证在 Studio 的Tools标签页找到getTransactions直接执行确认返回包含csvData的 JSONAgent 层验证进入 Agent 聊天界面用课程提供的三类问题列出交易、按商家统计、找最大金额触发工具调用定位与收敛若失败按上文表格区分是工具本身问题还是 Agent 编排问题下一步确认功能正常后进入 memory 章节为 Agent 补充跨会话记忆。这套先工具后 Agent的验证顺序贯穿了 docs/src/course/01-first-agent/09-testing-your-agent.mdAgent 基础对话验证到本文的完整链路也是 Mastra 官方课程推荐的最小可靠迭代方式每一层功能都在接入下一层之前得到独立验证从而把调试成本降到最低。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考