langchain-perplexity 1.3.0: ChatPerplexity에 use_responses_api 추가

ChatPerplexity에서 use_responses_api가 하는 일

use_responses_api는 ChatPerplexity 클래스에 새로 추가된 생성자 파라미터로, langchain-perplexity 1.3.0 에서 PR #37359 를 통해 출시되었습니다. 이 파라미터를 설정하면 표준 Chat Completions 엔드포인트(/v1/chat/completions) 대신 Perplexity의 Agent API — 정식 엔드포인트 /v1/agent, 별칭 /v1/responses — 로 호출이 라우팅됩니다. 이 패턴은 ChatOpenAI의 기존 use_responses_api 파라미터와 동일한 방식으로, LangChain 사용자라면 즉시 익숙하게 느낄 수 있습니다. 기본값은 None으로, 자동 감지를 활성화합니다. 기존에 ChatPerplexity(model="sonar")를 사용하던 코드는 별도로 옵트인하지 않는 한 동작 변화가 전혀 없습니다.

내부적으로 1.3.0은 LangChain의 메시지 형식과 Agent API 스키마를 연결하는 두 개의 내부 변환 레이어를 도입했습니다. _to_responses_payload는 Agent API 규격에 맞게 messages → input, max_tokens → max_output_tokens로 이름을 변경합니다. 대응 함수인 _convert_responses_to_chat_result는 Agent API 응답 객체를 AIMessage로 다시 래핑하며, 사용량 메타데이터와 인용 정보를 보존합니다. 세 번째 헬퍼인 _convert_responses_stream_event_to_chunk는 스트리밍을 처리합니다. LangChain 체인의 하위 단계 — 도구, 메모리, 출력 파서 — 는 표준 AIMessage를 수신하므로, 어느 엔드포인트가 요청을 처리했는지 알 필요가 없습니다.

from langchain_perplexity import ChatPerplexity

# 명시적으로 옵트인 — 항상 Agent API 사용
llm = ChatPerplexity(model="sonar-pro", use_responses_api=True)
response = llm.invoke("What are the latest changes to the Federal Reserve's rate policy?")

# Agent API 메타데이터는 additional_kwargs에서 확인 가능
citations = response.additional_kwargs.get("citations", [])
search_results = response.additional_kwargs.get("search_results", [])

기존 체인을 전환하기 전에 반드시 파악해야 할 제약이 있습니다. Agent API는 Chat Completions 전용 샘플링 제어 파라미터를 허용하지 않습니다. Agent API로 호출이 라우팅되면 temperature, top_p, top_k, stop, metadata는 자동으로 무시됩니다. tool_choice를 전달하면 ValueError가 발생합니다. .with_structured_output()을 통한 구조화된 출력은 Perplexity 티어 3 이상 사용자에게만 제공됩니다. 프로덕션 체인이 이 기능 중 어느 하나라도 의존하고 있다면, 업그레이드 전에 라우팅 동작을 테스트하세요.

라우팅 동작 한눈에: 자동 감지 · 강제 활성 · 강제 비활성

use_responses_api의 세 가지 모드 설계 덕분에 개발자는 각 호출을 처리할 Perplexity 엔드포인트를 정밀하게 제어할 수 있습니다. LangChain ChatPerplexity 통합 문서 에 따르면, use_responses_api=None(기본값)으로 설정하면 요청마다 페이로드를 검사합니다. 런타임은 내장 도구나 Agent 전용 필드의 존재 여부를 확인하고, 감지되면 Agent API로, 그렇지 않으면 Chat Completions로 연결합니다. 즉, Sonar 모델을 에이전틱 기능 없이 사용하는 기존 체인 대부분은 아무 변경 없이 Chat Completions를 계속 사용하게 됩니다.

자동 감지 로직은 Agent 전용 필드를 집합으로 취급합니다: previous_response_id, instructions, input, include. 이 중 하나라도 있으면 Agent API 라우팅이 트리거되며, 생성자 플래그를 명시적으로 설정할 필요가 없습니다. 따라서 개발자는 페이로드에 previous_response_id를 전달하는 것만으로 상태 기반 동작을 옵트인할 수 있고, ChatPerplexity 인스턴스 생성에 손댈 필요 없이 라우팅이 올바르게 처리됩니다.

