为 LangChain 搜索链路补齐审计记录

一个具备网页搜索能力的 LangChain Agent 可以结合更新鲜的上下文来回答问题，但仅仅保证信息新鲜还不够。

当答案看起来不对时，你需要知道 Agent 搜索了什么、使用了哪些 URL、搜索发生在什么时间，以及哪些结果被传入了最终 prompt。如果没有这些追踪记录，调试就只能靠猜。

本文将介绍一种简单的实现模式：使用 TalorData SERP API，为 LangChain 的搜索步骤记录来源 URL 和时间戳，使整个过程可审计。

已经确认可用的 LangChain package 是 langchain-talordata。

pip install langchain-talordata

设置该 package 所需的环境变量：

export TALOR_API_KEY="<TALORDATA_TOKEN>"

一种常见的初始化方式如下：

from langchain_talordata import TalorSerpTool

search_tool = TalorSerpTool.from_env()

该 package 会读取 TALOR_API_KEY，其值应当设置为你的 TalorData token。

应该记录哪些内容

一条实用的搜索追踪记录应该能够回答五个问题：

用户提出了什么问题？

Agent 实际搜索了什么 query？

搜索发生在什么时间？

返回了哪些 URL？

最终回答选择了哪些 URL？

这意味着日志既要保留工具调用信息，也要保留最终选中的证据。

可以先从一个简单的数据结构开始：

from dataclasses import dataclass, asdict
from datetime import datetime, timezone
from typing import Any

@dataclass
class SearchTrace:
    user_request: str
    generated_query: str
    searched_at: str
    selected_sources: list[dict[str, Any]]
    result_count: int

时间戳应该在获取搜索结果时生成，而不是等到最终答案生成之后再创建。

def utc_now() -> str:
    return datetime.now(timezone.utc).isoformat()

整理搜索结果的结构

默认情况下，不要把完整的 SERP 响应传入最终 prompt。应该只保留一个精简的来源对象。

def compact_source(item: dict) -> dict:
    return {
        "position": item.get("position"),
        "title": item.get("title"),
        "url": item.get("link"),
        "snippet": item.get("description"),
    }

对于许多 Agent 任务，最先需要保留的来源字段是排名、标题、URL 和摘要。

构建搜索包装器

具体如何封装，取决于你的 LangChain 应用调用工具的方式，但这层边界应该保持清晰：

def search_with_trace(user_request: str, generated_query: str) -> tuple[list[dict], dict]:
    searched_at = utc_now()

    result = search_tool.invoke(generated_query)

    organic = result.get("organic", []) if isinstance(result, dict) else []
    selected_sources = [compact_source(item) for item in organic[:5]]

    trace = SearchTrace(
        user_request=user_request,
        generated_query=generated_query,
        searched_at=searched_at,
        selected_sources=selected_sources,
        result_count=len(organic),
    )

    return selected_sources, asdict(trace)

如果你的工具调用返回的是另一种对象结构，请相应调整提取层。核心思路不变：保留生成的 query、时间戳和选中的 URL。

在最终答案中使用追踪记录

最终 prompt 应该只接收经过筛选的来源，而不是完整的原始响应。

prompt 输入示例：

User request:
{user_request}

Search query:
{generated_query}

Search timestamp:
{searched_at}

Selected sources:
{selected_sources}

Answer the user using the selected sources. If the sources are weak or incomplete, say so.

这样可以让模型更清楚地区分证据与推理之间的边界。

对于原型项目，将记录写入 JSON Lines 文件就足够了：

import json

def append_trace(path: str, trace: dict) -> None:
    with open(path, "a", encoding="utf-8") as file:
        file.write(json.dumps(trace, ensure_ascii=False) + "\n")

在生产环境中，这些追踪记录可能更适合存储在数据库、可观测性系统或内部评估表中。

这能帮助调试哪些问题

来源追踪记录可以帮助回答以下问题：

Agent 是否搜索了错误的 query？

SERP 是否返回了质量较差的结果？

筛选来源时是否移除了重要内容？

答案是否依赖推断，而不是证据？

生成答案时使用的是新鲜的搜索上下文，还是陈旧的搜索上下文？

这远胜于在没有任何搜索记录的情况下，仅仅检查最终答案。

为 Agent 添加网页搜索很有用，而让搜索过程具备可审计性，才是保证系统可维护的关键。

可以先记录生成的 query、时间戳、选中的 URL 和结果数量。这样一条简单的追踪记录，日后能节省大量调试时间。

如果你想使用实时 Google 搜索结果测试这种模式，TalorData 会为新账户提供 500 次响应额度，可用于构建和检查一个简单的来源日志工作流。

对于后续操作，你可以考虑屏蔽此人和/或举报滥用行为。