開發

建立 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、Tool 和 Workflow 提供 API。開啟 http://localhost:4111/api 瀏覽可用內容，然後使用 Mastra Client 連接前端。

當 src/mastra/ 目錄內有變更時，開發伺服器會自動重新啟動，因此開發期間毋須手動重新啟動。

使用 AI 建構

Mastra 提供 Skill 和 CLI，協助編程助手編寫高質素的 Mastra 程式碼。

Mastra Skill

AI 模型對 Mastra API 的認識未必是最新的。使用 Mastra Skill，為編程助手提供實作指引、最佳做法，以及取得最新 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，讓編程助手能夠找到並使用它。

Mastra CLI

使用 mastra CLI，為編程助手建立測試更新和檢查結果的反饋迴圈。CLI 讓它能夠存取 Agent、Workflow、Tool、memory、Evals、Trace 和日誌。

例如，編程助手可以運行 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，讓編程助手學會如何使用 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（包括透過網絡框架或伺服器適配器匯入），便不會找到以文件為基礎的 Agent。請在程式碼中註冊這些 Agent，或將 Mastra 作為獨立伺服器運行。

📹 觀看影片

如何建立第一個以文件為基礎的 Agent

使用以文件為基礎的 Agent 時，Mastra 會自動從 src/mastra/ 下受支援的文件中找到 Agent 和相關基本元件。你可按慣例組織這些文件，毋須逐一匯入每個基本元件並在 Mastra 實例上註冊。

文件系統會直接呈現項目結構，因此你和編程助手毋須追查程式碼中各部分的連接方式，也能了解項目如何組合起來。

你可以在整個項目中使用以文件為基礎的 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 和 workspace/	文件系統和 shell 存取權限
subagents/<agent-id>/	父 Agent 可委派工作的專門 Agent

將每項功能放在使用它的 Agent 旁。開發伺服器啟動或重新啟動時，Mastra 會找到並註冊這些文件。

瀏覽以文件為基礎的 Agent 參考，查看所有受支援的文件慣例和設定選項。