langchain-perplexity 1.3.1: 라우팅 로직, SSE 수정 사항 해설

2026년 5월 27일, LangChain 팀은 같은 날 하루 안에 langchain-perplexity를 두 차례 릴리스했습니다 — UTC 00:22에 1.3.0을 출시해 Responses API 라우팅을 도입했고, UTC 20:45에 1.3.1을 출시해 Perplexity가 몇 시간 뒤 업스트림 SDK를 패치한 후 임시 스트리밍 심(shim)을 제거했습니다. AI 툴링 릴리스를 주시하고 있다면 이번 업데이트는 주목할 만합니다. 하루 만에 Perplexity의 Agent API를 LangChain 사용자에게 개방하고, 프로덕션 스트리밍 엣지 케이스까지 해결했기 때문입니다.

1.3.0에서 1.3.1로: 기능 출시와 업스트림 수정

langchain-perplexity 1.3.0은 2026년 5월 27일 UTC 00:22에 PR #37359를 통해 배포되었습니다 . 핵심 변경 사항은 use_responses_api였습니다 — ChatPerplexity에 추가된 새로운 불리언 값으로, 요청을 Chat Completions 대신 Perplexity의 Agent API로 라우팅합니다. 같은 날 UTC 20:45에는 PR #37710이 머지되고 1.3.1 태그가 붙었습니다 — perplexityai 최소 버전이 >=0.34.1로 상향되고, 1.3.0에 포함되었던 임시 SSE 심이 제거되었습니다 .

한눈에 요약: langchain-perplexity 1.3.1(2026년 5월 27일)은 LangChain에서 Perplexity Agent API를 사용하기 위한 안정적인 기준 버전입니다. use_responses_api 라우팅을 추가하고, perplexityai 0.34.1에서 패치된 프로덕션 스트리밍 심을 제거했으며, CI 검사 28개를 모두 통과했습니다. 1.3.0은 과도기 버전으로 취급하세요.

당일 패치의 계기는 5월 27일 두 LangChain 릴리스 사이에 Perplexity 팀이 배포한 perplexityai 0.34.1이었습니다 . 이 버전은 1.3.0이 심으로 우회했던 0.34.0 SDK의 스트리밍 결함을 수정했습니다. 업스트림 수정이 완료되자 심을 제거하는 것은 자연스러운 다음 단계였고, LangChain 팀은 즉시 이를 실행했습니다. 1.3.1 태그가 붙기 전에 CI 검사 28개가 모두 통과되었습니다 .

개발자 관점에서: 1.3.0은 약 20시간 동안 유효한 역할을 한 과도기 버전으로 취급하세요. 지금 사용해야 할 기준 버전은 1.3.1입니다. 기능 세트는 동일하며, 심이 제거되고 의존성 최소 버전이 정리되었을 뿐입니다.

use_responses_api 플래그: 엔드포인트 라우팅과 자동 감지 로직

use_responses_api는 ChatPerplexity의 불리언 필드로, 요청이 향하는 API 엔드포인트를 제어합니다. True로 설정하면 0.x 시절부터 유일하게 지원되던 /v1/chat/completions 대신 /v1/agent(OpenAI 호환 별칭으로 /v1/responses도 지원)로 요청이 라우팅됩니다 . Agent API에는 Perplexity의 확장 기능이 집중되어 있습니다. 내장 툴, 서드파티 모델 라우팅, 상태 유지 필드가 모두 이 경로에서만 사용 가능합니다.

더 흥미로운 동작은 자동 감지 규칙입니다. use_responses_api가 설정되지 않은 경우, 라이브러리는 각 호출을 검사해 페이로드에 다음 중 하나가 포함되면 자동으로 Agent API 경로를 선택합니다:

• 함수 타입이 아닌 내장 툴 (예: Finance Search, People Search, 실시간 웹 검색)
• Responses 전용 필드: previous_response_id, instructions, 또는 include

두 조건 중 하나도 충족되지 않으면 라우팅은 기존 Chat Completions로 그대로 처리됩니다. 이것이 하위 호환성 보장입니다. Agent API 기능을 참조하지 않는 기존 ChatPerplexity 인스턴스는 1.3.0 이전과 완전히 동일하게 동작합니다. 코드 수정 불필요, 묵시적 회귀 없음.

