如何用 TalorData SERP API 建立 LangChain 搜索工具

当 LangChain 代理可以调用外部工具时，它会更有用。

模型可以根据已有上下文回答问题，但工具可以帮助它获取实时信息、查询 API、搜索公开网页结果，或把结构化数据传入后续工作流程。在 LangChain 中，tool 是代理在任务执行中可以调用的函数，而 @tool decorator 是常见的工具定义方式。

对搜索密集型应用来说，这非常重要。

LangChain 代理可能需要回答这类问题：

• 今天哪些页面在这个关键词下有排名？
• 哪些竞争对手出现在 Google Search 结果中？
• 这个主题最近有哪些市场报告？
• 哪些来源网址应该用于 RAG 工作流程？
• 当前可见的商品页或新闻结果有哪些？

静态知识库不足以完成这些任务。

使用 TalorData SERP API，开发者可以让 LangChain 代理获取实时、结构化搜索结果。工具会把搜索查询发送到 TalorData，接收 SERP JSON 数据，并把干净上下文返回给代理。

实际流程如下：

用户问题
↓
LangChain 代理
↓
TalorData SERP 搜索工具
↓
结构化搜索结果
↓
来源筛选
↓
代理回答或 RAG 工作流程

这篇文章会说明如何用 TalorData SERP API 建立 LangChain 搜索工具、应返回哪些字段、如何连接到代理，以及如何让工作流程保持可靠。

为什么要为 LangChain 建立搜索工具？

LangChain 代理可以把模型和工具组合起来使用。create_agent 接口可以配置模型、工具和系统提示词，让代理在执行过程中调用工具。

搜索工具可以让代理获取最新公开网页信息。

这适合：

目标不是让代理每次都搜索。

目标是在用户询问依赖当前搜索结果的信息时，给代理一个可靠搜索工具。

为什么使用 TalorData SERP API？

TalorData 为 AI 代理、SEO 工具、搜索工作流程、市场监控系统和 RAG pipeline 提供结构化 SERP 数据。

与其让代理手动浏览或解析原始搜索结果页面，TalorData 可以返回更容易筛选、存储、摘要并传入 LangChain 的结构化搜索数据。

TalorData 支持多搜索引擎 SERP 数据采集，包括 Google、Bing、Yandex 和 DuckDuckGo，并为开发者工作流程提供可直接使用的 JSON 输出。

对 LangChain 搜索工具来说，结构化输出比原始页面更重要。

好的搜索结果应包含：

对大多数 LangChain 代理来说，JSON 是最好的起点。

它更容易筛选、摘要、存储，也更容易传入后续工作流程。

搜索工具架构

简单的 LangChain 搜索工具包含四个部分：

流程如下：

代理收到用户问题
↓
代理判断是否需要搜索
↓
代理调用 talordata_search()
↓
工具发送 SERP 请求
↓
工具解析结构化结果
↓
代理使用结果回答或继续工作流程

保持工具范围清晰。

搜索工具应该负责搜索并返回结构化结果。抓取页面、撰写最终报告、评估来源可信度和生成商业建议，应该放在不同步骤中处理。

步骤 1：定义工具输入

先从少量输入开始。

有用参数包括：

输入示例：

{
  "query": "best customer support software",
  "country": "us",
  "language": "en",
  "device": "desktop",
  "num_results": 5
}

不要一开始就暴露所有 SERP 参数。

先保持简单。等工作流程真的需要时，再加入更多控制项。

步骤 2：建立 TalorData 搜索函数

搜索函数应调用 TalorData SERP API，并返回结构化结果。

敏感信息应使用环境变量。

import os
import requests
from typing import Any

TALORDATA_API_KEY = os.getenv("TALORDATA_API_KEY")
TALORDATA_SERP_API_URL = os.getenv("TALORDATA_SERP_API_URL")

