Tavily 研究工具

使用 Tavily Research API 运行多步骤研究任务并获取带引用的报告

TavilyResearchTool 让 CrewAI 智能体可以启动 Tavily 研究任务，返回综合了引用来源的报告（或进度事件流），而不是原始搜索结果。当智能体需要的是调查性答案而非单次网络搜索时，请使用它。

安装

要使用 TavilyResearchTool，请将 tavily-python 库与 crewai-tools 一起安装：

uv add 'crewai[tools]' tavily-python

环境变量

设置你的 Tavily API 密钥：

export TAVILY_API_KEY='your_tavily_api_key'

在 https://app.tavily.com/ 获取 API 密钥（注册后创建一个密钥）。

用法示例

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

# Ensure TAVILY_API_KEY is set in your environment
# 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())

配置选项

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"。

高级用法

在工具实例上配置默认值

from crewai_tools import TavilyResearchTool

tavily_tool = TavilyResearchTool(
    model="pro",                # use Tavily's most capable research model
    citation_format="apa",      # APA-style citations
)

流式输出研究进度

当 stream=True 时，工具返回一个 SSE 分块的生成器（或来自 _arun 的异步生成器），以便你的应用可以呈现增量进度：

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)

特性

• 端到端研究：返回经过综合、带引用的报告，而非原始搜索命中结果。
• 模型选择：通过 mini、pro 或 auto 在成本、速度和深度之间取舍。
• 流式传输：以 SSE 分块的形式流式输出增量进度和结果，用于响应式 UI。
• 结构化输出：将结果强制为你定义的 JSON Schema。
• 多种引用风格：可从编号、MLA、APA 或 Chicago 引用格式中选择。
• 同步与异步：根据应用的运行时选择使用 _run 或 _arun。

有关 Research API 的完整细节，请参阅 Tavily API 文档。