Adaptateur Koa

Le package @mastra/koa fournit un adaptateur de serveur permettant d'exécuter Mastra avec Koa. 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 Koa et le framework Koa :

npm

npm install @mastra/koa@latest koa koa-bodyparser

pnpm

pnpm add @mastra/koa@latest koa koa-bodyparser

Yarn

yarn add @mastra/koa@latest koa koa-bodyparser

Bun

bun add @mastra/koa@latest koa koa-bodyparser

Exemple d'utilisation

server.ts

import Koa from 'koa'
import bodyParser from 'koa-bodyparser'
import { MastraServer } from '@mastra/koa'
import { mastra } from './mastra'

const app = new Koa()
app.use(bodyParser())

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

await server.init()

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000')
})

Paramètres du constructeur

app:

Koa

Instance de l'application Koa

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?:

BodyLimitOptions

Limites de taille du corps des requêtes

streamOptions?:

StreamOptions

= { redact: true }

Configuration du masquage du flux. Lorsque la valeur est true (par défaut), masque les données sensibles (prompts système, définitions des Tools et clés d'API) dans les segments du flux avant leur envoi aux clients.

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?:

ToolsInput

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.

Gestion des erreurs

L'adaptateur Koa propage les erreurs des gestionnaires de routes dans la chaîne de middlewares de Koa, conformément au modèle standard de gestion des erreurs de Koa. Vous pouvez donc utiliser un middleware Koa classique de gestion des erreurs :

server.ts

const app = new Koa()
app.use(bodyParser())

// Your error middleware catches errors from Mastra route handlers
app.use(async (ctx, next) => {
  try {
    await next()
  } catch (err) {
    ctx.status = err.status || 500
    ctx.body = { error: err.message }
    // Log, report to Sentry, etc.
  }
})

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

Le hook server.onError est également pris en charge. Lorsqu'il est configuré, il est appelé avant la propagation de l'erreur au middleware et sa réponse est utilisée directement :

src/mastra/index.ts

const mastra = new Mastra({
  server: {
    onError: (err, c) => {
      console.error('Unhandled error:', err)
      return c.json({ error: err.message }, 500)
    },
  },
})

Lorsque init() est utilisé, un middleware global de gestion des erreurs est également enregistré comme filet de sécurité. Les erreurs qui atteignent ce middleware sont émises au moyen de ctx.app.emit('error', err, ctx), conformément à la convention standard de Koa.

Protection des routes brutes

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 Koa brutes montées directement sur l'application, utilisez createAuthMiddleware() :

server.ts

import Koa from 'koa'
import { createAuthMiddleware, MastraServer } from '@mastra/koa'
import { mastra } from './mastra'

const app = new Koa()
const server = new MastraServer({ app, mastra })

await server.init()

app.use(createAuthMiddleware({ mastra }))
app.use(async ctx => {
  if (ctx.path !== '/custom/protected') return

  const user = ctx.state.requestContext.get('user')
  ctx.body = { user }
})

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 Koa : configuration de base d'un serveur Koa

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