mastra-hono by jwynia/agent-skills
npx skills add https://github.com/jwynia/agent-skills --skill mastra-hono使用 Mastra v1 Beta 和 Hono API 服务器构建生产就绪的 AI 智能体、工具和工作流。此技能涵盖了从智能体定义到部署的完整技术栈。
目标版本 : Mastra v1 Beta (预计于 2026 年 1 月发布稳定版)
适用场景 :
不适用场景 :
Node.js 22.13.0+ (v1 Beta 必需)
包管理器 : npm、pnpm 或 bun
API 密钥 : OpenAI、Anthropic 或其他受支持的提供商
npm install @mastra/core@beta @mastra/hono@beta npm install @ai-sdk/openai # 或其他提供商 npm install zod hono @hono/node-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: "获取指定位置的当前天气",
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 开发者,精准高效
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", // 与用户关联
},
});
// v1 Beta: execute(inputData, context)
execute: async (inputData, context) => {
const { location } = inputData; // 第一个参数: 解析后的输入
const { mastra, runtimeContext, abortSignal } = context; // 第二个: 上下文
// 通过 mastra 访问嵌套智能体
const helper = mastra?.getAgent("helperAgent");
// 对于长时间操作,始终检查中止信号
if (abortSignal?.aborted) throw new Error("Aborted");
return { temperature: 72, conditions: "sunny" };
}
// v1 Beta 错误写法:
execute: async ({ context }) => { ... } // 这是稳定版 0.24.x 的签名
大多数错误发生在此处。完整模式请参阅 references/workflow-data-flow.md。
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 输入 | 必须完全匹配 |
| 最终步骤输出 → 工作流输出 | 必须完全匹配 |
步骤中的数据访问 :
execute: async ({
inputData, // 前一步骤的输出 (或第一步的工作流输入)
getStepResult, // 通过 ID 访问任意步骤的输出
getInitData, // 获取原始工作流输入
mastra, // 访问智能体、工具、存储
}) => {
const step1Result = getStepResult("step-1");
const originalInput = getInitData();
return { result: inputData.formatted };
}
import { MastraServer } from "@mastra/hono";
const app = new Hono();
const server = new MastraServer({ app, mastra });
await server.init();
// 自动注册的端点:
// POST /api/agents/{agent-name}/generate
// POST /api/agents/{agent-name}/stream
// POST /api/workflows/{workflow-id}/start
自定义路由前缀 :
const server = new MastraServer({
app,
mastra,
prefix: "/v1/ai" // 路由位于 /v1/ai/agents/...
});
自定义 API 路由 :
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 });
},
});
| 主题 | 错误 | 正确 |
|---|---|---|
| 导入 | 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 设置、模拟 LLMreferences/mcp-server-patterns.md - Model Context Protocol 编写references/agent-networks.md - 多智能体协作、A2Areferences/rag-memory-patterns.md - 向量存储、嵌入、记忆references/context-network-memory.md - 用于智能体记忆的上下文网络assets/agent-template.ts - 智能体样板代码assets/tool-template.ts - 工具样板代码 (v1 签名)assets/workflow-template.ts - 工作流样板代码assets/hono-server-template.ts - Hono+Mastra 服务器设置assets/vitest-setup-template.ts - 测试配置每周安装量
102
仓库
GitHub 星标数
37
首次出现
2026 年 1 月 20 日
安全审计
安装于
opencode85
codex84
gemini-cli79
github-copilot73
cursor71
claude-code71
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)
Use when :
Do NOT use when :
Node.js 22.13.0+ (required for v1 Beta)
Package manager : npm, pnpm, or bun
API keys : OpenAI, Anthropic, or other supported providers
npm install @mastra/core@beta @mastra/hono@beta npm install @ai-sdk/openai # or other provider npm install zod hono @hono/node-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
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
},
});
// 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
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 };
}
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 });
},
});
| 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 |
| 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 |
references/workflow-data-flow.md - Complete data flow patterns (CRITICAL)references/common-mistakes.md - Extended anti-patterns and fixesreferences/agent-patterns.md - Agent definition deep-divereferences/tool-patterns.md - Tool signatures, wrappersreferences/hono-server-patterns.md - Server setup, routes, middlewarereferences/testing-patterns.md - Vitest setup, mocking LLMsreferences/mcp-server-patterns.md - Model Context Protocol authoringassets/agent-template.ts - Agent boilerplateassets/tool-template.ts - Tool boilerplate (v1 signature)assets/workflow-template.ts - Workflow boilerplateassets/hono-server-template.ts - Hono+Mastra server setupassets/vitest-setup-template.ts - Test configurationWeekly Installs
102
Repository
GitHub Stars
37
First Seen
Jan 20, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
opencode85
codex84
gemini-cli79
github-copilot73
cursor71
claude-code71
超能力技能使用指南:AI助手技能调用优先级与工作流程详解
49,600 周安装
context.steps.step1.output |
inputData or getStepResult("step-1") |
| After parallel | inputData.result | inputData["step-id"].result |
| After branch | inputData.result | inputData["step-id"]?.result (optional) |
| Nested agents | import agent; agent.generate() | mastra.getAgent("name").generate() |
| State mutation | state.counter++ | setState({ ...state, counter: state.counter + 1 }) |
| v1 tool exec | execute: async ({ context }) | execute: async (inputData, context) |
scaffold-tool.ts | Create tool with schemas | deno run --allow-all scripts/scaffold-tool.ts --name fetch-weather |
validate-workflow-schemas.ts | Validate step schema matching | deno run --allow-read scripts/validate-workflow-schemas.ts ./src/mastra/workflows/ |
check-version-patterns.ts | Detect v1/stable pattern mixing | deno run --allow-read scripts/check-version-patterns.ts ./src/mastra/ |
references/agent-networks.md - Multi-agent collaboration, A2Areferences/rag-memory-patterns.md - Vector stores, embeddings, memoryreferences/context-network-memory.md - Context networks for agent memory