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

# Feedback

**Ajouté dans :** `@mastra/core@1.18.0`

Les API de Feedback stockent et interrogent les signaux d'Observability impliquant un humain, tels que les évaluations, les pouces, les commentaires et les corrections. Consultez le [guide du Feedback](https://mastra.zisheng.pro/fr/docs/observability/feedback) pour découvrir les modèles d'utilisation.

## Exemple d'utilisation

L'exemple suivant enregistre une évaluation pour une Trace persistée via le point d'entrée d'Observability. `addFeedback()` est facultatif sur ce point d'entrée ; vérifiez donc que l'implémentation active de l'Observability le prend en charge avant de l'appeler.

```typescript
if (!mastra.observability.addFeedback) {
  throw new Error('Feedback is not supported by the active observability implementation')
}

await mastra.observability.addFeedback({
  traceId: 'trace-123',
  spanId: 'span-456',
  feedback: {
    feedbackSource: 'user',
    feedbackType: 'rating',
    value: 1,
    comment: 'Helpful answer.',
  },
})
```

## Création de feedback

### `addFeedback(args)`

Ajoute du feedback à une Trace ou à un span persisté via le point d'entrée d'Observability.

```typescript
await mastra.observability.addFeedback?.({
  traceId: 'trace-123',
  spanId: 'span-456',
  feedback: {
    feedbackSource: 'user',
    feedbackType: 'rating',
    value: 1,
    comment: 'Helpful answer.',
  },
})
```

**traceId** (`string`): Trace qui sert de point d’ancrage à la cible du feedback.

**spanId** (`string`): Span qui sert de point d’ancrage à la cible du feedback.

**correlationContext** (`CorrelationContext`): Contexte de span ou de Trace actif depuis lequel émettre sans réhydrater la cible depuis le stockage.

**feedback** (`FeedbackInput`): Payload de feedback à ajouter.

### `createFeedback(args)`

Crée un enregistrement de feedback via le domaine de stockage de l'Observability. Les appels au niveau du stockage écrivent directement dans celui-ci ; incluez donc `timestamp`.

```typescript
await observability.createFeedback({
  feedback: {
    feedbackId: 'feedback-1',
    timestamp: new Date(),
    traceId: 'trace-123',
    spanId: 'span-456',
    feedbackSource: 'user',
    feedbackType: 'rating',
    value: 1,
    comment: 'Helpful answer.',
  },
})
```

La route de création HTTP et du SDK client accepte `CreateFeedbackBody` et définit `timestamp` côté serveur. Elle génère `feedbackId` lorsque celui-ci est omis :

```typescript
await mastraClient.createFeedback({
  feedback: {
    traceId: 'trace-123',
    spanId: 'span-456',
    feedbackSource: 'user',
    feedbackType: 'rating',
    value: 1,
  },
})
```

### `batchCreateFeedback(args)`

Crée plusieurs enregistrements de feedback via le domaine de stockage de l'Observability. Cette méthode n'est pas exposée par les routes HTTP ni par `@mastra/client-js`.

```typescript
await observability.batchCreateFeedback({
  feedbacks: [
    {
      feedbackId: 'feedback-1',
      timestamp: new Date(),
      traceId: 'trace-123',
      feedbackSource: 'user',
      feedbackType: 'rating',
      value: 1,
    },
    {
      feedbackId: 'feedback-2',
      timestamp: new Date(),
      traceId: 'trace-123',
      feedbackSource: 'qa',
      feedbackType: 'comment',
      value: 'Needs a citation before shipping.',
    },
  ],
})
```

## Liste du feedback

### `listFeedback(args?)`

Renvoie les enregistrements de feedback en mode page ou delta.

```typescript
const response = await mastraClient.listFeedback({
  filters: {
    feedbackType: 'rating',
    feedbackSource: 'studio',
  },
  pagination: { page: 0, perPage: 20 },
  orderBy: { field: 'timestamp', direction: 'DESC' },
})
```

**mode** (`'page' | 'delta'`): Mode de liste. Utilise 'page' par défaut.

**filters** (`FeedbackFilter`): Filtres des enregistrements de feedback.

**pagination** (`{ page?: number; perPage?: number }`): Pagination du mode page. page commence à zéro.

**orderBy** (`{ field?: 'timestamp'; direction?: 'ASC' | 'DESC' }`): Configuration du tri en mode page.

**after** (`string`): Curseur delta pour l'interrogation incrémentielle. Valide uniquement en mode delta.

**limit** (`number`): Nombre maximal de mises à jour à renvoyer en mode delta.

## Requêtes OLAP

Les requêtes OLAP de feedback s'appliquent aux champs `value` numériques.

### `getFeedbackAggregate(args)`

Renvoie une valeur agrégée de feedback.

