스키마 23개, 각 33ms. LangChain이 메모이제이션으로 해결했다.

LangChain의 6월 패치 주기에는 버전 번호 속에 묻혀 있는 작은 이야기가 있습니다. 회수된 릴리스, 4분의 간격, 그리고 서로 맞지 않아 보이도록 의도적으로 설계된 두 패키지의 별개 마이너 트랙입니다.

1.3.5 회수: 무슨 일이 있었고 왜 그랬나

2026년 6월 18일, LangChain 팀은 두 개의 연계 패치 릴리스를 배포했습니다: langchain-core 1.4.8과 langchain 1.3.10입니다. PyPI는 각 라인의 최신 버전으로 두 패키지 모두를 표시합니다 . 이 릴리스들은 1.0 안정성 계약 하의 버그·성능 패치로, API 변경도 마이그레이션도 필요하지 않습니다. 업그레이드 위험은 낮지만, 그래도 의식적으로 진행할 가치가 있습니다.

GitHub 릴리스 피드에 따르면 langchain-core==1.4.8은 UTC 19:39에, langchain==1.3.10은 19:43에 배포되어 core가 약 4분 먼저 나왔습니다. 이 간격은 모노레포가 스택 전반의 릴리스를 순차적으로 처리하는 방식을 반영합니다 .

6월 10일 배포된 langchain 1.3.5는 이후 호환성 회귀 문제로 PyPI에서 회수됐습니다 . 실제로 회수가 어떤 의미인지 정리하면:

• 잠긴 환경은 계속 실행됩니다. 1.3.5에 고정된 기존 설치는 조용히 계속 작동하며, 저절로 깨지는 것은 없습니다.
• 새 설치는 기본적으로 거부됩니다. 단순히 pip install langchain을 실행하면 정확한 버전 문자열을 직접 요청하지 않는 한 회수된 버전을 건너뜁니다.
• 1.3.5에 고정된 분들은 1.3.10으로 재고정해야 합니다. 회귀 문제를 해소하기 위해서입니다.

사람들이 혼동하는 부분이 하나 있습니다. 두 패키지의 마이너 번호가 1.3과 1.4로 다른 것은 실수가 아니라 의도된 설계입니다. LangChain의 정책은 패치 릴리스를 버그 수정·보안 업데이트·API 변경 없는 성능 개선으로 분류하며, 모노레포는 langchain과 langchain-core를 서로 맞물린 트랙에서 버전 관리합니다 . 이 간격은 의도된 것입니다.

v3 이벤트의 비용 귀속 공백

langchain-core 1.4.8의 핵심 수정은 관측성입니다. v3 스트리밍 경로가 이제 stream_events와 astream_events의 사용량 메타데이터에서 input_token_details와 output_token_details를 보존합니다 . 패치 전에는 v2 이벤트와 astream 집계에서 두 필드가 올바르게 보존되었음에도, v3 이벤트에서는 두 필드가 조용히 삭제됐습니다 . 에이전트 스트리밍에 v3를 채택했다면 토큰 텔레메트리가 조용히 불완전한 상태였던 셈입니다.

이 필드가 중요한 이유는 제공자들이 캐시된 토큰을 계산하는 방식에 있습니다. Anthropic 등은 캐시 읽기를 최상위 input_tokens 수치에 합산하고, 캐시된 부분을 input_token_details 하위에 분리해 표시합니다 . 이 세부 정보가 삭제되면 신규 입력과 캐시 읽기 입력을 구분할 수 있는 유일한 신호를 잃게 됩니다. v3 이벤트를 사용한 캐시 프롬프트 워크로드에서는 비용 귀속이 잘못됐습니다. 반올림 오차 수준이 아니라, 프롬프트 중 캐시에서 제공된 비율만큼 오차가 발생했습니다.

