开发

创建 Mastra 项目后，你就可以开始开发、运行和测试 Agent 了。

在本地运行 Mastra

查看 Agent 运行效果的最快方式是使用 Mastra Studio。在项目根目录，使用 mastra dev 同时启动 Studio 和本地开发服务器：

npm

npx mastra dev

pnpm

pnpm dlx mastra dev

Yarn

yarn dlx mastra dev

Bun

bun x mastra dev

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

开发服务器还会为 Agent、工具和 Workflow 暴露 API。打开 http://localhost:4111/api 浏览可用接口，然后使用 Mastra Client 连接前端。

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

使用 AI 构建

Mastra 提供技能和 CLI，帮助你的编码 Agent 编写高质量的 Mastra 代码。

Mastra 技能

AI 模型可能没有关于 Mastra API 的最新知识。使用 Mastra 技能为你的编码 Agent 提供实现指导和最佳实践，包括获取最新 Mastra 文档的说明。你的编码 Agent 还可以与 Mastra Factory 交互。

手动安装技能：

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

定期更新技能以获取最新指导：

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 技能，以便你的编码 Agent 发现并使用它们。

Mastra CLI

使用 mastra CLI 为编码 Agent 提供测试更新和检查结果的反馈闭环。CLI 让它能够访问 Agent、Workflow、工具、记忆、评估、Trace 和日志。

例如，你的编码 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 技能，让你的编码 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

备注

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

📹 观看

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

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

文件系统直接反映项目结构，因此你和编码 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 会注册名为 search_docs 的工具，而 skills/style-guide.md 会注册名为 style-guide 的技能。请参阅下方的扩展路径。

扩展你的 Agent

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

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

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

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