Perplexity 검색
@tanstack/ai-perplexity는 Search API 패키지입니다. POST https://api.perplexity.ai/search를 TanStack AI 도구(및 저수준 HTTP 클라이언트)로 래핑하여 에이전트가 인용과 그라운딩을 위한 순위가 매겨진 웹 결과를 가져올 수 있게 합니다.
TanStack text 어댑터는 제공하지 않습니다. 검색 도구를 openaiText 또는 anthropicText와 같은 함수 호출 어댑터와 함께 사용합니다. Sonar chat()은 여전히 openaiCompatible를 사용합니다. Sonar는 이미 웹을 검색하며 사용자 지정 도구를 허용하지 않습니다.
설치
npm install @tanstack/ai @tanstack/ai-openai @tanstack/ai-perplexity
API 키를 설정합니다(https://console.perplexity.ai/group/keys에서 발급할 수 있습니다).
export PERPLEXITY_API_KEY=...
# PPLX_API_KEY is also accepted
검색 도구
이 도구는 일급 함수 호출 어댑터와 함께 사용합니다. Sonar에는 전달하지 않습니다. Sonar Chat Completions는 사용자 지정 도구를 등록하지 않습니다.
import { chat } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'
import { perplexitySearchTool } from '@tanstack/ai-perplexity'
const search = perplexitySearchTool({
defaultMaxResults: 5,
})
const stream = chat({
adapter: openaiText('gpt-5.2'),
tools: [search],
messages: [
{ role: 'user', content: 'What were the top AI papers this week?' },
],
})
같은 방식으로 openaiText를 anthropicText(또는 다른 함수 호출 어댑터)로 바꿀 수 있습니다.
도구 입력 스키마는 다음을 허용합니다.
| 필드 | 타입 | Notes |
|---|---|---|
query | string (required) | 검색 쿼리입니다. |
max_results | integer (1–20) | 설정된 경우 defaultMaxResults를 사용하고, 그렇지 않으면 API 기본값(10)을 사용합니다. |
search_domain_filter | string[] | 최대 20개입니다. 허용 목록("nytimes.com") 또는 거부 목록("-pinterest.com") 중 하나만 사용할 수 있으며 둘 다 사용할 수는 없습니다. 호스트 이름, 선택적 경로 또는 TLD입니다. |
search_recency_filter | "hour" | "day" | "week" | "month" | "year" | 최신성 기간입니다. |
search_after_date_filter | string | m/d/yyyy — 이 날짜 이후(당일 포함)의 결과만 반환합니다. |
search_before_date_filter | string | m/d/yyyy — 이 날짜 이전(당일 포함)의 결과만 반환합니다. |
출력: { results: Array<{ title, url, snippet, date?, last_updated? }> }. 래퍼는 이러한 인용 필드와 client.search()의 선택적 응답 id를 유지하며 server_time은 노출하지 않습니다.
도구는 Search API 필터의 일부만 노출합니다(query는 단일 문자열입니다). PerplexitySearchClient는 max_tokens_per_page와 최대 5개의 쿼리를 string[]으로도 허용합니다.
직접 클라이언트
에이전트 루프 외부에서 Search API를 호출하려면 다음과 같이 합니다.
import { PerplexitySearchClient } from '@tanstack/ai-perplexity'
const client = new PerplexitySearchClient()
const { results } = await client.search({
query: 'mars sample return mission',
max_results: 5,
search_recency_filter: 'month',
})
구성
import { PerplexitySearchClient } from '@tanstack/ai-perplexity'
const client = new PerplexitySearchClient({
apiKey: process.env.PERPLEXITY_API_KEY, // explicit key (optional)
baseURL: 'https://api.perplexity.ai', // override (optional)
fetch: globalThis.fetch, // custom fetch (optional)
})
채팅 (Sonar)
Sonar는 이미 웹을 기반으로 답변을 생성합니다. @tanstack/ai-openai/compatible의 openaiCompatible를 사용합니다. 이 패키지는 해당 어댑터를 래핑하지 않으며, 여기에 perplexitySearchTool을 전달해서는 안 됩니다.
import { chat } from '@tanstack/ai'
import { openaiCompatible } from '@tanstack/ai-openai/compatible'
import { getPerplexityIntegrationHeaders } from '@tanstack/ai-perplexity'
const perplexity = openaiCompatible({
name: 'perplexity',
baseURL: 'https://api.perplexity.ai',
apiKey: process.env.PERPLEXITY_API_KEY!,
models: ['sonar', 'sonar-pro'],
defaultHeaders: getPerplexityIntegrationHeaders(),
})
const stream = chat({
adapter: perplexity('sonar'),
messages: [{ role: 'user', content: 'What is the latest on the Mars rover?' }],
})
getPerplexityIntegrationHeaders()는 선택 사항입니다. Perplexity의 X-Pplx-Integration 출처 표시 헤더(tanstack/<package-version>)를 추가합니다. Search 클라이언트는 이를 자동으로 전송하며, Sonar chat 요청에도 같은 헤더를 사용하려면 openaiCompatible에 전달합니다.
그러면 OpenAI SDK가 POST https://api.perplexity.ai/chat/completions를 호출합니다(Sonar를 위한 Perplexity의 OpenAI 호환 별칭입니다).