開發

擁有 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，協助 coding Agent 撰寫高品質的 Mastra 程式碼。

Mastra Skill

AI 模型可能不具備 Mastra API 的最新知識。使用 Mastra Skill，為 coding Agent 提供實作指引、最佳實務，以及取得最新 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，讓 coding Agent 能夠找到並使用它。

Mastra CLI

使用 mastra CLI，為 coding Agent 提供測試更新及檢查結果的回饋迴圈。CLI 可讓它存取 Agent、Workflow、Tool、記憶體、Evals、Trace 和記錄。

例如，coding 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 Skill，讓 coding Agent 學會如何使用 CLI。

專案結構

採用框架時，最先要做的決定之一就是如何組織專案。建議將框架程式碼放在 src/mastra/ 下，並把相關 primitive 分組到各自的檔案或資料夾中。使用 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，包括透過 Web 框架或伺服器轉接器匯入，將不會探索檔案式 Agent。請在程式碼中註冊這些 Agent，或將 Mastra 作為獨立伺服器執行。

📹 觀看影片

如何建立第一個檔案式 Agent

使用檔案式 Agent 時，Mastra 會自動從 src/mastra/ 下受支援的檔案中探索 Agent 及相關 primitive。你可以按照慣例組織這些檔案，不必將每個 primitive 匯入並註冊至 Mastra 執行個體。

檔案系統會直接呈現專案結構，因此你和 coding Agent 不必追查程式碼中各項目的連接方式，就能了解整個專案如何組成。

你可以在整個專案中使用檔案式 Agent，也可以搭配程式碼中定義的 primitive 逐步採用。目前尚未支援 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 and workspace/	檔案系統和 shell 存取權
subagents/<agent-id>/	父 Agent 可以委派工作的專業 Agent

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

瀏覽檔案式 Agent 參考，查看所有支援的檔案慣例和設定選項。