Feedback

追加バージョン： @mastra/core@1.18.0

Feedback API は、評価、賛否、コメント、訂正など、人間が介在する Observability シグナルを保存してクエリします。使用パターンについては、Feedback ガイドを参照してください。

使用例

次の例では、Observability エントリーポイントを介して永続化された Trace の評価を記録します。エントリーポイントの addFeedback() は省略可能なため、呼び出す前に、アクティブな Observability 実装が対応していることを確認してください。

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.',
  },
})

Feedback の作成

addFeedback(args)

Observability エントリーポイントを介して、永続化された Trace または Span に Feedback を追加します。

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

traceId?:

string

Feedback 対象の基準となる Trace。

spanId?:

string

Feedback 対象の基準となる Span。

correlationContext?:

CorrelationContext

ストレージから対象を復元せずに出力するための、アクティブな Span または Trace のコンテキスト。

feedback:

FeedbackInput

追加する Feedback payload。

createFeedback(args)

Observability の storage domain を介して、1件の Feedback レコードを作成します。ストレージレベルの呼び出しはストアへ直接書き込むため、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.',
  },
})

HTTP および Client SDK の作成ルートは CreateFeedbackBody を受け取り、サーバー側で timestamp を設定します。feedbackId を省略した場合は生成します。

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

batchCreateFeedback(args)

Observability の storage domain を介して、複数の Feedback レコードを作成します。このメソッドは HTTP ルートや @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.',
    },
  ],
})

Feedback の一覧取得

listFeedback(args?)

ページモードまたは差分モードで Feedback レコードを返します。

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

mode?:

'page' | 'delta'

一覧モード。デフォルトは 'page'。

filters?:

FeedbackFilter

Feedback レコードのフィルター。

pagination?:

{ page?: number; perPage?: number }

ページモードのページネーション。page はゼロ始まりです。

orderBy?:

{ field?: 'timestamp'; direction?: 'ASC' | 'DESC' }

ページモードの並べ替え設定。

after?:

string

増分ポーリング用の差分カーソル。差分モードでのみ有効です。

limit?:

number

差分モードで返す更新の最大数。

OLAP クエリ

OLAP Feedback クエリは数値の value フィールドを対象とします。

getFeedbackAggregate(args)

集計された Feedback 値を1つ返します。

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

feedbackType:

string

集計する Feedback タイプ。

feedbackSource?:

string

集計する Feedback ソース。

aggregation:

'sum' | 'avg' | 'min' | 'max' | 'count' | 'count_distinct' | 'last'

適用する集計方法。

filters?:

FeedbackFilter

追加のフィルター。

comparePeriod?:

'previous_period' | 'previous_day' | 'previous_week'

省略可能な前期間比較。

getFeedbackBreakdown(args)

ディメンション別にグループ化した Feedback 値を返します。

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

getFeedbackTimeSeries(args)

間隔ごとにバケット化した Feedback 値を返します。

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

getFeedbackPercentiles(args)

間隔ごとにバケット化したパーセンタイル値を返します。

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

型

FeedbackRecord

feedbackId?:

string | null

この Feedback イベントの一意な ID。省略した場合、サーバールートが生成します。

timestamp:

Date

Feedback が記録された時刻。

traceId?:

string | null

利用可能な場合に Feedback 対象の基準となる Trace。

spanId?:

string | null

利用可能な場合に Feedback 対象の基準となる Span。

feedbackSource?:

string | null

'user'、'qa'、'studio'、'system' などの省略可能なソースメタデータ。

source?:

string | null

feedbackSource の非推奨エイリアス。

feedbackType:

string

'rating'、'thumbs'、'comment'、'correction' などの Feedback タイプ。

value:

number | string

Feedback 値。数値は、集計、内訳、時系列、パーセンタイルのクエリに対応します。

comment?:

string | null

Feedback に関する追加コメントまたはコンテキスト。

feedbackUserId?:

string | null

Feedback を提供したユーザー。

sourceId?:

string | null

この Feedback が関連付けられているソースレコードの ID（実験結果 ID など）。

metadata?:

Record<string, unknown> | null

Feedback レコードのユーザー定義メタデータ。

共有コンテキストフィールド

Feedback レコードには、フィルタリング、グループ化、および Trace、ログ、メトリクス、Score との関連付けに使用する共有 Observability コンテキストフィールドを含められます。

entityType?:

EntityType | null

シグナルを生成した Entity のタイプ。

entityId?:

string | null

シグナルを生成した Entity の ID。

entityName?:

string | null

シグナルを生成した Entity の名前。

parentEntityType?:

EntityType | null

親 Entity のタイプ。

parentEntityId?:

string | null

親 Entity の ID。

parentEntityName?:

string | null

親 Entity の名前。

rootEntityType?:

EntityType | null

ルート Entity のタイプ。