디버그 로그는 호출마다 라우팅 결정을 기록합니다. 예상과 달리 체인이 Agent API에 도달하거나(또는 그 반대로) 있다면, 디버그 레벨 로깅을 활성화하면 추가 계측 없이도 분기 경로를 바로 확인할 수 있습니다. 체인이 동적으로 생성하는 구조화된 페이로드에 의도치 않게 Agent 전용 필드가 포함된 경우처럼, 라우팅 동작이 예상과 다를 때 가장 빠른 진단 방법입니다.

동일한 애플리케이션에서 Agent API 호출과 Chat Completions 호출에 서로 다른 파라미터 세트가 필요하다면, 자동 감지에 의존해 트래픽을 나누기보다 ChatPerplexity 객체를 두 개 인스턴스화하는 것이 가장 안전합니다 — 하나는 use_responses_api=True, 다른 하나는 use_responses_api=False로 설정합니다. 자동 감지는 동질적인 체인에 적합하고, 혼합 체인에서는 명시적 플래그가 모호함을 없애줍니다.

내장 도구: web_search, fetch_url, finance_search, people_search

Agent API는 /v1/agent로 라우팅될 때 ChatPerplexity를 통해 네이티브로 동작하는 네 가지 내장 도구를 제공합니다. 이 도구들은 Perplexity 서버 측에서 정의되며, 별도의 툴 래퍼, 외부 HTTP 클라이언트, 추가 API 키가 필요 없습니다. Agent API 자체는 2026년 2월 일반 공개(GA)에 도달했습니다 . 네 번째 도구인 finance_search는 2026년 5월 GA에 도달했으며 — 1.3.0 릴리스와 같은 달로, 두 기능을 동시에 사용할 수 있게 되었습니다.

내장 도구를 사용하려면 ChatPerplexity를 생성하거나 호출할 때 표준 tools 인수에 도구 디스크립터를 전달하면 됩니다. use_responses_api=None 상태에서는 페이로드에 도구가 존재하는 것만으로도 Agent API 라우팅이 트리거되며, 별도 플래그가 필요 없습니다. 각 도구의 구조화된 결과 객체는 반환된 AIMessage의 response.additional_kwargs에 담겨 있으며, 하위 단계에서 파싱하여 전달할 수 있습니다. 전체 도구 스키마 정의는 langchain-perplexity 도구 레퍼런스를 참조하세요.

web_search는 네 가지 중 가장 범용적입니다. 원시 텍스트가 아닌 구조화된 결과 객체를 반환하므로, 문자열 파싱 없이 인용 표시, 후속 쿼리, 하위 필터링에 적합합니다. 워크플로 중 특정 URL의 콘텐츠를 가져와야 하는 에이전트에는 fetch_url이 외부 HTTP 클라이언트나 별도 리트리버의 필요성을 없애줍니다. Perplexity 인프라가 페치를 처리하고 파싱된 콘텐츠를 반환합니다.

finance_search는 가장 전문화된 도구입니다. 상장사의 애널리스트 추정치, 실적 이력, ETF 보유 종목, 부문별 KPI 등 기계가 읽을 수 있는 구조화 데이터를 반환합니다. 이 데이터는 일반적으로 전용 금융 데이터 API 구독이나 불안정한 스크래핑이 필요한 영역입니다. LangChain으로 금융 리서치 에이전트를 구축하는 팀에게는, finance_search와 1.3.0 릴리스의 동시 GA 덕분에 별도 데이터 제공업체 계약 없이 Perplexity API 계층에서 즉시 구조화된 금융 데이터 조회가 가능해집니다.

from langchain_perplexity import ChatPerplexity

# finance_search는 자동 감지로 Agent API 라우팅을 트리거합니다
llm = ChatPerplexity(model="sonar-pro")
response = llm.invoke(
    "What are the latest earnings estimates for NVIDIA?",
    tools=[{"type": "finance_search"}]
)
# additional_kwargs의 구조화된 금융 데이터
print(response.additional_kwargs.get("search_results", []))

응답 보강: 인용, 이미지, 검색 결과

