당신의 코딩 에이전트(coding agent)는 데모에서는 통과할 수 있지만, 프로덕션 환경에서는 디버깅이 불가능할 수도 있습니다.

실행 과정에서 잘못된 파일을 수정하거나, 재시도 루프(retry loop)를 과도하게 소모하거나, 자식 에이전트 스팬(child-agent span)을 조용히 놓치는 경우, 유용한 질문은 단지 "모델이 무엇이라고 답했는가?"가 아닙니다. 그것은 바로 "전체 워크플로(workflow) 전반에 걸쳐 어떤 일이 일어났는가?"입니다.

이 비교는 세 가지 인기 있는 Python 스택의 관측성(observability) 경로를 살펴봅:

• OpenAI Agents SDK
• LangSmith를 사용하는 LangChain 에이전트
• Google Agent Development Kit (ADK)

실질적인 핵심: 저장소(repository) 콘텐츠를 유출하거나 모든 서비스를 하나의 텔레메트리(telemetry) 목적지로 고정하지 않으면서, 실패한 코딩 작업에 대해 팀에 적절한 증거를 제공하는 스택을 선택하십시오.

범위 및 평가 기준

이것은 2026년 7월 21일에 확인된 공식 문서 비교입니다. 저는 공유 벤치마크를 실행하거나, 내보내기 지연 시간(export latency)을 측정하거나, 대시보드 점수를 매기지 않았습니다. "최적의 적합성" 가이드는 보편적인 순위가 아닌 엔지니어링적 판단으로 간주하십시오.

저는 다섯 가지를 비교했습니다:

1. 기본 캡처 (Default capture): 커스텀 스팬(custom spans) 없이 에이전트 실행 한 번이 무엇을 기록하는가?
2. 제어 및 내보내기 (Control and export): 텔레메트리를 비활성화, 확장, 교체 또는 팬아웃(fan out)할 수 있는가?
3. 코딩 에이전트 유용성 (Coding-agent usefulness): 트레이스(trace)가 모델의 턴(turns), 도구 호출(tool calls), 핸드오프(handoffs) 및 실패를 설명할 수 있는가?
4. 개인정보 보호 제어 (Privacy controls): 프롬프트, 출력 또는 메시지 콘텐츠를 제외하는 경로가 얼마나 명시적인가?
5. 평가 루프 (Evaluation loop): 트레이스가 얼마나 자연스럽게 데이터셋, 피드백 또는 회귀 테스트(regression checks)가 될 수 있는가?

한눈에 보기

1. OpenAI Agents SDK: 워크플로 트레이스로 가는 가장 빠른 경로

이 SDK는 기본적으로 전체 Runner.run()을 트레이싱합니다. 문서화된 계층 구조에는 태스크(task) 및 턴(turn) 스팬, 에이전트(agent) 스팬, 모델 생성(model generations), 함수 도구(function tools), 가드레일(guardrails), 핸드오프(handoffs) 및 커스텀 스팬(custom spans)이 포함됩니다. 이는 최종 텍스트보다는 단계 사이의 전환에서 실패가 발생할 수 있는 코딩 에이전트(coding agent)에 매우 적합합니다.

따라서 최소한의 실행만으로 다음과 같은 질문에 답할 수 있습니다:

• 에이전트가 편집하기 전에 리포지토리 검색 도구를 호출했는가?
• 어떤 모델 턴(model turn)이 위험한 도구 인자(tool arguments)를 생성했는가?
• 핸드오프(handoff)가 태스크를 리뷰어 에이전트(reviewer agent)에게 전달했는가?
• 가드레일(guardrail)이 실행되었는가, 그리고 트레이스 내 어디에 위치했는가?

또한 이 SDK는 유용한 제어 경계(control boundary)를 제공합니다. 커스텀 트레이스 프로세서(custom trace processor)를 추가하여 다른 곳으로 두 번째 복사본을 보내거나, 기본 프로세서를 완전히 교체할 수 있습니다. 장시간 실행되는 워커(workers)의 경우, 문서에서는 작업 단위 이후 즉각적인 전달 보장이 필요할 때 flush_traces()를 사용할 것을 권장합니다.