rootEntityId?:

string | null

ルート Entity の ID。

rootEntityName?:

string | null

ルート Entity の名前。

userId?:

string | null

実行を開始した人間のエンドユーザー。

organizationId?:

string | null

マルチテナントの組織またはアカウント。

resourceId?:

string | null

より広範なリソースコンテキスト。

runId?:

string | null

実行 run 識別子。

sessionId?:

string | null

Trace をグループ化するセッション識別子。

threadId?:

string | null

会話スレッド識別子。

requestId?:

string | null

関連付け用の HTTP リクエスト ID。

environment?:

string | null

デプロイ環境。

serviceName?:

string | null

サービス名。

scope?:

Record<string, unknown> | null

パッケージ、アプリバージョン、またはデプロイのメタデータ。

entityVersionId?:

string | null

シグナルを生成した Entity のバージョン ID。

parentEntityVersionId?:

string | null

親 Entity のバージョン ID。

rootEntityVersionId?:

string | null

ルート Entity のバージョン ID。

experimentId?:

string | null

実験または Eval run の識別子。

executionSource?:

string | null

local、cloud、CI などの実行元。

tags?:

string[] | null

フィルタリング用のラベル。

FeedbackInput

FeedbackInput は、mastra.observability.addFeedback()、recordedTrace.addFeedback()、recordedSpan.addFeedback() で使用します。

feedbackSource?:

string

Feedback の省略可能なソースメタデータ。

source?:

string

feedbackSource の非推奨エイリアス。

feedbackType:

string

記録する Feedback のタイプ。

value:

number | string

記録する Feedback 値。

comment?:

string

追加のコメントまたはコンテキスト。

feedbackUserId?:

string

Feedback を提供したユーザー。

userId?:

string

feedbackUserId の非推奨エイリアス。

metadata?:

Record<string, unknown>

Feedback 固有の追加メタデータ。

experimentId?:

string

実験または Eval run の識別子。

sourceId?:

string

この Feedback が関連付けられているソースレコードの ID。

FeedbackFilter

FeedbackFilter は、listFeedback() および OLAP クエリの filters で使用します。

timestamp?:

{ start?: Date; end?: Date; startExclusive?: boolean; endExclusive?: boolean }

タイムスタンプ範囲でフィルタリングします。

traceId?:

string

Trace ID でフィルタリングします。

spanId?:

string

Span ID でフィルタリングします。

feedbackType?:

string | string[]

1つ以上の Feedback タイプでフィルタリングします。

feedbackSource?:

string

Feedback ソースでフィルタリングします。

source?:

string

feedbackSource の非推奨エイリアス。

feedbackUserId?:

string

Feedback を提供したユーザーでフィルタリングします。

entityType?:

EntityType

Entity タイプでフィルタリングします。

entityName?:

string

Entity 名でフィルタリングします。

entityVersionId?:

string

Entity バージョン ID でフィルタリングします。

parentEntityType?:

EntityType

親 Entity タイプでフィルタリングします。

parentEntityName?:

string

親 Entity 名でフィルタリングします。

parentEntityVersionId?:

string

親 Entity バージョン ID でフィルタリングします。

rootEntityType?:

EntityType

ルート Entity タイプでフィルタリングします。

rootEntityName?:

string

ルート Entity 名でフィルタリングします。

rootEntityVersionId?:

string

ルート Entity バージョン ID でフィルタリングします。

userId?:

string

人間のエンドユーザー ID でフィルタリングします。

organizationId?:

string

組織 ID でフィルタリングします。

resourceId?:

string

リソース ID でフィルタリングします。

runId?:

string

run ID でフィルタリングします。

sessionId?:

string

セッション ID でフィルタリングします。

threadId?:

string

スレッド ID でフィルタリングします。

requestId?:

string

リクエスト ID でフィルタリングします。

serviceName?:

string

サービス名でフィルタリングします。

environment?:

string

環境でフィルタリングします。

executionSource?:

string

実行元でフィルタリングします。

experimentId?:

string

実験または Eval run の識別子でフィルタリングします。

tags?:

string[]

タグでフィルタリングします。一致するレコードには、指定したすべてのタグが必要です。

HTTP ルート

メソッド	パス	用途	権限
GET	/api/observability/feedback	Feedback レコードの一覧取得	導出なし
POST	/api/observability/feedback	Feedback レコードの作成	導出なし
POST	/api/observability/feedback/aggregate	集計値を1つ返す	observability:read
POST	/api/observability/feedback/breakdown	Feedback をディメンション別にグループ化	observability:read
POST	/api/observability/feedback/timeseries	Feedback を間隔ごとにバケット化	observability:read
POST	/api/observability/feedback/percentiles	パーセンタイル系列を返す	observability:read

関連項目

• Feedback ガイド
• Client SDK Observability リファレンス
• Observability の設定