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

# Feedback

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

Feedback API は、評価、賛否、コメント、訂正など、人間が介在する Observability シグナルを保存してクエリします。使用パターンについては、[Feedback ガイド](https://mastra.zisheng.pro/ja/docs/observability/feedback)を参照してください。

## 使用例

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

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

## Feedback の作成

### `addFeedback(args)`

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

```typescript
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` を含めてください。

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

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

```typescript
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` では公開されていません。

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

## Feedback の一覧取得

### `listFeedback(args?)`

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

```typescript
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つ返します。

```typescript
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 値を返します。

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

### `getFeedbackTimeSeries(args)`

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

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

### `getFeedbackPercentiles(args)`

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

```typescript
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 ガイド](https://mastra.zisheng.pro/ja/docs/observability/feedback)
- [Client SDK Observability リファレンス](https://mastra.zisheng.pro/ja/reference/client-js/observability)
- [Observability の設定](https://mastra.zisheng.pro/ja/reference/observability/tracing/configuration)