Skip to main content
이 문서는 공식 OpenTelemetry GenAI Semantic Conventions에 Agent Lens 전용 규칙과 권장 사항을 더해 확장합니다. 업스트림에서 MAY 또는 SHOULD로 규정한 항목도 이 프로필에서는 대부분 MUST로 규정합니다(RFC 2119 기준). 이 문서에서 별도로 명시하지 않은 사항에는 공식 의미 규칙이 적용됩니다.

API

OTLP protobuf를 POST /agents/otel/v1/traces로 전송하세요. 인증 및 프로젝트 라우팅은 Agent Lens로 OpenTelemetry 스팬 전송하기를 참조하세요.

체크리스트

Agent Lens가 OTel span을 올바르게 수집하도록 하려면 span이 다음 규칙을 준수하는지 확인하세요.

Agent Lens 데이터 모델 매핑

다음 속성은 Agent Lens가 저장하고 노출합니다. 이 목록에 모든 속성이 포함된 것은 아니며, 실제 폴백 로직은 여기에 설명된 것보다 더 복잡할 수 있습니다. 레거시 속성 및 사용 중단된 속성(OpenInference 포함)은 best-effort 방식으로 지원됩니다.

특수 GenAI 오퍼레이션 이름

모든 span은 반드시 gen_ai.operation.name을 설정해야 합니다. 이 값으로는 공식 OTel 의미 규칙에 정의된 잘 알려진 이름을 사용하는 것이 좋습니다. 다음 오퍼레이션 이름은 Agent Lens에서 특별하게 처리됩니다. 이 오퍼레이션들은 대부분의 에이전트형 워크플로를 기술하는 데 필요한 최소한의 오퍼레이션입니다.

사용자 지정 속성

Agent Lens는 벤더별 속성 이름과 사용자 정의 속성 이름을 허용하며, 이를 사용자 지정 속성으로 사용할 수 있도록 제공합니다. 예를 들면 my_company.user.is_admin=true, my_company.user.sentiment="positive", my_company.eval.score=0.5와 같습니다.
  • 사용자 지정 속성 값은 반드시(MUST) 정수, 부동소수점, 문자열 또는 불리언 값이어야 합니다.
  • 사용자 지정 속성 이름은 반드시(MUST) 카디널리티가 낮아야 하며, 동적으로 생성해서는 안 됩니다(MUST NOT).
  • 사용자 지정 속성 이름에는 my_company.*와 같이 일관된 namespace를 사용해야 합니다(SHOULD).

OTel 스팬 및 속성

이 섹션은 공식 OTel 의미 규칙의 에이전트 span 및 추론 스팬의 구조를 따르되, 이 프로필이 공식 규칙과 다른 부분만 나열합니다. span 이름, span 종류, 여기에 나열되지 않은 스팬을 비롯한 나머지 항목은 모두 공식 가이드라인을 따릅니다.

Invoke workflow span

Agent Lens에서 루트 span은 반드시 invoke_workflow 또는 invoke_agent 중 하나여야 합니다. 사용자가 여러 에이전트를 한 번에 호출할 수 있는 복잡한 경우에는 invoke_workflow를 사용하세요. 그 외의 경우에는 invoke_agent를 사용하는 것이 좋습니다.

에이전트 호출 span

Agent Lens에서 루트 span은 반드시(MUST) invoke_workflow 또는 invoke_agent 중 하나여야 합니다. 사용자가 여러 에이전트를 한 번에 호출할 수 있는 복잡한 경우에는 invoke_workflow를 사용하세요. 그 밖의 경우에는 invoke_agent를 사용하는 것이 좋습니다.

추론 span

Agent Lens는 추론 span을 사용하여 대화의 메시지 이력을 구축하고 비용을 추정합니다. 추론 span에는 도구 Call 요청과 응답도 담깁니다. 모델이 도구 Call을 통해 최종 응답을 보내는 경우, 해당 도구 이름은 반드시 final_answer, final_result, set_model_response, send_message 중 하나여야 합니다.

토큰 사용량 및 비용

Agent Lens는 각 추론 span의 토큰 사용량과 gen_ai.response.model을 기반으로 비용을 추정합니다.
  • gen_ai.usage.input_tokens는 캐시된 토큰을 포함한 전체 입력이어야 합니다(MUST). 캐시 읽기 및 쓰기는 gen_ai.usage.cache_read.input_tokens와 gen_ai.usage.cache_write.input_tokens에도 기록해야 합니다(SHOULD). Agent Lens는 이 값을 전체에서 뺀 다음 각각의 단가를 적용해 비용을 계산합니다. gen_ai.usage.input_tokens에 캐시되지 않은 토큰만 집계되면 입력이 실제보다 적게 집계되어 비용이 음수로 표시될 수 있습니다.
  • gen_ai.usage.output_tokens는 추론 토큰을 포함한 전체 출력이어야 합니다(MUST).
  • 일부 공급자는 이러한 수치를 따로 보고하므로, 이를 합계에 다시 더하세요. Anthropic은 캐시된 토큰을 입력 토큰과 따로 보고하고, Gemini는 thinking 토큰을 출력 토큰과 따로 보고합니다. OpenAI는 캐시된 토큰을 입력 수치에, 추론 토큰을 출력 수치에 이미 포함합니다.
  • gen_ai.response.model은 공급자가 반환한 정확한 모델 ID여야 합니다(MUST). opus나 sonnet 같은 별칭에는 가격 정보가 없으므로 해당 Call에 Cost -가 표시됩니다.
  • 사용량 속성은 추론 span에만 설정해야 합니다(SHOULD). 턴의 합계를 해당 턴의 invoke_agent span에 복사하지 마세요.

도구 실행 span

도구 Call은 모델이 애플리케이션에 함수 실행을 요청할 때 발생합니다. 하나의 도구 Call은 세 개의 스팬에 걸쳐 나타나며, Agent Lens가 이들을 연결할 수 있도록 계측 코드는 각 스팬에 동일한 gen_ai.tool.call.id를 기록해야 합니다.
  1. 모델이 호출을 요청하는 추론 span입니다. gen_ai.output.messages에 tool_call 구성 요소로 기록됩니다.
  2. 함수 실행을 나타내는 execute_tool span입니다.
  3. 결과를 모델에 반환하는 다음 추론 span입니다. gen_ai.input.messages에 tool_call_response 구성 요소로 기록됩니다.
요청, 실행, 응답 구성 요소는 모두 동일한 gen_ai.tool.call.id로 연결되어야 하며(MUST), 이 ID는 트레이스 내에서 고유해야 합니다(MUST).

예시

에이전트가 도구를 사용해 질문에 답변하는 예

에이전트가 하위 에이전트를 도구로 호출하는 경우

워크플로에서 두 에이전트를 병렬로 실행

에이전트가 이미지를 생성하는 경우

실패하는 도구 Call

마지막 수정일 2026년 11월 18일