Agent API 응답은 Chat Completions 응답보다 훨씬 풍부한 메타데이터를 포함합니다. 모든 보강 필드는 반환된 AIMessage의 response.additional_kwargs를 통해 접근할 수 있으며, LangChain 체인의 하위 단계에서 추가 API 호출 없이 인용, 검색 결과, 이미지, 추론 흔적에 접근할 수 있습니다. 사용 가능한 전체 필드 목록은 citations, images, related_questions, search_results, videos, reasoning_steps입니다.

인용 표시 레이어를 구축하는 개발자에게 additional_kwargs["citations"]는 출처 추출을 위한 텍스트 파싱 없이 모델의 웹 검색에서 도출된 소스 URL과 제목을 제공합니다. 생성된 답변과 함께 검색 근거를 노출하는 애플리케이션에는 search_results가 응답에 참고한 순위별 결과를 제공합니다. related_questions는 추가 프롬프팅 없이 후속 제안 UI를 구동할 수 있으며, Agent API가 검색 과정의 부산물로 이를 생성합니다.

response = llm.invoke("Explain the latest LangChain release")

# Access enrichment fields
citations = response.additional_kwargs.get("citations", [])
images = response.additional_kwargs.get("images", [])
reasoning = response.additional_kwargs.get("reasoning_steps", [])
related = response.additional_kwargs.get("related_questions", [])

특정 필드를 선택적으로 반환하는 것은 include 파라미터로 제어됩니다. 이 Agent 전용 필드는 반환 객체에 포함할 응답 필드 목록을 명시적으로 받습니다. include=["citations", "search_results"]를 전달하면 응답 페이로드가 해당 두 필드로 제한되어 지연 시간에 민감한 애플리케이션에서 페이로드 크기를 줄일 수 있습니다. 라우팅 섹션에서 언급했듯이, use_responses_api=None일 때 페이로드에 include를 전달하는 것만으로도 Agent API로의 자동 감지 라우팅이 트리거됩니다.

reasoning_steps는 디버깅과 평가에 특히 유용합니다. 모델이 답변에 도달하기까지 사용한 중간 단계를 노출하여 별도의 계측 없이 추적 경로를 제공합니다. 평가(eval)를 구축하거나 Agent API가 다단계 쿼리를 처리하는 방식에 대한 투명성을 원하는 팀에게 이 필드는 구조화된 감사 추적을 제공합니다. 이 필드는 Agent API를 통해 라우팅된 호출에서만 존재하며, Chat Completions 응답에는 포함되지 않습니다.

단일 결제 계정으로 다양한 프로바이더 LLM 통합

Perplexity 자체 Sonar 모델 외에도 Agent API는 Anthropic, OpenAI, Google, NVIDIA, xAI의 서드파티 파운데이션 모델을 지원합니다. use_responses_api=True를 설정하면 개발자는 프로바이더 접두사가 붙은 모델 문자열을 ChatPerplexity에 전달할 수 있으며, Perplexity 인프라가 해당 모델의 응답에 실시간 웹 검색을 주입합니다 — 프로바이더별 별도 API 키 없이 단일 Perplexity API 계정으로 모두 청구됩니다.

1.3.0 릴리스 기준으로 Agent API는 다음 크로스 프로바이더 모델을 지원합니다: 2026년 4월에 추가된 OpenAI의 openai/gpt-5.4와 openai/gpt-5.5 , Anthropic의 anthropic/claude-sonnet-4-6과 anthropic/claude-opus-4-7, Google의 google/gemini-3-1-pro, NVIDIA Nemotron, Grok 4.20 Reasoning. 모델명 형식은 Perplexity 전용 라우팅 구문으로, 접두사(예: anthropic/)가 Agent API에 어느 프로바이더를 호출할지 알려줍니다. 이 문자열은 버전이 고정될 수 있으므로, 모델 릴리스가 진행됨에 따라 특정 접미사 식별자가 변경될 수 있습니다.

from langchain_perplexity import ChatPerplexity

# Claude Sonnet 4.6 via Perplexity, with live web search injected
# No Anthropic API key required — single Perplexity billing account
llm = ChatPerplexity(
    model="anthropic/claude-sonnet-4-6",
    use_responses_api=True
)
response = llm.invoke("What happened in AI tooling this week?")
citations = response.additional_kwargs.get("citations", [])