같은 문제는 추론 토큰에도 영향을 미쳤습니다. output_token_details에는 추론 토큰 분류가 포함되어 있어, v3 이벤트 관측성과 함께 확장 사고를 사용하는 에이전트도 동일한 맹점을 안고 있었습니다 . 캐시 생성·캐시 읽기·추론 토큰 모두 불투명한 합계로 합쳐진 것입니다.

메인테이너들은 라이브 claude-sonnet-4-6 캐시 프롬프트 호출로 수정 사항을 검증하여, 세부 필드가 v3 경로 끝까지 살아남는 것을 확인했습니다 . 릴리스 노트에서 말하듯, 이 변경은 v3 이벤트가 버려오던 호출별 분류를 복원한 것으로, 트레이스에 표시되는 내용과 대응되는 한 줄 요약입니다.

업그레이드 전후에 할 실질적인 조치:

• 현재 빌드에서 캐시 프롬프트 실행에 대한 LangSmith 트레이스를 가져와 input_token_details가 채워져 있는지 확인하세요. v3에서 비어 있다면 비용 대시보드가 캐시 읽기를 과소 계산하고 있었던 것입니다.
• langchain-core 1.4.8로 이동한 후 동일한 트레이스를 비교하여 추정치가 얼마나 차이 났는지 파악하세요.
• v3 이벤트를 통해 노출된 추론 토큰 수를 기반으로 비용이나 예산 로직을 구동하는 확장 사고 에이전트가 있다면 기준점을 재조정하세요.

이 문제 동안 예외가 발생하지도, 경고가 나타나지도 않았습니다. 코드는 계속 실행됐고 숫자만 틀렸을 뿐입니다. version="v3" 지원을 추가한 1.3.x 라인에 따라 더 풍부한 스트리밍을 위해 v3로 전환한 팀이 가장 큰 영향을 받습니다 .

스키마 변환 23개, 건당 33ms → 이제 메모이제이션 적용

langchain-core 1.4.8의 두 번째 핵심 수정은 순수한 성능 최적화입니다. BaseTool.tool_call_schema가 이제 서브셋 모델을 메모이즈하고 model_json_schema 결과를 캐시합니다. 약 23개 툴에 대한 워밍업 변환 패스가 약 33ms에서 약 0.33ms로 줄어들었으며, 스키마 변환 경로에서 약 100배 개선된 수치입니다 .

이번 패치 이전에는 매 반복마다 동일한 스키마가 처음부터 재계산되었습니다. 대규모 툴셋에서 툴을 반복적으로 바인딩하거나 토큰을 집계하는 에이전틱 루프는 매 패스마다 이 변환 비용을 지불해야 했습니다. 이번 최적화가 겨냥하는 워크로드가 바로 그것입니다 . 에이전트가 스텝마다 20개 이상의 툴을 다시 바인딩한다면, 긴 실행에서 오버헤드가 누적됩니다.

툴 인스턴스에서 name, description, args_schema를 재할당하면 캐시 무효화가 정상적으로 발생하므로, 런타임에 재구성한 툴도 새로운 스키마를 받습니다. 툴을 프로세스 경계 너머로 전달하거나 에이전트 상태를 영속화하는 경우를 고려해 피클링 안전장치도 추가되어, 툴 인스턴스의 직렬화 가능성이 유지됩니다 .

업그레이드 전에 반드시 점검해야 할 주의 사항이 하나 있습니다. 반환된 서브셋 클래스나 model_json_schema가 생성한 딕셔너리를 직접 변경하는 방식은 명시적으로 지원하지 않습니다. 해당 객체들은 이제 공유되며, PR 리뷰 코멘트에서는 하위 코드가 이를 제자리에서 편집할 경우 캐시 오염 위험이 있다고 지적했습니다 . 다음 패턴이 있는지 확인하세요:

• tool.tool_call_schema를 읽은 뒤 반환된 클래스의 필드를 직접 수정하는 코드.
• model_json_schema()를 호출한 뒤 반환된 딕셔너리를 편집(설명 추가, 키 삭제 등)해 프로바이더에 전달하는 코드.
• 접근할 때마다 새로운 독립적인 객체가 반환된다고 가정하는 코드. 이 가정은 더 이상 유효하지 않습니다.