개인정보 보호와 관련된 실수(footgun) 또한 명확합니다. 생성(generation) 및 함수 스팬(function spans)에는 민감한 데이터가 포함될 수 있으며, trace_include_sensitive_data는 기본값이 true입니다. 코딩 에이전트 팀은 비밀 정보(secrets)나 고객 데이터가 포함된 리포지토리에서 이 기능을 활성화하기 전에 프롬프트(prompts), 디프(diffs), 파일 내용 및 도구 인자가 트레이스에 포함되어도 되는지 결정해야 합니다.

다음과 같은 경우 이 경로를 선택하세요: 이미 OpenAI Agents SDK를 사용 중이고, 적은 양의 계측(instrumentation) 코드로 풍부한 워크플로 구조를 원하며, OpenAI Traces를 수용하거나 커스텀 프로세서(custom processor)를 설치할 준비가 된 경우입니다.

2. LangChain + LangSmith: 가장 완전한 트레이스-평가(trace-to-evaluation) 워크플로

LangChain의 현재 에이전트 문서에 따르면, create_agent로 구축된 에이전트는 LangSmith 트레이싱(tracing)을 자동으로 지원합니다. 이를 활성화하는 것은 주로 설정의 문제입니다. LANGSMITH_TRACING=true로 설정하고 API 키를 제공하면 됩니다. 결과물로 생성되는 트레이스(traces)는 도구(tools), 모델 상호작용, 결정 지점(decision points)을 포함하여 입력에서 출력까지의 경로를 포괄합니다. 호출(invocation)마다 태그(tags)와 메타데이터(metadata)를 부착할 수 있으며, 이는 저장소(repository), 브랜치(branch), 모델 경로(model route) 또는 작업 유형(task type)과 같은 코딩 에이전트의 세분화된 데이터(slices)를 다룰 때 특히 유용합니다.

차별점은 단순히 "트레이스가 있다"는 점만이 아닙니다. LangSmith의 관측성(observability) 문서는 트레이스를 디버깅(debugging), 평가(evaluation), 모니터링(monitoring), 피드백(feedback) 및 데이터셋(datasets)과 연결합니다. 이는 다음과 같은 질문을 던지는 팀에게 자연스러운 선택지가 됩니다.

• 여러 저장소에 걸쳐 반복적으로 나타나는 도구 오류(tool-error) 패턴은 무엇인가?
• 프롬프트(prompt)나 모델의 변경이 패치 시도 실패를 증가시켰는가?
• 프로덕션 트레이스(production traces)를 다음 하네스(harness) 변경 전 회귀 테스트 세트(regression set)의 시드로 사용할 수 있는가?

또한 벤더 중립적인(vendor-neutral) 경로도 제공합니다. LangSmith는 LangChain 및 비(non)-LangChain 애플리케이션을 위한 OpenTelemetry 트레이싱을 문서화하고 있으며, 여기에는 여러 목적지로의 콜렉터 팬아웃(collector fan-out)이 포함됩니다. 이는 코딩 에이전트가 API 서비스, 샌드박스 워커(sandbox worker), 그리고 별도의 테스트 러너(test runner)에 걸쳐 있는 경우 유용합니다.

테스트해 볼 가치가 있는 미묘한 분산 트레이싱(distributed-tracing) 제한 사항이 있습니다. 문서에 따르면 부모(parent)가 LangSmith로 전송되지 않은 스팬(span)은 누락됩니다. 콜렉터(collector)로부터 성공적인 OTLP 응답을 받았다고 해서 전체 트레이스가 하나의 연결된 실행으로 나타난다는 보장은 없습니다. 필요한 조상(ancestors) 스팬을 내보내거나(export), 자체 점검 시 손실 모드(loss mode)를 가시화하십시오.

다음과 같은 경우 이 경로를 선택하세요: 트레이스 검색, 메타데이터, 인간 피드백(human feedback), 평가 및 프로덕션 모니터링이 동일한 개선 루프의 일부이거나, OpenTelemetry 팬아웃(fan-out)이 필요한 경우입니다.

3. Google ADK: 프레임워크 기능으로서의 텔레메트리 (telemetry), 선택 가능한 백엔드

