Skip to main content

在你的 Express 项目中集成 Mastra

🌐 Integrate Mastra in your Express project

在本指南中，你将使用 Mastra 和 Express 构建一个调用工具的 AI 代理。通过使用 Express 服务器适配器，你可以将代理暴露为 HTTP 端点，而无需自己编写路由或运行单独的 Mastra 服务器。

🌐 In this guide, you'll build a tool-calling AI agent using Mastra and Express. Using the Express server adapter, you can expose your agents as HTTP endpoints without writing the routing yourself or running a separate Mastra server.

在你开始之前
Direct link to 在你开始之前

🌐 Before you begin

  • 你需要从支持的模型提供商获取一个 API 密钥。如果你没有偏好，可以使用OpenAI。
  • 安装 Node.js v22.13.0 或更高版本

创建一个新的 Express 应用（可选）
Direct link to 创建一个新的 Express 应用（可选）

🌐 Create a new Express app (optional)

如果你已经有一个 Express 应用，可以跳到下一步。

🌐 If you already have an Express app, skip to the next step.

克隆此 模板仓库 并安装依赖：

🌐 Clone this boilerplate repository and install dependencies:

git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
npm install

初始化 Mastra
Direct link to 初始化 Mastra

🌐 Initialize Mastra

在你的 Express 项目目录中，运行 mastra init。

🌐 Inside your Express project directory, run mastra init.

在提示时，选择一个提供商（例如 OpenAI）并输入你的密钥：

🌐 When prompted, choose a provider (e.g. OpenAI) and enter your key:

npx mastra@latest init

这将创建一个包含示例天气代理和以下文件的 src/mastra 文件夹：

🌐 This creates a src/mastra folder with an example weather agent and the following files:

  • index.ts - Mastra 配置，包括内存
  • tools/weather-tool.ts - 一个用于获取给定位置天气的工具
  • agents/weather-agent.ts——一个使用该工具的天气代理和提示

你稍后会将 src/mastra/index.ts 文件传递给 Express 服务器适配器。

🌐 You'll pass the src/mastra/index.ts file to the Express server adapter later.

添加服务器适配器
Direct link to 添加服务器适配器

🌐 Add server adapter

安装 Express 服务器适配器包：

🌐 Install the Express server adapter package:

npm install @mastra/express@latest

打开位于 src/index.ts 的 Express 入口文件，并添加所需的导入和初始化代码：

🌐 Open the Express entry file at src/index.ts and add the required import and initialization code:

src/index.ts
import express, { type Request, type Response } from "express";
import { MastraServer } from "@mastra/express";
import { mastra } from "./mastra";

const app = express();
const PORT = process.env.PORT || 3000;

// Middleware
app.use(express.json());

const server = new MastraServer({ app, mastra });
await server.init();

// Routes
app.get("/", (_req: Request, res: Response) => {
  res.json({ message: "Hello, World!" });
});

// Start server
app.listen(PORT, () => {
  console.log(`Server is running on http://localhost:${PORT}`);
});

MastraServer 使用现有的 Express app 和根 mastra 实例进行初始化。调用 ⁠init() 会注册 Mastra 中间件并公开所有可用的 Mastra 端点。

🌐 The ⁠MastraServer is initialized with the existing Express app and the root ⁠mastra instance. Calling ⁠init() registers the Mastra middleware and exposes all available Mastra endpoints.

测试你的代理
Direct link to 测试你的代理

🌐 Test your agent

默认情况下，Mastra 的端点会添加在 /api 子路径下，并使用你的代理/工作流 ID。由 mastra init 创建的默认 weather-agent 可在 /api/agents/weather-agent 访问。

🌐 By default, Mastra's endpoints are added under the /api subpath and use your agent/workflow IDs. The default weather-agent created by mastra init is available at /api/agents/weather-agent.

启动你的 Express 服务器：

🌐 Start your Express server:

npm run start

在另一个终端窗口中，使用 curl 向天气代理询问：

🌐 In a separate terminal window, use curl to ask the weather agent:

curl -X POST http://localhost:3000/api/agents/weather-agent/generate -H "Content-Type: application/json" -d "{\"messages\":[{\"role\":\"user\",\"content\":\"What is the weather like in Seoul?\"}]}"

下一步
Direct link to 下一步

🌐 Next steps

祝贺你使用 Express 成功创建了你的 Mastra 代理！🎉

🌐 Congratulations on building your Mastra agent with Express! 🎉

从这里，你可以使用你自己的工具和逻辑来扩展项目：

🌐 From here, you can extend the project with your own tools and logic:

  • 了解更多关于代理的信息
  • 给你的代理分配自己的工具
  • 给你的代理添加类似人类的内存

当你准备好时，阅读更多关于 Mastra 如何与 Express 集成的内容：

🌐 When you're ready, read more about how Mastra integrates with Express:

目录