在构建基于大模型的Agent系统时，最让人头疼的往往不是模型效果本身，而是系统跑起来之后完全像一个黑盒。一次用户请求可能触发规划、记忆读取、多轮工具调用和反思，任何一环出问题都难以从终端日志里看出来。LangSmith提供了一套面向LLM应用的追踪基础设施，可以把Agent运行的每一步以树状链路完整记录下来，包括调用了哪个提示词、传了什么参数、模型回了什么、花了多长时间。通过合理的配置，开发者能够在本地或云端直观看到每一次交互的全貌。
环境准备与基础凭证配置
要让Agent的链路被LangSmith捕捉，第一步是准备好对应的运行环境与凭证。LangSmith本身由LangChain团队提供，既支持云版也支持私有部署，但无论哪种形式，都需要先在平台中创建项目并拿到API Key。这个Key用于标识你的调用身份，而项目名则决定了追踪数据归到哪个看板下。很多团队在初期忽略项目隔离，把所有实验和生产的链路混在同一个项目里，后续筛选时非常麻烦，因此建议按环境或业务线明确划分。
在代码运行环境中，主要通过环境变量完成注入。最核心的三个变量分别是LANGCHAIN_TRACING_V2、LANGCHAIN_API_KEY和LANGCHAIN_PROJECT。其中LANGCHAIN_TRACING_V2需要设为true以开启v2版本的追踪协议，它相比旧版在嵌套结构表达上更清晰。下面是一段典型的Shell环境配置，适用于Linux或macOS的开发机：
export LANGCHAIN_TRACING_V2=true export LANGCHAIN_API_KEY=your_api_key_here export LANGCHAIN_PROJECT=agent_prod_monitor
如果你在Python脚本中临时设置，也可以直接在进程内写入os.environ，但要确保设置在任何LangChain组件导入之前生效，否则部分全局配置不会生效。对于使用Docker部署的Agent服务，则应当把这些变量写进compose文件或Kubernetes的Secret中，避免明文出现在代码仓库。注意Windows下使用set命令而非export，路径分隔符如C:appconfig中的反斜杠必须原样保留。
在Agent构建中接入追踪回调
凭证就位后，真正的链路采集发生在Agent执行期间。LangChain生态中的AgentExecutor、LangGraph以及LCEL链都内置了对Callback机制的支持，而LangSmith的追踪本质上就是一组特定的Callback Handler。当你不显式传参时，只要环境变量正确，新版本客户端会自动探测并挂载默认Handler，但这在复杂定制场景中不够稳妥。更推荐的方式是显式构造Client与tracing_callback_var，在调用时传入。
以最常见的AgentExecutor为例，下面代码展示了如何把LangSmith客户端作为回调传入，并附带自定义标签，方便后续在界面中按版本筛选。这里metadata字段非常关键，它可以承载业务上下文，比如用户ID哈希、实验分组等，而不会污染实际输入输出：
from langchain.agents import AgentExecutor, create_react_agent
from langchain_openai import ChatOpenAI
from langchain_core.prompts import PromptTemplate
from langsmith import Client
from langchain.callbacks.tracers import LangChainTracer
client = Client(api_key="your_api_key_here")
tracer = LangChainTracer(project_name="agent_prod_monitor", client=client)
llm = ChatOpenAI(model="gpt-4o")
prompt = PromptTemplate.from_template("回答用户问题：{input}")
agent = create_react_agent(llm, tools=[], prompt=prompt)
executor = AgentExecutor(agent=agent, tools=[], verbose=True)
result = executor.invoke(
{"input": "查询北京明天天气并预算出行成本"},
config={
"callbacks": [tracer],
"metadata": {"env": "prod", "trace_id": "abc123"}
}
)
print(result)
如果你的Agent是基于LangGraph编排的，配置方式略有不同，但原理一致：在compile之后的invoke或stream调用里传入包含callbacks的config字典即可。这里需要避免一个常见误区，即把Tracer实例化放在每次请求内部，这会带来不必要的连接开销。正确做法是把Tracer作为单例或模块级变量复用。同时，当Agent内部嵌套调用其他Runnable时，子链路会自动继承父级追踪上下文，不需要手动透传。
链路数据解读与高级可观测实践
配置完成并跑通一次请求后，打开LangSmith项目看板，你会看到每次运行对应一条顶层Run，下面展开为Planning、Action、Observation等子节点。每个节点都记录了开始时间、耗时、输入字典和输出内容。对于可观测性来说，最有价值的是通过对比正常与异常链路，快速发现某次工具调用返回了空值却仍被模型当作有效信息采纳。此时可以借助平台的筛选器，按error状态或耗时阈值过滤出可疑Run。
除了基础追踪，还可以利用反馈机制增强可观测性。例如当用户对Agent回答点踩时，通过SDK发送client.create_feedback把评分关联到具体Trace ID，这样就能在看板中统计哪些链路模式更容易引发不满。另一个高级做法是自定义Evaluation，在每次链路结束后自动跑一个校验函数，判断输出是否符合格式约束，结果同样回写到追踪记录。下面示例展示如何给已有追踪追加反馈：
from langsmith import Client
client = Client()
client.create_feedback(
run_id="对应的_run_id",
key="user_rating",
score=0.2,
comment="工具调用超时导致答案不完整"
)
在生产环境中，链路数据量会快速增长，因此建议对高频Agent开启采样，例如只追踪百分之十的请求，或仅追踪带有特定metadata标记的内部测试流量。LangSmith也支持将追踪导出到自有数仓，通过Webhook或批量导出实现与既有监控体系打通。当Agent演进到多智能体协作时，更要在每个子Agent的config中保持项目名一致，才能在同一张图里看清角色分工与阻塞点。
LangSmithagent_observabilitytrace_configuration修改时间：2026-08-16 06:14:14