Google ADK의 관측성 (Observability) 문서는 로깅 (logging), 메트릭 (metrics), 트레이스 (traces)를 사후 고려 사항이 아닌 내장된 기능으로 취급합니다. 제공되는 예제들은 트레이스를 위한 OpenTelemetry와 상세 출력을 위한 로깅 플러그인을 보여줍니다. 또한 문서는 복잡한 에이전트의 경우 기본적인 입출력 모니터링만으로는 불충분하다고 경고합니다. 디버깅을 위해서는 텔레메트리 (telemetry)에 표현되는 추론 트레이스 (reasoning traces), 도구 호출 (tool calls) 및 기타 내부 활동에 대한 가시성이 필요하기 때문입니다.

이 모델은 오케스트레이션 그래프 (orchestration graph)가 중요한 멀티 에이전트 코딩 워크플로우에 적합합니다. 예를 들어, 플래너 (planner)가 코드 검색 에이전트 (code-search agent)에게 작업을 위임하면, 해당 에이전트가 도구를 호출하고, 이것이 다시 테스트 러너 (test runner)를 트리거하는 구조입니다. 이때 사용자는 단순히 최종 응답을 검사하는 것에 그치지 않고, 이러한 이벤트들을 서비스 수준의 메트릭 (service-level metrics)과 상관관계 분석 (correlate)하고자 합니다.

ADK는 백엔드 선택권을 사용자에게 더 많이 부여합니다. 공식 퀵 스타트 (quick start)에서는 OTLP 익스포터 (exporter)를 구성하며, 문서는 추가적인 모니터링 및 분석을 위한 관측성 통합 (observability integrations)을 안내합니다. 이는 이미 OpenTelemetry Collector를 운영 중인 팀에게는 장점이 될 수 있지만, 동시에 설정 작업이 수반됨을 의미합니다. 사용자는 익스포터 (exporter), 백엔드 (backend), 보관 정책 (retention policy), 그리고 콘텐츠 캡처 정책 (content-capture policy)을 직접 선택해야 합니다.

개인정보 보호 제어는 문서의 Kotlin 예제에 명시적으로 나타나 있습니다. 전체 메시지 콘텐츠를 캡처하는 것은 설정 가능하며, 프로덕션 (production) 환경에서는 주의해서 사용해야 합니다. 동일한 운영 규칙이 어떤 언어로 작성된 코딩 에이전트에도 적용됩니다. 즉, 전체 프롬프트 (prompts), 디프 (diffs), 또는 도구 페이로드 (tool payloads)를 저장하는 것보다 리포지토리 ID (repository ID), 작업 ID (task ID), 모델 이름 (model name), 종료 상태 (exit status)와 같은 구조화된 메타데이터 (structured metadata)를 사용하는 것이 대개 더 안전합니다.

이 경로를 선택해야 하는 경우: 프레임워크 수준의 로깅 (logging), 메트릭 (metrics), 트레이스 (traces)를 원하고, 멀티 에이전트 워크플로우를 실행하며, 이미 OpenTelemetry 중심의 플랫폼 팀을 보유하고 있는 경우.

실무적인 코딩 에이전트 트레이스 계약 (trace contract)

어떤 프레임워크를 선택하든, 가능한 모든 페이로드 (payload)를 텔레메트리에 추가하기 전에 작은 계약 (contract)을 정의하십시오.

task_id: task_2026_07_21_0042
repo: payments-api
base_revision: abc123
...

보안 정책이 허용하는 범위 내에서만 전체 diff, 명령 출력(command output), 그리고 프롬프트(prompt)를 저장하세요. 콘텐츠 캡처(content capture)가 비활성화된 경우에도 트레이스(trace)가 유용하게 유지되도록 해야 합니다. 작업 ID(task ID)와 안정적인 에러 클래스(error class)만으로도 편집된(redacted) 트레이스를 내부 아티팩트 저장소(artifact store)와 연결하기에 충분한 경우가 많습니다.

이는 회귀 전략(regression strategy)을 대체하는 것이 아니라 보완하는 것입니다. 트레이스는 무엇이 일어났는지를 보여주며, 평가(evaluation) 또는 리플레이(replay) 체크는 그 동작이 수용 가능한지 여부를 결정합니다. 구체적인 워크플로우는 Stop Replaying Coding-Agent Bugs by Hand: Turn Traces Into Regression Tests를 참조하세요.

결정 체크리스트 (Decision checklist)

다음의 경우 OpenAI Agents SDK를 선택하세요:

