Tavily 검색 통합

Tavily 검색 통합 (Tavily search integration)

LangChain JavaScript로 Tavily 검색 툴과 통합해요.

Tavily의 Search API는 AI 에이전트(LLM)를 위해 특별히 구축된 검색 엔진으로, 실시간으로 정확하고 사실적인 결과를 빠르게 제공해요.

개요 (Overview)

통합 세부 정보 (Integration details)

클래스	패키지	PY 지원	Downloads	Version
`TavilySearch`	`@langchain/tavily`	✅

툴 기능 (Tool features)

아티팩트 반환	네이티브 비동기	반환 데이터	가격
❌	✅	title, URL, content snippet, raw_content, answer, images	1,000 free searches / month

설정 (Setup)

이 통합은 @langchain/tavily 패키지에 있어요:

```bash npm npm install @langchain/tavily @langchain/core ```

yarn add @langchain/tavily @langchain/core

pnpm add @langchain/tavily @langchain/core

자격 증명 (Credentials)

Tavily API 키를 만들고 TAVILY_API_KEY 환경 변수로 설정하세요.

process.env.TAVILY_API_KEY = "YOUR_API_KEY"

최고 수준의 관측 가능성을 위해 LangSmith를 설정하는 것도 도움이 돼요 (필수는 아니에요):

process.env.LANGSMITH_TRACING="true"
process.env.LANGSMITH_API_KEY="your-api-key"

인스턴스화 (Instantiation)

툴은 인스턴스화 시 다양한 파라미터를 받아요:

maxResults (선택, number): 반환할 최대 검색 결과 수. 기본값은 5.
topic (선택, string): 검색 카테고리. "general", "news", "finance" 중 하나. 기본값은 "general".
includeAnswer (선택, boolean): 결과에 원래 쿼리에 대한 답변 포함 여부. 기본값은 false.
includeRawContent (선택, boolean | "markdown" | "text"): 각 검색 결과의 정리·파싱된 콘텐츠 포함 여부. 기본값은 false.
includeImages (선택, boolean): 응답에 쿼리 관련 이미지 목록 포함 여부. 기본값은 false.
includeImageDescriptions (선택, boolean): 각 이미지에 대한 설명 텍스트 포함 여부. 기본값은 false.
searchDepth (선택, string): 검색 깊이. "basic" 또는 "advanced". 기본값은 "basic".
timeRange (선택, string): 현재 날짜부터 결과를 필터링할 시간 범위 — "day", "week", "month", "year". 기본값은 undefined.
includeDomains (선택, string[]): 특별히 포함할 도메인. 기본값은 [].
excludeDomains (선택, string[]): 특별히 제외할 도메인. 기본값은 [].

사용 가능한 파라미터에 대한 종합적인 개요는 Tavily Search API 문서를 참고하세요.

import { TavilySearch } from "@langchain/tavily";

const tool = new TavilySearch({
  maxResults: 5,
  topic: "general",
  // includeAnswer: false,
  // includeRawContent: false,
  // includeImages: false,
  // includeImageDescriptions: false,
  // searchDepth: "basic",
  // timeRange: "day",
  // includeDomains: [],
  // excludeDomains: [],
});

호출 (Invocation)

인자로 직접 호출

Tavily 검색 툴은 호출 시 다음 인자를 받아요:

query (필수): 자연어 검색 쿼리.
다음 인자도 호출 중에 설정할 수 있어요: includeImages, searchDepth, timeRange, includeDomains, excludeDomains.
신뢰성·성능상 이유로 응답 크기에 영향을 주는 일부 파라미터는 호출 중에 수정할 수 없어요: includeAnswer와 includeRawContent. 이 제한은 예상치 못한 컨텍스트 윈도우 문제를 방지하고 일관된 결과를 보장해요.

참고: 선택적 인자는 에이전트가 동적으로 설정할 수 있어요. 인스턴스화 때 인자를 설정한 뒤 다른 값으로 호출하면, 호출 때 전달한 값이 사용돼요.

await tool.invoke({ query: "What happened at the last wimbledon" });

ToolCall로 호출

모델이 생성한 ToolCall로도 툴을 호출할 수 있는데, 이 경우 ToolMessage가 반환돼요:

// This is usually generated by a model, but we'll create a tool call directly for demo purposes.
const modelGeneratedToolCall = {
  args: { query: "euro 2024 host nation" },
  id: "1",
  name: tool.name,
  type: "tool_call",
};

const toolMsg = await tool.invoke(modelGeneratedToolCall);

// The content is a JSON string of results
console.log(toolMsg.content.slice(0, 400));

{"query": "euro 2024 host nation", "follow_up_questions": null, "answer": null, "images": [], "results": [{"title": "UEFA Euro 2024 - Wikipedia", "url": "https://en.wikipedia.org/wiki/UEFA_Euro_2024", "content": "Tournament details Host country Germany Dates 14 June – 14 July Teams 24 Venue(s) 10 (in 10 host cities) Final positions Champions Spain (4th title) Runners-up England Tournament statisti

에이전트 내에서 사용 (Use within an agent)

검색 툴을 createAgent에 전달해 LangChain 에이전트와 직접 사용할 수 있어요. 에이전트는 includeDomains, searchDepth, timeRange 같은 파라미터를 툴 호출의 일부로 동적으로 설정할 수 있어요.

아래 예제에서 "What nation hosted Euro 2024? Include only wikipedia sources."를 요청하면 에이전트가 인자를 동적으로 설정해 { query: "Euro 2024 host nation", includeDomains: ["wikipedia.org"] }로 Tavily 검색 툴을 호출해요.

// @lc-docs-hide-cell
import { ChatOpenAI } from "@langchain/openai";

const llm = new ChatOpenAI({
  model: "gpt-5.5",
  temperature: 0,
});

import { TavilySearch } from "@langchain/tavily";
import { createAgent } from "langchain";

// Initialize Tavily Search Tool
const tavilySearchTool = new TavilySearch({
  maxResults: 5,
  topic: "general",
});

const agent = createAgent({
  model: llm,
  tools: [tavilySearchTool],
});

const userInput = "What nation hosted Euro 2024? Include only wikipedia sources.";

const stream = await agent.streamEvents(
  { messages: [["human", userInput]] },
  { version: "v3" },
);

for await (const snapshot of stream.values) {
  const lastMsg = snapshot.messages[snapshot.messages.length - 1];
  if (lastMsg.tool_calls?.length) {
    console.dir(lastMsg.tool_calls, { depth: null });
  } else if (lastMsg.content) {
    console.log(lastMsg.content);
  }
}

API reference

모든 Tavily Search API 기능과 구성에 대한 자세한 문서는 API reference를 참고하세요: docs.tavily.com/documentation/api-reference/endpoint/search

출처: 문서

본문

TavilySearch는 @langchain/tavily 패키지의 검색 툴로, 실시간 검색 결과를 반환해요. maxResults·topic·includeAnswer·searchDepth·timeRange·includeDomains·excludeDomains 등 옵션으로 인스턴스화하고, 쿼리로 직접 호출하거나 createAgent에 툴로 전달할 수 있어요. TAVILY_API_KEY 환경 변수로 API 키를 설정해야 해요.

더 알아보기 (Learn more)

LangChain JavaScript 툴 통합 문서