1.3.0 PR에는 각 호출의 라우팅 결정 과정을 기록하는 디버그 로깅도 추가되었습니다. 인증 실패나 속도 제한 응답이 원시 SDK 예외로 노출되는 대신, 로거가 이제 무엇이 잘못되었는지, 왜 특정 라우팅 분기가 선택되었는지를 실행 가능한 메시지로 출력합니다. 통합 테스트 중 유용하며, "왜 잘못된 엔드포인트로 가는가" 버그를 추적하기 전에 활성화해 두면 좋습니다.

1.3.0의 SSE 심(Shim)과 perplexityai 0.34.1이 이를 제거한 배경

1.3.0의 SSE 심은 perplexityai 0.34.0(2026년 5월 13일 릴리스)의 결함을 임시 보완하기 위해 존재했습니다 . 업스트림 SDK의 Responses API 경로에서 두 가지 문제가 있었습니다: responses.create 호출에서 SSE가 명명된 이벤트를 발행하지 않았고, 클라이언트 측에서 ResponseStreamEvent 유니온 타입이 올바르게 구분되지 않았습니다. 명명된 이벤트 없이는 스트리밍 소비자가 처리 중인 이벤트 유형을 안정적으로 식별할 수 없으며, 이는 명확한 오류가 아닌 간헐적 장애를 유발하는 유형의 결함으로 진단을 더욱 어렵게 만듭니다.

"yield named SSE events for responses.create + discriminate ResponseStreamEvent union" — perplexityai 0.34.1 CHANGELOG, Perplexity AI (2026년 5월 27일)

LangChain 1.3.0은 이를 처리하기 위해 ChatPerplexity 내부에 임시 심을 제공했습니다. 기능적으로는 동작했으며 비스트리밍 Responses API 사용 사례는 문제없었지만, 프로덕션 스트리밍에서는 취약한 계층이었습니다. 심의 가정과 SDK가 실제로 반환하는 값 사이에 동작 차이가 생기면 잘못된 출력이 조용히 발생할 수 있었기 때문입니다. 심의 유일한 목적은 업스트림 버그를 보완하는 것이었습니다.

perplexityai 0.34.1이 2026년 5월 27일 위의 두 줄짜리 수정과 함께 출시되자, 심의 존재 이유가 사라졌습니다. PR #37710은 이를 완전히 제거하고 의존성 사양에 >=0.34.1 하한선을 명시했습니다 . langchain-perplexity>=1.3.1을 설치하면 pip가 SDK 하한선을 강제하고 설치된 코드에 심이 존재하지 않습니다 — 유지 관리할 것도, 예상치 못한 동작도 없습니다.

실질적인 의미: Responses 엔드포인트에서의 스트리밍을 위해 1.3.0을 평가하면서 불일치한 스트림 이벤트를 목격했다면, 바로 이것이 원인입니다. 1.3.1을 설치하세요.

Responses 엔드포인트의 기본 제공 도구: Perplexity 확장 기능 한눈에

Responses(Agent API) 엔드포인트는 /v1/chat/completions에 존재하지 않는 기능을 노출합니다. Perplexity 공식 문서에 따르면, 이 경로를 통해서만 이용 가능한 기본 제공 도구에는 Finance Search, People Search, 실시간 웹 검색, URL 가져오기가 포함됩니다 . 이것들은 Perplexity가 관리하는 검색 도구로, 도구 목록에 이름을 명시하면 Agent API가 웹 검색 인프라를 직접 관리하지 않아도 적절히 검색을 라우팅합니다.

서드파티 모델 라우팅도 또 다른 중요한 기능입니다. Responses 엔드포인트는 Perplexity의 인프라를 통해 Google, OpenAI, Anthropic 모델로 요청을 라우팅하는 것을 지원합니다 . Chat Completions 경로에는 이에 해당하는 기능이 없습니다. Perplexity의 검색 기능을 결합하면서 여러 모델 제공자로 디스패치하는 단일 API 진입점을 원하는 개발자에게는 이 경로가 이를 가능하게 합니다.

상태 유지(stateful) 필드에는 특별히 주목할 필요가 있습니다. previous_response_id는 API 호출 간 멀티턴 연속성을 가능하게 합니다 — 서버가 대화 상태를 추적하므로 전체 메시지 히스토리를 다시 전송할 필요가 없습니다. instructions와 include는 호출별로 응답 내용과 형식을 조정할 수 있게 합니다. 이 필드들은 자동 감지를 트리거합니다: ChatPerplexity 호출에 이 중 하나를 포함하면 use_responses_api=True를 설정하지 않아도 라이브러리가 자동으로 Agent API로 라우팅합니다.