def call_talordata_serp_api(
    query: str,
    country: str = "us",
    language: str = "en",
    device: str = "desktop",
    num_results: int = 5,
) -> dict[str, Any]:
    if not TALORDATA_API_KEY:
        raise ValueError("Missing TALORDATA_API_KEY environment variable.")

    if not TALORDATA_SERP_API_URL:
        raise ValueError("Missing TALORDATA_SERP_API_URL environment variable.")

    payload = {
        "engine": "google",
        "q": query,
        "country": country,
        "language": language,
        "device": device,
        "num_results": num_results,
    }

    response = requests.post(
        TALORDATA_SERP_API_URL,
        headers={
            "Authorization": f"Bearer {TALORDATA_API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=30,
    )

    response.raise_for_status()
    return response.json()

请使用 TalorData dashboard 或 API 文档中的 endpoint 和请求格式。

重要设计原则很简单：

将 API 调用和 LangChain tool wrapper 分开。

这会让测试更容易。

步骤 3：标准化 SERP 结果

代理不需要所有原始字段。

只返回能帮助代理理解和使用结果的字段。

from urllib.parse import urlparse
from typing import Any

def extract_domain(url: str) -> str:
    try:
        return urlparse(url).netloc.replace("www.", "")
    except Exception:
        return ""

def normalize_serp_results(
    data: dict[str, Any],
    num_results: int = 5,
) -> list[dict[str, Any]]:
    raw_results = (
        data.get("organic_results")
        or data.get("results")
        or []
    )

    normalized_results = []

    for item in raw_results[:num_results]:
        url = item.get("url") or item.get("link") or ""

        normalized_results.append(
            {
                "position": item.get("position"),
                "title": item.get("title"),
                "url": url,
                "domain": item.get("domain") or extract_domain(url),
                "snippet": item.get("snippet") or item.get("description"),
            }
        )

    return normalized_results

标准化结果应该像这样：

{
  "position": 1,
  "title": "Best Customer Support Software for Growing Teams",
  "url": "https://www.example.com/customer-support-software",
  "domain": "example.com",
  "snippet": "Compare customer support platforms by features, pricing, automation, and team size."
}

代理可以用它比较来源、选择网址、摘要 snippet，或把来源网址传入其他工作流程。

步骤 4：将函数包装成 LangChain Tool

LangChain 的 @tool decorator 可以把 Python 函数转成工具。Type hints 有助于定义输入 schema，函数 docstring 则帮助模型理解何时应使用工具。

简单工具封装如下：

from typing import Any
from langchain.tools import tool

@tool("talordata_google_search")
def talordata_google_search(
    query: str,
    country: str = "us",
    language: str = "en",
    device: str = "desktop",
    num_results: int = 5,
) -> dict[str, Any]:
    """
    Search Google using TalorData SERP API and return structured SERP results.

    Use this tool when the user asks for fresh public web information,
    current Google search results, SEO research, competitor pages,
    market research sources, or source URLs for RAG workflows.
    """
    data = call_talordata_serp_api(
        query=query,
        country=country,
        language=language,
        device=device,
        num_results=num_results,
    )

    results = normalize_serp_results(data, num_results=num_results)

    return {
        "query": query,
        "country": country,
        "language": language,
        "device": device,
        "results": results,
    }

docstring 很重要。

弱描述：

Search Google.

更好的描述：

Search Google using TalorData SERP API and return structured SERP results. Use this for fresh public web information, SEO research, competitor pages, market research, and source discovery.

模型会根据工具描述判断是否使用工具。

步骤 5：将工具连接到 LangChain Agent

把 TalorData 搜索工具传入 LangChain agent。

from langchain.agents import create_agent

tools = [talordata_google_search]

agent = create_agent(
    model="provider:model-name",
    tools=tools,
    system_prompt=(
        "You are a research assistant. "
        "Use the TalorData search tool only when the user asks for current, "
        "public, search-based, or source-discovery information. "
        "When using search results, mention the most relevant source URLs."
    ),
)

然后调用代理：

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": (
                    "Find recent sources about AI customer support tools "
                    "and summarize the top visible pages."
                ),
            }
        ]
    }
)

print(result)

模型服务商和模型名称应配合你自己的 LangChain 设置。

此时，搜索工具已可被代理使用。

步骤 6：控制代理何时搜索

好的搜索工具不应该对每个问题都被调用。

应使用 system prompt 和工具描述来引导代理。

适合搜索的触发条件包括：

通常不需要工具的情况包括：

这种区分可以让代理更快，也更容易评估。

步骤 7：使用结果前先筛选

搜索结果不会自动成为好来源。

代理回答前应先筛选。

有用筛选规则包括：

你可以在工具内加入筛选：

from typing import Any

def filter_results(results: list[dict[str, Any]]) -> list[dict[str, Any]]:
    seen_urls = set()
    filtered = []

    for result in results:
        url = result.get("url")

        if not url or url in seen_urls:
            continue

        if not result.get("title"):
            continue

        seen_urls.add(url)
        filtered.append(result)

    return filtered[:5]

然后更新工具：

results = normalize_serp_results(data, num_results=num_results)
results = filter_results(results)

对 RAG 工作流程来说，这一步更重要。

坏来源会形成坏上下文。坏上下文会带来不可靠回答。

步骤 8：用搜索工具做 RAG 来源发现

TalorData 搜索工具可以放在 RAG 步骤之前使用。

模式很简单：

