> Discover all available pages from the documentation index: https://mastra.ai/llms.txt # File-based agents **Added in:** `@mastra/core@1.50.0` > **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable. File-based agents are an experimental, convention-based way to define [Mastra agents](https://mastra.ai/docs/agents/overview) and the primitives they use in files under `src/mastra/`, instead of registering them manually on your [`Mastra`](https://mastra.ai/reference/core/mastra-class) instance. This approach reduces glue code and makes the file system itself a direct representation of your [project structure](https://mastra.ai/reference/project-structure), so both you and your coding agent can understand it at a glance. You can build your entire project with file-based agents or combine this approach with agents and other primitives defined directly in code, making it easy to adopt incrementally. File-based agents have some limitations while in beta. Not every Mastra feature can be defined in a file yet, and they are not the best fit for dynamic configuration or runtime wiring. When needed, you can define agents and related primitives directly in code. > **Note:** All Mastra documentation currently shows agents and primitives defined directly in code. File-based agents use the same underlying concepts and APIs, so the guidance elsewhere in the docs still applies. As file-based agents mature, more examples may use this structure where appropriate. ## Basic layout A small file-based agent looks like this: ```text src/mastra/ agents/ weather/ config.ts instructions.md tools/ get-weather.ts skills/ forecast-review.md ``` The main files in an agent directory are: - [`config.ts`](https://mastra.ai/reference/file-based-agents/config): Model selection and runtime options - [`instructions.md`](https://mastra.ai/reference/file-based-agents/instructions): The prompt that applies to every response - [`tools/`](https://mastra.ai/reference/file-based-agents/tools): Typed functions the model can call - [`skills/`](https://mastra.ai/reference/file-based-agents/skills): Reusable instructions You need to define `config.ts` and `instructions.md` at a minimum. Add optional files as needed. Learn more in the [add capabilities](#add-capabilities) section. ## Quickstart Create a folder at `src/mastra/agents/weather`. Inside, add a `config.ts` and an `instructions.md` file with these contents: ```typescript import { agentConfig } from '@mastra/core/agent' export default agentConfig({ model: 'openai/gpt-5.5', }) ``` ```markdown You are a helpful weather assistant. Answer questions about current conditions and forecasts. ``` Start Mastra's development server with `mastra dev`. Inside Studio, you can now call the `weather` agent and ask it about the weather. ## Add capabilities Map each primitive or feature to its file convention: | Primitive or feature | File convention | | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | [Agent config](https://mastra.ai/reference/file-based-agents/config) | `src/mastra/agents//config.ts` | | [Agent instructions](https://mastra.ai/reference/file-based-agents/instructions) | `src/mastra/agents//instructions.md` | | [Tools](https://mastra.ai/reference/file-based-agents/tools) | `src/mastra/agents//tools/` | | [Skills](https://mastra.ai/reference/file-based-agents/skills) | `src/mastra/agents//skills/` | | [Memory](https://mastra.ai/reference/file-based-agents/memory) | `src/mastra/agents//memory.ts` | | [Workspace](https://mastra.ai/reference/file-based-agents/workspace) | `src/mastra/agents//workspace.ts` and `src/mastra/agents//workspace/` | | [Processors](https://mastra.ai/reference/file-based-agents/processors) | `src/mastra/agents//processors/` | | [Scorers](https://mastra.ai/reference/file-based-agents/scorers) | `src/mastra/agents//scorers/` | | [Subagents](https://mastra.ai/reference/file-based-agents/subagents) | `src/mastra/agents//subagents/` | | [Workflows](https://mastra.ai/reference/file-based-agents/workflows) | `src/mastra/workflows/` | | [Storage](https://mastra.ai/reference/file-based-agents/storage) | `src/mastra/storage.ts` | | [Observability](https://mastra.ai/reference/file-based-agents/observability) | `src/mastra/observability.ts` | | [Logger](https://mastra.ai/reference/file-based-agents/logger) | `src/mastra/logger.ts` | | [Server config](https://mastra.ai/reference/file-based-agents/server) | `src/mastra/server.ts` | | [Studio config](https://mastra.ai/reference/file-based-agents/studio) | `src/mastra/studio.ts` | | [Schedules](https://mastra.ai/docs/long-running-agents/schedules) | Not yet file-based — create at runtime with `mastra.schedules.create()` | ## Discovery lifecycle File-based primitives are discovered by the Mastra bundler under `mastra dev` and `mastra build`. During discovery, Mastra reads supported files under `src/mastra/`, imports TypeScript and JavaScript modules, reads markdown instructions and skills, copies workspace seed files, and registers the assembled primitives with your Mastra app. After discovery, a file-based agent runs as a normal [`Agent`](https://mastra.ai/reference/agents/agent). Calling it from the Agent API, Studio, workflows, or your application code uses the same runtime as a code-defined agent. Discovery is source-based and conservative. It skips symlinks, ignores test files, treats workflows and singleton project files as file-routed only when they have a default export, and ignores directories that aren't agent directories. Start your app through the Mastra CLI so discovery runs: **npm**: ```bash npx mastra dev ``` **pnpm**: ```bash pnpm dlx mastra dev ``` **Yarn**: ```bash yarn dlx mastra dev ``` **Bun**: ```bash bun x mastra dev ``` If you import your `mastra` instance directly, `agents//` directories and the other conventions aren't discovered. When you consume Mastra as a library, register those primitives in code instead.