伺服器概覽

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

資訊

本頁介紹傳遞至 Mastra 建構函式的 server 配置選項。如要以你自己的 HTTP 伺服器（Hono、Express 等）運行 Mastra，請參閱伺服器適配器。

伺服器功能

• 中介軟件：攔截請求以進行驗證、記錄、CORS，或注入請求專用的上下文。
• 自訂 API 路由：使用可存取 Mastra 實例的自訂 HTTP 端點擴充伺服器。
• 請求上下文：根據運行時條件，將請求專用的值傳遞至 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 路由和中介軟件
• 跨 Provider 的驗證
• 用於運行時配置的請求上下文
• 為安全回應遮蔽串流資料

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。這些路由是建基於 Agent 的適配器，底層使用 Mastra Agent、記憶和儲存空間，因此請求會經由所選的 Mastra Agent 運行，而非充當原始 Provider 的代理。

這些 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/**/*"]
}

後續步驟

• 加入中介軟件
• 建立自訂 API 路由
• 加入驗證
• 將你的伺服器部署至生產環境