구체적인 시나리오를 들자면, 검색에 Perplexity를 이미 표준으로 채택한 팀이 동일한 그라운디드 응답 태스크에서 다양한 파운데이션 모델을 평가하고자 할 때, Anthropic·OpenAI·Google API 키를 별도로 관리할 필요 없이 단일 ChatPerplexity 인스턴스의 model 문자열만 교체하면 됩니다. 실시간 검색을 공통 기준선으로 삼아 모델 프로바이더 간 A/B 평가를 수행하는 팀이라면, 키 관리 오버헤드를 단일 자격증명으로 줄일 수 있습니다.

주요 트레이드오프는 서드파티 모델에 대해 Perplexity의 통합 일정에 종속된다는 점입니다. Anthropic이나 OpenAI가 새 모델 버전을 출시하더라도 Agent API를 통한 지원 시점은 프로바이더의 출시일이 아닌 Perplexity의 일정에 달려 있습니다. 엄격한 모델 버전 요구사항이 있거나 프로바이더 릴리스를 당일 접근해야 하는 팀은 직접 프로바이더 API를 선호할 수 있습니다. Perplexity의 검색 주입을 원하면서 모델 버전에 유연한 팀에게는 통합 청구가 실용적인 편의를 제공합니다.

previous_response_id로 대화 상태 유지

Agent API 전용 필드 세 가지(previous_response_id, instructions, include)는 Chat Completions에는 없는 상태 유지 및 범위 지정 동작을 가능하게 합니다. 각 필드는 고유한 역할을 하며, use_responses_api=None일 때 이 중 하나라도 전달하면 자동 감지 라우팅이 활성화됩니다 — 생성자 플래그는 필요하지 않습니다.

previous_response_id는 전체 대화 기록을 재전송하지 않고도 여러 API 요청에 걸쳐 멀티턴 메모리를 유지하는 메커니즘입니다. 매 턴마다 input 배열에 이전 메시지를 누적하는 대신, 호출자는 마지막 응답의 ID를 저장하여 다음 요청에 전달합니다. Agent API는 서버 측에서 이전 컨텍스트를 조회합니다. 이를 통해 페이로드 크기가 줄고 클라이언트 측 상태 관리가 단순해집니다 — 클라이언트는 늘어나는 메시지 목록 대신 단일 ID만 추적하면 됩니다. 장시간 대화를 처리하는 에이전트에게는 대역폭과 토큰 비용 양면에서 실질적인 최적화입니다.

llm = ChatPerplexity(model="sonar-pro")  # use_responses_api=None (auto-detect)

# First turn
response_1 = llm.invoke("What is LangChain's latest major version?")
response_id = response_1.additional_kwargs.get("id")

# Second turn — passing previous_response_id triggers Agent API routing automatically
response_2 = llm.invoke(
    "What breaking changes did it introduce?",
    previous_response_id=response_id
)

instructions는 Agent API 호출 범위에 적용되는 시스템 레벨 동작 프롬프트로, input 배열 내 타입이 지정된 메시지가 아닌 전용 필드로 정의됩니다. 기능적으로 시스템 메시지와 유사하지만, 분리된 필드 형태이므로 더 명시적이며, 변환 시 input으로 이름이 바뀌는 메시지 목록 안에 시스템 역할 메시지 객체를 삽입할 때의 모호함을 피할 수 있습니다.

include는 반환 객체에 포함할 응답 필드 목록을 명시적으로 받습니다 — 예를 들어 ["citations", "search_results"]. 특정 메타데이터가 필요하고 응답 페이로드 크기를 예측 가능하게 유지하려는 애플리케이션에 유용합니다. 이 세 필드는 모두 Agent API를 통해 라우팅될 때만 의미가 있으며, Chat Completions 엔드포인트에서는 효과가 없고 오류를 유발할 수 있습니다.

의존성 업데이트: 1.3.0과 1.3.1

