Mastra v1 Beta + Hono 构建生产级 AI 智能体：完整开发指南与部署教程

mastra-hono by jwynia/agent-skills

102 周安装量

37 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/jwynia/agent-skills --skill mastra-hono

AI/机器学习 Node.js API

🇨🇳中文介绍

Mastra + Hono 开发

使用 Mastra v1 Beta 和 Hono API 服务器构建生产就绪的 AI 智能体、工具和工作流。此技能涵盖了从智能体定义到部署的完整技术栈。

目标版本 : Mastra v1 Beta (预计于 2026 年 1 月发布稳定版)

何时使用此技能

适用场景 :

创建带有工具和记忆功能的 Mastra 智能体
使用 Zod 输入/输出模式定义工具
构建具有多步骤数据流的工作流
使用 Mastra 适配器设置 Hono API 服务器
实现用于多智能体协作的智能体网络
编写 MCP 服务器以暴露智能体/工具
集成 RAG 和对话记忆

不适用场景 :

使用 Mastra 稳定版 (0.24.x) - 模式差异很大
构建非 AI 的 Web API (直接使用 Hono)
没有智能体/工具的简单 LLM 调用

先决条件

Node.js 22.13.0+ (v1 Beta 必需)
包管理器 : npm、pnpm 或 bun
API 密钥 : OpenAI、Anthropic 或其他受支持的提供商

安装 v1 Beta 包

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

快速开始

最小化智能体 + 工具 + Hono 服务器

// src/mastra/tools/weather-tool.ts
import { createTool } from "@mastra/core/tools";
import { z } from "zod";

export const weatherTool = createTool({
  id: "get-weather",
  description: "获取指定位置的当前天气",
  inputSchema: z.object({
    location: z.string().describe("城市名称，例如 'Seattle'"),
  }),
  outputSchema: z.object({
    temperature: z.number(),
    conditions: z.string(),
  }),
  // v1 Beta 签名: (inputData, context)
  execute: async (inputData, context) => {
    const { location } = inputData;
    const { abortSignal } = context;

    if (abortSignal?.aborted) throw new Error("Aborted");

    // 获取天气数据...
    return { temperature: 72, conditions: "sunny" };
  },
});



// src/mastra/agents/weather-agent.ts
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { weatherTool } from "../tools/weather-tool.js";

export const weatherAgent = new Agent({
  name: "weather-agent",
  instructions: "你是一个有用的天气助手。",
  model: openai("gpt-4o-mini"),
  tools: { weatherTool },  // 对象，而非数组
});



// src/mastra/index.ts
import { Mastra } from "@mastra/core/mastra";
import { weatherAgent } from "./agents/weather-agent.js";

export const mastra = new Mastra({
  agents: { weatherAgent },
});



// src/index.ts
import { serve } from "@hono/node-server";
import { Hono } from "hono";
import { MastraServer } from "@mastra/hono";
import { mastra } from "./mastra/index.js";

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

app.get("/", (c) => c.text("Mastra + Hono Server"));

serve({ fetch: app.fetch, port: 3000 });
console.log("Server running at http://localhost:3000");
// 智能体端点: POST /api/agents/weather-agent/generate

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

FlyClaw：零登录航班聚合查询工具，Python实现多源航班信息与价格搜索

4,000,000 周安装

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

867,400 周安装

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

116,600 周安装

AI Elements：基于shadcn/ui的AI原生应用组件库，快速构建对话界面

66,200 周安装

import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  name: "my-agent",                           // 必需: 唯一标识符
  instructions: "You are a helpful assistant.", // 必需: 系统提示词
  model: openai("gpt-4o-mini"),               // 必需: LLM 模型
  tools: { weatherTool, searchTool },         // 可选: 包含命名工具的对象
});

// 模型路由 (来自 53 个提供商的 1113+ 个模型)
model: "openai/gpt-4o-mini"
model: "anthropic/claude-3-5-sonnet"
model: "google/gemini-2.5-flash"

// 用于增强韧性的模型回退
model: [
  { model: "anthropic/claude-3-opus", maxRetries: 3 },
  { model: "openai/gpt-4o", maxRetries: 2 },
  { model: "google/gemini-pro", maxRetries: 1 },
]

// 带有记忆的智能体执行
const response = await agent.generate("Remember my name is Alex", {
  memory: {
    thread: "conversation-123",   // 隔离对话
    resource: "user-456",         // 与用户关联
  },
});

