Server

Mastra 以 HTTP 服务器形式运行，将你的 agents、workflows 及其他功能暴露为 API 端点。服务器负责请求路由、中间件执行、身份验证和流式响应。

备注

本页介绍传给 Mastra 构造函数的 server 配置选项。若要使用自己的 HTTP 服务器（Hono、Express 等）运行 Mastra，请访问服务器适配器。

服务器功能

• 中间件：拦截请求，用于身份验证、日志、CORS 或注入请求特定上下文。
• 自定义 API 路由：用可访问 Mastra 实例的自定义 HTTP 端点扩展服务器。
• 请求上下文：根据运行时条件，将请求特定的值传给 agents、工具和 workflows。
• 服务器适配器：使用 Express、Hono 或自己的 HTTP 服务器运行 Mastra，而非生成的服务器。
• 自定义适配器：为官方未支持的框架构建适配器。
• Mastra Client SDK：类型安全的客户端，可从浏览器或服务器环境调用 agents、workflows 和工具。
• A2A：通过 A2A agent cards、任务流和推送通知暴露 agents。
• 身份验证：使用 JWT、Clerk、Supabase、Firebase、Auth0 或 WorkOS 保护端点。

配置

通过向 Mastra 构造函数传入 server 对象来配置服务器：

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 服务器。

服务器提供：

• 所有已注册 agents 和 workflows 的 API 端点
• 自定义 API 路由和中间件
• 跨提供商的身份验证
• 用于运行时配置的请求上下文
• 流数据脱敏，确保响应安全

REST API

你可以在 http://localhost:4111/api/openapi.json 查看 OpenAPI 规范中的所有可用端点，其中详细说明了每个端点及其请求和响应 schemas。

要以交互方式探索 API，请访问 Swagger UI：http://localhost:4111/swagger-ui。你可以在这里发现端点并直接在浏览器中测试。

备注

OpenAPI 和 Swagger 端点在默认情况下于生产环境中禁用。要启用它们，请分别将 server.build.openAPIDocs 和 server.build.swaggerUI 设为 true。

OpenAI Responses API

Mastra 暴露兼容 OpenAI 的 Responses 和 Conversations 路由，让你可以把 Mastra Agents 作为 Responses API 使用。这些路由是基于 Mastra agents、memory 和 storage 的 Agent 适配器，因此请求会通过选定的 Mastra Agent 运行，而不是充当原始提供商代理。

这些 API 目前处于实验阶段。

使用 agent_id 选择应处理该请求的 Mastra Agent。初始请求直接指向某个 Agent。已存储的后续轮次可通过 previous_response_id 继续。传入 model 可为单个请求覆盖已配置的模型，省略则使用 Agent 现有模型。

Responses 路由支持流式传输、函数调用（工具）、通过 previous_response_id 存储续接、通过 conversation_id 使用对话线程、通过 providerOptions 进行提供商特定透传，以及通过 text.format 输出 JSON。

完整的请求和响应契约参见 Responses API 参考和 Conversations API 参考。完整的 HTTP 路由列表参见服务器路由。

流数据脱敏

流式传输 Agent 响应时，HTTP 层会在将每个 chunk 发送给客户端之前，从中移除 system prompts、工具定义、API 密钥及类似数据。该功能默认启用。

该行为只能通过服务器适配器配置。对于服务器适配器，流数据脱敏同样默认启用。

TypeScript 配置

Mastra 要求 module 和 moduleResolution 设置与现代 Node.js 兼容。不支持 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 路由
• 添加身份验证
• 部署服务器到生产环境