평가와 테스트

/** 에이전트 실행의 단일 단계를 표현합니다. */
type TrajectoryStep = {
  /** 이 단계를 실행한 에이전트 이름 */
  agent: string
  /** 수행한 행위 — tool 호출, handoff, 응답 등 */
  action: string
  /** 에이전트에 주어진 입력 (프롬프트, 이전 결과 등) */
  input: unknown
  /** 에이전트가 반환한 출력 */
  output: unknown
  /** 실행 소요 시간 (ms) */
  duration: number
  /** 소비된 토큰 수 (prompt + completion) */
  tokens: { prompt: number; completion: number }
}

type Trajectory = {
  traceId: string
  startedAt: string          // ISO 8601
  steps: TrajectoryStep[]
  totalDuration: number      // ms
  totalTokens: number
  success: boolean
}

import { randomUUID } from 'node:crypto'

class TraceCollector {
  private steps: TrajectoryStep[] = []
  private startTime = Date.now()
  readonly traceId = randomUUID()

  /** 각 에이전트 호출을 감싸는 wrapper */
  async wrap<T>(
    agent: string,
    action: string,
    input: unknown,
    fn: () => Promise<T>,
  ): Promise<T> {
    const stepStart = Date.now()
    const tokensBefore = this.currentTokenUsage()

    const result = await fn()

    const tokensAfter = this.currentTokenUsage()
    this.steps.push({
      agent,
      action,
      input,
      output: result,
      duration: Date.now() - stepStart,
      tokens: {
        prompt: tokensAfter.prompt - tokensBefore.prompt,
        completion: tokensAfter.completion - tokensBefore.completion,
      },
    })
    return result
  }

  /** 전체 trajectory를 직렬화합니다. */
  finalize(success: boolean): Trajectory {
    const totalTokens = this.steps.reduce(
      (sum, s) => sum + s.tokens.prompt + s.tokens.completion,
      0,
    )
    return {
      traceId: this.traceId,
      startedAt: new Date(this.startTime).toISOString(),
      steps: this.steps,
      totalDuration: Date.now() - this.startTime,
      totalTokens,
      success,
    }
  }

  private currentTokenUsage() {
    // 실제 구현에서는 LLM 클라이언트의 usage 카운터를 읽습니다
    return { prompt: 0, completion: 0 }
  }
}

const collector = new TraceCollector()

// 라우팅 단계 수집
const routeResult = await collector.wrap(
  'router', 'classify_intent', userMessage,
  () => routerAgent.run(userMessage),
)

// 실행 단계 수집
const execResult = await collector.wrap(
  routeResult.targetAgent, 'execute', routeResult,
  () => executeAgent.run(routeResult),
)

// 저장
const trajectory = collector.finalize(execResult.success)
await trajectoryStore.save(trajectory)

당신은 에이전트 응답의 사실 정확성을 평가하는 전문 평가자입니다.

## 입력
- 사용자 질문: {question}
- 에이전트 응답: {agent_response}
- 참조 정답 (있는 경우): {reference_answer}
- 에이전트가 사용한 도구 결과: {tool_outputs}

## 평가 기준
1. 응답에 포함된 사실이 도구 결과와 일치하는가
2. 도구 결과에 없는 내용을 지어내지 않았는가 (hallucination)
3. 핵심 정보가 누락되지 않았는가
4. 수치, 날짜, 고유명사가 정확한가

## 출력 형식 (JSON)
{
  "score": 1-5,
  "hallucination_found": boolean,
  "missing_facts": ["누락된 사실 목록"],
  "reasoning": "채점 근거를 2-3문장으로 설명"
}

당신은 에이전트의 도구 사용 품질을 평가하는 전문 평가자입니다.

## 입력
- 사용자 질문: {question}
- 사용 가능한 도구 목록: {available_tools}
- 에이전트의 도구 호출 기록:
  {tool_call_sequence}

## 평가 기준
1. 질문 해결에 필요한 도구를 모두 사용했는가
2. 불필요한 도구를 호출하지 않았는가
3. 도구 호출 순서가 논리적인가 (의존 관계 준수)
4. 도구에 전달한 인자가 적절한가
5. 같은 도구를 반복 호출한 경우 그 이유가 합리적인가

## 출력 형식 (JSON)
{
  "score": 1-5,
  "unnecessary_calls": ["불필요한 호출 목록"],
  "missing_calls": ["누락된 호출 목록"],
  "order_issues": ["순서 문제 설명"],
  "reasoning": "채점 근거를 2-3문장으로 설명"
}

