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

# 反馈

反馈记录用于捕获人工参与环节中的信号，例如点赞、评分、评论和修正。当你需要将用户、QA、Studio 或系统审查数据附加到 Trace 或 span，并与其他可观测性信号一起查询时，可以使用反馈。

与指标和分数不同，反馈通常由人员或审查 Workflow 提供。数值反馈可以进行聚合、分组、按时间绘图和百分位查询。

## 何时使用反馈

- 收集用户对 Agent 响应的满意度评分。
- 将 QA 评论或修正存储在其审查的 Trace 旁边。
- 按 Agent、环境或实验构建评分仪表板。

## 添加反馈

如果要从应用代码为已持久化的 Trace 或 span 添加注释，请使用 `mastra.observability.addFeedback()`。该 helper 在可观测性入口上是可选的，因此请检查当前可观测性实现是否支持它。所有客户端方法请参阅[客户端 SDK 可观测性参考](https://mastra.zisheng.pro/reference/client-js/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: 'The answer solved my issue.',
  },
})
```

## 查找消息对应的 Trace

反馈通常针对用户已经读过的消息收集，因此你需要该消息的 `traceId`。无论是在流结果中，还是之后从 memory 召回消息时，助手消息都会在 `content.metadata` 中携带它：

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

该值与运行结果中作为 `traceId` 报告的 Trace 相同，因此生成时收集的反馈和之后针对已存储消息收集的反馈都会锚定到同一 Trace。禁用 tracing 时生成的消息没有 `traceId`。

## 创建反馈

每次调用 `createFeedback()` 都需要 `feedbackType` 和 `value`。如果反馈需要锚定到 Trace 或特定 span，请添加 `traceId` 或 `spanId`。将 `feedbackSource` 用作可选字符串元数据，例如 `user`、`qa`、`studio` 或 `system`。

在存储层写入时，请包含 `timestamp`，因为该方法会直接写入存储。

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

## 列出反馈

使用 `listFeedback()` 分页浏览原始记录，或使用 delta 模式轮询。

```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)
```

过滤器包括 `traceId` 和 `spanId` 等目标字段，`feedbackType`、`feedbackSource` 和 `feedbackUserId` 等反馈字段，以及 `entityName`、`environment`、`experimentId` 和 `tags` 等共享上下文字段。

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

## 查询反馈分析

OLAP 反馈查询针对数值 `value` 字段执行。可用于评分、编码为 `1` 和 `-1` 的赞踩、数值 QA 分数或其他数值反馈类型。

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

所有字段、过滤器、返回类型和百分位查询参数请参阅[反馈参考](https://mastra.zisheng.pro/reference/observability/feedback)。

## 将反馈导出到外部平台

反馈会流经可观测性事件总线，因此支持反馈的 exporter 会自动转发。[PostHog exporter](https://mastra.zisheng.pro/reference/observability/tracing/exporters/posthog) 会将反馈作为原生 `$ai_feedback` 事件发送，并显示在 PostHog 中关联的 Trace 上。

## 相关内容

- [可观测性概览](https://mastra.zisheng.pro/docs/observability/overview)
- [Tracing 概览](https://mastra.zisheng.pro/docs/observability/tracing/overview)
- [指标概览](https://mastra.zisheng.pro/docs/observability/metrics/overview)
- [客户端 SDK 可观测性参考](https://mastra.zisheng.pro/reference/client-js/observability)
- [反馈参考](https://mastra.zisheng.pro/reference/observability/feedback)