• 즉각적이고 상세한 에이전트 네이티브 스팬(agent-native spans)을 원하는 경우.
• 팀이 OpenAI의 트레이싱 대상(tracing destination) 또는 커스텀 프로세서(custom processors)를 사용하는 데 익숙한 경우.
• 에이전트의 주요 복잡성이 핸드오프(handoffs), 가드레일(guardrails), 그리고 도구 실행(tool execution)에 있는 경우.

다음의 경우 LangChain + LangSmith를 선택하세요:

• 피드백, 데이터셋(datasets), 평가(evaluations), 그리고 모니터링(monitoring)과 연결된 트레이스가 필요한 경우.
• 코딩 작업을 세분화하기 위한 태그(tags)와 메타데이터(metadata)가 필요한 경우.
• 문서화된 OpenTelemetry 내보내기(export) 또는 다중 대상 팬아웃(multi-destination fan-out)이 필요한 경우.

다음의 경우 Google ADK를 선택하세요:

• ADK 워크플로우의 일부로 로깅(logging), 메트릭(metrics), 트레이스(traces)를 원하는 경우.
• 멀티 에이전트 시스템(multi-agent system)을 운영 중이며 이미 OTLP 백엔드(backend) 또는 콜렉터(collector)를 보유하고 있는 경우.
• 설정이 필요 없는 호스팅 대시보드(hosted dashboard)보다 백엔드 이식성(portability)이 더 중요한 경우.

에이전트가 부수 효과(side effects)를 일으킨다면, 관측성(observability)을 명시적인 에러 분류(error classification) 및 재시도 정책(retry policy)과 결합하세요. 트레이스는 도구가 실패했음을 드러낼 수 있지만, 비멱등적(non-idempotent) 쓰기 작업을 조용히 재시도로 전환해서는 안 됩니다. Tool Errors Are Not Retries에서 이 경계에 대해 다룹니다.

지금 해야 할 일 (What to do now)

1. 대표적인 코딩 작업 하나를 선정하세요: 실패한 테스트와 작은 패치(patch) 정도면 충분합니다.
2. 먼저 콘텐츠 캡처(content capture)를 비활성화한 상태로 실행하세요.
3. 트레이스(trace)가 에이전트(agent), 모델(model), 도구(tool), 핸드오프(handoff), 소요 시간(duration), 상태(status), 그리고 작업 ID(task ID)를 여전히 기록하는지 확인하세요.
4. 팀이 실제로 운영 중인 백엔드로 트레이스 하나를 내보내기(export) 하세요.
5. 의도적으로 도구(tool)를 실패하게 만들고, 비밀 정보(secrets)를 노출하지 않으면서 실패가 가시적으로 확인되는지 확인하세요.
6. 예상되는 결과(expected outcome)를 명시할 수 있게 된 후에만 해당 트레이스를 회귀 테스트 케이스(regression case)로 격상시키세요.

솔직한 한계점 (Candid limitations)

이것은 문서에 기반한 비교이며, 공통 벤치마크가 아닙니다. 저는 대시보드 쿼리 속도, 내보내기 오버헤드(export overhead), 보관 기간(retention), 가격, 또는 프로세스 충돌 시의 트레이스 완전성(trace completeness)을 측정하지 않았습니다. 프레임워크 버전과 통합(integration) 방식은 빠르게 변합니다. 또한 OpenTelemetry 호환성이 모든 백엔드에서 동일한 의미론(semantics)을 보장하지는 않습니다. 스팬 이름(span names), 속성(attributes), 샘플링(sampling), 그리고 레드액션(redaction, 정보 마스킹) 동작은 여전히 소규모 통합 테스트가 필요합니다.

적절한 관측성(observability) 스택이란, 실행 실패 시 팀이 실제로 조사할 수 있고, 데이터 보관 및 보안 제약 조건 내에서 운영 가능한 스택입니다.

출처 (Sources)

• OpenAI Agents SDK tracing
• LangChain observability
• LangSmith OpenTelemetry tracing
• Google ADK observability
• OpenTelemetry GenAI semantic conventions

코딩 에이전트 트레이스에서 절대 생략해서는 안 될 첫 번째 필드나 이벤트는 무엇이며, 그 이유는 무엇인가요?