跳到主要内容

在 Express 项目中集成 Mastra

本指南将介绍如何使用 Mastra 和 Express 构建一个可调用 Tool 的 AI Agent。借助 Express server adapter，你无需自行编写路由或运行单独的 Mastra 服务器，即可将 Agent 公开为 HTTP 端点。

开始之前
开始之前的直接链接

  • 你需要受支持的模型 Provider所提供的 API 密钥。如果没有偏好，请使用 OpenAI。
  • 安装 Node.js v22.13.0 或更高版本

创建新的 Express 应用（可选）
创建新的 Express 应用（可选）的直接链接

如果已有 Express 应用，请跳到下一步。

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

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

初始化 Mastra
初始化 Mastra的直接链接

在 Express 项目目录中运行 mastra init。

出现提示时，选择 Provider（例如 OpenAI）并输入密钥：

npx mastra@latest init

这会创建一个 src/mastra 文件夹，其中包含示例天气 Agent 和以下文件：

  • index.ts - Mastra 配置，包括 memory
  • tools/weather-tool.ts - 获取指定位置天气的 Tool
  • agents/weather-agent.ts- 使用该 Tool 的天气 Agent 及其提示词

稍后你会把 src/mastra/index.ts 文件传给 Express server adapter。

添加 server adapter
添加 server adapter的直接链接

安装 Express server adapter 软件包：

npm install @mastra/express@latest

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

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}`)
})

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

测试 Agent
测试 Agent的直接链接

默认情况下，Mastra 端点添加在 /api 子路径下，并使用你的 Agent/Workflow ID。由 mastra init 创建的默认 weather-agent 可通过 /api/agents/weather-agent 访问。

启动 Express 服务器：

npm run start

在另一个终端窗口中，使用 curl 向天气 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?\"}]}"

后续步骤
后续步骤的直接链接

恭喜你使用 Express 构建了 Mastra Agent！🎉

接下来，你可以使用自己的 Tool 和逻辑扩展项目：

  • 进一步了解 Agent
  • 为 Agent 添加自己的 Tool
  • 为 Agent 添加类似人类的 memory

准备就绪后，可进一步了解 Mastra 与 Express 的集成方式：

On this page