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

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

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/

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

• references/agent-networks.md

• Multi-agent collaboration, A2A

• references/rag-memory-patterns.md

• Vector stores, embeddings, memory

• references/context-network-memory.md

• Context networks for agent memory

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

• Mastra v1 Beta Docs

• Hono Documentation

• Mastra GitHub

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