두 버전 모두 2026년 5월 27일에 출시되었습니다 . 버전 1.3.0은 00:22 UTC에 use_responses_api 기능과 함께 네 가지 의존성 하한 상향을 담아 출시되었습니다: langsmith 0.8.0 → 0.8.5, idna 3.10 → 3.15, urllib3 2.6.3 → 2.7.0, langchain-core ≥ 1.3.3. 버전 1.3.1은 20:45 UTC에 순수 의존성 패치로 뒤따랐으며 — 새로운 공개 API 표면 없이 — PR #37710과 #37720을 통해 perplexityai Python SDK를 0.34.0에서 0.34.1로 업데이트했습니다.

perplexityai 0.34.1의 구체적인 변경 내용은 LangChain 체인지로그에 노출되지 않습니다. 두 릴리스가 같은 날 출시된 만큼 1.3.0을 굳이 고정할 이유가 없습니다 — 새 플래그와 함께 SDK 수정 사항을 받으려면 1.3.1로 고정하세요.

이전 버전에서 업그레이드하는 경우 langchain-core와 langsmith의 고정 버전을 확인하세요. 의존성 트리의 다른 곳에 엄격한 버전 제약이 있다면 1.3.0의 하한 상향으로 인해 일괄 업그레이드가 필요할 수 있습니다. idna와 urllib3 업데이트는 보안 및 유지보수 목적이며 API 표면 변경은 없습니다.

자주 묻는 질문

langchain-perplexity 1.3.0으로 업그레이드하면 기존 ChatPerplexity 사용이 깨지나요?

아니요. use_responses_api 파라미터의 기본값은 None으로, 요청 페이로드에 Agent 전용 필드(previous_response_id, instructions, input, include)나 내장 도구가 없을 경우 Chat Completions로 자동 감지·전환됩니다. 기존 ChatPerplexity(model="sonar") 호출자는 코드 변경 없이 계속 Chat Completions 엔드포인트를 사용합니다. 1.3.0 릴리스는 완전한 하위 호환성을 보장하며, 별도의 옵트아웃이 필요하지 않습니다.

ChatPerplexity의 Chat Completions 엔드포인트와 Agent API 엔드포인트는 어떻게 다른가요?

Chat Completions(/v1/chat/completions)는 Perplexity의 Sonar 모델 패밀리를 활용한 표준 증강 채팅을 처리합니다. Agent API(/v1/agent, /v1/responses로 별칭 지정)는 내장 도구 4개(web_search, fetch_url, finance_search, people_search), 상태 유지 필드(previous_response_id, instructions, include), 서드파티 제공업체 모델(Anthropic, OpenAI, Google) 지원, 그리고 citations, search_results, images, reasoning_steps를 포함한 풍부한 응답 메타데이터를 추가합니다. Agent API는 2026년 2월 정식 출시(GA)되었으며 , Chat Completions는 그보다 앞서 존재했습니다. temperature, top_p 같은 샘플링 파라미터는 Chat Completions에서는 사용 가능하지만 Agent API에서는 조용히 무시됩니다.

Perplexity Agent API에서 finance_search와 web_search의 차이는 무엇인가요?

finance_search는 상장 기업의 구조화된 금융 데이터(주가 시세, 실적 이력, 애널리스트 예측, ETF 구성 종목, 부문별 KPI)를 반환합니다. web_search는 인용 출처와 함께 관련성 기준으로 정렬된 일반 웹 결과를 반환합니다. 금융 애플리케이션에서는 이 차이가 중요합니다. finance_search는 모델 텍스트 파싱이 필요 없는 기계 가독형 구조화 출력을 생성하는 반면, web_search는 일반 웹 콘텐츠를 반환합니다. finance_search는 2026년 5월 정식 출시되었으며 , web_search는 2026년 2월 Agent API GA 시점부터 사용 가능했습니다.

ChatPerplexity를 통해 Claude나 GPT-5를 실행하면서 실시간 웹 검색을 주입받을 수 있나요?

