Mastra Framework: Cấu trúc dự án mặc định và tổ chức thư mục
Trust: ★★★☆☆ (0.90) · 0 validations · factual
Published: 2026-05-09 · Source: crawler_authoritative
Tình huống
Tài liệu kỹ thuật về framework Mastra - một framework AI agent dành cho việc xây dựng và điều phối các agent thông minh. Dự án được tạo thông qua lệnh create mastra.
Insight
Mastra là một framework nhưng không bắt buộc cách tổ chức hay đặt cùng vị trí các file. CLI cung cấp cấu trúc mặc định hợp lý hoạt động tốt cho hầu hết các dự án, nhưng có thể tự do điều chỉnh theo quy trình làm việc hoặc quy ước nhóm. Thậm chí có thể xây dựng toàn bộ dự án trong một file duy nhất. Cấu trúc dự án mặc định gồm: src/mastra chứa agents (định nghĩa agent với behavior, goals, tools), workflows (quy trình đa bước điều phối agents và tools), tools (công cụ tái sử dụng agent có thể gọi), scorers (định nghĩa scorers Reviews hiệu suất agent theo thời gian), và index.ts (entry point trung tâm cấu hình và khởi tạo Mastra). Các file cấp cao nhất: .env.example (template biến môi trường cho model provider keys), package.json (metadata dự án, dependencies, npm scripts), tsconfig.json (cấu hình TypeScript như path aliases, compiler settings). Folder mcp (tùy chọn) triển khai MCP servers để chia sẻ tools với external agents. Folder public (tùy chọn) chứa nội dung được copy vào .build/output directory khi build.
Hành động
Sử dụng lệnh create mastra để tạo dự án mới với cấu trúc mặc định. Sao chép và điều chỉnh các file template được định nghĩa sẵn để nhanh chóng tạo agents, tools, workflows riêng. Copy và đổi tên .env.example thành .env để thêm secret model provider keys. Có thể tích hợp với frontend frameworks: Next.js, React (Vite), hoặc Astro.
Điều kiện áp dụng
Framework linh hoạt, không bắt buộc cấu trúc cố định. Phù hợp cho developer xây dựng AI agents và workflows. Có thể adapt theo quy trình team hoặc thậm chí xây dựng trong một file duy nhất nếu muốn.
Nội dung gốc (Original)
Project structure
Your new Mastra project, created with the create mastra command, comes with a predefined set of files and folders to help you get started.
Mastra is a framework, but it’s unopinionated about how you organize or colocate your files. The CLI provides a sensible default structure that works well for most projects, but you’re free to adapt it to your workflow or team conventions. You could even build your entire project in a single file if you wanted! Whatever structure you choose, keep it consistent to ensure your code stays maintainable and straightforward to navigate.
Default project structure
A project created with the create mastra command looks like this:
src/
├── mastra/
│ ├── agents/
│ │ └── weather-agent.ts
│ ├── tools/
│ │ └── weather-tool.ts
│ ├── workflows/
│ │ └── weather-workflow.ts
│ ├── scorers/
│ │ └── weather-scorer.ts
│ └── index.ts
├── .env.example
├── package.json
└── tsconfig.jsonTip: Use the predefined files as templates. Duplicate and adapt them to quickly create your own agents, tools, workflows, etc.
Folders
Folders organize your agent’s resources, like agents, tools, and workflows.
| Folder | Description |
|---|---|
src/mastra | Entry point for all Mastra-related code and configuration. |
src/mastra/agents | Define and configure your agents - their behavior, goals, and tools. |
src/mastra/workflows | Define multi-step workflows that orchestrate agents and tools together. |
src/mastra/tools | Create reusable tools that your agents can call |
src/mastra/mcp | (Optional) Implement custom MCP servers to share your tools with external agents |
src/mastra/scorers | (Optional) Define scorers for evaluating agent performance over time |
src/mastra/public | (Optional) Contents are copied into the .build/output directory during the build process, making them available for serving at runtime |
Top-level files
Top-level files define how your Mastra project is configured, built, and connected to its environment.
| File | Description |
|---|---|
src/mastra/index.ts | Central entry point where you configure and initialize Mastra. |
.env.example | Template for environment variables - copy and rename to .env to add your secret model provider keys. |
package.json | Defines project metadata, dependencies, and available npm scripts. |
tsconfig.json | Configures TypeScript options such as path aliases, compiler settings, and build output. |
Next steps
- Read more about Mastra’s features.
- Integrate Mastra with your frontend framework: Next.js, React, or Astro.
- Build an agent from scratch following one of our guides.
- Watch conceptual guides on our YouTube channel and subscribe!
Liên kết
- Nền tảng: Other
- Nguồn: https://mastra.ai/docs/getting-started/project-structure
Xem thêm: