tavily-python

环境要求

• Python 环境（README 未指定具体版本，需能运行 pip）
• 可访问 Tavily 公开 API 的网络环境
• 有 Tavily API Key 可解锁全部接口（可选，无 Key 可先用 keyless 模式）

安装与启动步骤

1. 1安装 SDK

   在目标 Python 环境中用 pip 安装官方包 tavily-python，安装完成后即可在代码中导入 TavilyClient。

   pip install tavily-python

   复制

2. 2免 Key 试用搜索

   不传任何参数实例化 TavilyClient 即进入 keyless 模式，仅支持 search() 与 extract()，且受速率限制。

   from tavily import TavilyClient, TavilyKeylessLimitError
   
   client = TavilyClient()
   
   try:
       response = client.search("Who is Leo Messi?")
       print(response)
   except TavilyKeylessLimitError as e:
       print(e)
       print("retry after:", e.retry_after_seconds, "seconds")

   复制

3. 3配置 API Key

   需要更高限额以及 crawl、map、research 等完整接口时，去 tavily.com 注册获取 Key，并以 api_key 参数传入客户端。

   from tavily import TavilyClient
   
   tavily_client = TavilyClient(api_key="tvly-xxxxxxxx")

   复制

4. 4调用搜索接口

   用配置好的客户端调用 search 查询关键词，返回结构化搜索结果，可直接用于 Agent 或 RAG 流程。

   response = tavily_client.search("Who is Leo Messi?")
   print(response)

   复制

5. 5查询研究额度消耗

   research 任务默认不返回用量数据，需在获取结果时显式开启 include_usage，再从 usage.credits 读取消耗。

   result = tavily_client.get_research(request_id, include_usage=True)
   print(result.get("usage", {}).get("credits"))

   复制

关键配置

如何确认成功

运行 client.search("Who is Leo Messi?") 能打印出结构化结果（或 keyless 模式的限流异常信息）即表示安装与调用链路正常。

常见问题

注意事项

• keyless 模式仅支持 search 和 extract，crawl、map、research 必须提供 API Key。
• Keyless 调用有速率上限，生产环境建议注册正式 Key 以获得更高限额。
• 示例中的 tvly-xxxxxxxx 是占位值，请替换为你自己的真实 Key，避免泄露。