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 pour connaître toutes les méthodes du client.

src/mastra/feedback.ts

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 :

src/mastra/message-trace.ts

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.

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.

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.

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.

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 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 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é
• Présentation du traçage
• Présentation des métriques
• Référence de l’observabilité du SDK client
• Référence des retours