开发

拥有 Mastra 项目后，就可以开始开发、运行和测试 Agent。

在本地运行 Mastra

查看 Agent 运行效果最快的方法是使用 Mastra Studio。在项目根目录中，使用 mastra dev 启动 Studio 和本地开发 Server：

npm

npx mastra dev

pnpm

pnpm dlx mastra dev

Yarn

yarn dlx mastra dev

Bun

bun x mastra dev

在 http://localhost:4111 打开 Studio，以测试 Agent 并检查其运行记录。

开发 Server 还会公开 Agent、Tool 和 Workflow 的 API。打开 http://localhost:4111/api 浏览可用内容，然后使用 Mastra Client 连接前端。

src/mastra/ 目录中的更改会自动重启开发 Server，因此构建过程中无需手动重启。

使用 AI 构建

Mastra 提供 Skill 和 CLI，帮助 coding agent 编写高质量的 Mastra 代码。

Mastra Skill

AI 模型掌握的 Mastra API 知识可能不是最新的。使用 Mastra Skill 为 coding agent 提供实现指导、最佳实践以及获取最新 Mastra 文档的说明。

手动安装 Skill：

npm

npx skills add mastra-ai/skills

pnpm

pnpm dlx skills add mastra-ai/skills

Yarn

yarn dlx skills add mastra-ai/skills

Bun

bun x skills add mastra-ai/skills

定期更新 Skill 以获取最新指导：

npm

npx skills update mastra

pnpm

pnpm dlx skills update mastra

Yarn

yarn dlx skills update mastra

Bun

bun x skills update mastra

备注

使用 create mastra 创建项目时，该命令会自动安装 Mastra Skill，以便 coding agent 发现并使用它。

Mastra CLI

使用 mastra CLI 为 coding agent 提供反馈循环，以测试更新并检查结果。CLI 让它能够访问 Agent、Workflow、Tool、Memory、Evals、Trace 和日志。

例如，coding agent 可以运行 Agent，然后拉取 Trace 来检查结果：

npx mastra api --url http://localhost:4111 agent run agent '{"messages":"Hello"}'
npx mastra api --url http://localhost:4111 trace list

请记得安装 Mastra Skill，让 coding agent 学会使用 CLI。

项目结构

采用框架时，首要决策之一是如何组织项目。建议将框架代码放在 src/mastra/ 下，并将相关原语分组到各自的文件或文件夹中。使用 src/mastra/index.ts 作为配置和注册这些原语的中心位置。

最小项目可以采用以下结构：

src/
  mastra/
    agents/
      agent.ts
    tools/
      tool.ts
    workflows/
      workflow.ts
    scorers/
      scorer.ts
    skills.ts
    index.ts

有关默认布局和推荐约定，请参阅项目结构参考。

基于文件的 Agent

beta

基于文件的 Agent 目前处于 beta 阶段，在稳定之前可能会发生变化。

基于文件的发现仅通过 mastra dev 或 mastra build 运行。如果应用直接导入 mastra（包括通过 Web 框架或 Server 适配器导入），则不会发现基于文件的 Agent。请在代码中注册这些 Agent，或将 Mastra 作为独立 Server 运行。

📹 观看

如何创建第一个基于文件的 Agent

使用基于文件的 Agent 时，Mastra 会自动从 src/mastra/ 下受支持的文件中发现 Agent 和相关原语。你可以按照约定组织这些文件，而无需在 Mastra 实例中逐个导入和注册原语。

文件系统会直接呈现项目结构，因此你和 coding agent 无需追踪代码中各部分的连接方式，也能了解项目如何组合在一起。

你可以在整个项目中使用基于文件的 Agent，也可以将其与代码中定义的原语并用，逐步采用。目前尚未支持所有 Mastra 功能或使用场景。

创建第一个 Agent

基于文件的 Agent 位于 src/mastra/agents/ 下自己的目录中。要创建可运行的 Agent，请添加用于模型和运行时选项的 config.ts 文件，以及用于常驻提示词的 instructions.md 文件：

src/mastra/agents/
  writing-assistant/
    config.ts
    instructions.md

目录名称会成为 Agent 的默认 id 和 name。在此示例中，Mastra 会将 Agent 注册为 writing-assistant。

src/mastra/agents/writing-assistant/config.ts

import { agentConfig } from '@mastra/core/agent'

export default agentConfig({
  model: 'openai/gpt-5.6-sol',
})

src/mastra/agents/writing-assistant/instructions.md

Rewrite text clearly and concisely.

运行 npx mastra dev，打开 Studio，然后选择 writing-assistant 进行测试。

发现机制

Mastra 使用路径来发现基于文件的能力并为其命名。Agent 目录提供默认的 Agent id 和 name。例如，tools/search_docs.ts 会将 Tool 注册为 search_docs，而 skills/style-guide.md 会将 Skill 注册为 style-guide。扩展路径见下文。

扩展 Agent

当 Agent 需要更多功能时，添加相应文件或目录：

路径	添加的功能
tools/<tool-name>.ts	模型可以调用的函数
skills/<skill-name>.md	Agent 在相关情况下加载的详细指导
memory.ts	对话历史记录和工作上下文
workspace.ts and workspace/	文件系统和 shell 访问权限
subagents/<agent-id>/	父 Agent 可以委派任务的专用 Agent

将每项能力放在使用它的 Agent 旁边。开发 Server 启动或重启时，Mastra 会发现并注册这些文件。

浏览基于文件的 Agent 参考，了解所有受支持的文件约定和配置选项。