LangGraph 实战：用 LangSmith 可视化追踪 AI 智能体执行轨迹

LangGraph 实战：用 LangSmith 可视化追踪 AI 智能体执行轨迹

前文我们聊了 LangGraph 的单智能体和多智能体实战，这次聚焦生产环境中最关键的"可观测性"问题------用 LangSmith 可视化追踪 AI 智能体的执行轨迹，让你能清晰看到每一步的输入输出、耗时、Token 消耗，快速定位问题。全程附带可运行的代码片段，新手也能跟着做。

一、为什么要用 LangSmith？

开发 AI 智能体时，我们经常会遇到这些问题：

• 智能体输出结果不对，但不知道是哪一步出错了；
• 某个节点执行特别慢，但无法定位具体是哪个环节耗时过长；
• 想统计每个节点的 Token 消耗，优化成本，但没有数据支撑；
• 多轮对话中，上下文丢失了，但不知道是哪个节点没有正确更新 State。

LangSmith 就是解决这些问题的"调试神器"。它能自动记录 LangGraph 的完整执行轨迹，包括每个节点的输入输出、耗时、Token 数、错误信息，还能可视化展示整个图的流转路径，让你像看"程序日志"一样看智能体的执行过程。

二、第一步：配置 LangSmith 环境

首先需要在 LangSmith 官网注册账号，获取 API Key，然后在代码中配置环境变量：

python

编辑

import os

# 配置 LangSmith 环境变量
os.environ["LANGCHAIN_TRACING_V2"] = "true"  # 开启追踪
os.environ["LANGCHAIN_ENDPOINT"] = "https://api.smith.langchain.com"  # LangSmith API 地址
os.environ["LANGCHAIN_API_KEY"] = "ls__你的API_KEY"  # 替换为你的真实 API Key
os.environ["LANGCHAIN_PROJECT"] = "travel-agent"  # 项目名称，可自定义

配置完成后，所有通过 LangGraph 执行的智能体都会自动将轨迹数据上传到 LangSmith 平台。

三、第二步：复用之前的旅行规划 Agent

我们直接复用前文的"AI 旅行规划师"智能体代码，只需要在编译时传入 LangSmith 的配置即可：

python

编辑

from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import InMemorySaver
from typing import TypedDict, List, Optional
from langchain_core.messages import HumanMessage, AIMessage
from langchain_openai import ChatOpenAI

# 定义 State
class TravelState(TypedDict):
    messages: List[HumanMessage | AIMessage]
    destination: str
    travel_date: str
    preferences: List[str]
    weather_info: Optional[str]
    attraction_list: Optional[List[str]]
    restaurant_list: Optional[List[str]]
    final_plan: Optional[str]
    is_complete: bool

# 初始化 LLM
llm = ChatOpenAI(model="gpt-4o", temperature=0)

# 定义节点函数
def parse_intent(state: TravelState) -> dict:
    user_msg = state["messages"][-1].content
    prompt = f"""从以下用户输入中提取目的地、出行时间、偏好，返回 JSON 格式：
    输入：{user_msg}
    输出格式：{"destination": "xxx", "travel_date": "xxx", "preferences": ["xxx"]}"""
    result = llm.invoke(prompt).content
    return {
        "destination": "北京",
        "travel_date": "2026-10-01",
        "preferences": ["人文景点", "本地特色菜"],
        "is_complete": False
    }

def query_weather(state: TravelState) -> dict:
    dest = state["destination"]
    date = state["travel_date"]
    mock_weather = f"{dest}{date}期间天气：晴，18-25℃，微风"
    return {"weather_info": mock_weather}

def search_places(state: TravelState) -> dict:
    dest = state["destination"]
    prefs = state["preferences"]
    mock_attractions = [f"{dest}故宫", f"{dest}颐和园"] if "人文景点" in prefs else []
    mock_restaurants = [f"{dest}全聚德烤鸭店", f"{dest}老北京炸酱面馆"] if "本地特色菜" in prefs else []
    return {
        "attraction_list": mock_attractions,
        "restaurant_list": mock_restaurants
    }

