Introducing File-Based Agents for Mastra

You can now build file-based agents in Mastra. Each agent is defined by a folder with model config, instructions, tools, skills, memory, and workspace as separate files.

We shipped file-based agents to give you a convention to follow and a faster path toward creating your first agent. Existing Mastra code-registered agents will continue to work and can be used alongside file-based agents.

File-based agents follow a defined file and folder structure.

Files are for one-of-a-kind pieces. The config.ts and instructions.md follow a new convention, while memory.ts and workspace.ts use existing Mastra classes.

Folders are for the many. tools/ remain the same, but subagents/ now follow the same convention as top-level file-based agents.

└── weather-agent/
    ├── config.ts
    ├── instructions.md
    ├── memory.ts
    └── workspace.ts
    ├── tools/
    │   └── get-weather.ts
    └── subagents/
        └── activity-planner/
            ├── config.ts
            └── instructions.md
            ├── memory.ts
            └── workspace.ts

Skills live in a skills/ folder and can be setup in different ways:

1. An .md file (forecasting.md) defines the skill as markdown text.
2. A .ts file (temperature-units.ts) defines the skill in code.
3. A <name>/ folder (severe-weather/) defines the skill as markdown text (SKILL.md) with optional additional references (thresholds.md).

└── weather-agent/
    // ...
    └── skills/
        ├── forecasting.md
        ├── temperature-units.ts
        └── severe-weather/
            ├── SKILL.md
            └── references/
                └── thresholds.md
 

Use file-based agents when you want one directory per agent; use code-registered agents when you need dynamic configuration or programmatic registration.

Get started

Create a folder for the agent under src/mastra/agents/.

Create a config.ts defining the model to use:

import { agentConfig } from "@mastra/core/agent";
 
export default agentConfig({
  model: "anthropic/claude-opus-4-8"
});

Create an instructions.md for the agent's instructions:

You are a helpful weather assistant. Provide accurate current conditions and suggest activities that suit the forecast.

Export an empty Mastra instance from src/mastra/index.ts. This step might not be required in future releases:

import { Mastra } from "@mastra/core/mastra";
 
export const mastra = new Mastra({});

For more information and full configuration options, see:

• File-based agents
• Agents overview
• Agent skills
• Supervisor agents
• Workspace