如何用 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 更適合。