1.3.0에서 추가된 응답 변환기는 별도로 언급할 가치가 있습니다. Agent API 응답은 Chat Completions 응답과 구조적으로 다릅니다 — 인용, 이미지 결과, 검색 페이로드, 도구 호출 구조가 포함되어 있어 표준 AIMessage 스키마에 깔끔하게 매핑되지 않습니다. 변환기가 이 변환을 처리하므로 다운스트림 LangChain 체인과 에이전트는 Agent API 메타데이터가 추가 필드로 보존된 표준 메시지 객체를 받습니다. Perplexity 특유의 응답 형태를 직접 파싱할 필요 없이 풍부한 응답을 활용할 수 있습니다.

1.3.x 버전 고정: 각 휠이 제공하는 것

현재 langchain-perplexity 사용자에게는 세 가지 업그레이드 선택지가 있으며, 올바른 선택은 통합을 어떻게 활용하느냐에 따라 달라집니다. 요약하면: 특별한 이유가 없는 한 1.3.1로 고정하세요 .

1.3.0 미만 — Chat Completions만 지원. Chat Completions를 통한 Sonar 모델은 계속 정상 작동하며 문제는 없습니다. 강제 마이그레이션도 없습니다. Perplexity의 내장 도구, 서드파티 모델 라우팅, 상태 유지 필드에 관심이 없다면 이 버전에 머물러도 무방합니다. 다만 더 깔끔한 의존성 그래프를 위해서는 1.3.1로 업그레이드하는 것이 여전히 권장 경로입니다.

정확히 1.3.0 — 기능 완전, shim 포함. Responses 엔드포인트 라우팅과 자동 감지가 작동합니다. 스트리밍이 없는 Responses 사용 사례에서는 수용 가능한 버전입니다. 단, Responses 엔드포인트를 통한 프로덕션 스트리밍에는 1.3.0을 사용하지 마세요: SSE shim이 일관되지 않은 스트림 이벤트 동작을 유발할 수 있습니다. 이 버전을 고정할 이유는 거의 없습니다 — 1.3.1이 shim 없이 동일한 기능을 제공합니다.

1.3.1 (권장 최소 버전) — shim 제거, 안정적인 기반. perplexityai>=0.34.1 제약이 패키지 스펙에 명시되어 있으며 pip이 설치 시 자동으로 적용합니다. Responses 엔드포인트를 통한 모든 스트리밍 작업에 안전한 최소 버전입니다 . 태깅 전 28개의 CI 검사가 모두 통과되었습니다.

한 가지 주의할 점이 있습니다: 1.3.1이 게시될 당시 perplexityai는 이미 0.35.0과 0.35.1로 이동한 상태였으며, 두 버전 모두 2026년 5월 27일에 출시되었습니다 . 1.3.1의 의존성 최소 버전은 의도적으로 0.35.x가 아닌 0.34.1로 설정되었습니다. 이는 의도적인 보수적 접근입니다: 0.35.x는 1.3.1과 문제없이 해석되어야 하지만 아직 LangChain 휠에서 검증되지 않았습니다. requirements 파일에 perplexityai>=0.35.1을 별도로 고정하면 해당 제약이 우선 적용됩니다 — 다만 이는 1.3.1 CI 매트릭스에서 다루지 않은 범위임을 인지하세요.

자주 묻는 질문

ChatPerplexity에서 use_responses_api=True로 설정하면 무엇이 달라지나요?

모든 요청이 Perplexity의 /v1/agent 엔드포인트(Agent API, OpenAI 호환을 위해 /v1/responses로도 접근 가능)로 라우팅됩니다. 이 경로에서만 사용할 수 있는 기능들이 활성화됩니다: Finance Search, People Search, 실시간 웹 검색, URL 가져오기 등 내장 도구; Perplexity 인프라를 통한 Google, OpenAI, Anthropic 모델로의 서드파티 모델 라우팅; 상태 유지 대화 필드(previous_response_id, instructions, include). 이 기능들은 모두 /v1/chat/completions에서는 사용할 수 없습니다. 플래그를 False로 설정하거나 — Agent API 전용 필드를 전달하지 않은 채 미설정으로 두면 — Chat Completions 경로 라우팅이 그대로 유지됩니다.

langchain-perplexity 1.3.1은 기존 사용자에게 호환성을 깨는 변경인가요?

아닙니다. 하위 호환성은 완전히 유지됩니다. Chat Completions를 통해 Sonar 모델을 사용하고 Agent API 도구나 상태 유지 필드를 참조하지 않는 기존 ChatPerplexity 코드는 1.3.1로 업그레이드한 후에도 동일하게 라우팅됩니다. 라이브러리의 자동 감지는 페이로드에 Responses 전용 신호가 있을 때만 새 라우팅을 활성화합니다. Responses 엔드포인트 기능을 의도적으로 사용하지 않는 개발자는 코드를 변경할 필요가 없습니다.