import { createWorkflow, createStep } from "@mastra/core/workflows";

const step1 = createStep({
  id: "step-1",
  inputSchema: z.object({ message: z.string() }),
  outputSchema: z.object({ formatted: z.string() }),
  execute: async ({ inputData }) => {
    // inputData = 工作流输入 (对于第一步)
    return { formatted: inputData.message.toUpperCase() };
  },
});

const step2 = createStep({
  id: "step-2",
  inputSchema: z.object({ formatted: z.string() }),  // 必须匹配 step1 的输出
  outputSchema: z.object({ emphasized: z.string() }),
  execute: async ({ inputData }) => {
    // inputData = step1 的返回值直接传递
    return { emphasized: `${inputData.formatted}!!!` };
  },
});

const workflow = createWorkflow({
  id: "my-workflow",
  inputSchema: z.object({ message: z.string() }),     // 必须匹配 step1 的输入
  outputSchema: z.object({ emphasized: z.string() }), // 必须匹配最终输出
})
  .then(step1)
  .then(step2)
  .commit();

规则	描述
工作流输入 → 步骤 1 输入	必须完全匹配
步骤 N 输出 → 步骤 N+1 输入	必须完全匹配
最终步骤输出 → 工作流输出	必须完全匹配

主题	错误	正确
导入	`import { Agent } from "@mastra/core"`	`import { Agent } from "@mastra/core/agent"`
工具数组	`tools: [tool1, tool2]`	`tools: { tool1, tool2 }`
记忆上下文	`{ threadId: "123" }`	`{ memory: { thread: "123", resource: "user" } }`
工作流数据	`context.steps.step1.output`	`inputData` 或 `getStepResult("step-1")`
并行步骤后	`inputData.result`	`inputData["step-id"].result`
分支步骤后	`inputData.result`	`inputData["step-id"]?.result` (可选)
嵌套智能体	`import agent; agent.generate()`	`mastra.getAgent("name").generate()`
状态突变	`state.counter++`	`setState({ ...state, counter: state.counter + 1 })`
v1 工具执行	`execute: async ({ context })`	`execute: async (inputData, context)`

脚本	用途	用法
`scaffold-project.ts`	创建新的 Mastra+Hono 项目	`deno run --allow-all scripts/scaffold-project.ts --name my-project`
`scaffold-agent.ts`	创建带有工具的智能体	`deno run --allow-all scripts/scaffold-agent.ts --name weather`
`scaffold-workflow.ts`	创建带有步骤的工作流	`deno run --allow-all scripts/scaffold-workflow.ts --name process-data`
`scaffold-tool.ts`	创建带有模式的工具	`deno run --allow-all scripts/scaffold-tool.ts --name fetch-weather`
`validate-workflow-schemas.ts`	验证步骤模式匹配	`deno run --allow-read scripts/validate-workflow-schemas.ts ./src/mastra/workflows/`
`check-version-patterns.ts`	检测 v1/稳定版模式混合	`deno run --allow-read scripts/check-version-patterns.ts ./src/mastra/`

references/workflow-data-flow.md - 完整的数据流模式 (关键)
references/common-mistakes.md - 扩展的反模式和修复方法
references/agent-patterns.md - 智能体定义深度解析
references/tool-patterns.md - 工具签名、包装器
references/hono-server-patterns.md - 服务器设置、路由、中间件
references/testing-patterns.md - Vitest 设置、模拟 LLM
references/mcp-server-patterns.md - Model Context Protocol 编写
references/agent-networks.md - 多智能体协作、A2A
references/rag-memory-patterns.md - 向量存储、嵌入、记忆
references/context-network-memory.md - 用于智能体记忆的上下文网络

🇺🇸English

Mastra + Hono Development

Build production-ready AI agents, tools, and workflows using Mastra v1 Beta with Hono API servers. This skill covers the complete stack from agent definition to deployment.

Target version : Mastra v1 Beta (stable release expected January 2026)

When to Use This Skill

Use when :

Creating Mastra agents with tools and memory
Defining tools with Zod input/output schemas
Building workflows with multi-step data flow
Setting up Hono API servers with Mastra adapters
Implementing agent networks for multi-agent collaboration
Authoring MCP servers to expose agents/tools
Integrating RAG and conversation memory

Do NOT use when :

Working with Mastra stable (0.24.x) - patterns differ significantly
Building non-AI web APIs (use Hono directly)
Simple LLM calls without agents/tools

