服务器概览

Mastra 以 HTTP 服务器运行，将 Agent、Workflow 和其他功能公开为 API 端点。服务器负责请求路由、中间件执行、身份验证和流式响应。

信息

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

服务器功能

• 中间件：拦截请求以进行身份验证、日志记录、CORS，或注入请求特定的上下文。
• 自定义 API 路由：使用可访问 Mastra 实例的自定义 HTTP 端点扩展服务器。
• 请求上下文：根据运行时条件将请求特定的值传递给 Agent、Tool 和 Workflow。
• 服务器 Adapter：使用 Express、Hono 或自己的 HTTP 服务器运行 Mastra，而不是使用生成的服务器。
• 自定义 Adapter：为未获官方支持的框架构建 Adapter。
• Mastra Client SDK：用于从浏览器或服务器环境调用 Agent、Workflow 和 Tool 的类型安全客户端。
• A2A：通过 A2A Agent 卡片和任务流以及推送通知公开 Agent。
• 身份验证：使用 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 服务器。

服务器提供：

• 所有已注册 Agent 和 Workflow 的 API 端点
• 自定义 API 路由和中间件
• 跨 Provider 身份验证
• 用于运行时配置的请求上下文
• 用于安全响应的流数据删减

REST API

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

要以交互方式浏览 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 支持的 Adapter，因此请求会通过所选 Mastra Agent 运行，而不是充当原始 Provider 代理。

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

使用 agent_id 选择应处理请求的 Mastra Agent。初始请求直接以 Agent 为目标，存储的后续轮次可以通过 previous_response_id 继续。也可以传递 model，为单个请求覆盖 Agent 配置的模型。如果省略 model，Mastra 会使用 Agent 上已配置的模型。

Responses 路由支持流式传输、函数调用（Tool）、使用 previous_response_id 的存储延续、通过 conversation_id 使用对话 Thread、使用 providerOptions 进行 Provider 特定的透传，以及通过 text.format 输出 JSON。

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

流数据删减

流式传输 Agent 响应时，HTTP 层会在向客户端发送每个数据块之前删减系统提示、Tool 定义、API 密钥和类似数据。此功能默认启用。

只有使用服务器 Adapter 时才能配置此行为。服务器 Adapter 也默认启用流数据删减。

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 路由
• 添加身份验证
• 将服务器部署到生产环境