LangChain이 같은 날 1.3.x 휠을 두 개 출시한 이유는 무엇인가요?

perplexityai 0.34.0(2026년 5월 13일)에는 Responses API 경로의 스트리밍 결함이 있었습니다: SSE가 responses.create에 대한 명명된 이벤트를 발생시키지 않았고, ResponseStreamEvent 유니온 타입이 올바르게 구별되지 않았습니다. LangChain 1.3.0은 이를 우회하기 위한 임시 shim을 포함하여 출시되었습니다. 같은 날(5월 27일) 이후에 Perplexity가 업스트림 수정이 포함된 perplexityai 0.34.1을 출시했고, LangChain 팀은 불필요해진 shim을 즉시 제거하고 1.3.1을 게시했습니다. 두 번의 릴리스 패턴은 의존성이 일반적인 릴리스 주기보다 빠르게 움직인 결과로, 양 팀이 하루 만에 프로덕션 엣지 케이스를 해결한 것입니다.

어떤 Perplexity 기능에 use_responses_api 또는 Responses 엔드포인트가 필요한가요?

Finance Search, People Search, 실시간 웹 검색, URL 가져오기는 Responses(Agent API) 경로에서만 사용할 수 있습니다. Perplexity 인프라를 통해 Google, OpenAI, Anthropic 모델로 요청을 전송하는 서드파티 모델 라우팅도 Responses 전용입니다. 상태 유지 대화 필드(previous_response_id, instructions, include) 역시 Agent API 경로가 필요합니다. use_responses_api=True로 명시적으로 활성화하거나, 자동 감지에 맡길 수 있습니다: 위의 도구나 필드가 페이로드에 포함되면 langchain-perplexity>=1.3.0이 명시적 플래그 없이도 Agent API로 자동 라우팅합니다.

requirements 파일에 perplexityai >= 0.34.1을 별도로 고정해야 하나요?

langchain-perplexity를 1.3.1 미만 버전으로 독립적으로 제한하는 경우에만 필요합니다. requirements에 langchain-perplexity>=1.3.1을 지정했다면, perplexityai>=0.34.1 최소 버전이 이미 해당 패키지의 의존성 스펙에 포함되어 있으므로 pip이 해석 시 자동으로 적용합니다. 별도 고정은 필요 없습니다. langchain-perplexity==1.3.0과 같은 레거시 고정을 사용 중이라면 SSE shim이 포함된 버전을 사용하는 것입니다. 가장 안전한 수정은 상한을 제거하고 pip이 1.3.1을 가져오도록 두는 것입니다.

앞으로 주목할 것들

당장 실천할 사항: 1.3.x 휠을 사용 중이라면 langchain-perplexity==1.3.1로 업그레이드하고, requirements 최소 버전으로 langchain-perplexity>=1.3.1을 사용하세요. 기능 — Agent API 라우팅, 자동 감지, 응답 변환기, 디버그 로깅 — 은 안정적이며 의존성 그래프도 깔끔합니다.

추적할 가치가 있는 두 가지 미해결 질문이 있습니다. 첫째, 공식 Perplexity LangChain 통합 문서는 검색 기준일 현재 use_responses_api나 Agent API 라우팅을 문서화하도록 업데이트되지 않았습니다 — 공식 문서만 참고하는 개발자라면 이 기능이 존재하는지조차 알 수 없습니다. 해당 문서 업데이트를 주시하세요. 둘째, TypeScript @langchain/community 패키지가 동등한 Agent API 구현을 받았다는 공식 확인이 없습니다. Python과 함께 JS/TS 스택을 운용한다면, 기능 동등성을 가정하기 전에 이 격차를 조사할 필요가 있습니다.

장기적으로: perplexityai는 1.3.1이 게시된 같은 날 0.35.1로 이동했습니다. 해당 최소 버전을 검증하고 — 잠재적으로 0.35.x의 추가 사항을 반영하는 — 후속 langchain-perplexity 릴리스가 자연스러운 다음 단계입니다. 5월 27일의 빠른 릴리스 속도는 의존성 양쪽에서 활발한 반복 개발이 이루어지고 있음을 시사합니다.

최종 업데이트: 2026-05-30. 이 글은 2026년 5월 27일 릴리스 기준 langchain-perplexity 1.3.1 및 perplexityai 0.34.1을 반영합니다.