Prerequisites

Node.js 22.13.0+ (required for v1 Beta)
Package manager : npm, pnpm, or bun
API keys : OpenAI, Anthropic, or other supported providers

Install v1 Beta packages

npm install @mastra/core@beta @mastra/hono@beta npm install @ai-sdk/openai # or other provider npm install zod hono @hono/node-server

Quick Start

Minimal Agent + Tool + Hono Server

// src/mastra/tools/weather-tool.ts
import { createTool } from "@mastra/core/tools";
import { z } from "zod";

export const weatherTool = createTool({
  id: "get-weather",
  description: "Fetches current weather for a location",
  inputSchema: z.object({
    location: z.string().describe("City name, e.g., 'Seattle'"),
  }),
  outputSchema: z.object({
    temperature: z.number(),
    conditions: z.string(),
  }),
  // v1 Beta signature: (inputData, context)
  execute: async (inputData, context) => {
    const { location } = inputData;
    const { abortSignal } = context;

    if (abortSignal?.aborted) throw new Error("Aborted");

    // Fetch weather data...
    return { temperature: 72, conditions: "sunny" };
  },
});



// src/mastra/agents/weather-agent.ts
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { weatherTool } from "../tools/weather-tool.js";

export const weatherAgent = new Agent({
  name: "weather-agent",
  instructions: "You are a helpful weather assistant.",
  model: openai("gpt-4o-mini"),
  tools: { weatherTool },  // Object, not array
});



// src/mastra/index.ts
import { Mastra } from "@mastra/core/mastra";
import { weatherAgent } from "./agents/weather-agent.js";

export const mastra = new Mastra({
  agents: { weatherAgent },
});



// src/index.ts
import { serve } from "@hono/node-server";
import { Hono } from "hono";
import { MastraServer } from "@mastra/hono";
import { mastra } from "./mastra/index.js";

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

app.get("/", (c) => c.text("Mastra + Hono Server"));

serve({ fetch: app.fetch, port: 3000 });
console.log("Server running at http://localhost:3000");
// Agent endpoint: POST /api/agents/weather-agent/generate

Core Patterns

Agent Definition

import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  name: "my-agent",                           // Required: unique identifier
  instructions: "You are a helpful assistant.", // Required: system prompt
  model: openai("gpt-4o-mini"),               // Required: LLM model
  tools: { weatherTool, searchTool },         // Optional: object with named tools
});

// Model routing (1113+ models from 53 providers)
model: "openai/gpt-4o-mini"
model: "anthropic/claude-3-5-sonnet"
model: "google/gemini-2.5-flash"

// Model fallbacks for resilience
model: [
  { model: "anthropic/claude-3-opus", maxRetries: 3 },
  { model: "openai/gpt-4o", maxRetries: 2 },
  { model: "google/gemini-pro", maxRetries: 1 },
]

// Agent execution with memory
const response = await agent.generate("Remember my name is Alex", {
  memory: {
    thread: "conversation-123",   // Isolates conversation
    resource: "user-456",         // Associates with user
  },
});

Tool Signatures (v1 Beta - CRITICAL)

// v1 Beta: execute(inputData, context)
execute: async (inputData, context) => {
  const { location } = inputData;  // First parameter: parsed input
  const { mastra, runtimeContext, abortSignal } = context;  // Second: context

  // Access nested agents via mastra
  const helper = mastra?.getAgent("helperAgent");

  // Always check abort signal for long operations
  if (abortSignal?.aborted) throw new Error("Aborted");

  return { temperature: 72, conditions: "sunny" };
}

// WRONG for v1 Beta:
execute: async ({ context }) => { ... }  // This is stable 0.24.x signature

Workflow Data Flow (CRITICAL)

This is where most errors occur. See references/workflow-data-flow.md for complete patterns.

import { createWorkflow, createStep } from "@mastra/core/workflows";

const step1 = createStep({
  id: "step-1",
  inputSchema: z.object({ message: z.string() }),
  outputSchema: z.object({ formatted: z.string() }),
  execute: async ({ inputData }) => {
    // inputData = workflow input (for first step)
    return { formatted: inputData.message.toUpperCase() };
  },
});

const step2 = createStep({
  id: "step-2",
  inputSchema: z.object({ formatted: z.string() }),  // MUST match step1 output
  outputSchema: z.object({ emphasized: z.string() }),
  execute: async ({ inputData }) => {
    // inputData = step1's return value directly
    return { emphasized: `${inputData.formatted}!!!` };
  },
});

