Observation 설계

observation_type은 실제 기술 작업을 나타냅니다. 서비스 역할이나 validation 같은 업무 단계를 넣는 칸이 아닙니다. 이 값들은 metadata에 기록하세요. 각 예제에는 코드 위치, 실행 시점, Langfuse에 표시되는 타입과 이름을 함께 적었습니다.

공식 observation type

SDK가 허용하는 값은 Langfuse의 공식 소문자 타입과 같습니다.

event
span, generation, agent, tool, chain,
retriever, evaluator, embedding, guardrail

event는 시작과 끝이 없는 순간 기록입니다. 나머지 아홉 타입은 실행 시간을 재는 구간형 observation API를 사용합니다.

from llamon_agent.observability import observe, record_event

with observe(
    "validate-fields",
    observation_type="evaluator",  # Langfuse 기술 유형
    metadata={"stage": "validation", "policyVariant": "contract-v3"},  # 업무 단계와 비교 기준
) as observation:
    issues = validate_document()
    observation.set_output({"issueCount": len(issues)})

record_event(
    "manual-review-required",
    metadata={"reason": "missing-signature"},
)

코드 위치	실행 시점	Langfuse 표시
실제 작업 함수 안. Flow는 app/nodes.py, Agent는 app/tools.py나 app/runtime_adapter.py 같은 업무 코드에 둡니다.	with observe(...) 진입 시 시작하고 블록을 나올 때 종료합니다. record_event()는 호출한 순간 한 번 기록합니다.	현재 trace 또는 Flow 노드 아래에 Evaluator validate-fields가 생깁니다. 이벤트는 Event manual-review-required로 별도 표시됩니다.

validation·normalization·decision처럼 개발자가 정한 단계 이름을 observation_type으로 보내지 마세요. 실제 작업과 가장 가까운 공식 타입을 고르고 단계는 metadata에 둡니다. 딱 맞는 타입이 없으면 span, 여러 작업을 묶는 부모라면 chain이 안전한 기본값입니다.

Flow의 세 가지 축

축	소유자	결정하는 것
node_kind	LLaMON SDK	실행 방식, Studio UI, 코드 생성, 오류 컨텍스트
observation_type	Langfuse	기술 타입, UI 아이콘, 타입 필터
observation_metadata	개발자	단계, 정책, 버전 같은 분석 기준

Python 업무 노드가 규칙 검증을 수행한다면 node_kind와 observation_type이 달라도 정상입니다.

graph = (
    GraphBuilder()
    .node(
        "validate-document",
        validate_document,
        node_kind="business",  # LLaMON 실행 방식
        observation_type="evaluator",  # Langfuse 기술 유형
        observation_metadata={  # 업무 단계와 비교 기준
            "stage": "validation",
            "policyVariant": "contract-v3",
        },
    )
    .edge(START, "validate-document")
    .edge("validate-document", END)
    .build()
)

코드 위치	실행 시점	Langfuse 표시
Flow 스캐폴드의 app/graph.py	validate-document 노드가 실행될 때마다 SDK가 자동으로 시작하고 종료합니다. 별도로 observe()를 감쌀 필요가 없습니다.	Evaluator business-validate-document가 생기고 해당 observation의 metadata에 stage=validation, policyVariant=contract-v3가 표시됩니다.

기본 타입 선택

observation_type을 생략하면 canonical node_kind에 따라 기본값을 고릅니다.

표준 node_kind	기본 observation type
registry_node, registry_llm, llm	agent
business, merge, transform	chain
http, postgres	tool
guardrail	guardrail
미지정 또는 그 밖의 종류	span

Flow 노드가 원격 검증 에이전트를 호출한다면 노드 호출의 타입은 agent입니다. 그 에이전트 안에서 수행한 규칙 판정은 evaluator, 정책 차단은 guardrail로 기록할 수 있습니다.

GraphBuilder().node(
    "verification-agent",
    verification_agent,
    node_kind="registry_node",  # LLaMON 실행 방식
    observation_type="agent",  # 원격 에이전트 호출
    observation_metadata={"stage": "verification"},  # 업무 단계
)

코드 위치	실행 시점	Langfuse 표시
Flow 스캐폴드의 app/graph.py	verification-agent 노드가 원격 에이전트를 호출할 때마다 자동 기록합니다.	호출 측에 Agent registry-node-verification-agent와 stage=verification이 표시됩니다. 같은 Langfuse 프로젝트에서 분산 추적을 쓰면 원격 에이전트의 내부 observation도 같은 trace로 이어집니다.

stage는 모든 observation의 필수값이 아닙니다. 같은 워크플로우에서 단계별 비교가 필요한 노드나 호출에만 일관되게 설정합니다. 프레임워크가 실제 LLM·tool 호출을 이미 generation이나 tool 하위 observation으로 기록했다면 상위 래퍼까지 같은 타입으로 중복 기록하지 마세요.

실제 작업별 타입 선택

실제 작업	권장 type	판단 기준과 metadata 예시
파일 수신·외부 API 호출	tool	경계 밖 시스템 호출. stage=intake
문서 파싱·정규화	span 또는 chain	단일 변환인지 여러 단계인지로 구분
사건·계약 기록 조회	retriever	읽기 전용 조회일 때만 사용
분류·요약 모델 호출	generation	실제 모델 호출의 하위 observation
규칙 적합성 판정	evaluator	품질이나 기준 충족 여부 평가
PII·보안 정책 검사	guardrail	차단·마스킹 같은 보호 정책
여러 단계를 고르는 에이전트 루프	agent	애플리케이션 흐름을 결정
위 작업을 묶는 파이프라인	chain	하위 observation을 포함하는 부모

배포 서비스의 역할은 루트 metadata.serviceRole, 현재 observation의 업무 단계는 로컬 metadata.stage, 기술 작업은 observation_type으로 나눕니다. 이 세 축을 섞지 않아야 배포가 달라도 같은 작업끼리 비교할 수 있습니다.

Orchestrator의 자식 호출

metadata=는 원격 A2A 요청에 실리는 값입니다. Langfuse 분류에만 쓸 값은 observation_metadata=에 두어 원격 페이로드와 섞이지 않게 합니다.

result = await ctx.call(
    "verification",
    text=ctx.user_text,
    metadata={"requestId": "case-123"},  # 원격 A2A 요청에 전달
    observation_type="agent",  # Langfuse 기술 유형
    observation_metadata={  # 해당 호출의 observation에만 기록
        "stage": "verification",
        "policyVariant": "contract-v3",
    },
)

코드 위치	실행 시점	Langfuse 표시
Orchestrator 스캐폴드의 app/orchestrator.py	run_turn()에서 ctx.call()로 자식 에이전트를 호출할 때 자동 기록합니다.	Agent orchestrator.call:verification의 metadata에 stage=verification, policyVariant=contract-v3가 표시됩니다. requestId는 원격 요청 metadata로만 전달됩니다.

부모가 끝난 하위 observation에 점수를 붙이려면 call_observed()로 observation 참조를 받습니다. 연결 방법은 Score 기록에 있습니다.

이 문서의 observe() 예제는 개발자가 evaluation observation을 만들고 score를 직접 기록하는 저수준 계측입니다. Runtime Evaluator를 연결하면 SDK가 evaluation:<evaluator-name> evaluator observation을 만들고, score는 평가받은 원래 대상에 연결합니다. 대상이 열려 있는 Flow 노드에서는 evaluation observation도 그 하위에 기록됩니다. 두 구조의 차이는 Runtime Evaluator의 기록 구조를 참고하세요.