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

# Retours

Les retours enregistrent les signaux issus d’une intervention humaine, tels que les pouces, les évaluations, les commentaires et les corrections. Utilisez-les lorsque vous devez associer les données de vérification d’un utilisateur, du contrôle qualité, de Studio ou du système à une trace ou à un span, puis interroger ces données avec d’autres signaux d’observabilité.

Contrairement aux métriques et aux scores, les retours proviennent généralement d’une personne ou d’un processus de vérification. Leurs valeurs numériques peuvent être agrégées, regroupées, représentées graphiquement au fil du temps et interrogées afin d’obtenir des percentiles.

## Quand utiliser les retours

- Recueillez les évaluations de satisfaction des utilisateurs concernant les réponses d’un agent.
- Stockez les commentaires ou corrections du contrôle qualité à côté de la trace concernée.
- Créez des tableaux de bord présentant les évaluations par agent, environnement ou expérimentation.

## Ajouter un retour

Utilisez `mastra.observability.addFeedback()` pour annoter une trace ou un span persisté depuis le code de l’application. Cette fonction d’assistance est facultative sur le point d’entrée de l’observabilité ; vérifiez donc que l’implémentation active de l’observabilité la prend en charge. Consultez la [référence de l’observabilité du SDK client](https://mastra.zisheng.pro/fr/reference/client-js/observability) pour connaître toutes les méthodes du client.

```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: 'The answer solved my issue.',
  },
})
```

## Trouver la trace d’un message

Les retours sont généralement recueillis à propos d’un message que l’utilisateur a déjà lu. Vous avez donc besoin du `traceId` de ce message. Les messages de l’assistant le contiennent dans `content.metadata`, aussi bien dans le résultat du flux que lorsque le message est récupéré ultérieurement depuis la mémoire :

```typescript
const agent = mastra.getAgent('weatherAgent')
const memory = await agent.getMemory()

const { messages } = await memory!.recall({ threadId, perPage: false })

const message = messages.find(m => m.id === messageId)
const traceId = message?.content.metadata?.traceId
```

Cette valeur désigne la même trace que celle indiquée par l’exécution sous la forme `traceId` dans son résultat. Ainsi, les retours recueillis lors de la génération et ceux ajoutés ultérieurement à un message stocké sont rattachés à la même trace. Les messages produits lorsque le traçage est désactivé ne possèdent pas de `traceId`.

## Créer un retour

Chaque appel à `createFeedback()` nécessite `feedbackType` et `value`. Ajoutez `traceId` ou `spanId` lorsque le retour doit être rattaché à une trace ou à un span précis. Utilisez `feedbackSource` comme métadonnée de chaîne facultative, par exemple `user`, `qa`, `studio` ou `system`.

Pour les écritures au niveau du stockage, incluez `timestamp`, car la méthode écrit directement dans le stockage.

```typescript
const observability = await mastra.getStorage()!.getStore('observability')

await observability!.createFeedback({
  feedback: {
    feedbackId: 'feedback-rating-1',
    timestamp: new Date(),
    traceId: 'trace-123',
    spanId: 'span-456',
    feedbackSource: 'user',
    feedbackType: 'rating',
    value: 1,
    comment: 'The answer solved my issue.',
    tags: ['production'],
  },
})

await observability!.createFeedback({
  feedback: {
    feedbackId: 'feedback-comment-1',
    timestamp: new Date(),
    feedbackSource: 'qa',
    feedbackType: 'comment',
    value: 'Needs a citation before shipping.',
    experimentId: 'support-agent-eval',
  },
})
```

## Répertorier les retours

Utilisez `listFeedback()` pour parcourir les enregistrements bruts page par page ou effectuer des interrogations en mode différentiel.

```typescript
const result = await observability!.listFeedback({
  filters: {
    feedbackType: 'rating',
    feedbackSource: 'user',
    timestamp: { start: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000) },
  },
  pagination: { page: 0, perPage: 20 },
  orderBy: { field: 'timestamp', direction: 'DESC' },
})

console.log(result.feedback, result.pagination?.hasMore)
```

Les filtres comprennent des champs de cible tels que `traceId` et `spanId`, des champs de retour tels que `feedbackType`, `feedbackSource` et `feedbackUserId`, ainsi que des champs de contexte partagés tels que `entityName`, `environment`, `experimentId` et `tags`.

```typescript
await observability!.listFeedback({
  filters: {
    traceId: 'trace-123',
    feedbackType: ['rating', 'thumbs'],
    tags: ['production'],
  },
})
```

## Interroger les analyses des retours

Les requêtes OLAP sur les retours utilisent des champs `value` numériques. Employez-les pour les évaluations, les pouces encodés sous la forme `1` et `-1`, les scores numériques du contrôle qualité ou d’autres types de retours numériques.

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

const byAgent = await observability!.getFeedbackBreakdown({
  feedbackType: 'rating',
  groupBy: ['entityName'],
  aggregation: 'avg',
  filters: { environment: 'production' },
})

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

Consultez la [référence des retours](https://mastra.zisheng.pro/fr/reference/observability/feedback) pour connaître tous les champs, filtres, types de retour et paramètres des requêtes de percentiles.

## Exporter les retours vers des plateformes externes

Les retours transitent par le bus d’événements de l’observabilité. Les exportateurs qui les prennent en charge les transmettent donc automatiquement. L’[exportateur PostHog](https://mastra.zisheng.pro/fr/reference/observability/tracing/exporters/posthog) envoie les retours sous forme d’événements natifs `$ai_feedback`, qui apparaissent sur la trace associée dans PostHog.

## Pages connexes

- [Présentation de l’observabilité](https://mastra.zisheng.pro/fr/docs/observability/overview)
- [Présentation du traçage](https://mastra.zisheng.pro/fr/docs/observability/tracing/overview)
- [Présentation des métriques](https://mastra.zisheng.pro/fr/docs/observability/metrics/overview)
- [Référence de l’observabilité du SDK client](https://mastra.zisheng.pro/fr/reference/client-js/observability)
- [Référence des retours](https://mastra.zisheng.pro/fr/reference/observability/feedback)