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 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.

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.

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.

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 :

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.

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.

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.

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.

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

getFeedbackTimeSeries(args)

Renvoie les valeurs de feedback regroupées par intervalles.

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

getFeedbackPercentiles(args)

Renvoie les valeurs de percentile regroupées par intervalles.

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
• Référence de l'Observability du SDK client
• Configuration de l'Observability