Tavily Research 도구

Tavily Research 도구 (TavilyResearchTool)

CrewAI의 TavilyResearchTool은 Tavily 리서치 태스크를 시작해서, raw 검색 결과 대신 종합되고 인용이 포함된 리포트(또는 진행 이벤트 스트림)를 반환하는 도구예요. 단일 웹 검색이 아니라 조사형 답변이 필요할 때 사용하세요.

출처: 문서

본문

TavilyResearchTool은 Tavily 리서치 태스크를 시작해 raw 검색 결과 대신 종합되고 인용이 포함된 리포트(또는 진행 이벤트 스트림)를 반환합니다. 단일 웹 검색이 아닌 조사형 답변이 필요할 때 사용하세요.

설치 (Installation)

TavilyResearchTool을 사용하려면 crewai-tools와 함께 tavily-python 라이브러리를 설치하세요.

uv add 'crewai[tools]' tavily-python

환경변수 (Environment Variables)

Tavily API 키를 설정하세요.

export TAVILY_API_KEY='your_tavily_api_key'

API 키는 https://app.tavily.com/에서 받을 수 있어요 (가입 후 키 생성).

사용 예시 (Example Usage)

import os
from crewai import Agent, Crew, Task
from crewai_tools import TavilyResearchTool

# 환경에 TAVILY_API_KEY가 설정되어 있는지 확인
# os.environ["TAVILY_API_KEY"] = "YOUR_API_KEY"

tavily_tool = TavilyResearchTool()

researcher = Agent(
    role="Research Analyst",
    goal="Investigate questions and produce concise, well-cited briefings.",
    backstory=(
        "You are a meticulous analyst who delegates web research to the Tavily "
        "Research tool, then synthesizes the findings into short briefings."
    ),
    tools=[tavily_tool],
    verbose=True,
)

research_task = Task(
    description=(
        "Investigate notable open-source agent orchestration frameworks released "
        "in the last six months and summarize their differentiators."
    ),
    expected_output="A bulleted briefing with citations.",
    agent=researcher,
)

crew = Crew(agents=[researcher], tasks=[research_task])
print(crew.kickoff())

설정 옵션 (Configuration Options)

TavilyResearchTool은 다음 인자를 받습니다. 모두 도구 인스턴스(모든 호출의 기본값)에 설정하거나 에이전트의 도구 입력을 통해 호출별로 설정할 수 있어요.

input (str): 필수. 조사할 리서치 태스크 또는 질문.
model (Literal["mini", "pro", "auto"]): Tavily 리서치 모델. "auto"는 Tavily가 선택, "mini"는 더 빠르고 저렴, "pro"는 가장 강력. 기본값 "auto".
output_schema (dict | None): 리서치 출력을 구조화하는 선택적 JSON Schema. 엄격하게 타입이 지정된 결과가 필요할 때 유용.
stream (bool): True이면 도구가 단일 문자열 대신 리서치 진행과 최종 결과를 내보내는 SSE 청크의 이터레이터를 반환. 기본값 False.
citation_format (Literal["numbered", "mla", "apa", "chicago"]): 리포트의 인용 형식. 기본값 "numbered".

고급 사용법 (Advanced Usage)

도구 인스턴스에 기본값 설정하기

from crewai_tools import TavilyResearchTool

tavily_tool = TavilyResearchTool(
    model="pro",                # Tavily의 가장 강력한 리서치 모델 사용
    citation_format="apa",      # APA 스타일 인용
)

리서치 진행 스트리밍하기

stream=True이면 도구가 SSE 청크의 제네레이터(_arun에서는 async 제네레이터)를 반환해 애플리케이션이 점진적 진행 상황을 표시할 수 있어요.

tavily_tool = TavilyResearchTool(stream=True)

for chunk in tavily_tool.run(input="Summarize recent advances in retrieval-augmented generation."):
    print(chunk)

JSON Schema를 통한 구조화된 출력

자유 형식 리포트 대신 타입이 지정된 결과가 필요할 때 output_schema를 전달하세요.

output_schema = {
    "type": "object",
    "properties": {
        "summary": {"type": "string"},
        "key_points": {"type": "array", "items": {"type": "string"}},
        "sources": {"type": "array", "items": {"type": "string"}},
    },
    "required": ["summary", "key_points", "sources"],
}

tavily_tool = TavilyResearchTool(output_schema=output_schema)

기능 (Features)

종단 간 리서치: raw 검색 히트가 아니라 종합되고 인용된 리포트를 반환
모델 선택: mini, pro, auto를 통해 비용, 속도, 심도를 조절
스트리밍: 반응형 UI를 위해 SSE 청크로 점진적 진행과 결과 스트리밍
구조화된 출력: 정의한 JSON Schema로 결과 강제
여러 인용 스타일: numbered, MLA, APA, Chicago 인용 선택
동기 및 비동기: 애플리케이션 런타임에 따라 _run 또는 _arun 사용

Research API에 대한 전체 세부 내용은 Tavily API 문서를 참고하세요.

Tavily Research 도구