用户提出研究问题
↓
代理使用 TalorData 搜索
↓
工具返回标题、摘要和网址
↓
代理选择有用网址
↓
工作流程抓取或索引选中页面
↓
RAG 回答使用选中的来源内容

适合：

搜索用于来源发现。

RAG 用于使用选中的来源内容。

这两个步骤应该分开处理。

步骤 9：加入错误处理

搜索工具应该能优雅失败。

常见失败情况包括：

示例：

import requests
from typing import Any
from langchain.tools import tool

@tool("talordata_google_search")
def talordata_google_search(
    query: str,
    country: str = "us",
    language: str = "en",
    device: str = "desktop",
    num_results: int = 5,
) -> dict[str, Any]:
    """
    Search Google using TalorData SERP API and return structured SERP results.
    Use this for fresh public web information, SEO research,
    competitor research, market research, and source discovery.
    """
    try:
        data = call_talordata_serp_api(
            query=query,
            country=country,
            language=language,
            device=device,
            num_results=num_results,
        )

        results = normalize_serp_results(data, num_results=num_results)
        results = filter_results(results)

        return {
            "query": query,
            "country": country,
            "language": language,
            "device": device,
            "results": results,
        }

    except requests.Timeout:
        return {
            "error": "Search request timed out.",
            "query": query,
        }

    except requests.HTTPError as error:
        return {
            "error": "Search API request failed.",
            "details": str(error),
            "query": query,
        }

    except Exception as error:
        return {
            "error": "Unexpected search tool error.",
            "details": str(error),
            "query": query,
        }

错误处理是工具设计的一部分。

如果工具静默失败，代理可能会在上下文不完整的情况下继续执行。

步骤 10：记录搜索行为

如果这个工具用在生产环境，应记录搜索行为。

有用字段包括：

日志有助于：

• 调试
• 评估
• 来源审核
• 成本追踪
• 提示词改进
• 工具行为分析
• 合规审核

具备搜索能力的代理应该可追踪。

如果它搜索了，你应该知道它搜了什么、找到什么，以及用了什么。

直接工具、SDK，还是 MCP？

将 TalorData 搜索数据接入 LangChain workflow，通常有三种实用方式：

本文使用自定义工具方式，是为了展示底层设计。

在生产环境中，SDK 或 MCP integration 可以降低维护成本，也更容易让搜索能力在多个代理和工作流程中复用。

TalorData 如何支持 LangChain 搜索工作流程？

TalorData 可以作为 LangChain agents 的结构化 SERP 数据层。

与其让代理手动浏览或处理原始搜索页面，开发者可以使用 TalorData 获取结构化搜索结果，其中包含适合代理推理和后续工作流程使用的字段。

典型流程如下：

LangChain 代理
↓
TalorData SERP 工具
↓
结构化 Google Search 结果
↓
筛选后的来源网址
↓
回答、报告、仪表盘或 RAG 工作流程

这支持以下使用场景：

价值不只是能搜索。

真正的价值是提供 LangChain 代理可以实际使用的、结构化且可重复利用的搜索上下文。

结语

用 TalorData SERP API 建立 LangChain 搜索工具，可以让代理获取实时搜索上下文。

基本流程是：

定义搜索输入。
调用 TalorData SERP API。
标准化搜索结果。
将函数包装成 LangChain tool。
把工具连接到 agent。
控制代理何时搜索。
回答前先筛选结果。
记录搜索行为。
必要时将选中网址用于 RAG。

对 SEO 工具、研究代理、竞争对手监控、内容规划、市场情报和 RAG 工作流程来说，结构化搜索工具可以让 LangChain 代理更有用。

代理负责推理。

TalorData 提供结构化搜索数据。

工具把两者连接起来。

FAQ

LangChain 代理可以使用自定义搜索工具吗？

可以。LangChain tools 是具有明确输入和输出的可调用函数，代理可以在任务执行中使用工具。

TalorData 搜索工具应该返回什么？

有用搜索工具应返回结构化 SERP 结果，包括 position、title、url、domain、snippet、country、language、device 和 collection time。

工具应该返回原始 HTML 吗？

通常不需要。对代理来说，结构化 JSON 通常更容易使用。原始 HTML 更适合进阶解析或自定义 SERP 模块提取。

这个工具可以支持 RAG 工作流程吗？

可以。搜索工具可以发现相关来源网址。后续可用独立提取或抓取步骤获取选中页面内容，用于 RAG。

应该使用 SDK、MCP，还是自定义工具？

想理解或完全控制流程时，可以使用自定义工具。需要快速原型时，SDK 更适合。需要生产环境或多代理共享搜索服务时，MCP 更适合。