Studio

Studio 提供交互式 UI，用于构建、测试和管理 Agent、Workflow 与 Tool。你可以在开发期间本地运行 Studio、添加身份验证，或将其部署到生产环境，让团队管理 Agent、监控性能，并通过内置 Observability 获取洞察。

📹 观看视频

观看 Mastra Studio 概述，快速了解如何在 Studio 中构建、测试和管理 Agent。

启动 Studio

如果应用是通过 create mastra 创建的，请使用 dev 脚本启动开发 Server。也可以直接运行 mastra dev。

npm

npm run dev

pnpm

pnpm run dev

Yarn

yarn dev

Bun

bun run dev

Server 运行后，你可以：

• 打开 localhost:4111 上的 Studio UI，与 Agent、Workflow 和 Tool 交互。
• 访问 localhost:4111/swagger-ui，浏览底层 REST API 并与之交互。

Studio 运行期间，你可以实时编辑 Agent、Workflow 和 Mastra 应用的其他部分。

部署 Studio

准备好与团队共享 Studio 时，可以使用 Mastra platform 上的 Studio 或自己的基础设施将其部署到生产环境。有关具体方法，请参阅部署文档。

原语

Agent

直接与 Agent 对话、切换模型，并调整 temperature、top-p 等设置，了解它们对输出的影响。

与 Agent 交互时，你可以跟踪其推理过程并查看 Tool 调用输出。还可以通过 Observability 查看 Trace 和日志，了解响应的生成方式。

你还可以关联 Scorer，长期衡量和比较响应质量。

在 Agent 响应流式传输期间，你可以在同一 thread 中发送后续消息。Studio 会将该消息显示为待处理，直到流确认它，然后在后续消息下方继续响应。打开同一 thread 的其他 Studio 标签页也能观察活跃的流。

使用 Editor，让非技术团队成员迭代 Agent、对每次更改进行版本控制，并且无需重新部署即可运行实验。

Workflow

将 Workflow 可视化为图，并使用自定义输入逐步运行。执行期间，界面会实时更新，显示当前活动步骤和经过的路径。

运行 Workflow 时，还可以查看详细 Trace，其中包含 Tool 调用、原始 JSON 输出，以及过程中可能发生的任何错误。

Processor

查看关联到每个 Agent 的输入和输出 Processor。Agent 详情面板会按名称和类型列出所有 Processor，便于你在测试前确认 guardrail、token limiter 和自定义 Processor 均已正确连接。

有关配置详情，请参阅 Processor 和 guardrail。

MCP Server

列出关联到 Mastra 实例的 MCP Server，并浏览其可用 Tool。

Tool

单独运行 Tool，观察其行为并在分配给 Agent 前进行测试。如果出现问题，可单独重新运行 Tool 来调试。

Workspace

使用内置文件浏览器浏览 Agent Workspace 文件系统中的文件。你可以在 Workspace 挂载点之间切换、创建目录，并通过语法高亮查看文件内容。可写 Workspace 支持创建目录和删除文件；只读 Workspace 会带有相应标签。Skills 标签页会列出发现的所有 Skill 及其说明、Reference 和 metadata。你可以从 skills.sh 安装社区 Skill，或移除现有 Skill。

有关配置详情，请参阅 Workspace。

请求上下文

设置运行时变量，通过依赖注入将其传入 Agent 指令和 Tool。你可以将请求上下文编辑为 JSON；如果 Agent 定义了 requestContextSchema，也可以使用由 schema 驱动的表单。值会在测试对话和实验之间保留，因此无需重启即可触发条件流程。

有关配置详情，请参阅请求上下文。

评估

使用日期筛选器，将评分指标限制在预设或自定义时间范围内。

Scorer

Scorers 标签页会在 Agent 的 Scorer 运行时显示结果。当消息经过 Agent 时，定义的 Scorer 会异步评估每个输出，并在此处呈现结果。你可以了解 Scorer 对不同交互的响应、比较各测试用例的表现，并找出需要改进的方面。

数据集

创建并管理测试用例集合，用于评估 Agent 和 Workflow。你可以从 CSV 或 JSON 导入条目、定义输入和 ground-truth schema，并固定到特定版本以准确复现实验。使用 Scorer 运行实验，比较不同 prompt、模型或代码更改的质量。

有关完整 API 和版本控制详情，请参阅数据集概述。

实验

针对 Agent、Workflow 或 Scorer 运行数据集中的所有条目，并集中收集结果。选择目标、按需关联 Scorer，然后触发实验。结果视图会显示每个条目的输入、输出、状态和各项评分明细。你可以并排比较两个实验，衡量 prompt、模型或代码更改的影响。

有关设置详情，请参阅数据集概述。

Observability

请参阅 Studio Observability 文档了解详情。

设置

配置 Studio 与 Mastra Server 之间的连接。设置页面包括：

• Mastra 实例 URL：Mastra Server 的基础 URL（例如 http://localhost:4111）。
• API 前缀：所有 API 请求的可选路径前缀（默认为 /api）。
• 自定义 header：添加随每个请求发送的键值对，可用于身份验证 token 或路由 header。
• 主题：在深色、浅色或系统主题之间切换。

代码配置

除设置 UI 外，你还可以通过 src/mastra/index.ts 中的 server 选项配置本地开发 Server 和 Studio。

Studio 默认运行在 http://localhost:4111。你可以更改 host 和 port。

Mastra 还通过 --https 标志支持 HTTPS 开发，该标志会自动为项目创建和管理证书。运行 mastra dev --https 时，系统会为 localhost（或你配置的 host）生成私钥和证书。有关详情，请参阅 HTTPS Reference。

后续步骤

• 了解如何将 Studio 部署到生产环境。
• 添加身份验证，控制对已部署 Studio 的访问。
• 探索 Studio Observability，通过指标、Trace 和日志监控 Agent 性能。