深入学LangChain官方文档：Observability 与 Studio——先看清 Agent 到底做了什么

深入学LangChain官方文档Observability 与 Studio——先看清 Agent 到底做了什么本篇对应的官方文档LangChain Observability支撑create_agent自动 tracing、project、选择性追踪以及 tags、metadata 的接入路径。LangSmith Observability concepts用于划清 Project、Trace、Run、Thread 四种数据粒度。LangSmith Studio支撑本地 Agent Server、langgraph.json、langgraph dev与 Studio 调试链路。How to use Studio支撑 state 检查、thread 管理、checkpoint 重跑和调试分支边界。本篇讲解范围本篇完整讲清如何为 LangChain Agent 开启 LangSmith tracing怎样沿 Thread、Trace、Run 定位一次真实故障以及如何用 Studio 在本地检查 state 并从 checkpoint 重跑。测试与评估分别留给第 24、25 篇生产部署、告警平台和可靠恢复机制也不在本篇展开。一个售后退款 Agent 收到用户消息“我只想确认订单 A102 是否还能退款先不要执行。”最终回复看起来很正常“订单符合退款条件需要继续吗”但业务流水里出现了两次退款接口调用其中一次失败、一次被幂等键挡住同一时段还有少量会话从 4 秒变成 19 秒。只保存最终答案团队最多得到三个猜测模型不稳定、工具有重试、网络变慢。猜测不能回答具体是哪一轮模型请求了工具、工具参数是什么、第一次调用为何失败、第二次调用从哪里产生也无法把 19 秒拆成模型等待、工具执行和框架调度。Agent 进入生产阶段后真正稀缺的不是更多日志文本而是一条能还原执行结构、关联业务上下文、继续下钻到具体步骤的证据链。最终答案只覆盖输出端trace 则保留从输入到模型、工具和最终响应的运行树。二者的差异决定了排障能否从“Agent 表现不对”收窄到“第二个工具 run 在第一次错误之后被再次创建”。这正是 Observability可观测性在 Agent 工程里的起点不是让系统永不出错而是让错误发生后有足够证据解释它怎样发生。1. 可观测性不是多打印几行日志普通应用日志通常由开发者手写进入接口、查询订单、返回结果。Agent 的控制路径却由模型输出、工具结果和状态共同推进。相同用户输入可能直接回答也可能产生一个或多个工具调用工具返回错误后模型还可能更换参数、重试或选择另一项能力。若日志仍按固定业务步骤平铺执行树会被压扁父子关系和时间消耗也容易丢失。LangSmith tracing 把一次 Agent 操作记录成 trace并把其中的模型调用、工具调用、检索或其他工作单元记录成 run。每个 run 有输入、输出、开始结束时间、错误、类型以及父子关系。开发者看到的不再是一串互不关联的字符串而是一次请求内部的结构化执行路径。这并不意味着 trace 自动证明每个业务事实正确。工具返回“订单可退款”只能证明该 run 收到了这份返回值订单数据库当时是否正确、权限是否真实有效仍要由业务系统保证。可观测性回答的是“应用做了什么、看到了什么、花了多久、在哪里失败”不是替业务系统签发真相证书。2. 四种运行粒度不能混用LangSmith 的四个核心粒度很容易被口头上的“一次运行”混在一起。排障前先把它们放回各自职责Project是一组 trace 的容器通常对应一个应用、服务或环境例如refund-prod。Trace是一次操作的完整执行树。用户发出一条消息Agent 完成这一轮处理通常形成一条 trace。Run是 trace 中的单个工作单元例如一次模型调用、一次lookup_refund_policy工具调用或一次检索。Thread是多轮会话的 trace 序列。同一用户围绕订单 A102 连续追问三轮会形成多个 trace但可由同一个thread_id聚合。观察这组关系时重点是 Thread 横跨多轮而 Run 纵向嵌套在单条 Trace 中Project 只负责为大量 Trace 提供稳定容器。层级关系并不是简单的四层树Project 包含大量 trace每条 trace 由 run 树组成Thread 则横向连接同一会话的多条 trace。排查“这一轮为什么重复调用工具”时看 trace 和 run排查“为什么第三轮突然忘记用户已经拒绝退款”时要先回到 thread 查看前两轮 trace 的输入输出与状态关联。thread_id还需要一个边界说明。LangSmith 通过 metadata 中的thread_id、session_id或conversation_id聚合 tracing threadLangGraph persistence 也常用 thread 标识保存 checkpoint。两者可以采用同一个业务会话 ID便于联查但“名称相同”不会自动建立关联。应用必须在调用配置、持久化配置和业务会话表中主动保持标识策略一致。3.create_agent怎样进入 LangSmith tracingLangChain 的create_agent已支持 LangSmith tracing。最小接入不需要给每个工具增加日志代码只要在运行环境设置追踪开关和 API keyLANGSMITH_TRACINGtrueLANGSMITH_API_KEYlsv2_你的密钥LANGSMITH_PROJECTrefund-prodLANGSMITH_TRACING决定是否启用追踪LANGSMITH_API_KEY用于连接 LangSmithLANGSMITH_PROJECT决定 trace 进入哪个项目。默认项目虽然能快速跑通但生产、预发布和个人实验都写入同一容器后筛选、权限和成本核算会迅速变乱因此项目名应体现稳定的应用或环境边界。自动 instrumentation 会沿 LangChain 对象捕获运行结构开发者仍要决定哪些环境开启、送往哪个 project、附带哪些业务上下文。若只想追踪一段高风险调用可以使用tracing_context(enabledTrue)做选择性追踪它适合本地诊断、灰度路径或临时扩大采样不必把整个进程的所有调用都切换成相同策略。接入成功也不等于“所有信息都应记录”。Prompt、工具参数和工具结果可能包含姓名、电话、地址、订单备注甚至访问凭据。启用 tracing 前要完成字段分级、脱敏和访问控制否则可观测系统会从排障工具变成新的敏感数据副本。4. Tags 与 metadata 让证据可以被找到退款事故发生后如果项目里有几十万条 trace人工翻页没有意义。调用时附加 tags 和 metadata才能按环境、版本、租户、案件号和会话号快速缩小范围。importosfromlangchain.agentsimportcreate_agentfromlangchain.toolsimporttoolfromlangchain_openaiimportChatOpenAI# 作用只读查询订单的退款资格不执行退款写操作。tooldeflookup_refund_eligibility(order_id:str)-dict:按订单号返回退款资格与规则版本。return{order_id:order_id,eligible:True,policy_version:refund-policy-2026-07,}modelChatOpenAI(modelqwen3.7-plus,api_keyos.environ[DASHSCOPE_API_KEY],base_urlos.environ[DASHSCOPE_BASE_URL],)refund_agentcreate_agent(modelmodel,tools[lookup_refund_eligibility],system_prompt你是售后助手。用户未明确确认前只能查询不得执行退款。,)resultrefund_agent.invoke({messages:[{role:user,content:确认订单 A102 是否还能退款先不要执行。,}]},config{tags:[production,refund-agent,read-only-check],metadata:{thread_id:thread-refund-A102,case_id:CASE-8848,environment:production,app_version:2026.07.25,},},)这段代码的重点不是再次解释模型连接而是调用配置怎样进入 trace。tags是便于分类的字符串集合适合production、refund-agent这类有限枚举metadata是键值上下文适合case_id、environment和app_version。thread_id放入 metadata 后同一会话的多条 trace 才能形成 thread 视图。筛选字段要服务诊断而不是复制业务数据库。case_id可以作为关联键完整订单对象、用户身份证号和访问 token 不应为“以后可能有用”直接写入 metadata。高基数值也要受控每次生成随机字段名、把整段输入当 tag都会让索引和查询失去稳定边界。较好的设计是用少量稳定维度找到 trace再凭关联号到受权限保护的业务系统核对详情。代码还故意只提供只读工具。若 Agent 同时拥有issue_refund写工具Prompt 中的“不得执行”仍不是强授权边界工具端权限、HITL 与幂等控制必须继续存在。Tracing 可以证明模型发起过什么调用却不能代替这些控制。5. 从 Thread 下钻到出错的 Run现在回到CASE-8848。排障不要一上来盯着最长的 prompt而应按粒度逐层收窄。第一步用case_idCASE-8848、environmentproduction和事故时间窗口筛出候选 thread。Thread 视图回答跨轮次问题用户是否在前一轮已经说过“不要执行”后续 trace 是否仍携带相关消息异常是单轮行为还是会话状态逐步偏离。第二步在 thread 中选择出现重复退款的那条 trace。Trace 顶层先看总 latency、总 token、最终状态和错误再展开执行树。若总耗时 19 秒而两个工具 run 分别只用 300 毫秒瓶颈就更可能在模型调用或重试等待不应先优化数据库。第三步定位具体 run。比较两次工具调用的名称、参数、父 run、时间顺序、返回值和错误。假设第一次issue_refund返回timeout_after_commit第二次由后续模型 run 再次发起那么根因候选不是“工具自动重试”而是工具返回没有表达“写入结果未知”Agent 将它当作可安全重试的普通失败。这条下钻顺序保留了上下文Thread 解释多轮关系Trace 解释一次请求的完整路径Run 解释单个步骤。直接从 Runs 表搜索issue_refund虽然也能找到失败调用却可能看不到用户前文、父模型为何选择该工具以及同一 trace 中是否已有成功结果。证据足够后团队可以形成可验证假设工具在“服务端已提交、客户端等待超时”时返回了模糊错误Agent 因而发起第二次调用幂等键挡住了重复写入但第一次等待和第二轮模型判断共同推高延迟。下一步应修正工具结果契约把committed、operation_id和retryable明确返回并建立对应测试而不是仅把 Prompt 改成“千万不要重复退款”。6. Trace 能看见什么又不能证明什么官方文档会用“记录模型交互、工具调用和 decision points”描述 trace。工程上需要更谨慎地理解系统能记录的是应用显式发送、接收和产生的事件例如 prompt、模型响应中的 tool call、工具参数与结果、状态字段、错误和时延。它不是读取模型未输出的隐藏思维过程。如果模型提供公开的 reasoning content 或结构化推理摘要应用可以按供应商和数据政策决定是否采集没有被接口返回的内部推理LangSmith 也无法凭空展示。把 trace 树上的步骤称为“决策路径”可以但不能据此宣称看到了模型全部心理过程。还要区分“记录到的值”和“现实中的事实”。Trace 显示工具返回eligibletrue证明 Agent 当时基于这个值继续运行它不证明退款规则服务没有脏读。Trace 显示第二次调用收到幂等冲突证明重复请求被业务接口拒绝它不证明第一次写入一定成功仍要凭operation_id查询交易流水。这种边界反而让 Observability 更可靠。团队不把 trace 当万能真相而是把它当运行证据层用关联 ID 连接业务审计用 run 时间解释性能用输入输出解释控制路径再把需要保证的行为转成测试和评估。7. Studio 把本地 Agent 变成可交互的调试对象LangSmith Web 中的 production trace 适合分析已经发生的运行Studio 更偏向开发阶段的交互式检查。它连接本地运行的 Agent Server可以提交输入、查看 prompt、工具参数和返回值、检查中间 state、观察异常以及 token/latency并在修改代码后通过热重载快速重试。最小项目需要把 Agent 暴露给 LangGraph CLI。create_agent返回的是 compiled LangGraph graph可以直接登记在langgraph.json{dependencies:[.],graphs:{refund_agent:./src/refund_agent.py:refund_agent},env:.env}dependencies告诉本地 server 安装或加载哪些依赖graphs把公开名称映射到 Python 模块中的 compiled graphenv指向环境变量文件。随后安装带内存运行时的 CLI 并启动开发服务器pipinstall--upgradelanggraph-cli[inmem]langgraph dev默认情况下本地 API 位于http://127.0.0.1:2024Studio 通过该地址连接 Agent。Safari 对 localhost 连接有限制时官方文档建议使用langgraph dev --tunnel。Tunnel 会改变暴露边界团队仍需按环境政策判断是否允许不应把便利参数直接带入含真实敏感数据的调试流程。Studio 与 tracing 的数据离开边界也不能混为一谈。官方说明在应用.env中设置LANGSMITH_TRACINGfalse时trace 数据不会离开本地 serverStudio 连接仍需要 LangSmith API key。这个模式适合本地调试敏感样例但“数据不上传”并不免除开发机自身的访问控制、临时文件和屏幕共享风险。Studio 不是生产监控面板。它不会替团队定义错误率 SLO、值班告警、跨服务指标、审计保留期和业务补偿流程。它的价值是缩短“修改 Agent → 提交输入 → 观察步骤 → 检查 state → 再次运行”的开发反馈回路。8. 从 checkpoint 重跑验证修复而不是改写历史团队根据 production trace 修正退款工具超时后先用operation_id查询写入状态只有明确未提交且retryabletrue才允许重试。下一步不是拿真实生产会话再次退款而是在本地 Studio 构造同样的输入和工具返回。Studio 可以查看已有 thread展开节点和 state并从某个 checkpoint 重新运行。若不改 state使用 “Re-run from here” 会从选定 checkpoint 创建新的 forked run若先编辑节点 state再确认 Fork同样会形成调试分支。原路径仍然保留便于比较修复前后的工具参数、错误处理和最终输出。分支重跑不是现实副作用回滚。Checkpoint 能恢复的是 Agent state 和执行位置已经提交到支付、退款、邮件或工单系统的动作不会因为 Studio 回到旧节点而撤销。调试写工具时应使用 sandbox、fake tool 或只读替身确需连真实测试环境也要有独立幂等键和可清理测试账户。修复验证应比较具体对象而不是只看最终回答是否“更像人话”第一次工具返回timeout_after_commit后state 是否保留operation_id后续模型 run 是否收到明确的retryablefalse执行树中是否不再出现第二个写工具 run总 latency 是否移除了无意义的第二轮等待用户未确认时是否始终只调用资格查询工具。这五项仍是一次交互式验证。要保证它们在以后版本持续成立第 24 篇还会把关键路径写成 Unit、Integration 与 Trajectory tests。Observability 帮团队发现和解释问题Testing 才把修复沉淀成可重复执行的行为合同。9. 生产可观测性需要一套治理预算Tracing 越详细排障证据越丰富同时也会增加数据、成本和权限风险。生产方案至少要明确以下几组取舍。采集范围与采样。高风险写操作、错误 trace 和灰度版本可以提高采样率稳定的大流量只读路径可按策略采样。选择性追踪不能只看成本还要保证事故发生时仍能沿业务关联号找到足够上下文。敏感数据与访问权限。Prompt 和工具结果进入 trace 前应按字段脱敏。Project 的访问权限要与生产环境分级开发者不应因为能改 Prompt 就自动获得所有用户会话原文。API key 只能从环境变量或密钥系统读取不得写进任务卡、metadata 或示例输出。Tags、metadata 与索引。Tags 使用有限、稳定的枚举metadata 保存必要关联键和版本维度。无界高基数字段、完整对象和大段文本应留在业务存储通过case_id、operation_id等键关联。保留期与删除。Trace 是数据资产也可能成为合规负担。团队需要按环境和数据类型决定保留周期、删除流程和导出权限不能因为平台默认可保存就无限期保留。Tracing 与 metrics、logs、alerts 的协作。Trace 擅长解释单次调用的结构metrics 擅长发现错误率和延迟趋势logs 承担框架外服务事件alerts 负责在阈值触发时通知人员。生产系统需要把它们通过trace_id、case_id或operation_id关联而不是期待一种工具包办全部职责。治理矩阵最终约束的是“哪些证据值得采、谁能看、保存多久、怎样联查、成本由谁承担”。缺少这些答案时全面 tracing 可能在事故中提供大量噪声却找不到关键业务关联也可能为了排障保留过多敏感内容。可观测性成熟的标志不是 trace 数量最多而是关键故障能被稳定定位同时数据和成本仍处于明确边界内。这些治理条件落实后退款故障中的每一份证据才既能被找到也不会越过数据与权限预算主线可以由治理选择回到一次完整排障。10. 把一次退款故障重新复述成工程链路售后退款 Agent 的完整定位过程现在可以压缩成一条可复述主线用户在同一thread_id下询问退款资格一轮请求形成 tracetrace 内的模型与工具步骤分别形成 run。调用配置用 tags 区分环境和应用用 metadata 保存case_id、版本和 thread 关联。事故发生后团队先在 Thread 视图确认用户跨轮次意图再进入异常 Trace 比较总耗时最后下钻两个工具 Run发现模糊的“提交后超时”结果触发了第二次调用。团队没有把 trace 当作交易真相而是用operation_id回查业务流水确认幂等层阻止了重复写入。随后在本地 Agent Server 中加载修复后的refund_agent用 Studio 检查 state从 checkpoint 创建新调试分支确认写入结果未知时不再重复调用。生产侧再补齐脱敏、采样、访问权限、保留期以及 trace 与指标告警的关联。到这里“Agent 到底做了什么”已经不再依赖猜测。但能看清一次运行只解决了诊断问题下一个版本是否仍遵守“未确认不退款”“提交结果未知不盲目重试”还需要自动化测试持续回答。第 24 篇将从这两条行为合同出发建立 Unit、Integration 与 Trajectory Evals 的分层测试体系。