```typescript
const response = await mastraClient.getFeedbackAggregate({
  feedbackType: 'rating',
  feedbackSource: 'user',
  aggregation: 'avg',
  comparePeriod: 'previous_day',
})
```

**feedbackType** (`string`): Type de feedback à agréger.

**feedbackSource** (`string`): Source de feedback à agréger.

**aggregation** (`'sum' | 'avg' | 'min' | 'max' | 'count' | 'count_distinct' | 'last'`): Agrégation à appliquer.

**filters** (`FeedbackFilter`): Filtres supplémentaires.

**comparePeriod** (`'previous_period' | 'previous_day' | 'previous_week'`): Comparaison facultative d'une période à l'autre.

### `getFeedbackBreakdown(args)`

Renvoie les valeurs de feedback regroupées par dimensions.

```typescript
const response = await mastraClient.getFeedbackBreakdown({
  feedbackType: 'rating',
  groupBy: ['entityName'],
  aggregation: 'avg',
})
```

### `getFeedbackTimeSeries(args)`

Renvoie les valeurs de feedback regroupées par intervalles.

```typescript
const response = await mastraClient.getFeedbackTimeSeries({
  feedbackType: 'rating',
  interval: '1h',
  aggregation: 'avg',
  groupBy: ['feedbackSource'],
})
```

### `getFeedbackPercentiles(args)`

Renvoie les valeurs de percentile regroupées par intervalles.

```typescript
const response = await mastraClient.getFeedbackPercentiles({
  feedbackType: 'rating',
  percentiles: [0.5, 0.95],
  interval: '1d',
})
```

## Types

### `FeedbackRecord`

**feedbackId** (`string | null`): Identifiant unique de cet événement de feedback. La route serveur en génère un lorsqu’il est omis.

**timestamp** (`Date`): Date et heure d'enregistrement du feedback.

**traceId** (`string | null`): Trace qui sert de point d’ancrage à la cible du feedback, si disponible.

**spanId** (`string | null`): Span qui sert de point d’ancrage à la cible du feedback, si disponible.

**feedbackSource** (`string | null`): Métadonnées de source facultatives, telles que 'user', 'qa', 'studio' ou 'system'.

**source** (`string | null`): Alias obsolète de feedbackSource.

**feedbackType** (`string`): Type de feedback, tel que 'rating', 'thumbs', 'comment' ou 'correction'.

**value** (`number | string`): Valeur du feedback. Les valeurs numériques prennent en charge les requêtes d’agrégation, de ventilation, de série temporelle et de percentile.

**comment** (`string | null`): Commentaire ou contexte supplémentaire du feedback.

**feedbackUserId** (`string | null`): Utilisateur ayant fourni le feedback.

**sourceId** (`string | null`): Identifiant de l'enregistrement source auquel ce feedback est associé, tel que l'identifiant d'un résultat d'expérience.

**metadata** (`Record<string, unknown> | null`): Métadonnées définies par l'utilisateur pour l'enregistrement de feedback.

### Champs de contexte partagés

Les enregistrements de feedback peuvent inclure des champs de contexte d'Observability partagés afin de filtrer, regrouper et corréler les Traces, les logs, les métriques et les scores.

**entityType** (`EntityType | null`): Type de l'entité ayant produit le signal.

**entityId** (`string | null`): Identifiant de l'entité ayant produit le signal.

**entityName** (`string | null`): Nom de l'entité ayant produit le signal.

**parentEntityType** (`EntityType | null`): Type de l'entité parente.

**parentEntityId** (`string | null`): Identifiant de l'entité parente.

**parentEntityName** (`string | null`): Nom de l'entité parente.

**rootEntityType** (`EntityType | null`): Type de l'entité racine.

**rootEntityId** (`string | null`): Identifiant de l'entité racine.

**rootEntityName** (`string | null`): Nom de l'entité racine.

**userId** (`string | null`): Utilisateur humain final ayant déclenché l'exécution.

**organizationId** (`string | null`): Organisation ou compte mutualisé.

**resourceId** (`string | null`): Contexte plus large de la ressource.

**runId** (`string | null`): Identifiant de l'exécution.

**sessionId** (`string | null`): Identifiant de session permettant de regrouper les Traces.

**threadId** (`string | null`): Identifiant du fil de conversation.

**requestId** (`string | null`): Identifiant de requête HTTP pour la corrélation.

**environment** (`string | null`): Environnement de déploiement.

**serviceName** (`string | null`): Nom du service.

**scope** (`Record<string, unknown> | null`): Métadonnées du package, de la version de l'application ou du déploiement.

**entityVersionId** (`string | null`): Identifiant de version de l'entité ayant produit le signal.

**parentEntityVersionId** (`string | null`): Identifiant de version de l'entité parente.

**rootEntityVersionId** (`string | null`): Identifiant de version de l'entité racine.

**experimentId** (`string | null`): Identifiant d'exécution d'expérience ou d'Eval.