당신은 에이전트 trajectory의 효율성을 평가하는 전문 평가자입니다.

## 입력
- 사용자 질문: {question}
- 전체 trajectory:
  {trajectory_steps}
- 총 소요 시간: {total_duration}ms
- 총 토큰 사용량: {total_tokens}

## 평가 기준
1. 동일한 결과를 더 적은 단계로 달성할 수 있었는가
2. 병렬 실행 가능한 단계를 순차 실행하지 않았는가
3. 불필요한 재시도(retry)가 있었는가
4. 토큰 사용량이 작업 복잡도에 비해 과도하지 않은가
5. 전체 소요 시간이 SLA 기준을 충족하는가

## 출력 형식 (JSON)
{
  "score": 1-5,
  "redundant_steps": ["제거 가능한 step 목록"],
  "parallelizable_steps": ["병렬화 가능한 step 쌍"],
  "token_efficiency": "적정 | 과다 | 매우 과다",
  "reasoning": "채점 근거를 2-3문장으로 설명"
}

async function multiRunConsensus<T>(
  fn: () => Promise<T>,
  runs: number,
  extractKey: (result: T) => string,
): Promise<{ majority: string; agreement: number; results: T[] }> {
  const results = await Promise.all(
    Array.from({ length: runs }, () => fn()),
  )

  const counts = new Map<string, number>()
  for (const r of results) {
    const key = extractKey(r)
    counts.set(key, (counts.get(key) ?? 0) + 1)
  }

  const sorted = [...counts.entries()].sort((a, b) => b[1] - a[1])
  const [majority, majorityCount] = sorted[0]

  return {
    majority,
    agreement: majorityCount / runs,  // 0.0 ~ 1.0
    results,
  }
}

// 사용 예: 라우팅 결과가 5회 중 4회 이상 일치하는지 확인
const consensus = await multiRunConsensus(
  () => routerAgent.classify(userMessage),
  5,
  (r) => r.targetAgent,
)
assert(consensus.agreement >= 0.8, '라우팅 합의율 80% 미달')

import { describe, it, expect } from 'vitest'

/** 에이전트 출력의 속성을 검증하는 assertion 모음 */
const agentAssertions = {
  /** 구조적 속성: 필수 필드가 존재하는가 */
  hasRequiredFields(output: Record<string, unknown>, fields: string[]) {
    for (const field of fields) {
      expect(output).toHaveProperty(field)
    }
  },

  /** 행위 속성: 금지 패턴이 출력에 없는가 */
  noProhibitedPatterns(text: string, patterns: RegExp[]) {
    for (const pattern of patterns) {
      expect(text).not.toMatch(pattern)
    }
  },

  /** 의미 속성: 응답이 주어진 주제와 관련 있는가 */
  async isRelevantTo(response: string, topic: string, threshold = 0.7) {
    const score = await semanticSimilarity(response, topic)
    expect(score).toBeGreaterThanOrEqual(threshold)
  },

  /** 경계 속성: 수치가 허용 범위 안인가 */
  withinBounds(value: number, min: number, max: number) {
    expect(value).toBeGreaterThanOrEqual(min)
    expect(value).toBeLessThanOrEqual(max)
  },
}

describe('환불 처리 에이전트', () => {
  it('응답에 필수 필드가 포함된다', async () => {
    const result = await refundAgent.run(sampleRequest)
    agentAssertions.hasRequiredFields(result, [
      'decision',
      'reasoning',
      'amount',
    ])
  })

  it('PII를 노출하지 않는다', async () => {
    const result = await refundAgent.run(sampleRequest)
    agentAssertions.noProhibitedPatterns(result.reasoning, [
      /\d{3}-\d{2}-\d{4}/,     // SSN
      /\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}/, // 카드번호
      /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+/,        // 이메일
    ])
  })

  it('환불 금액이 원래 주문 금액을 초과하지 않는다', async () => {
    const result = await refundAgent.run(sampleRequest)
    agentAssertions.withinBounds(
      result.amount,
      0,
      sampleRequest.orderTotal,
    )
  })

  it('5회 실행 중 결정이 80% 이상 일치한다', async () => {
    const consensus = await multiRunConsensus(
      () => refundAgent.run(sampleRequest),
      5,
      (r) => r.decision,
    )
    expect(consensus.agreement).toBeGreaterThanOrEqual(0.8)
  })
})

type EvalRecord = {
  caseId: string
  expectedAction: 'respond' | 'escalate' | 'abort'
  contractPassed: boolean
  toolErrors: number
  humanOverride: boolean
  score: number
}