위 패턴 중 하나라도 해당된다면, 변경 전에 객체를 복사하거나 변환 로직을 캐시 호출 앞단으로 옮기세요. 그 외의 경우라면 이번 변경은 공짜 속도 향상입니다. API 변경도, 마이그레이션도 없이, 에이전트 스텝마다 몇 밀리초가 줄어듭니다.

langchain 레이어의 조용한 오작동

최상위 langchain 패키지는 코어 배포 4분 후 같은 날 1.3.10을 출시했으며, 사용자에게 영향을 주는 두 가지 수정은 같은 테마를 공유합니다. 오류 없이 실행되었지만 조용히 잘못된 동작을 했다는 점입니다 . 예외도 발생하지 않고, 경고도 나타나지 않았습니다. 트레이스를 직접 확인해야만 발견할 수 있었습니다.

첫 번째 수정은 SummarizationMiddleware에 해당합니다. _create_summary와 _acreate_summary가 이제 XML 포매팅으로 get_buffer_string을 호출하므로, URL 기반 멀티모달 블록이 원시 메시지 메타데이터를 덤프하는 대신 요약기 프롬프트에 온전히 전달됩니다 . 이미지, 오디오, 동영상 URL이 포함된 긴 대화를 에이전트가 요약하는 경우, 기존 동작은 참조된 콘텐츠 대신 직렬화된 메타데이터를 요약기에 전달하고 있었습니다. 요약기는 실제 텍스트가 아닌 깨진 메타데이터를 받고 있었던 것입니다.

두 번째 수정은 더 미묘하며 놓치기 쉽습니다. response_format을 사용한 create_agent가 gpt-5.2-2025-12-01, gpt-5.4-2026-03-05와 같이 날짜가 붙은 OpenAI 스냅샷에서 네이티브 구조화 출력 ProviderStrategy 대신 ToolStrategy로 폴백되고 있었는데, 감지 정규식이 YYYY-MM-DD 접미사를 거부했기 때문입니다 . 해당 PR은 -pro 변형은 계속 차단하면서 gpt-5.2와 gpt-5.4에 대한 선택적 날짜 그룹을 추가합니다 . 재현성을 위해 날짜 스냅샷을 고정하고 구조화 출력을 사용했다면, 내내 조용히 더 낮은 수준의 실행 경로로 라우팅되고 있었던 것입니다.

LangChain 팀이 릴리스 정책을 정의하는 방식에 따르면, "패치 릴리스는 API 변경 없이 버그 수정, 보안 업데이트, 문서 개선, 성능 최적화를 위한 것"입니다 (source: LangChain release policy, 2026). 이번 두 수정 모두 해당 기준을 충족합니다. 마이그레이션도, 시그니처 변경도 없이 올바른 동작이 복원되었습니다.

이번 릴리스에는 langchain_v1 락 영역의 의존성 업그레이드도 포함됩니다. 긴급 대응 여부를 판단하기 전에, 해당 패키지가 본인 스택의 직접 런타임 의존성인지 먼저 확인하세요:

• cryptography 46.0.7 → 48.0.1
• aiohttp 3.14.0 → 3.14.1
• PyJWT 2.12.0 → 2.13.0

이는 모노레포 락 유지 관리 수준으로, 보안 강제 사항이 아닙니다. cryptography가 메이저 버전 두 단계 올라간 점은 직접 의존하는 경우 확인할 가치가 있지만, 릴리스 노트만 보고 긴급하다고 판단하기보다는 본인의 의존성 트리를 직접 살펴보세요.

두 패키지를 고정하는 법 (그리고 스모크 테스트 항목)

두 패키지를 의도적으로 업그레이드하세요. pip install -U 'langchain==1.3.10' 'langchain-core==1.4.8'를 실행하거나 , uv/poetry/pip-tools 락을 재생성해 리졸버가 langchain-protocol을 >=0.0.17, langgraph를 >=1.2.5로 확정하는지 확인하세요 . 중요한 건 기억 속의 설치 명령어가 아니라 락파일입니다.

