피드백

피드백 기록은 엄지손가락, 평점, 댓글, 수정 사항과 같은 인간 참여 신호를 캡처합니다. 사용자, QA, Studio 또는 시스템 검토 데이터를 추적 또는 범위에 연결하고 다른 Observability 신호와 함께 해당 데이터를 쿼리해야 할 때 피드백을 사용하세요.

메트릭 및 점수와 달리 피드백은 일반적으로 사람이나 검토 작업 흐름에 의해 제공됩니다. 숫자 피드백 값은 시간에 따라 집계, 그룹화, 차트 작성 및 백분위수 쿼리가 가능합니다.

피드백을 사용해야 하는 경우

• Agent 응답에 대한 사용자 만족도 평점을 수집하세요.
• 검토한 추적 옆에 QA 의견이나 수정 사항을 저장하세요.
• Agent, 환경 또는 실험별로 평가할 수 있는 대시보드를 구축하세요.

피드백 추가

앱 코드에서 영구 저장된 Trace나 Span에 주석을 추가하려면 mastra.observability.addFeedback()을 사용하세요. 이 도우미는 Observability 진입점에서 선택 사항이므로 활성 Observability 구현이 이를 지원하는지 확인하세요. 모든 클라이언트 메서드는 클라이언트 SDK Observability 참고 문서를 참조하세요.

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

메시지에 대한 추적 찾기

피드백은 일반적으로 사용자가 이미 읽은 메시지에 대해 수집되므로 해당 메시지의 traceId가 필요합니다. 어시스턴트 메시지에는 스트림 결과와 나중에 Memory에서 다시 불러온 메시지 모두에서 content.metadata에 이 값이 포함됩니다.

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

이 값은 실행 결과에 보고되는 Trace의 traceId와 동일하므로 생성 시 수집한 피드백과 나중에 저장된 메시지에 대해 수집한 피드백이 동일한 Trace에 연결됩니다. Tracing이 비활성화된 동안 생성된 메시지에는 traceId가 없습니다.

피드백 만들기

모든 createFeedback() 호출에는 feedbackType과 value가 필요합니다. 피드백을 Trace 또는 특정 Span에 연결해야 한다면 traceId 또는 spanId를 추가하세요. feedbackSource는 user, qa, studio 또는 system 같은 선택적 문자열 메타데이터로 사용하세요. 스토리지 수준에서 쓸 때는 메서드가 스토어에 직접 기록하므로 timestamp를 포함하세요.

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()을 사용하세요.

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 같은 공유 컨텍스트 필드가 포함됩니다.

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

쿼리 피드백 분석

OLAP 피드백 쿼리는 숫자 value 필드를 대상으로 작동합니다. 평점, 1과 -1로 인코딩한 좋아요/싫어요, 숫자형 QA 점수 또는 기타 숫자형 피드백 유형에 사용하세요.

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

전체 필드, 필터, 반환 유형, 백분위수 쿼리 매개변수는 피드백 참고 문서를 참조하세요.

피드백을 외부 플랫폼으로 내보내기

피드백은 Observability 이벤트 버스를 통해 흐르므로 피드백을 지원하는 Exporter가 자동으로 전달합니다. PostHog Exporter는 피드백을 PostHog에서 연결된 Trace에 표시되는 네이티브 $ai_feedback 이벤트로 전송합니다.

관련된

• Observability 개요
• 추적 개요
• 측정항목 개요
• 클라이언트 SDK 관측 가능성 참조
• 피드백 참조