네. ChatPerplexity에 use_responses_api=True와 함께 제공업체 접두사가 붙은 모델 이름(예: model="anthropic/claude-sonnet-4-6" 또는 model="openai/gpt-5.4")을 전달하면 됩니다. Perplexity의 Agent API가 지정된 제공업체로 호출을 라우팅하고 실시간 웹 검색 컨텍스트를 응답에 주입합니다. 이 모든 것이 단일 Perplexity 청구 계정에서 실행되므로 별도의 Anthropic이나 OpenAI API 키가 필요하지 않습니다. 이 모델 이름 문자열은 Perplexity 전용 라우팅 구문이며, 모델 버전이 변경됨에 따라 달라질 수 있음을 유의하세요.

1.3.0의 _to_responses_payload 변환 레이어는 어떤 역할을 하나요?

_to_responses_payload는 ChatPerplexity의 내부 메서드로, 표준 LangChain 메시지 페이로드를 Agent API가 요구하는 스키마로 변환합니다. 구체적으로는 messages 키를 input으로, max_tokens를 max_output_tokens로 이름을 바꿉니다. 쌍을 이루는 메서드 _convert_responses_to_chat_result는 역방향을 수행합니다. Agent API 응답 객체를 AIMessage로 감싸면서 사용량 메타데이터와 인용 정보를 보존하여, LangChain 체인의 나머지 부분이 표준 메시지 타입을 받고 어떤 엔드포인트가 사용되었는지 알지 못하게 합니다. 세 번째 메서드 _convert_responses_stream_event_to_chunk는 스트리밍 이벤트 변환을 담당합니다.

업그레이드 체크리스트와 주의 사항

1.3.0 릴리스는 실시간 데이터 검색이 필요한 LangChain 에이전트에서 ChatPerplexity를 더욱 완성도 높은 선택지로 만들었습니다. 내장 도구 4개, 크로스 제공업체 모델 지원, 상태 유지 필드가 함께 맞물려 이전에는 커스텀 도구 래퍼나 별도 API 통합이 필요했던 공백을 메웁니다. 금융 데이터 에이전트를 구축하는 팀이라면, finance_search의 동시 GA 출시를 계기로 Perplexity의 구조화된 금융 데이터 검색이 추가 데이터 제공업체 계약 없이 요구 사항을 충족하는지 평가해볼 적기입니다.

Agent API를 프로덕션 체인에 적용하기 전에 다음 사항을 점검하세요:

• 1.3.0이 아닌 1.3.1로 버전을 고정하세요 — 같은 날 배포된 perplexityai SDK 0.34.1 패치가 포함되어 있습니다.
• 샘플링 파라미터를 확인하세요 — 체인이 temperature, top_p, top_k, stop, metadata를 전달하는 경우, Agent API로 라우팅될 때 조용히 제거됩니다. 해당 파라미터를 삭제하거나 use_responses_api=False로 조건 분기하세요.
• tool_choice 사용 여부를 확인하세요 — Agent API에서 tool_choice를 전달하면 ValueError가 발생합니다. 옵트인 전에 제거하세요.
• Perplexity 티어를 확인하세요 — .with_structured_output()을 통한 구조화 출력은 티어 3 이상이 필요합니다. 이를 기반으로 빌드하기 전에 티어를 확인하세요.
• langchain-core와 langsmith를 업데이트하세요 — 1.3.0은 langchain-core ≥ 1.3.3 및 langsmith ≥ 0.8.5를 최소 버전으로 요구합니다.
• 크로스 제공업체 모델 문자열을 버전 고정으로 취급하세요 — "anthropic/claude-sonnet-4-6" 같은 문자열은 Perplexity 전용 라우팅 구문입니다. 모델 버전이 변경됨에 따라 업데이트를 위해 Perplexity의 변경 이력을 모니터링하세요.

Chat Completions 대비 Agent API 가격 정책 및 Perplexity 티어 3+ 요건의 정확한 정의는 Perplexity의 가격 문서를 직접 확인하세요 — 이 두 가지는 LangChain 릴리스 노트에 명시되어 있지 않습니다. ChatPerplexity 클래스 레퍼런스와 Perplexity의 LangChain 통합 가이드가 현재 파라미터 세부 사항과 지원 모델 목록에 대한 공식 출처입니다.

최종 업데이트: 2026-05-30. langchain-perplexity 1.3.1 PyPI 릴리스 노트, LangChain GitHub 릴리스 로그, 2026년 5월 기준 Perplexity Agent API 문서를 참고하였습니다.