进阶 mastra.ai 2026-10-12 10:15:56 · 30 阅读
第19章 Mastra Studio 使用指南
# Studio
Studio 提供了一个交互式界面，用于构建、测试和管理你的 agent、workflow 和工具。开发阶段可以在本地运行，也可以加上认证后部署到生产环境，让团队管理 agent、监控性能，并通过内置的可观测性功能获取洞察。
📹 观看 Mastra Studio 概览，快速了解如何在 Studio 中构建、测试和管理 agent。
## 启动 Studio
如果你是用 create mastra 创建的应用，直接用 dev 脚本启动开发服务器即可，也可以用 mastra dev 直接运行。
npmpnpmYarnBunnpm run dev
pnpm run dev
yarn dev
bun run dev
服务器运行后，你可以： 在 localhost:4111 打开 Studio 界面，与你的 agent、workflow 和工具进行交互。 访问 localhost:4111/swagger-ui 查看并调试底层 REST API。 Studio 让你可以实时编辑 agent、workflow 以及 Mastra 应用的其他部分。 部署 Studio 想与团队共享 Studio 时，可以通过 Mastra 平台上的 Studio 或自己的基础设施将其部署到生产环境。详情请参阅部署文档。 核心功能 Agents 直接与 agent 对话，切换模型，调整 temperature、top-p 等参数，观察它们对输出的影响。 与 agent 交互时，你可以查看它的推理过程和工具调用输出，也可以通过 trace 和日志了解响应是如何生成的。 如果响应中包含 markdown 表格，可以点击表格上方的 Copy table as markdown，将其单独复制（不含周围消息）。复制的表格保留 markdown 格式，并包含其使用的链接和脚注定义。要以 CSV 格式下载表格，点击复制按钮旁的箭头并选择 Download CSV。这两个操作要等包含表格的文本段完成流式输出并显示后才可用——此时 agent 可能仍在运行工具或输出后续内容。 CSV 导出只包含纯文本单元格，链接显示为标签文字而非 URL。脚注标记会保留，但定义不会写入 CSV。可能被表格软件识别为公式的值会自动加上前导单引号，确保表格软件将其当作文本处理；普通的带符号数字则原样保留。 你还可以为 agent 挂载 scorer，用于度量和对比不同时期的响应质量。 在 agent 流式响应期间，你也可以在同一会话中发送后续消息。Studio 会先将其显示为待处理，等流式传输确认后再在其下方继续输出响应。其他打开了同一会话的 Studio 标签页也能观察到正在进行的流式输出。 使用 Editor，让非技术团队成员也能迭代 agent，每次修改都会记录版本，还能在不重新部署的情况下做实验。 使用 Agent Builder，通过独立的浏览器界面创建和管理完全持久化的 agent。 Workflows 将 workflow 以图形方式可视化，用自定义输入逐步运行。执行过程中，界面会实时更新，显示当前步骤和已走过的路径。 Workflow 的 trace 会展示工具调用和原始 JSON 输出，以及执行过程中的报错。 点击运行按钮旁的 Run Options，可以为启动的运行设置 Resource ID。Studio 会为每个 workflow 记住该值，创建的运行会列在 GET /api/workflows/:workflowId/runs?resourceId=... 中。留空则创建不带 resource 的运行。如果服务端根据已认证用户生成 resource ID，则以服务端的值为准。 Processors 查看每个 agent 挂载的输入和输出处理器。agent 详情面板会按名称和类型列出所有处理器，方便你在测试前确认 guardrail、token 限制器以及自定义处理器都已正确接入。 配置详情请参阅 processors 和 guardrails。 MCP servers 列出 Mastra 实例挂载的 MCP server，并浏览它们提供的可用工具。 Tools 单独运行工具，观察其行为，在分配给 agent 之前先做测试。出问题时，可以隔离重跑该工具来排查。 Workspaces 用内置的文件浏览器查看 agent 的 workspace 文件系统。可以在不同 workspace 挂载点之间切换、创建目录、以语法高亮查看文件内容。可写的 workspace 支持创建目录和删除文件，只读的 workspace 会有相应标注。Skills 标签页列出所有已发现的 skill 及其指令、引用文件和元数据，可以从 skills.sh 安装社区 skill，也可以删除已有的。 配置详情请参阅 workspaces。 Request context 通过依赖注入设置运行时变量，供 agent 的指令和工具使用。可以以 JSON 形式编辑 request context；如果 agent 定义了 requestContextSchema，还可以使用基于 schema 的表单。这些值在测试对话和实验之间会保持，因此无需重启即可触发条件分支。 配置详情请参阅 request context。 评估 使用日期筛选器，将分数指标限制在预设或自定义的时间范围内。 Scorers Scorers 标签页会实时展示 agent 的 scorer 运行结果。消息经过 agent 处理时，已定义的 scorer 会异步评估每个输出，并把结果呈现在这里。你可以借此了解 scorer 在不同交互下的表现，对比不同测试用例的效果，并找出需要改进的地方。 Datasets 创建并管理用于评估 agent 和 workflow 的测试用例集合。可以从 CSV 或 JSON 导入条目，定义输入和标准答案（ground truth）的 schema，还可以固定到特定版本，确保实验可精确复现。搭配 scorer 运行实验，即可对比不同 prompt、模型或代码改动下的质量差异。 完整的 API 和版本管理说明请参阅 datasets overview。 Experiments 将数据集中的所有条目在某个 agent、workflow 或 scorer 上批量运行，并把结果集中到一处。选择目标，可选挂载 scorer，然后触发实验。结果视图展示每个条目的输入、输出、状态和各项得分明细。还可以将两次实验并排对比，衡量 prompt、模型或代码改动带来的影响。 配置说明请参阅 datasets overview。 可观测性 详见 Studio 可观测性文档。 Settings 配置 Studio 与 Mastra 服务器之间的连接。设置页面包括： Mastra instance URL：Mastra 服务器的基础 URL（例如 http://localhost:4111）。 API prefix：所有 API 请求的可选路径前缀（默认为 /api）。 Custom headers：为每个请求添加键值对，适合放认证 token 或路由相关的 header。 Theme：在深色、浅色和跟随系统主题之间切换。 代码配置 除了设置界面，你还可以在 src/mastra/index.ts 的 server 选项中配置本地开发服务器和 Studio。 默认情况下，Studio 运行在 http://localhost:4111，你可以修改主机和端口。 Mastra 还支持通过 --https 标志进行 HTTPS 开发，并会自动为项目创建和管理证书。运行 mastra dev --https 时，会为 localhost（或你配置的主机）生成私钥和证书。详见 HTTPS 参考。 后续步骤 了解如何将 Studio 部署到生产环境。 为已部署的 Studio 添加身份验证，控制访问权限。 探索 Studio 可观测性，通过指标、trace 和日志监控 agent 性能。
pnpm run dev
yarn dev
bun run dev
服务器运行后，你可以： 在 localhost:4111 打开 Studio 界面，与你的 agent、workflow 和工具进行交互。 访问 localhost:4111/swagger-ui 查看并调试底层 REST API。 Studio 让你可以实时编辑 agent、workflow 以及 Mastra 应用的其他部分。 部署 Studio 想与团队共享 Studio 时，可以通过 Mastra 平台上的 Studio 或自己的基础设施将其部署到生产环境。详情请参阅部署文档。 核心功能 Agents 直接与 agent 对话，切换模型，调整 temperature、top-p 等参数，观察它们对输出的影响。 与 agent 交互时，你可以查看它的推理过程和工具调用输出，也可以通过 trace 和日志了解响应是如何生成的。 如果响应中包含 markdown 表格，可以点击表格上方的 Copy table as markdown，将其单独复制（不含周围消息）。复制的表格保留 markdown 格式，并包含其使用的链接和脚注定义。要以 CSV 格式下载表格，点击复制按钮旁的箭头并选择 Download CSV。这两个操作要等包含表格的文本段完成流式输出并显示后才可用——此时 agent 可能仍在运行工具或输出后续内容。 CSV 导出只包含纯文本单元格，链接显示为标签文字而非 URL。脚注标记会保留，但定义不会写入 CSV。可能被表格软件识别为公式的值会自动加上前导单引号，确保表格软件将其当作文本处理；普通的带符号数字则原样保留。 你还可以为 agent 挂载 scorer，用于度量和对比不同时期的响应质量。 在 agent 流式响应期间，你也可以在同一会话中发送后续消息。Studio 会先将其显示为待处理，等流式传输确认后再在其下方继续输出响应。其他打开了同一会话的 Studio 标签页也能观察到正在进行的流式输出。 使用 Editor，让非技术团队成员也能迭代 agent，每次修改都会记录版本，还能在不重新部署的情况下做实验。 使用 Agent Builder，通过独立的浏览器界面创建和管理完全持久化的 agent。 Workflows 将 workflow 以图形方式可视化，用自定义输入逐步运行。执行过程中，界面会实时更新，显示当前步骤和已走过的路径。 Workflow 的 trace 会展示工具调用和原始 JSON 输出，以及执行过程中的报错。 点击运行按钮旁的 Run Options，可以为启动的运行设置 Resource ID。Studio 会为每个 workflow 记住该值，创建的运行会列在 GET /api/workflows/:workflowId/runs?resourceId=... 中。留空则创建不带 resource 的运行。如果服务端根据已认证用户生成 resource ID，则以服务端的值为准。 Processors 查看每个 agent 挂载的输入和输出处理器。agent 详情面板会按名称和类型列出所有处理器，方便你在测试前确认 guardrail、token 限制器以及自定义处理器都已正确接入。 配置详情请参阅 processors 和 guardrails。 MCP servers 列出 Mastra 实例挂载的 MCP server，并浏览它们提供的可用工具。 Tools 单独运行工具，观察其行为，在分配给 agent 之前先做测试。出问题时，可以隔离重跑该工具来排查。 Workspaces 用内置的文件浏览器查看 agent 的 workspace 文件系统。可以在不同 workspace 挂载点之间切换、创建目录、以语法高亮查看文件内容。可写的 workspace 支持创建目录和删除文件，只读的 workspace 会有相应标注。Skills 标签页列出所有已发现的 skill 及其指令、引用文件和元数据，可以从 skills.sh 安装社区 skill，也可以删除已有的。 配置详情请参阅 workspaces。 Request context 通过依赖注入设置运行时变量，供 agent 的指令和工具使用。可以以 JSON 形式编辑 request context；如果 agent 定义了 requestContextSchema，还可以使用基于 schema 的表单。这些值在测试对话和实验之间会保持，因此无需重启即可触发条件分支。 配置详情请参阅 request context。 评估 使用日期筛选器，将分数指标限制在预设或自定义的时间范围内。 Scorers Scorers 标签页会实时展示 agent 的 scorer 运行结果。消息经过 agent 处理时，已定义的 scorer 会异步评估每个输出，并把结果呈现在这里。你可以借此了解 scorer 在不同交互下的表现，对比不同测试用例的效果，并找出需要改进的地方。 Datasets 创建并管理用于评估 agent 和 workflow 的测试用例集合。可以从 CSV 或 JSON 导入条目，定义输入和标准答案（ground truth）的 schema，还可以固定到特定版本，确保实验可精确复现。搭配 scorer 运行实验，即可对比不同 prompt、模型或代码改动下的质量差异。 完整的 API 和版本管理说明请参阅 datasets overview。 Experiments 将数据集中的所有条目在某个 agent、workflow 或 scorer 上批量运行，并把结果集中到一处。选择目标，可选挂载 scorer，然后触发实验。结果视图展示每个条目的输入、输出、状态和各项得分明细。还可以将两次实验并排对比，衡量 prompt、模型或代码改动带来的影响。 配置说明请参阅 datasets overview。 可观测性 详见 Studio 可观测性文档。 Settings 配置 Studio 与 Mastra 服务器之间的连接。设置页面包括： Mastra instance URL：Mastra 服务器的基础 URL（例如 http://localhost:4111）。 API prefix：所有 API 请求的可选路径前缀（默认为 /api）。 Custom headers：为每个请求添加键值对，适合放认证 token 或路由相关的 header。 Theme：在深色、浅色和跟随系统主题之间切换。 代码配置 除了设置界面，你还可以在 src/mastra/index.ts 的 server 选项中配置本地开发服务器和 Studio。 默认情况下，Studio 运行在 http://localhost:4111，你可以修改主机和端口。 Mastra 还支持通过 --https 标志进行 HTTPS 开发，并会自动为项目创建和管理证书。运行 mastra dev --https 时，会为 localhost（或你配置的主机）生成私钥和证书。详见 HTTPS 参考。 后续步骤 了解如何将 Studio 部署到生产环境。 为已部署的 Studio 添加身份验证，控制访问权限。 探索 Studio 可观测性，通过指标、trace 和日志监控 agent 性能。
