Tavily 크롤 통합

Tavily 크롤 통합 (Tavily crawl integration)

LangChain JavaScript로 Tavily 크롤 툴과 통합해요.

Tavily는 AI 에이전트(LLM)를 위해 특별히 구축된 검색 엔진으로, 실시간으로 정확하고 사실적인 결과를 빠르게 제공해요. Tavily는 시작 URL에서 구조화된 웹 순회(traversal)를 수행하는 Crawl 엔드포인트를 제공하며, 내장된 콘텐츠 추출과 지능형 발견을 포함해요.

개요 (Overview)

통합 세부 정보 (Integration details)

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

툴 기능 (Tool features)

설정 (Setup)

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

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)

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

• maxDepth (선택, number): 시작 URL에서 최대 홉(hop) 수. 기본값은 3.
• maxBreadth (선택, number): 레벨당 크롤할 최대 페이지 수. 기본값은 50.
• limit (선택, number): 크롤할 총 최대 페이지 수. 기본값은 100.
• instructions (선택, string): 크롤러를 안내하는 자연어 지침.
• selectPaths (선택, string[]): 이 경로 정규식을 포함한 URL만 크롤.
• selectDomains (선택, string[]): 이 도메인 정규식만 크롤.
• excludePaths (선택, string[]): 이 경로 정규식을 포함한 URL 건너뜀.
• excludeDomains (선택, string[]): 이 도메인 정규식의 URL 건너뜀.
• allowExternal (선택, boolean): 크롤러가 외부 링크를 따라갈 수 있는지.
• extractDepth (선택, string): 각 크롤 페이지의 추출 깊이 "basic" 또는 "advanced". 기본값은 "basic".
• format (선택, string): "markdown" 또는 "text" 콘텐츠 포맷. 기본값은 "markdown".
• includeImages (선택, boolean): 각 페이지에서 발견된 이미지 포함 여부. 기본값은 false.

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

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

const tool = new TavilyCrawl({
  maxDepth: 3,
  maxBreadth: 50,
  // limit: 100,
  // extractDepth: "basic",
  // format: "markdown",
  // includeImages: false,
  // allowExternal: false,
});

호출 (Invocation)

인자로 직접 호출

Tavily 크롤 툴은 호출 시 다음 인자를 받아요:

• url (필수): 크롤링을 시작할 기본 URL.
• 다음 인자도 호출 중에 설정할 수 있어요: instructions, selectPaths, selectDomains, excludePaths, excludeDomains, allowExternal.

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

await tool.invoke({ url: "https://docs.tavily.com" });

{
  "base_url": "https://docs.tavily.com",
  "results": [
    {
      "url": "https://docs.tavily.com/",
      "raw_content": "... (페이지의 파싱된 콘텐츠) ...",
      "favicon": "https://docs.tavily.com/mintlify-assets/_mintlify/favicons/tavilyai/SXaxSfweEU3ftIlh/_generated/favicon/apple-touch-icon.png"
    },
    {
      "url": "https://docs.tavily.com/documentation/about",
      "raw_content": "... (페이지의 파싱된 콘텐츠) ...",
      "favicon": "https://docs.tavily.com/mintlify-assets/_mintlify/favicons/tavilyai/SXaxSfweEU3ftIlh/_generated/favicon/apple-touch-icon.png"
    },
    {
      "url": "https://docs.tavily.com/documentation/api-reference/introduction",
      "raw_content": "... (페이지의 파싱된 콘텐츠) ...",
      "favicon": "https://docs.tavily.com/mintlify-assets/_mintlify/favicons/tavilyai/SXaxSfweEU3ftIlh/_generated/favicon/apple-touch-icon.png"
    },
    {
      "url": "https://github.com/tavily-ai",
      "raw_content": "... (페이지의 파싱된 콘텐츠) ...",
      "favicon": "https://github.githubassets.com/favicons/favicon.svg"
    }
  ],
  "response_time": 13.45
}

각 results 항목은 크롤된 URL의 raw_content(마크다운/텍스트 추출 결과), favicon 등을 포함해요.

ToolCall로 호출

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

// This is usually generated by a model, but we'll create a tool call directly for demo purposes.
const modelGeneratedToolCall = {
  args: {
    url: "https://docs.tavily.com",
    instructions: "Find API reference pages",
  },
  id: "1",
  name: tool.name,
  type: "tool_call",
};

const toolMsg = await tool.invoke(modelGeneratedToolCall);

console.log(toolMsg.content.slice(0, 400));

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

크롤 툴을 createAgent에 전달해 LangChain 에이전트와 직접 사용할 수 있어요. 에이전트는 툴 호출의 일부로 url, instructions, 경로/도메인 필터를 동적으로 설정할 수 있어요.

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

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

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

const tavilyCrawlTool = new TavilyCrawl({
  maxDepth: 1,
  maxBreadth: 10,
  limit: 10,
});

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

const userInput = "Crawl https://docs.tavily.com and find the API reference for the search endpoint.";

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 Crawl API 기능과 구성에 대한 자세한 문서는 API reference를 참고하세요: docs.tavily.com/documentation/api-reference/endpoint/crawl

출처: 문서

본문

TavilyCrawl은 시작 URL에서 구조화된 웹 순회를 수행하는 툴이에요. maxDepth·maxBreadth·limit·instructions·selectPaths·selectDomains·excludePaths·excludeDomains·allowExternal·extractDepth·format·includeImages 등 옵션으로 인스턴스화하고, url로 직접 호출하거나 createAgent에 툴로 전달할 수 있어요. 응답은 크롤된 각 페이지의 url과 raw_content(마크다운/텍스트)를 포함해요.

더 알아보기 (Learn more)

• LangChain JavaScript 툴 통합 문서