const workflow = createWorkflow({
  id: "my-workflow",
  inputSchema: z.object({ message: z.string() }),     // MUST match step1 input
  outputSchema: z.object({ emphasized: z.string() }), // MUST match final output
})
  .then(step1)
  .then(step2)
  .commit();

Schema matching rules :

Rule	Description
Workflow input → Step 1 input	Must match exactly
Step N output → Step N+1 input	Must match exactly
Final step output → Workflow output	Must match exactly

Data access in steps :

execute: async ({
  inputData,      // Previous step's output (or workflow input for step 1)
  getStepResult,  // Access ANY step's output by ID
  getInitData,    // Get original workflow input
  mastra,         // Access agents, tools, storage
}) => {
  const step1Result = getStepResult("step-1");
  const originalInput = getInitData();
  return { result: inputData.formatted };
}

Hono Server Setup

import { MastraServer } from "@mastra/hono";

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

// Endpoints auto-registered:
// POST /api/agents/{agent-name}/generate
// POST /api/agents/{agent-name}/stream
// POST /api/workflows/{workflow-id}/start

Custom route prefix :

const server = new MastraServer({
  app,
  mastra,
  prefix: "/v1/ai"  // Routes at /v1/ai/agents/...
});

Custom API routes :

import { registerApiRoute } from "@mastra/core/server";

registerApiRoute("/my-custom-route", {
  method: "POST",
  handler: async (c) => {
    const mastra = c.get("mastra");
    const agent = mastra.getAgent("my-agent");
    const result = await agent.generate("Hello");
    return c.json({ response: result.text });
  },
});

Common Mistakes Quick Reference

Topic	Wrong	Correct
Imports	`import { Agent } from "@mastra/core"`	`import { Agent } from "@mastra/core/agent"`
Tools array	`tools: [tool1, tool2]`	`tools: { tool1, tool2 }`
Memory context	`{ threadId: "123" }`	`{ memory: { thread: "123", resource: "user" } }`
Workflow data

Scripts Reference

Script	Purpose	Usage
`scaffold-project.ts`	Create new Mastra+Hono project	`deno run --allow-all scripts/scaffold-project.ts --name my-project`
`scaffold-agent.ts`	Create agent with tools	`deno run --allow-all scripts/scaffold-agent.ts --name weather`
`scaffold-workflow.ts`	Create workflow with steps	`deno run --allow-all scripts/scaffold-workflow.ts --name process-data`

Additional Resources

Reference Files

references/workflow-data-flow.md - Complete data flow patterns (CRITICAL)
references/common-mistakes.md - Extended anti-patterns and fixes
references/agent-patterns.md - Agent definition deep-dive
references/tool-patterns.md - Tool signatures, wrappers
references/hono-server-patterns.md - Server setup, routes, middleware
references/testing-patterns.md - Vitest setup, mocking LLMs
references/mcp-server-patterns.md - Model Context Protocol authoring

Asset Templates

assets/agent-template.ts - Agent boilerplate
assets/tool-template.ts - Tool boilerplate (v1 signature)
assets/workflow-template.ts - Workflow boilerplate
assets/hono-server-template.ts - Hono+Mastra server setup
assets/vitest-setup-template.ts - Test configuration

External Documentation

Limitations

Targets v1 Beta only; stable (0.24.x) patterns differ significantly
Scripts require Deno runtime with appropriate permissions
MCP server patterns require MCP-compatible clients
Agent networks require all participating agents to be registered in same Mastra instance

Related Skills

research-workflow - Deep dive research for AI agent design
web-search - Real-time information retrieval for agents

Weekly Installs

102

Repository

jwynia/agent-skills

GitHub Stars

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

opencode85

codex84

gemini-cli79

github-copilot73

cursor71

claude-code71

Mastra v1 Beta + Hono 构建生产级 AI 智能体：完整开发指南与部署教程

🇨🇳中文介绍

Mastra + Hono 开发

何时使用此技能

先决条件

安装 v1 Beta 包

快速开始

最小化智能体 + 工具 + Hono 服务器

相关 Skills

核心模式

智能体定义

工具签名 (v1 Beta - 关键)

工作流数据流 (关键)

Hono 服务器设置

常见错误快速参考

脚本参考

附加资源

参考文件

资产模板

外部文档

限制

相关技能