함정이 있습니다: langchain 1.3.10은 core의 하한선을 >=1.4.7,<2.0.0으로만 지정하며, 1.4.8을 명시하지는 않습니다 . 이미 langchain-core 1.4.7이 고정된 환경은 langchain 1.3.10의 요건을 충족하므로, 최상위 패키지만 올리면 core를 명시적으로 고정하거나 락을 재생성하지 않는 한 (토큰 상세 정보 및 스키마 캐시 수정이 없는) 1.4.7에 머물 수 있습니다.

Python 3.10은 이제 하드 하한선입니다: langchain-core 1.4.8이 구버전 호환성 심(shim)을 제거했습니다 . 아직 3.9를 사용 중인 런너는 이 업그레이드 전에 먼저 이전해야 합니다.

직렬화 헬퍼를 직접 호출한다면 한 가지 더 점검하세요: 1.4.8은 allowed_objects='core'와 같은 명시적 역직렬화 허용 목록으로 테스트를 전환했습니다 . 자체 코드에서 load/loads를 호출한다면 관대한 기본값에 의존하지 말고 해당 인수를 직접 전달해야 합니다.

이 패치가 실제로 영향을 주는 네 가지 경로로 회귀 테스트 범위를 좁히세요:

tool_call_schema가 반환하는 클래스나 model_json_schema가 반환하는 딕셔너리를 직접 변경하는 코드가 있다면 의도적으로 테스트하세요. 메모이제이션 PR은 공유 객체 변경을 비지원 동작으로 간주하며, 리뷰어들도 캐시 오염 가능성을 지적했습니다 .

2.0을 향한 전망: 1.0 계약이 유지되는 이유

이번 6월 수정 사항 중 어느 것도 기존 임포트를 깨뜨리지 않은 것은 1.0 안정성 계약 덕분입니다. LangChain은 2025년 말 LangGraph 1.0과 함께 첫 번째 안정 메이저 버전인 1.0을 출시하면서 2.0까지 호환성을 유지하겠다는 명시적 약속을 했습니다 . 최근의 빠른 릴리즈 속도(5월 11일 langchain-core 1.4.0, 5월 12일 langchain 1.3.0, 6월 18일 1.3.10/1.4.8 쌍)는 그 계약이 의도대로 작동하는 결과입니다: 공개 API를 유지한 채 실질적인 패치와 마이너 업데이트를 제공하는 것입니다 .

이 보장을 가능하게 하는 핵심 요인 중 하나는 의도적으로 줄인 API 표면입니다. 1.0에서 핵심 langchain 네임스페이스는 주요 추상화만 남기고 정리되었으며, 레거시 항목은 별도로 이동했습니다:

• 레거시 체인, 리트리버, 인덱싱, hub, 커뮤니티 재익스포트는 이제 langchain-classic에 있습니다 .
• 기존 Agent/AgentExecutor 구조는 더 이상 권장되지 않으며, LangChain 내에서 에이전트를 정의하고 미들웨어를 확장 개념으로 사용하는 방식이 권장됩니다 .

안정화된 API 표면이 좁을수록 패치로 인한 영향도 줄어듭니다. 1.3.0 이후 가장 중요한 두 가지 변경 사항이 비호환 수정으로 제공될 수 있었던 것도 이 때문입니다: 사용 메타데이터에 input_token_details/output_token_details를 복원하는 v3 stream_events 관측 가능성 복구, 그리고 약 23개 툴에 대한 웜 패스를 ~33 ms에서 ~0.33 ms로 단축한 tool_call_schema 메모이제이션입니다 . 둘 다 프로덕션 에이전틱 워크로드에 중요하며, 기존 API는 건드리지 않았습니다.