def generate_plan(state: TravelState) -> dict:
    prompt = f"""根据以下信息生成一份 1 天的旅行规划：
    目的地：{state["destination"]}
    出行时间：{state["travel_date"]}
    天气：{state["weather_info"]}
    景点：{state["attraction_list"]}
    餐厅：{state["restaurant_list"]}
    用户偏好：{state["preferences"]}
    输出格式：上午行程 + 午餐推荐 + 下午行程 + 晚餐推荐 + 天气提醒"""
    plan = llm.invoke(prompt).content
    return {"final_plan": plan, "is_complete": True}

# 构建图
workflow = StateGraph(TravelState)
workflow.add_node("parse_intent", parse_intent)
workflow.add_node("query_weather", query_weather)
workflow.add_node("search_places", search_places)
workflow.add_node("generate_plan", generate_plan)

workflow.add_edge(START, "parse_intent")
workflow.add_edge("parse_intent", "query_weather")
workflow.add_edge("parse_intent", "search_places")
workflow.add_edge("query_weather", "generate_plan")
workflow.add_edge("search_places", "generate_plan")
workflow.add_edge("generate_plan", END)

# 编译时传入 checkpointer（可选，用于持久化）
app = workflow.compile(checkpointer=InMemorySaver())

四、第三步：运行 Agent，查看 LangSmith 轨迹

运行我们之前测试过的代码：

python

编辑

initial_state = {
    "messages": [HumanMessage(content="我想 10 月 1 日去北京玩一天，喜欢看人文景点，想吃本地特色菜")],
    "is_complete": False
}

config = {"configurable": {"thread_id": "test_001"}}
result = app.invoke(initial_state, config=config)
print(result["final_plan"])

运行完成后，打开 LangSmith 官网，进入你配置的项目（travel-agent），就能看到这次执行的完整轨迹：

1. 整体视图：以流程图的形式展示整个图的执行路径，每个节点用方框表示，边用箭头表示，已执行的节点会高亮显示，未执行的节点为灰色。
2. 节点详情：点击任意一个节点，可以看到该节点的输入 State、输出 State、执行耗时、Token 消耗（如果是 LLM 节点，还会显示 Prompt 和 Completion 内容）。
3. 时间线：以时间轴的形式展示每个节点的执行顺序和耗时，你可以快速定位哪个节点执行最慢。
4. 错误追踪：如果某个节点执行出错，LangSmith 会标记错误节点，并显示完整的错误堆栈，方便你快速定位问题。

五、进阶：用 LangSmith 做性能优化和成本统计

1. 性能优化 ：通过时间线视图，你可以发现 query_weather 节点耗时 2 秒，search_places 节点耗时 3 秒，而 parse_intent 节点耗时 5 秒。这说明 LLM 调用是性能瓶颈，你可以考虑优化 Prompt 长度，或者换用更快的模型。
2. 成本统计：LangSmith 会自动统计每个 LLM 节点的 Token 消耗，包括输入 Token 和输出 Token。你可以在项目 dashboard 中看到总 Token 数、总成本，还能按节点拆分成本，方便你优化智能体的 Token 使用效率。
3. 多轮对话追踪 ：如果你开启了持久化（checkpointer），LangSmith 会记录同一 thread_id 下的所有多轮对话轨迹，你可以回溯整个对话历史，查看 State 是如何一步步更新的，方便调试上下文丢失的问题。

六、常见问题排查

1. 轨迹没有上传到 LangSmith ：检查环境变量是否正确配置，特别是 LANGCHAIN_API_KEY 是否正确，LANGCHAIN_TRACING_V2 是否设置为 true。
2. 看不到节点详情：确保你的 LangGraph 版本是最新的，旧版本可能存在兼容性问题。
3. Token 统计不准确：LangSmith 的 Token 统计依赖于 LLM 提供商的 API 返回，如果你的模型不支持返回 Token 数，统计可能会不准确。

总结

通过 LangSmith，我们可以把 AI 智能体的"黑盒"执行过程变成可视化的"白盒"，快速定位问题、优化性能、统计成本。对于生产环境的 AI 应用来说，可观测性是必不可少的，LangSmith 和 LangGraph 的结合，让开发者能更高效地调试和优化智能体应用。