Tavily 研究工具

TavilyResearchTool 让 CrewAI 智能体可以启动 Tavily 研究任务，返回一份综合整理、带引用的报告（或一个进度事件流），而不是原始搜索结果。当智能体需要的是调查性答案，而不是单次网页搜索时，应使用它。

安装

要使用 TavilyResearchTool，请同时安装 tavily-python 库和 crewai-tools：

uv add 'crewai[tools]' tavily-python

环境变量

设置你的 Tavily API key：

export TAVILY_API_KEY='your_tavily_api_key'

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

使用示例

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())

配置选项

TavilyResearchTool 接受以下参数 - 它们都可以在工具实例上设置（作为每次调用的默认值），也可以通过智能体的工具输入在单次调用中设置：

input (str)：必需。要调查的研究任务或问题。
model (Literal[“mini”, “pro”, “auto”])：Tavily 研究模型。"auto" 让 Tavily 自行选择；"mini" 更快/更便宜；"pro" 能力最强。默认值为 "auto"。
output_schema (dict | None)：可选的 JSON Schema，用于结构化研究输出。当你希望结果具有严格类型时很有用。
stream (bool)：当为 True 时，工具会返回一个 SSE chunk 迭代器，持续输出研究进度和最终结果，而不是返回单个字符串。默认值为 False。
citation_format (Literal[“numbered”, “mla”, “apa”, “chicago”])：报告的引用格式。默认值为 "numbered"。

高级用法

在工具实例上配置默认值

from crewai_tools import TavilyResearchTool

tavily_tool = TavilyResearchTool(
    model="pro",                # 使用 Tavily 最强大的研究模型
    citation_format="apa",      # APA 格式引用
)

流式获取研究进度

当 stream=True 时，工具会返回 SSE chunk 的生成器（或者 _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 chunk 的形式流式传输增量进度和结果，适合响应式界面。
结构化输出：将结果约束为你定义的 JSON Schema。
多种引用风格：可选择编号、MLA、APA 或 Chicago 引用。
同步与异步：根据应用运行时，使用 _run 或 _arun。

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