伺服器概覽

Mastra 會以 HTTP 伺服器的形式執行，並將 Agent、Workflow 及其他功能公開為 API 端點。伺服器會處理請求路由、middleware 執行、驗證及串流回應。

資訊

本頁說明傳入 Mastra 建構函式的 server 設定選項。如要搭配自己的 HTTP 伺服器（Hono、Express 等）執行 Mastra，請參閱伺服器轉接器。

伺服器功能

• Middleware：攔截請求，以進行驗證、記錄、CORS，或注入請求專屬的 context。
• 自訂 API 路由：使用可存取 Mastra 執行個體的自訂 HTTP 端點擴充伺服器。
• 請求 Context：根據執行階段條件，將請求專屬的值傳給 Agent、Tool 及 Workflow。
• 伺服器轉接器：使用 Express、Hono 或自己的 HTTP 伺服器來執行 Mastra，而非使用產生的伺服器。
• 自訂轉接器：為官方尚未支援的框架建置轉接器。
• Mastra Client SDK：型別安全的用戶端，可從瀏覽器或伺服器環境呼叫 Agent、Workflow 及 Tool。
• A2A：透過 A2A Agent 卡片與任務串流公開 Agent，並支援推播通知。
• 驗證：使用 JWT、Clerk、Supabase、Firebase、Auth0 或 WorkOS 保護端點。

設定

將 server 物件傳給 Mastra 建構函式，即可設定伺服器：

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    port: 3000, // Defaults to PORT env var or 4111
    host: '0.0.0.0', // Defaults to MASTRA_HOST env var or 'localhost'
  },
})

如需所有可用伺服器選項的完整清單，請參閱設定參考。

部署伺服器

Mastra 伺服器可以部署至任何與 Node.js 相容的環境。你可以透過 Mastra 平台或自己的基礎架構部署至正式環境。詳情請參閱部署文件。

伺服器架構

Mastra 使用 Hono 作為底層 HTTP 伺服器框架。使用 mastra build 建置 Mastra 應用程式時，系統會在 .mastra 目錄中產生以 Hono 為基礎的 HTTP 伺服器。

伺服器提供：

• 所有已註冊 Agent 與 Workflow 的 API 端點
• 自訂 API 路由與 middleware
• 跨 Provider 的驗證
• 用於執行階段設定的請求 context
• 確保回應安全的串流資料遮蔽

REST API

你可以在 http://localhost:4111/api/openapi.json 的 OpenAPI 規格中查看所有可用端點，以及每個端點的請求與回應結構描述。

如要以互動方式探索 API，請開啟 http://localhost:4111/swagger-ui 的 Swagger UI。你可以在此尋找端點，並直接從瀏覽器測試。

備註

OpenAPI 與 Swagger 端點預設會在正式環境停用。如要分別啟用，請將 server.build.openAPIDocs 與 server.build.swaggerUI 設為 true。

OpenAI Responses API

Mastra 公開與 OpenAI 相容的 Responses 與 Conversations 路由，讓你能將 Mastra Agent 當作 Responses API 使用。這些路由是在 Mastra Agent、記憶體及儲存空間之上，由 Agent 支援的轉接器，因此請求會透過所選的 Mastra Agent 執行，而非作為原始 Provider Proxy 運作。

這些 API 目前仍屬實驗性功能。

使用 agent_id 選擇應處理請求的 Mastra Agent。初始請求會直接以某個 Agent 為目標，已儲存的後續輪次則可透過 previous_response_id 繼續。你也可以傳入 model，針對單一請求覆寫 Agent 設定的模型。若省略 model，Mastra 會使用 Agent 上既有的模型設定。

Responses 路由支援串流、函式呼叫（Tool）、透過 previous_response_id 接續已儲存的內容、透過 conversation_id 建立對話執行緒、使用 providerOptions 傳遞 Provider 專屬選項，以及透過 text.format 輸出 JSON。

如需完整的請求與回應契約，請參閱 Responses API 參考與 Conversations API 參考。如需完整的 HTTP 路由清單，請參閱伺服器路由。

串流資料遮蔽

串流傳送 Agent 回應時，HTTP 層會先從每個區塊遮蔽系統提示詞、Tool 定義、API 金鑰及類似資料，再將其傳送給用戶端。此功能預設為啟用。

只有使用伺服器轉接器時才能設定此行為。伺服器轉接器也會預設啟用串流資料遮蔽。

TypeScript 設定

Mastra 需要與現代 Node.js 相容的 module 與 moduleResolution 設定。不支援 CommonJS 或 node 等舊版選項。

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"]
}

後續步驟

• 新增 middleware
• 建立自訂 API 路由
• 新增驗證
• 將伺服器部署至正式環境