실제 SDK 검증 없이 배포된 LLM agent debugger의 테스트 결함

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

게시자는 LLM agent용 local-first debugger인 agent-lens에서 실제 OpenAI SDK와 가짜 SDK의 API가 어긋나면서 4개월 동안 오류가 배포된 사례를 기록했습니다. 코드는 Completions.acreate를 패치했지만 OpenAI SDK 1.0.0, 1.30, 2.0, 3.7에서는 비동기 클라이언트가 별도 AsyncCompletions 클래스이고 acreate 속성도 존재하지 않았습니다. 비동기 경로 테스트 네 개가 모두 통과한 이유는 실제 vendor가 아니라 코드가 호출하는 형태에 맞춘 fake SDK를 사용했기 때문이며, capture layer 커버리지는 85–93%였지만 문제를 막지 못했습니다. 게시자는 실제 설치 SDK의 속성과 패치 대상 hook을 확인하는 테스트와 vendor SDK를 설치해 실행하는 CI job을 추가했고, respx가 OpenAI SDK 3.7·httpx 0.28.1 조합의 요청을 가로채지 못해 실서비스로 나가던 e2e 테스트도 발견했습니다. 이 사례는 mock이 의존성의 증거가 될 수 없고, 의존성 미설치 시 자동 skip되는 테스트는 의도적으로 관리하지 않으면 결함을 숨긴다는 점을 보여줍니다.

실용적 조언

가짜 SDK의 메서드와 속성을 구현 코드가 아니라 실제 설치된 vendor SDK에서 조회하는 계약 테스트를 추가하십시오.
OpenAI SDK, httpx, respx처럼 함께 동작하는 의존성 조합을 CI에 설치하고, mocked HTTP 테스트에서 외부 네트워크 호출이 발생하면 실패하도록 구성하십시오.
의존성 미설치에 따른 테스트 skip을 기본 동작으로 두지 말고, 필수 의존성은 dev extra와 CI 설정에 명시해 의도적인 skip과 환경 누락을 구분하십시오.
상속 기반 handler는 override한 hook 이름이 vendor base class에 실제로 존재하는지 확인해, 조용히 실행되지 않는 경로를 방지하십시오.

섹션별 상세

게시자가 유지하는 local-first LLM agent debugger의 문서상 진입점 agent_lens.install()은 OpenAI SDK가 설치된 환경에서 AttributeError를 일으켰습니다. 코드는 Completions.acreate를 패치했지만 게시자가 확인한 OpenAI SDK 1.0.0, 1.30, 2.0, 3.7에서는 비동기 클라이언트가 별도 AsyncCompletions 클래스였고 해당 속성은 어느 버전에도 없었습니다. import 경로 역시 1.x 전용이어서, 코드가 실제로 가져올 수 있는 버전과 패치하려는 API가 처음부터 맞지 않았습니다.

capture layer의 커버리지는 85–93%였고 비동기 경로를 겨냥한 테스트 네 개도 모두 통과했습니다. 그러나 테스트가 실제 OpenAI SDK가 아니라 코드가 호출하는 형태에 맞춰 만든 fake SDK를 사용했기 때문에, 대역에 acreate를 넣는 순간 잘못된 구현도 정상 동작처럼 확인됐습니다. 게시자는 문제의 원인을 커버리지 부족이 아니라 의존성의 실제 API 계약을 테스트하지 않은 구조로 판단하고, 패치 대상 속성이 설치된 SDK에 존재하는지 반대 방향에서 확인하는 테스트를 추가했습니다.

게시자는 LangChain과 LlamaIndex handler에도 같은 검사를 확장했습니다. 두 handler는 vendor base class를 상속하고 hook을 override하므로, hook 이름이 바뀌면 오류 없이 아무 동작도 하지 않을 수 있지만 이번 검사에서는 문제가 발견되지 않았습니다. 이어 실제 vendor를 설치해 테스트하는 CI job을 만들고, OpenAI SDK가 없을 때 dev extra 때문에 e2e suite가 자동 skip되던 조건도 수정 대상으로 삼았습니다.

