Adaptateur Hono

Le package @mastra/hono fournit un adaptateur de serveur permettant d'exécuter Mastra avec Hono. Pour en savoir plus sur les concepts généraux des adaptateurs (options du constructeur, déroulement de l'initialisation, etc.), consultez les adaptateurs de serveur.

Installation

Installez l'adaptateur Hono et le framework Hono :

npm

npm install @mastra/hono@latest hono

pnpm

pnpm add @mastra/hono@latest hono

Yarn

yarn add @mastra/hono@latest hono

Bun

bun add @mastra/hono@latest hono

Exemple d'utilisation

server.ts

import { Hono } from 'hono'
import { HonoBindings, HonoVariables, MastraServer } from '@mastra/hono'
import { mastra } from './mastra'

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

await server.init()

export default app

Paramètres du constructeur

app:

Hono

Instance de l'application Hono

mastra:

Mastra

Instance Mastra

prefix?:

string

= ''

Préfixe du chemin des routes (par exemple, /api/v2)

openapiPath?:

string

= ''

Chemin depuis lequel servir la spécification OpenAPI (par exemple, /openapi.json)

bodyLimitOptions?:

{ maxSize: number, onError: (err) => unknown }

Limites de taille du corps des requêtes

streamOptions?:

{ redact?: boolean }

= { redact: true }

Configuration du masquage des flux. Lorsque la valeur est true, masque les données sensibles dans les flux.

customRouteAuthConfig?:

Map<string, boolean>

Remplacements de l'authentification propres à chaque route. Les clés suivent le format METHOD:PATH (par exemple, GET:/api/health). La valeur false rend la route publique, tandis que true exige une authentification.

tools?:

Record<string, Tool>

Tools disponibles pour le serveur

taskStore?:

InMemoryTaskStore

Stockage des tâches pour les opérations A2A (Agent-to-Agent)

mcpOptions?:

MCPOptions

Options de transport MCP. Définissez serverless: true pour les environnements sans état tels que Cloudflare Workers ou Vercel Edge.

Ajout de routes personnalisées

Ajoutez des routes directement à l'application Hono :

server.ts

import { Hono } from 'hono'
import { HonoBindings, HonoVariables, MastraServer } from '@mastra/hono'

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

// Before init - runs before Mastra middleware
app.get('/early-health', c => c.json({ status: 'ok' }))

await server.init()

// After init - has access to Mastra context
app.get('/custom', c => {
  const mastraInstance = c.get('mastra')
  return c.json({ agents: Object.keys(mastraInstance.listAgents()) })
})

astuce

Les routes ajoutées avant init() s'exécutent sans contexte Mastra. Ajoutez les routes après init() pour accéder à l'instance Mastra et au contexte de requête.

Lorsque vous souhaitez utiliser l'authentification gérée par Mastra et des métadonnées de route telles que requiresAuth, privilégiez registerApiRoute(). Pour les routes Hono brutes montées directement sur app, utilisez createAuthMiddleware() :

server.ts

import { Hono } from 'hono'
import { createAuthMiddleware, HonoBindings, HonoVariables, MastraServer } from '@mastra/hono'
import { mastra } from './mastra'

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

await server.init()

app.get('/custom/protected', createAuthMiddleware({ mastra }), c => {
  const user = c.get('requestContext').get('user')
  return c.json({ user })
})

app.get('/custom/public', createAuthMiddleware({ mastra, requiresAuth: false }), c => {
  return c.json({ ok: true })
})

Accès au contexte

Dans les middlewares Hono et les gestionnaires de routes, accédez au contexte Mastra au moyen de c.get() :

app.get('/custom', async c => {
  const mastra = c.get('mastra')
  const requestContext = c.get('requestContext')
  const abortSignal = c.get('abortSignal')

  const agent = mastra.getAgent('myAgent')
  return c.json({ agent: agent.name })
})

Clés de contexte disponibles :

Clé	Description
mastra	Instance Mastra
requestContext	Map du contexte de requête
abortSignal	Signal d'annulation de la requête
tools	Tools disponibles
taskStore	Stockage des tâches pour les opérations A2A
customRouteAuthConfig	Remplacements de l'authentification propres à chaque route
user	Utilisateur authentifié (si l'authentification est configurée)

Ajout de middlewares

Ajoutez les middlewares Hono avant ou après init() :

server.ts

import { Hono } from 'hono'
import { HonoBindings, HonoVariables, MastraServer } from '@mastra/hono'

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

// Middleware before init
app.use('*', async (c, next) => {
  console.log(`${c.req.method} ${c.req.url}`)
  await next()
})

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

// Middleware after init has access to Mastra context
app.use('*', async (c, next) => {
  const mastra = c.get('mastra')
  await next()
})

Initialisation manuelle

Pour personnaliser l'ordre des middlewares, appelez chaque méthode séparément au lieu d'utiliser init(). Pour en savoir plus, consultez l'initialisation manuelle.

Exemples

• Adaptateur Hono : configuration de base d'un serveur Hono

Voir aussi

• Adaptateurs de serveur : concepts communs aux adaptateurs
• Référence de MastraServer : référence complète de l'API
• Référence de createRoute() : création de routes personnalisées avec typage sûr