Skip to main content

在你的 Hono 项目中集成 Mastra

🌐 Integrate Mastra in your Hono project

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

🌐 In this guide, you'll build a tool-calling AI agent using Mastra and Hono. Using the Hono 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 或更高版本

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

🌐 Create a new Hono app (optional)

如果你已经有一个 Hono 应用，请跳到下一步。

🌐 If you already have a Hono app, skip to the next step.

运行以下命令来创建一个新的 Hono 应用：

🌐 Run the following command to create a new Hono app:

npm create hono@latest mastra-hono -- --template nodejs --install --pm npm

这会创建一个名为 mastra-hono 的项目，但你可以用你想要的任何名字替代它。

🌐 This creates a project called mastra-hono, but you can replace it with any name you want.

初始化 Mastra
Direct link to 初始化 Mastra

🌐 Initialize Mastra

导航到你的 Hono 项目目录：

🌐 Navigate to your Hono project directory:

cd mastra-hono

运行 mastra init。出现提示时，选择一个提供商（例如 OpenAI）并输入你的密钥：

🌐 Run mastra init. 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 文件传给 Hono 服务器适配器。

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

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

🌐 Add server adapter

安装 Hono 服务器适配器包：

🌐 Install the Hono server adapter package:

npm install @mastra/hono@latest

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

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

src/index.ts
import { serve } from '@hono/node-server'
import { Hono } from 'hono'
import {
  type HonoBindings,
  type HonoVariables,
  MastraServer
} from '@mastra/hono';
import { mastra } from './mastra/index.js';

const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>();
const server = new MastraServer({ app, mastra });

await server.init();

app.get('/', (c) => {
  return c.text('Hello Hono!')
})

serve({
  fetch: app.fetch,
  port: 3000
}, (info) => {
  console.log(`Server is running on http://localhost:${info.port}`)
})

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

🌐 The ⁠MastraServer is initialized with the existing Hono 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.

启动你的 Hono 服务器：

🌐 Start your Hono server:

npm run dev

在另一个终端窗口中，使用 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

祝贺你使用 Hono 构建了你的 Mastra 代理！🎉

🌐 Congratulations on building your Mastra agent with Hono! 🎉

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

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

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

准备好后，了解更多关于 Mastra 如何与 Hono 集成的信息：

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

目录