> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# Adaptateur Koa

Le package `@mastra/koa` fournit un adaptateur de serveur permettant d'exécuter Mastra avec [Koa](https://koajs.com). 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](https://mastra.zisheng.pro/fr/docs/server/server-adapters).

## Installation

Installez l'adaptateur Koa et le framework Koa :

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

## Exemple d'utilisation

```typescript
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) (Default: `''`)

**openapiPath** (`string`): Chemin depuis lequel servir la spécification OpenAPI (par exemple, /openapi.json) (Default: `''`)

**bodyLimitOptions** (`BodyLimitOptions`): Limites de taille du corps des requêtes

**streamOptions** (`StreamOptions`): 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. (Default: `{ redact: true }`)

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

```typescript
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`](https://mastra.zisheng.pro/fr/reference/configuration) 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 :

```typescript
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()`](https://mastra.zisheng.pro/fr/reference/server/register-api-route). Pour les routes Koa brutes montées directement sur l'application, utilisez `createAuthMiddleware()` :

```typescript
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](https://mastra.zisheng.pro/fr/docs/server/server-adapters).

## Exemples

- [Adaptateur Koa](https://github.com/mastra-ai/mastra/tree/main/examples/server-koa-adapter) : configuration de base d'un serveur Koa

## Voir aussi

- [Adaptateurs de serveur](https://mastra.zisheng.pro/fr/docs/server/server-adapters) : concepts communs aux adaptateurs
- [Référence de MastraServer](https://mastra.zisheng.pro/fr/reference/server/mastra-server) : référence complète de l'API
- [Référence de createRoute()](https://mastra.zisheng.pro/fr/reference/server/create-route) : création de routes personnalisées avec typage sûr