运行 Mastra Studio用npm run dev启动本地开发环境并测试你的第一个 Agent【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本篇指南是 Mastra 官方入门课程创建第一个 Agent系列中的一环讲解如何启动Mastra Studio——Mastra 框架内置的交互式开发与测试工作台。你将在本地运行npm run dev启动开发服务器在http://localhost:4111打开 Studio与自己的 Agent 对话、观察其思考过程、直接测试工具并排查问题为后续编写系统提示词、注册自定义工具和接入记忆能力打下调试基础。为什么需要一个交互式 Studio在你编写 Agent 的过程中代码是否正确、提示词是否生效、工具返回是否符合预期往往只有真正跑起来才知道。Mastra Studio 正是为此而生的可视化开发环境它连接你本地的 Mastra 服务器把 Agent、工作流Workflow、工具Tool等原语以图形界面暴露出来让你无需编写额外客户端代码就能边构建边验证。从仓库的文档结构看官方对 Studio 的定位是用于构建、测试和管理 agents、workflows、processors、tools 与 MCP servers同时检查 trace 与运行时行为的交互式 UI参见 Studio 总览文档。本文聚焦入门课程第 5 步的核心任务把 Studio 跑起来并理解它能为你做什么。前提项目结构就绪在启动 Studio 之前请确保你的 Mastra 项目已经创建完成并具备标准目录结构。按入门课程 Verifying Project Structure 的描述一个由 CLI 生成的项目应包含src/mastra/ ├── index.ts # Mastra 项目主入口 ├── agents/ # 存放各个 Agent 定义 ├── scorers/ # 存放各个评分器Scorer定义 ├── tools/ # 存放各个工具定义 └── workflows/ # 存放各个工作流定义其中index.ts是 Mastra 应用的主入口mastra dev命令会读取它并启动开发服务器agents/、tools/等目录则按约定组织你的业务代码。启动 Studio一条命令在项目根目录执行npm run dev该命令会启动开发服务器并自动拉起 Studio。启动完成后在浏览器打开http://localhost:4111即可进入 Studio 界面与你的 Agent 交互并测试其能力。npm run dev背后发生了什么npm run dev实际执行的是 Mastra CLI 的mastra dev命令。查看 CLI 源码 dev.ts 可以发现dev 命令会定位项目入口文件src/mastra/index.ts通过findMastraEntryFile解析使用 DevBundler 对入口进行打包产物写入.mastra/index.mjs源码中commands.push(join(dotMastraPath, index.mjs))即是最终启动的服务入口以子进程方式启动打包后的服务器并持续监听文件变化代码改动后自动重启在服务就绪后输出 Studio 的访问地址。值得注意的是端口分配逻辑源码中预定义了一个端口池——Array.from({ length: 21 }, (_, i) 4111 i)即从4111 到 4131 共 21 个候选端口再通过getPort从中挑选第一个空闲端口。因此默认情况下 Studio 运行在4111但若该端口被占用会自动向后顺延不会直接启动失败。这也解释了为什么你在终端里看到的实际端口可能偶尔不是 4111。默认配置的源码依据独立运行的mastra studio命令用于以生产模式托管 Studio在 studio.ts 中给出的默认参数为{ serverHost: localhost, serverPort: 4111, serverProtocol: http, }也就是说本地开发时默认以http协议、监听localhost:4111。官方 Studio 总览文档 还提到服务启动后你还可以访问http://localhost:4111/swagger-ui查看并交互调用底层 REST API方便用脚本或 curl 直接验证接口行为。Studio 能帮你做什么根据入门文档Studio 提供了一套用户友好的测试界面支持向 Agent 发送消息像聊天一样输入你的问题或指令查看 Agent 的响应观察最终输出查看 Agent 的思考过程追踪推理链路与每一步决策直接测试工具不经过 Agent单独调用工具验证其行为调试问题定位开发中出现的各类错误。这些能力覆盖了 Agent 开发中最常用的构建—测试—调试循环。更深一层Studio 的完整功能面入门课程只用到 Studio 最基础的能力但结合 Studio 总览文档可以了解到面向完整开发周期的更多功能方便你后续探索Agents直接与 Agent 对话切换模型调节 temperature、top-p 等采样参数以观察输出差异跟随推理过程、查看工具调用输出也能在同一线程中发送追加上下文的消息。Workflows将工作流可视化为图用自定义输入逐步运行界面实时高亮当前执行步骤与路径工作流 trace 会展示工具调用与原始 JSON 输出以及执行错误。Processors查看挂载在每个 Agent 上的输入/输出处理器含 guardrails 与 token 限制器等确认守卫配置正确后再开始测试。MCP servers列出实例上挂载的 MCP 服务器并浏览其可用工具。Tools单独运行某个工具观察其行为、测试后再挂给 Agent出错时可在隔离状态下重跑以便定位。Workspaces内置文件浏览器查看 Agent 工作区文件、切换挂载点、新建目录、查看带语法高亮的文件内容。Request context通过依赖注入设置运行时变量例如用户 ID、区域设置以 JSON 或 schema 驱动的表单编辑值在测试会话间持久化可触发条件分支而无需重启服务。Evaluation评估查看 Scorer 的异步评估结果创建并管理数据集Dataset支持 CSV/JSON 导入与版本固定对数据集批量运行实验Experiment并对比两次实验以衡量提示词、模型或代码改动的影响。Observability查看 trace 与日志了解响应是如何一步步生成的。Settings配置 Studio 与 Mastra 服务器的连接包括 Mastra 实例 URL、API 前缀默认/api、自定义请求头和主题深色/浅色/跟随系统。这些模块与你后续课程中将要接触的 memory、evals 等内容相互衔接Studio 是观察它们运行效果的统一入口。用 Studio 测试你的第一个 Agent入门课程的 Testing Your Agent 给出了完整测试步骤确保开发服务器已通过npm run dev启动在浏览器打开http://localhost:4111/在 Agent 列表中应能看到你的 Agent例如课程示例中的 Financial Assistant Agent尝试发送类似Hello, can you help me analyze my spending?的消息。此时 Agent 还只能回答基础问题尚未接入交易数据。通过这种交互式测试你可以观察 Agent 对不同输入的反应并在部署到生产环境之前发现需要修复的问题——这正是 Studio 在开发流程中的核心价值。自定义开发服务器配置除了界面中的 Settings 面板官方还支持通过src/mastra/index.ts中的server配置项调整开发服务器行为参见 Server 配置参考 与 Configuration 参考若存在对应的配置章节。常用选项包括server.port修改监听端口默认4111server.host修改监听主机默认localhost可改为0.0.0.0以便局域网访问server.https/--https标志以 HTTPS 模式启动开发服务器。运行mastra dev --https时CLI 会自动为localhost或你配置的 host生成并管理私钥与证书源码中通过devcert实现适合需要安全上下文的本地调试场景。小结与下一步npm run dev是 Mastra 本地开发的核心入口它一键启动开发服务器并拉起 Studio默认http://localhost:4111端口池 4111–4131 自动避让占用。在 Studio 中你可以对话测试 Agent、查看思考链路、独立运行工具、调试问题还可以进一步探索工作流可视化、评估实验与可观测性。下一步按照入门课程 Understanding System Prompts 与 Creating Your Agent 的内容为 Agent 编写系统提示词并注册到src/mastra/index.ts然后回到 Studio 中验证效果——你会直观看到提示词改动如何影响 Agent 的行为表现。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
运行 Mastra Studio：用 `npm run dev` 启动本地开发环境并测试你的第一个 Agent
运行 Mastra Studio用npm run dev启动本地开发环境并测试你的第一个 Agent【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本篇指南是 Mastra 官方入门课程创建第一个 Agent系列中的一环讲解如何启动Mastra Studio——Mastra 框架内置的交互式开发与测试工作台。你将在本地运行npm run dev启动开发服务器在http://localhost:4111打开 Studio与自己的 Agent 对话、观察其思考过程、直接测试工具并排查问题为后续编写系统提示词、注册自定义工具和接入记忆能力打下调试基础。为什么需要一个交互式 Studio在你编写 Agent 的过程中代码是否正确、提示词是否生效、工具返回是否符合预期往往只有真正跑起来才知道。Mastra Studio 正是为此而生的可视化开发环境它连接你本地的 Mastra 服务器把 Agent、工作流Workflow、工具Tool等原语以图形界面暴露出来让你无需编写额外客户端代码就能边构建边验证。从仓库的文档结构看官方对 Studio 的定位是用于构建、测试和管理 agents、workflows、processors、tools 与 MCP servers同时检查 trace 与运行时行为的交互式 UI参见 Studio 总览文档。本文聚焦入门课程第 5 步的核心任务把 Studio 跑起来并理解它能为你做什么。前提项目结构就绪在启动 Studio 之前请确保你的 Mastra 项目已经创建完成并具备标准目录结构。按入门课程 Verifying Project Structure 的描述一个由 CLI 生成的项目应包含src/mastra/ ├── index.ts # Mastra 项目主入口 ├── agents/ # 存放各个 Agent 定义 ├── scorers/ # 存放各个评分器Scorer定义 ├── tools/ # 存放各个工具定义 └── workflows/ # 存放各个工作流定义其中index.ts是 Mastra 应用的主入口mastra dev命令会读取它并启动开发服务器agents/、tools/等目录则按约定组织你的业务代码。启动 Studio一条命令在项目根目录执行npm run dev该命令会启动开发服务器并自动拉起 Studio。启动完成后在浏览器打开http://localhost:4111即可进入 Studio 界面与你的 Agent 交互并测试其能力。npm run dev背后发生了什么npm run dev实际执行的是 Mastra CLI 的mastra dev命令。查看 CLI 源码 dev.ts 可以发现dev 命令会定位项目入口文件src/mastra/index.ts通过findMastraEntryFile解析使用 DevBundler 对入口进行打包产物写入.mastra/index.mjs源码中commands.push(join(dotMastraPath, index.mjs))即是最终启动的服务入口以子进程方式启动打包后的服务器并持续监听文件变化代码改动后自动重启在服务就绪后输出 Studio 的访问地址。值得注意的是端口分配逻辑源码中预定义了一个端口池——Array.from({ length: 21 }, (_, i) 4111 i)即从4111 到 4131 共 21 个候选端口再通过getPort从中挑选第一个空闲端口。因此默认情况下 Studio 运行在4111但若该端口被占用会自动向后顺延不会直接启动失败。这也解释了为什么你在终端里看到的实际端口可能偶尔不是 4111。默认配置的源码依据独立运行的mastra studio命令用于以生产模式托管 Studio在 studio.ts 中给出的默认参数为{ serverHost: localhost, serverPort: 4111, serverProtocol: http, }也就是说本地开发时默认以http协议、监听localhost:4111。官方 Studio 总览文档 还提到服务启动后你还可以访问http://localhost:4111/swagger-ui查看并交互调用底层 REST API方便用脚本或 curl 直接验证接口行为。Studio 能帮你做什么根据入门文档Studio 提供了一套用户友好的测试界面支持向 Agent 发送消息像聊天一样输入你的问题或指令查看 Agent 的响应观察最终输出查看 Agent 的思考过程追踪推理链路与每一步决策直接测试工具不经过 Agent单独调用工具验证其行为调试问题定位开发中出现的各类错误。这些能力覆盖了 Agent 开发中最常用的构建—测试—调试循环。更深一层Studio 的完整功能面入门课程只用到 Studio 最基础的能力但结合 Studio 总览文档可以了解到面向完整开发周期的更多功能方便你后续探索Agents直接与 Agent 对话切换模型调节 temperature、top-p 等采样参数以观察输出差异跟随推理过程、查看工具调用输出也能在同一线程中发送追加上下文的消息。Workflows将工作流可视化为图用自定义输入逐步运行界面实时高亮当前执行步骤与路径工作流 trace 会展示工具调用与原始 JSON 输出以及执行错误。Processors查看挂载在每个 Agent 上的输入/输出处理器含 guardrails 与 token 限制器等确认守卫配置正确后再开始测试。MCP servers列出实例上挂载的 MCP 服务器并浏览其可用工具。Tools单独运行某个工具观察其行为、测试后再挂给 Agent出错时可在隔离状态下重跑以便定位。Workspaces内置文件浏览器查看 Agent 工作区文件、切换挂载点、新建目录、查看带语法高亮的文件内容。Request context通过依赖注入设置运行时变量例如用户 ID、区域设置以 JSON 或 schema 驱动的表单编辑值在测试会话间持久化可触发条件分支而无需重启服务。Evaluation评估查看 Scorer 的异步评估结果创建并管理数据集Dataset支持 CSV/JSON 导入与版本固定对数据集批量运行实验Experiment并对比两次实验以衡量提示词、模型或代码改动的影响。Observability查看 trace 与日志了解响应是如何一步步生成的。Settings配置 Studio 与 Mastra 服务器的连接包括 Mastra 实例 URL、API 前缀默认/api、自定义请求头和主题深色/浅色/跟随系统。这些模块与你后续课程中将要接触的 memory、evals 等内容相互衔接Studio 是观察它们运行效果的统一入口。用 Studio 测试你的第一个 Agent入门课程的 Testing Your Agent 给出了完整测试步骤确保开发服务器已通过npm run dev启动在浏览器打开http://localhost:4111/在 Agent 列表中应能看到你的 Agent例如课程示例中的 Financial Assistant Agent尝试发送类似Hello, can you help me analyze my spending?的消息。此时 Agent 还只能回答基础问题尚未接入交易数据。通过这种交互式测试你可以观察 Agent 对不同输入的反应并在部署到生产环境之前发现需要修复的问题——这正是 Studio 在开发流程中的核心价值。自定义开发服务器配置除了界面中的 Settings 面板官方还支持通过src/mastra/index.ts中的server配置项调整开发服务器行为参见 Server 配置参考 与 Configuration 参考若存在对应的配置章节。常用选项包括server.port修改监听端口默认4111server.host修改监听主机默认localhost可改为0.0.0.0以便局域网访问server.https/--https标志以 HTTPS 模式启动开发服务器。运行mastra dev --https时CLI 会自动为localhost或你配置的 host生成并管理私钥与证书源码中通过devcert实现适合需要安全上下文的本地调试场景。小结与下一步npm run dev是 Mastra 本地开发的核心入口它一键启动开发服务器并拉起 Studio默认http://localhost:4111端口池 4111–4131 自动避让占用。在 Studio 中你可以对话测试 Agent、查看思考链路、独立运行工具、调试问题还可以进一步探索工作流可视化、评估实验与可观测性。下一步按照入门课程 Understanding System Prompts 与 Creating Your Agent 的内容为 Agent 编写系统提示词并注册到src/mastra/index.ts然后回到 Studio 中验证效果——你会直观看到提示词改动如何影响 Agent 的行为表现。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考