**executionSource** (`string | null`): Source de l'exécution, telle que locale, cloud ou CI.

**tags** (`string[] | null`): Labels destinés au filtrage.

### `FeedbackInput`

Utilisez `FeedbackInput` avec `mastra.observability.addFeedback()`, `recordedTrace.addFeedback()` et `recordedSpan.addFeedback()`.

**feedbackSource** (`string`): Métadonnées de source facultatives du feedback.

**source** (`string`): Alias obsolète de feedbackSource.

**feedbackType** (`string`): Type de feedback à enregistrer.

**value** (`number | string`): Valeur de feedback à enregistrer.

**comment** (`string`): Commentaire ou contexte supplémentaire.

**feedbackUserId** (`string`): Utilisateur ayant fourni le feedback.

**userId** (`string`): Alias obsolète de feedbackUserId.

**metadata** (`Record<string, unknown>`): Métadonnées supplémentaires propres au feedback.

**experimentId** (`string`): Identifiant d'exécution d'expérience ou d'Eval.

**sourceId** (`string`): Identifiant de l'enregistrement source auquel ce feedback est associé.

### `FeedbackFilter`

Utilisez `FeedbackFilter` dans `listFeedback()` et dans les `filters` des requêtes OLAP.

**timestamp** (`{ start?: Date; end?: Date; startExclusive?: boolean; endExclusive?: boolean }`): Filtre selon une plage d'horodatages.

**traceId** (`string`): Filtre selon l'identifiant de Trace.

**spanId** (`string`): Filtre selon l'identifiant du span.

**feedbackType** (`string | string[]`): Filtre selon un ou plusieurs types de feedback.

**feedbackSource** (`string`): Filtre selon la source du feedback.

**source** (`string`): Alias obsolète de feedbackSource.

**feedbackUserId** (`string`): Filtre selon l’utilisateur ayant fourni le feedback.

**entityType** (`EntityType`): Filtre selon le type d'entité.

**entityName** (`string`): Filtre selon le nom de l'entité.

**entityVersionId** (`string`): Filtre selon l'identifiant de version de l'entité.

**parentEntityType** (`EntityType`): Filtre selon le type de l'entité parente.

**parentEntityName** (`string`): Filtre selon le nom de l'entité parente.

**parentEntityVersionId** (`string`): Filtre selon l'identifiant de version de l'entité parente.

**rootEntityType** (`EntityType`): Filtre selon le type de l'entité racine.

**rootEntityName** (`string`): Filtre selon le nom de l'entité racine.

**rootEntityVersionId** (`string`): Filtre selon l'identifiant de version de l'entité racine.

**userId** (`string`): Filtre selon l'identifiant de l'utilisateur humain final.

**organizationId** (`string`): Filtre selon l'identifiant de l'organisation.

**resourceId** (`string`): Filtre selon l'identifiant de la ressource.

**runId** (`string`): Filtre selon l'identifiant de l'exécution.

**sessionId** (`string`): Filtre selon l'identifiant de la session.

**threadId** (`string`): Filtre selon l'identifiant du fil de discussion.

**requestId** (`string`): Filtre selon l'identifiant de la requête.

**serviceName** (`string`): Filtre selon le nom du service.

**environment** (`string`): Filtre selon l'environnement.

**executionSource** (`string`): Filtre selon la source de l'exécution.

**experimentId** (`string`): Filtre selon l'identifiant d'exécution de l'expérience ou de l'Eval.

**tags** (`string[]`): Filtre selon les tags. Les enregistrements correspondants doivent posséder tous les tags indiqués.

## Routes HTTP

| Méthode | Chemin                                    | Objectif                                    | Autorisation                |
| ------- | ----------------------------------------- | ------------------------------------------- | --------------------------- |
| `GET`   | `/api/observability/feedback`             | Répertorier les enregistrements de feedback | Aucune autorisation dérivée |
| `POST`  | `/api/observability/feedback`             | Créer un enregistrement de feedback         | Aucune autorisation dérivée |
| `POST`  | `/api/observability/feedback/aggregate`   | Renvoyer une valeur agrégée                 | `observability:read`        |
| `POST`  | `/api/observability/feedback/breakdown`   | Regrouper le feedback par dimensions        | `observability:read`        |
| `POST`  | `/api/observability/feedback/timeseries`  | Regrouper le feedback par intervalles       | `observability:read`        |
| `POST`  | `/api/observability/feedback/percentiles` | Renvoyer une série de percentiles           | `observability:read`        |

## Voir aussi

- [Guide du Feedback](https://mastra.zisheng.pro/fr/docs/observability/feedback)
- [Référence de l'Observability du SDK client](https://mastra.zisheng.pro/fr/reference/client-js/observability)
- [Configuration de l'Observability](https://mastra.zisheng.pro/fr/reference/observability/tracing/configuration)