mastra-hono

用途

mastra-hono 是一个技能文档，用于指导开发者结合 Mastra v1 Beta 与 Hono API 服务器，构建可用于生产的 AI 智能体、工具与工作流，覆盖从智能体定义到部署的完整技术栈。目标版本为 Mastra v1 Beta（资料称稳定版预计 2026 年 1 月发布）。

何时使用

资料列出以下适用场景：

创建带工具和记忆的 Mastra 智能体
使用 Zod 输入/输出 schema 定义工具
构建多步骤数据流的工作流
通过 Mastra 适配器搭建 Hono API 服务器
实现多智能体协作的 agent networks
编写用于暴露智能体/工具的 MCP 服务器
集成 RAG 与对话记忆

以下情况不建议使用：

使用 Mastra 稳定版（0.24.x），其模式差异较大
构建非 AI 的 Web API（可直接使用 Hono）
不带智能体/工具的简单 LLM 调用

前置条件

Node.js 22.13.0+（v1 Beta 所需）
包管理器：npm、pnpm 或 bun
API key：OpenAI、Anthropic 或其他支持的提供商

安装 v1 Beta 包的命令：

npm install @mastra/core@beta @mastra/hono@beta
npm install @ai-sdk/openai  # 或其他提供商
npm install zod hono @hono/node-server

主要能力与核心模式

智能体定义：通过 Agent 类定义，包含 name（唯一标识，必填）、instructions（系统提示，必填）、model（LLM 模型，必填）和 tools（可选，具名工具对象）。支持模型路由，可引用来自 53 个提供商的 1113+ 模型，并支持模型回退以增强韧性。智能体执行时可传入记忆配置，包含 thread（隔离对话）与 resource（关联用户）。

工具签名（v1 Beta 关键差异）：v1 Beta 的 execute 签名为 execute(inputData, context)，第一个参数为解析后的输入，第二个参数为上下文，可获取 mastra、runtimeContext、abortSignal。资料特别提醒，execute: async ({ context }) 是稳定版 0.24.x 的写法，在 v1 Beta 中是错误的。

工作流数据流（关键）：使用 createWorkflow 与 createStep 构建。资料强调 schema 匹配规则：工作流输入与步骤 1 输入必须完全匹配；步骤 N 输出与步骤 N+1 输入必须完全匹配；最终步骤输出与工作流输出必须完全匹配。步骤中可通过 inputData、getStepResult、getInitData、mastra 等访问数据。

Hono 服务器设置：通过 MastraServer 初始化后会自动注册端点，如 POST /api/agents/{agent-name}/generate、POST /api/agents/{agent-name}/stream、POST /api/workflows/{workflow-id}/start。支持自定义路由前缀（如 prefix: "/v1/ai"）与自定义 API 路由。

使用方式

资料提供了一个最小示例（智能体 + 工具 + Hono 服务器），包含工具定义、智能体定义、Mastra 实例，以及通过 @hono/node-server 启动服务器。同时给出了脚本参考：scaffold-project.ts、scaffold-agent.ts、scaffold-workflow.ts、scaffold-tool.ts、validate-workflow-schemas.ts、check-version-patterns.ts，均需通过 Deno 运行并授予相应权限。

资料还包含常见错误速查表，例如：导入路径应使用 @mastra/core/agent 而非 @mastra/core；tools 应为对象而非数组；memory 上下文应使用 { memory: { thread, resource } } 而非 { threadId } 等。

附加资源

参考资料文件涵盖工作流数据流、常见错误、智能体模式、工具模式、Hono 服务器模式、测试模式、MCP 服务器模式、agent networks、RAG 记忆模式、上下文网络记忆等；资源模板包含智能体、工具、工作流、Hono 服务器、Vitest 配置等模板。还列出了外部文档（Mastra v1 Beta 文档、Hono 文档、Mastra GitHub）。

限制

仅面向 v1 Beta，稳定版（0.24.x）模式差异显著
脚本需要 Deno 运行时及相应权限
MCP 服务器模式需要 MCP 兼容客户端
agent networks 要求所有参与的智能体注册在同一个 Mastra 实例中

技能介绍

用途