코딩 에이전트 메타데이터 계약

코딩 에이전트 메타데이터 계약

코딩 에이전트가 런을 LangSmith로 보낼 때 방출해야 하는 트레이스 메타데이터를 표준화하는 스키마에요. 이 스키마는 코딩 에이전트가 LangSmith 런에 연결하는 메타데이터에 대한 권위 있는 계약입니다.

출처: 문서

본문

이 스키마는 코딩 에이전트가 LangSmith 런에 연결하는 메타데이터에 대한 권위 있는 계약입니다. 매 런마다 필수인 필드, 런타임이 제공할 수 있을 때 기대되는 필드, 특정 런 유형에만 적용되는 필드를 정의합니다.

코딩 에이전트 통합은 이 스키마를 사용해 트레이스가 일관되게 구조화되고, 쿼리 가능하며, LangSmith의 관측성 및 필터링 기능과 호환되도록 합니다.

지원되는 통합

이 스키마를 구현하는 통합은 다음과 같습니다:

통합 ls_integration 값
Claude Code claude-code
OpenAI Codex openai-codex
Deep Agents deepagents-code
Cursor cursor
Pi pi
Opencode opencode
GitHub Copilot copilot

전역 정체성 블록

모든 런 유형은 메타데이터에 다음 정체성 필드를 포함해야 합니다:

필드 설명
ls_agent_type 에이전트 내 런의 유형. "root", "subagent", "middleware", "compaction" 중 하나여야 합니다.
ls_agent_purpose 에이전트의 상위 목적. 예: "coding".
ls_integration 런을 방출하는 통합의 식별자 (지원되는 통합 참고).
ls_agent_runtime 사람이 읽을 수 있는 런타임 이름. 예: "Claude Code 1.0.28".
thread_id 대화 스레드의 안정적인 식별자. LangSmith의 Threads 뷰에서 관련 런을 그룹화하는 데 사용됩니다.
ls_trace_schema_version 현재 "coding-agent-v1".

가용성 등급

이 스키마의 필드는 세 가지 가용성 등급 중 하나로 표시됩니다:

등급 의미
always 매 런마다 있어야 합니다.
where_known 런타임이 값을 노출할 수 있을 때마다 필요합니다. 런타임이 정말로 정보를 제공할 수 없을 때만 생략합니다.
contextual 선택적 메타데이터. 해당하지 않으면 생략합니다.

런 유형

이 스키마는 다섯 가지 런 유형을 구분합니다. 일부 필드는 런 유형의 하위 집합에만 적용됩니다.

런 유형 설명
root 전체 에이전트 턴 또는 세션을 나타내는 최상위 런.
llm 턴 내의 언어 모델 호출.
tool 턴 내의 도구 호출.
subagent 중첩되거나 위임된 에이전트 런.
interrupted 완료 전에 중단된 런.

런 유형별 필수 필드

모든 런 유형

전역 정체성 블록 필드는 모든 런 유형에서 항상 필요합니다.

모든 런 유형에 필수인 추가 필드:

필드 등급 설명
ls_agent_version where_known 에이전트 런타임의 버전 문자열. 예: "1.0.28".
git_branch where_known 편집 중인 저장소의 활성 Git 브랜치.
git_commit_sha where_known 현재 Git 커밋의 전체 SHA.
git_repo_url where_known 저장소의 원격 URL.
working_directory where_known 작업 디렉터리의 절대 경로.

llm 런

필드 등급 설명
ls_model_name where_known 모델 식별자. 예: "claude-opus-4-5".
ls_provider where_known 모델 제공자. 예: "anthropic".

tool 런

필드 등급 설명
ls_tool_name always 호출된 도구의 이름. 예: "bash" 또는 "computer".

subagent 런

필드 등급 설명
ls_subagent_id always 서브에이전트의 안정적인 식별자.
ls_subagent_type always 서브에이전트의 유형 또는 역할. 예: "researcher".

interrupted 런

중단된 런은 root 런과 동일한 필드를 가집니다. 런 유형 자체가 비정상 종료 상태를 알리며, 추가 필수 필드는 추가되지 않습니다.

관련 문서

더 알아보기