CrewAI 中 Tavily Research Tool 深度使用指南接入 Tavily 研究 API 实现结构化网络研究【免费下载链接】crewAIFramework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.项目地址: https://gitcode.com/GitHub_Trending/cr/crewAITavily Research Tool 是 crewAI 官方工具库crewai-tools中对接 Tavily Research 服务的高层封装让 CrewAI 的 Agent 能够发起一个多步骤深度网络研究任务并可选地通过 Server-Sent EventsSSE流式接收研究进度与结果。读完本文你将掌握该工具的安装、环境配置、在 Agent/Crew 中的集成、五大核心参数input/model/output_schema/stream/citation_format的完整语义、结构化输出 Schema 与四种引文格式并能从源码层面理解其同步/异步调用链与底层实现原理。工具概览与定位Tavily Research Tool 的实现位于 tavily_research_tool.py与 Tavily 系列的其他工具如TavilySearchTool、TavilyExtractorTool、TavilyGetResearchTool见 tools/init.py同属 crewai-tools 的搜索与检索工具家族。它内部创建的是 Tavily 的TavilyClient/AsyncTavilyClient并在构造时传入client_namecrewai见 tavily_research_tool.py因此可以理解为官方 SDK 之上的一层工具化适配输入一句研究任务描述input执行Tavily Research 服务端的多步骤研究流程输出研究完成后的 JSON 字符串或streamTrue时的 SSE 字节块生成器。与传统的搜索→取链接→读网页三步走方案不同该工具把整条深挖链路下沉到 Tavily 研究服务Agent 只需调用一次run()即可拿到带引用的结构化研究报告。安装与前置环境安装依赖TavilyResearchTool 依赖tavily-python官方库。推荐在已经安装了crewai[tools]的项目中执行uv add crewai[tools] tavily-python从源码看该工具类声明了package_dependencies: [tavily-python]见 tavily_research_tool.py并在__init__中尝试from tavily import AsyncTavilyClient, TavilyClient若导入失败会弹出确认框提示自动安装tavily-python或提示手动执行uv add tavily-python后重启应用见 tavily_research_tool.py。因此如果仓库根目录的 pyproject.toml 未包含该依赖直接from crewai_tools import TavilyResearchTool会在初始化时触发依赖提醒。配置 API Key初始化时工具会读取环境变量TAVILY_API_KEYexport TAVILY_API_KEYyour_tavily_api_key也可以在 .env 文件中配置因为源码顶部调用了load_dotenv()见 tavily_research_tool.py。该 Key 被声明为必需项工具类通过env_vars字段注册了EnvVar(nameTAVILY_API_KEY, ..., requiredTrue)见 tavily_research_tool.py这与基类 BaseTool 的env_vars协议一致。若 Key 缺失Tavily 服务端会拒绝请求。在 CrewAI Agent 中使用下面是一个将TavilyResearchTool挂载到 Researcher Agent并通过 Crew 编排一次AI 基础设施初创公司最新进展调研任务的完整示例对应官方 READMEfrom crewai import Agent, Task, Crew from crewai_tools import TavilyResearchTool # Initialize the tool tavily_research_tool TavilyResearchTool() # Create an agent that uses the tool researcher Agent( roleResearch Analyst, goalProduce structured research reports, backstoryAn expert analyst who uses Tavily Research for deep web research., tools[tavily_research_tool], verboseTrue, ) # Create a task for the agent research_task Task( descriptionResearch the latest developments in AI infrastructure startups., expected_outputA detailed report with citations and supporting sources., agentresearcher, ) # Run the crew crew Crew( agents[researcher], tasks[research_task], verbose2, ) result crew.kickoff() print(result)关键点工具无需传入args_schema之外的任何字段即可运行默认参数由类字段兜底modelauto、streamFalse、citation_formatnumbered。在 Agent 执行 Task 时LLM 会依据工具的name/description决定何时调用它因此建议将 research 类任务拆分为独立 Task以保证 Agent 明确在何时使用该工具。直接调用 run() 的三种用法工具支持脱离 Agent 单独使用run()与官方 SDK 的research()在参数上保持一致提供了三种典型用法。用法一默认研究非流式、无 Schemaresult tavily_research_tool.run( inputResearch the latest developments in AI infrastructure startups. )返回 JSON 字符串含研究内容与引用。用法二结构化输出output_schema 引文格式Tavily 会根据 JSON Schema 将研究结果规整为结构化数据。官方 README 的完整示例structured_result tavily_research_tool.run( inputResearch the latest developments in AI infrastructure startups., modelpro, output_schema{ properties: { summary: { type: string, description: A concise summary of the research findings, }, key_trends: { type: array, description: The major trends identified in the research, items: {type: string}, }, companies: { type: array, description: Notable companies mentioned in the research, items: { type: object, description: A company entry, properties: { name: { type: string, description: The company name, }, focus: { type: string, description: The companys main area of focus, }, notable_update: { type: string, description: A notable recent update about the company, }, }, required: [name, focus, notable_update], }, }, }, required: [summary, key_trends, companies], }, citation_formatapa, ) print(structured_result)关于output_schema有三点来自官方 README 的约束务必遵守Schema 顶层必须包含propertiesrequired为可选项每个property都应携带description用于引导 Tavily 研究模型生成对应字段内容该 Schema 是传给 Tavily 服务端约束输出的契约而非本地 Pydantic 模型——工具本身不校验 Schema 结构。用法三流式输出streamTruestream tavily_research_tool.run( inputResearch the latest developments in AI infrastructure startups., modelmini, streamTrue, ) for chunk in stream: print(chunk.decode(utf-8, errorsreplace), end)当streamTrue时返回值为 SSE 事件流的字节块生成器调用方逐块decode(utf-8)即可实时呈现研究进度适合长耗时任务的进度展示与日志场景。参数详解Arguments工具参数在初始化或调用run()时均可传入二者语义略有差异。官方 README 的参数清单及源码默认值见 tavily_research_tool.py整理如下参数类型默认值说明inputstr必填要调查的研究任务或问题modelLiteral[mini, pro, auto]auto使用的 Tavily 研究模型output_schemadict[str, Any] \| NoneNone约束研究输出的 JSON SchemastreamboolFalse是否返回 Tavily 流式 SSE chunk 生成器citation_formatLiteral[numbered, mla, apa, chicago]numbered报告的引文格式参数优先级规则源码可证实_run()中每个可空参数都遵循None则回退到实例字段默认值的逻辑见 tavily_research_tool.py在TavilyResearchTool(...)构造时设置的是实例级默认值如TavilyResearchTool(modelpro)在run(...)中显式传入的值会覆盖对应实例默认值run()中未传的参数使用实例字段最终由类字段默认auto/False/numbered/None兜底。返回格式与响应处理工具按调用方式返回两种结果官方 README Response Format 一节非流式研究返回 JSON 字符串。实现上若 Tavily 返回原生字符串则原样透传否则通过json.dumps(response, indent2)格式化后返回见 tavily_research_tool.py流式研究返回Generator[bytes, None, None]SSE 字节块生成器。更完整的响应体结构与流式事件格式以 Tavily Research API 官方文档为准——crewai 这一层只负责参数透传与结果的字符串化不解析、不裁剪响应内容。源码级原理同步与异步双通道TavilyResearchTool继承自 crewAI 的 BaseTool实现了_run与_arun两条执行路径这也是 CrewAI Agent 在同步/异步编排场景下会分别调用的底层方法。构造阶段tavily_research_tool.py在TAVILY_AVAILABLE时同时创建TavilyClient同步与AsyncTavilyClient异步两个私有客户端api_key均取自环境变量并携带client_namecrewai标识请求来源。同步调用链tavily_research_tool.py校验同步客户端已初始化否则抛出带安装指引的ValueError用参数优先级规则合并model/output_schema/citation_formatstream同理调用self._client.research(...)streamTrue时将底层生成器cast为Generator[bytes, None, None]返回否则调用_stringify_response转成格式化 JSON 字符串。异步调用链tavily_research_tool.py结构与同步版本一一对应区别在于使用AsyncTavilyClient.research(...)await并返回AsyncGenerator[bytes, None]。因此在高并发 Crew 编排中异步调用不会阻塞事件循环。这一同步 异步双实现模式在 crewai-tools 的多数工具中保持一致便于在 tools/init.py 导出、对外统一以from crewai_tools import TavilyResearchTool方式使用。常见问题与排查建议ImportError: tavily-python is required说明tavily-python未安装或安装失败。手动执行uv add tavily-python或pip install tavily-python后重启 Python 进程再初始化工具。ValueError: Tavily client is not initialized多因依赖缺失导致客户端创建失败构造时走到了 else 分支。请先确认安装成功并重启应用。401 / API key 无效确认TAVILY_API_KEY环境变量已正确导出或写入 .env源码在模块级调用load_dotenv()且 Key 仍有有效配额。结构化输出不生效检查output_schema是否满足 Tavily 契约顶层含properties、每个属性带description。model取值越界仅支持mini、pro、auto类型注解为Literal传其他值会触发 pydantic 校验错误。小结TavilyResearchTool把深度多步网络研究压缩为一次工具调用通过output_schema获得可直接喂给下游 Agent 或程序的 JSON 结构化结果通过citation_format控制报告引用样式通过stream支持实时流式展示是 CrewAI 工作流中构建研究分析师角色的实用组件。其源码位于 tavily_research_tool.py实际研究执行能力由 Tavily Research 服务提供底层细节请以 Tavily Research API 官方文档为准。【免费下载链接】crewAIFramework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.项目地址: https://gitcode.com/GitHub_Trending/cr/crewAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考