Score 기록

record_score()는 개발자가 계산한 평가값을 trace 또는 정확히 지정한 observation에 연결합니다. 이 저수준 API 자체는 평가기를 고르거나 실행하지 않습니다. 실행 중 evaluator를 선언적으로 연결하려면 Runtime Evaluator Framework를 사용하세요. Runtime Evaluator는 score를 evaluation observation이 아니라 평가받은 원래 대상에 연결합니다. 아래 예제는 모두 개발자가 값을 직접 기록하는 경로입니다. 코드 위치와 실행 시점, Langfuse에 표시되는 대상도 함께 보여 줍니다.

지원하는 값과 대상

구분	허용 값
`data_type`	`NUMERIC`, `BOOLEAN`, `CATEGORICAL`, `TEXT`
`target`	`trace`, `observation`

# 전체 실행 품질
record_score(
    "answer_correctness",
    0.86,
    data_type="NUMERIC",
    target="trace",
)

# Flow 노드 안에서 호출하면 현재 노드 observation에 기록됩니다.
record_score(
    "groundedness",
    True,
    data_type="BOOLEAN",
    target="observation",
)

# 종료된 observation의 품질
record_score(
    "policy_grade",
    "A",
    data_type="CATEGORICAL",
    target="observation",
    observation=observation_ref,
    config_id="contract-grade-v1",
)

# 별도 평가 프로세스에서 ID로 기록하는 사후 평가
record_score(
    "review_note",
    "citation missing",
    data_type="TEXT",
    target="observation",
    trace_id=trace_id,
    observation_id=observation_id,
)

코드 위치	실행 시점	Langfuse 표시
Agent·Flow·Orchestrator의 최종 결과 처리부	전체 실행의 평가값을 계산한 직후	현재 trace의 `answer_correctness` score
Flow 노드 함수 또는 `observe()` 블록 안	현재 작업의 평가값이 나온 직후	Flow 안에서는 현재 Flow 노드 observation, `observe()` 안에서는 해당 observation의 `groundedness` score
`ObservationRef`를 받은 부모 워크플로 또는 평가 함수	대상 observation이 끝난 뒤	해당 observation의 `policy_grade` score
별도 평가 프로세스나 배치 작업	저장된 `trace_id`와 `observation_id`로 사후 평가할 때	지정한 observation의 `review_note` score

종료된 자식 observation 평가

Orchestrator 부모가 자식 호출의 결과를 평가하려면 observation 참조를 돌려주는 call_observed()를 사용합니다.

from llamon_agent.observability import record_score

observed = await ctx.call_observed(
    "verification",
    text=ctx.user_text,
    observation_type="agent",
    observation_metadata={"stage": "verification"},
)

if observed.observation is not None:
    record_score(
        "verification_quality",
        evaluate(observed.result),  # 개발자가 구현한 평가 로직
        data_type="NUMERIC",
        target="observation",
        observation=observed.observation,  # 종료된 자식 호출에 점수 연결
    )

코드 위치	실행 시점	Langfuse 표시
Orchestrator scaffold의 `app/orchestrator.py`	`ctx.call_observed()`가 끝나고 `evaluate(observed.result)`로 값을 계산한 직후	`Agent orchestrator.call:verification`의 `verification_quality` score

call_stream_observed()도 같은 방식으로 스트리밍 호출의 최종 결과와 observation 참조를 반환합니다. 관측 백엔드가 꺼져 있으면 참조가 없을 수 있습니다. 애플리케이션 로직이 참조의 존재 여부에 의존해서는 안 됩니다.

비교 가능한 평가 지표

반복 실행의 점수를 비교하려면 다음 항목을 고정합니다.

같은 의미에는 같은 score 이름과 데이터 타입을 사용합니다.
NUMERIC은 값의 범위와 방향, 즉 높을수록 좋은지 낮을수록 좋은지를 고정합니다.
CATEGORICAL은 허용 라벨과 Langfuse Score Config ID를 고정합니다.
비교 필터의 축이 되는 평가 기준 버전(policyVariant)은 evaluator observation의 로컬 metadata에 둡니다. rubric·모델 버전 같은 참고 정보는 score metadata나 config_id에 남깁니다.
TEXT는 피드백 저장에는 적합하지만 평균 비교에는 쓰지 않습니다.

평가 코드를 둘 위치

평가 코드는 다음 네 위치 중 실행 책임이 있는 곳에 둡니다.

Agent 또는 Flow 노드 안에서 계산해 현재 observation에 기록
Orchestrator 부모가 call_observed() 결과를 평가해 종료된 하위 observation에 기록
외부 evaluator가 trace 또는 observation ID로 사후 기록
단위 테스트에서 메모리 capture로 스키마와 점수 대상 검증

실행 위치와 평가 알고리즘은 개발자가 정합니다. SDK는 값의 타입을 검증하고 점수를 올바른 trace 또는 observation에 연결합니다. 비교 기준과 필터 조합은 Langfuse 필터와 비교에서 이어집니다.