두 트랙 모두에서 매월 이루어지는 마이너 버전 업데이트를 기본 운영 기준으로 삼으세요. langchain과 langchain-core를 명시적으로 고정하고, 패치 세부 사항이 늦게 반영되는 공식 문서 변경 이력보다 GitHub 릴리즈 피드에서 다음 업데이트를 먼저 확인하세요.

자주 묻는 질문

두 패키지를 모두 업그레이드해야 하나요, 아니면 langchain만 1.3.10으로 올리면 충분한가요?

두 패키지를 명시적으로 고정하세요. langchain 1.3.10은 langchain-core의 하한을 >=1.4.8이 아닌 >=1.4.7로 지정합니다 . 따라서 langchain만 올리면 잠긴 환경이 core 1.4.7에 머물러, v3 토큰 상세 정보 및 스키마 메모이제이션 수정이 적용되지 않을 수 있습니다. pip install -U 'langchain==1.3.10' 'langchain-core==1.4.8'을 실행하거나, uv/poetry/pip-tools 잠금 파일을 재생성한 뒤 langchain-protocol이 >=0.0.17로, langgraph가 >=1.2.5로 해석되는지 확인하세요 .

코드에서 반환된 스키마 객체를 변경할 경우, tool_call_schema 메모이제이션이 안전한가요?

안전하지 않습니다. 성능 관련 PR에서는 반환된 서브셋 클래스나 model_json_schema의 딕셔너리를 변경하는 것이 지원되지 않는다고 명시했으며, 리뷰 댓글에서도 캐시 오염 가능성이 지적되었습니다 . 해당 최적화는 BaseTool.tool_call_schema의 서브셋 모델을 메모이제이션하고 JSON 스키마를 캐싱하며, name·description·args_schema 재할당 시에만 캐시를 무효화합니다. 조회 후 이 객체들을 수정하는 코드가 있다면, 업그레이드 전 반드시 감사(audit)하고 테스트하세요.

환경이 langchain 1.3.5에 고정되어 있는데, 즉시 문제가 생기나요?

즉각적인 오류는 없습니다. yanked 패키지는 이미 설치된 환경에서는 계속 실행되며, pip은 yanked된 후 langchain 1.3.5를 새로 설치하지 않을 뿐입니다 . 다만 yank를 유발한 호환성 회귀는 실제 문제이므로, 다음 번 새 배포나 잠금 파일 재생성 전에 1.3.10으로 다시 고정하세요. 그렇지 않으면 CI와 신규 빌드에서 의존성 해석에 실패합니다.

아직 v0.3을 사용 중인데 1.3.10으로 바로 건너뛰는 건 어떤가요?

이 패치들은 v1 라인에 올라야 적용됩니다. 먼저 v1 마이그레이션을 완료하세요. 축소된 langchain 네임스페이스로의 이전, 레거시 체인·리트리버·인덱싱·허브·커뮤니티 재익스포트를 위한 langchain-classic 설치, Python 3.10+로의 업그레이드, 메시지 content_blocks 업데이트가 모두 필요합니다. 이 모든 항목이 v1의 필수 브레이킹 체인지 작업입니다 . 해당 작업 없이 0.3에서 1.3.10으로 핀을 바꾸면 패치 수준의 수정이 아닌 임포트 오류 및 API 오류가 발생합니다.

cryptography와 PyJWT 버전 업은 별도로 우선 처리해야 할 보안 패치인가요?

경우에 따라 다릅니다. 의존성 그래프에 따라 달라집니다. 1.3.10 릴리스에는 langchain_v1 영역에서 cryptography 46.0.7→48.0.1, aiohttp 3.14.0→3.14.1, PyJWT 2.12.0→2.13.0이 포함되어 있는데, 이는 선언된 프로덕션 런타임 의존성이라기보다 모노레포 잠금 및 의존성 유지보수 성격으로 보입니다 . 각 패키지가 여러분 스택의 직접 런타임 의존성인지에 따라 보안 중요도가 달라지므로, 업그레이드가 긴급하다고 단정 짓지 말고 직접 의존성 트리를 확인하세요.