release gate에서는 'mocked HTTP'로 문서화된 e2e suite가 실제로 api.openai.com에 요청을 보내는 별도 결함이 드러났습니다. OpenAI SDK 3.7, httpx 0.28.1, respx 0.23.1 조합에서 respx route가 매칭되지 않아 클라이언트 요청이 가로채지지 않았고, SDK가 설치되지 않은 환경에서는 suite 자체가 skip되어 문제가 늦게 드러났습니다. 따라서 HTTP mock의 동작 여부를 실제 클라이언트 조합에서 확인하고, 필요한 의존성을 CI에 명시적으로 설치해야 외부 네트워크 호출을 막을 수 있습니다.

이미지 분석

Screenshot
이미지는 게시자가 유지하는 agent-lens 저장소의 정체성과 기본 기능을 보강합니다. 본문에서 말한 local-first debugger가 실행 중인 agent를 멈추고 검사하거나 분기하는 도구라는 점을 저장소 소개 문구와 연결할 수 있습니다.
agent-lens GitHub 저장소 화면으로, LLM agent용 interactive debugger라는 설명과 pause·inspect·fork 기능이 표시되어 있습니다.

용어 해설

테스트 대역(Test Double): — 실제 외부 의존성 대신 테스트에서 사용하는 가짜 객체나 SDK 구현입니다. 코드가 호출하는 메서드와 속성만 흉내 내므로, 실제 vendor SDK에 해당 API가 존재하는지는 검증하지 못합니다. 구현과 대역의 계약이 어긋나면 높은 테스트 커버리지에서도 오류가 통과합니다.
계약 테스트(Contract Test): — 애플리케이션과 외부 의존성이 공유하는 API 계약을 실제 의존성에 대조하는 테스트입니다. 패치 대상 속성이나 상속된 hook이 설치된 SDK에 실제로 존재하는지 확인해, 가짜 객체가 숨기는 호환성 오류를 잡습니다. SDK 버전 변경에도 유용합니다.
respx: — httpx 요청을 가로채 모의 HTTP 응답을 반환하는 테스트 도구입니다. 이 글에서는 OpenAI SDK 3.7, httpx 0.28.1, respx 0.23.1 조합에서 route가 매칭되지 않아 api.openai.com으로 실제 요청이 나간 사례와 연결됩니다.
AsyncCompletions: — OpenAI SDK에서 비동기 completions 기능을 담당하는 별도 클래스입니다. 글의 오류 코드는 이 클래스와 분리된 Completions에 존재하지 않는 acreate 속성을 패치하려 했고, 버전 1.0.0, 1.30, 2.0, 3.7 모두에서 같은 구조가 확인됐습니다.

코드 예제

python

agent_lens.install()

문서에 적힌 agent-lens 설치 진입점으로, OpenAI SDK가 설치된 환경에서 AttributeError를 일으켰습니다.

python

Completions.acreate

실제 SDK에 존재하지 않는 비동기 메서드를 패치 대상으로 사용한 코드 경로입니다.

bash

pip install agentlens-tracer

게시자가 공유한 패키지 설치 명령입니다.

언급된 도구

agent-lens중립링크

LLM agent를 실행 중 일시 정지하고 검사하거나 분기하는 local-first debugger입니다.

OpenAI SDK중립

게시자의 debugger가 Completions.acreate를 패치하려 했던 외부 SDK입니다.

LangChain중립

vendor base class를 상속하는 handler의 연동 대상입니다.

LlamaIndex중립

vendor base class를 상속하는 handler의 연동 대상입니다.

respx비추천

HTTP mock 테스트에서 클라이언트 요청을 가로채는 도구입니다.

언급된 리소스

GitHubRAJUSHANIGARAPU/agent-lens