LangChain 发布 LangSmith Engine:基于追踪日志的自主代理优化架构解析
LangChain 正式推出 LangSmith Engine,这是一个专门用于改进其他 AI 智能体的元智能体。该工具直接接入智能体的执行追踪数据(Traces),自动识别重复性错误模式并生成具体的优化建议。文章详细披露了其处理大规模追踪数据的底层架构决策与输入输出机制。
报道正文
本文目录39 个章节
LangSmithAgent ArchitectureDeep AgentsTutorials & How-Tos
我们如何构建 LangSmith Engine:用于改进 Agent 的 Agent

Palash ShahMay 19, 202617min返回博客创建 agents创建 agents
上周,我们发布了 LangSmith Engine。Engine 是一个位于你的 agent traces 之上的 agent,它能够发现反复出现的问题,并建议下一步该怎么做。
本文将深入探讨其技术细节:我们为何构建 Engine,它处理哪些输入和输出,以及使其能够分析海量 traces 的架构决策。
我们为何构建 Engine
LangSmith 是 agent 改进循环的核心所在。构建、测试、部署和监控是驱动 agent 开发的这一循环的四大支柱。
随着你部署的 agent 数量增加,它们生成的 traces 数量也会随之增长。因此,你需要花费越来越多的时间来梳理 traces,并找出 agent 出错的地方。
基本的工具错误相对容易捕捉。整体轨迹在 trace 视图中也清晰可见。但许多 agent 问题除非对每个 trace 进行细粒度检查,否则很难检测出来:
- agent 陷入相同工具调用的循环
- 使用了错误的工具参数
- 执行效率低下
- 遗漏了本应使用的工具
- 在不同运行中反复未能处理同类请求
在 LangChain 内部遇到这一问题后,我们着手构建了 LangSmith Engine。
Engine 有三项职责:
- 在 traces 中发现反复出现的失败。
- 将这些失败转化为可操作的 issues。
- 将这些 issues 转化为持久的改进措施:evaluators、dataset examples 和 fixes。
Engine 本身就是一个 agent:一个编排器,使用专门的组件端到端地运行改进循环。它会拉取 traces,在连接代码仓库时读取代码,将失败归类为 issues,提出 evaluators 和 dataset examples,并随时间推移更新对你 agent 的理解。

Engine 的输出:issues
从核心来看,Engine 识别的是 issues。
Issue 是一种由证据 trace 支撑、并附带建议后续操作的可复现失败模式。这些 Issue 会呈现在 Issue Board(问题看板)上,即 Engine 在 tracing 项目中发现的问题列表。
一个 Issue 包含以下要素:
- 名称: Issue 的标题
- 描述: 对 Issue 的段落式说明
- 类别: 预定义的 Agent 失败类别之一
- 严重程度: 低、中或高
- Traces: 提供该 Issue 发生位置证据的相关 traces
- 建议操作: 为防止该 Issue 再次发生而提出的下一步措施
- 标签: 用于驱动后续工作流的元数据,例如
needs_fix
建议操作可以包括:
- 建议的在线评估器(online evaluator): 如果该 Issue 再次发生,能够将其标记出来的评估器
- 建议的数据集示例: 添加到离线数据集中、能代表该 Issue 的样本
- 建议的修复方案: 用于解决根本问题的代码或 prompt 更改
关键在于,Engine 不仅仅是指出某个糟糕的 trace。它试图将生产环境中的故障转化为你团队可以采取行动并在未来进行测试的内容。
Engine 消费哪些内容
Engine 接收或能够获取四类主要输入。
指令
Engine 由 Agent Overview(Agent 概览)指导。这类似于 AGENTS.md 文件:一份关于你的 agent 功能、预期 trace 结构、需关注的失败模式以及团队偏好表达的动态描述。
首次运行基于入职问答和项目上下文进行引导。在那次初始运行期间,Engine 分析 traces,并利用所学内容创建第一版 Agent Overview。在后续运行中,Agent Overview 成为 Engine 读取和更新的持久化输入。
你也可以随时手动编辑 Agent Overview。
Traces
Engine 通过 LangSmith CLI 从相关的 LangSmith tracing 项目中拉取 traces。
完整的 trace 包含一次 agent 运行的消息和轨迹。为了应对规模问题,Engine 并不总是从一开始就加载每个 trace 的全部内容。它通常从紧凑的轨迹摘要开始,然后在需要深入调查某个 trace 时,选择性地加载完整的 trace 内容。
现有 Issues
Engine 获取当前的 Issue Board,包括未解决的 issues 和之前已关闭的 issues。
这使 Engine 能够获取项目的当前状态。它可以避免重复已知问题,为现有问题补充证据,并了解哪些问题已经解决或关闭。
代码库(可选)
你可以选择将 Engine 连接到你的代码库。这使得 Engine 能够更精准地诊断问题,并允许独立的修复代理提出更改建议。
如果连接了仓库,该仓库将被安装到沙箱中。在设置过程中,你可以指定 Engine 应使用的分支或子目录。
Engine 更新的内容
Engine 在运行过程中可以更新多种输出内容。
Issue Board(问题看板)
Engine 的主要作用是更新 Issue Board。它可以创建新问题、更新现有问题、附加证据追踪记录以及修改问题元数据。
对于每个问题,Engine 可以提议一个评估器,以便在未来的追踪记录中捕获相同的模式。它还可以从证据追踪记录中提议回归测试示例,从而将生产环境中观察到的失败转化为离线测试覆盖率。此外,它还能建议对提示词或代码进行修改,以解决根本问题。
Agent Overview(代理概览)
Engine 可以记录其发现的信息,并更新 Agent Overview 以供后续运行使用。
这就是 Engine 随时间推移记住项目特定信息的方式:常见的故障模式、追踪记录模式、工具行为以及用户偏好。
高层架构
Engine 构建于 Deep Agents 之上,并连接到一个沙箱环境,在该环境中它可以写入文件、检查追踪记录、执行代码以及与检出的仓库进行交互。

从高层来看,Engine 由以下部分驱动:
- 系统提示词和指令: 包括 Agent Overview
- 沙箱: Engine 工作的环境
- LangSmith CLI: Engine 用于获取数据并将更新推送回 LangSmith 的主要接口
- 自定义工具: 特别是用于测试评估器和提议回归示例的工具
- 子代理: 用于筛选追踪记录并在不溢出主代理上下文的情况下调查潜在问题
- 记忆: 通过 Agent Overview 维护,并根据用户操作进行更新
本文其余部分将介绍核心循环:
- 准备代理的上下文。
- 大规模筛选追踪记录。
- 调查潜在问题。
- 创建问题、评估器和数据集示例。
- 必要时将修复工作移交给单独的代理。
- 更新记忆以供下次运行使用。
1. 准备代理的上下文
在 Engine 能够分析追踪数据(traces)之前,它需要一个运行环境以及足够的上下文来理解其正在检查的 Agent。
沙箱设置
Engine 连接到一个沙箱环境中运行。我们使用 LangSmith Sandboxes 来实现这一点。
在运行 Engine 之前,我们会配置好 Agent 的环境。首先,我们拉取基础的 Engine Docker 镜像。该镜像包含了所需的库以及 LangSmith CLI,Engine 利用后者与 LangSmith 数据进行交互。
如果 Engine 连接到了 GitHub 仓库,我们还会拉取相关的代码工件(code artifacts)。用户可以在设置期间指定要使用的分支或子目录。
沙箱至关重要,因为 Engine 通常需要检查追踪数据、写入中间文件、测试评估器代码,并对提议的输出进行迭代。为 Agent 提供一个受控的工作环境使得这一工作流更加可靠。
Agent 概览
Agent 概览既是一个指令文件,也是一个记忆层。
当你设置 Engine 时,你需要回答一组基础的新手引导问题。Engine 会结合这些答案以及其在首次运行中发现的信息,生成初始的 Agent 概览。
该概览有助于 Engine 持续记录以下内容:
- 你的 Agent 的功能
- 预期的追踪数据结构
- 需要警惕的常见陷阱
- 项目特定的上下文
- 用户偏好
Engine 会在连续的运行中读取并更新此文件。
LangSmith CLI
Engine 与 LangSmith 交互的主要方式是通过 LangSmith CLI。
在很大程度上,我们更倾向于使用 CLI,而不是为每一个 LangSmith 操作创建自定义工具。CLI 为 Engine 提供了一个通用接口,用于拉取追踪数据、查询问题、创建问题、附加追踪数据、更新问题元数据以及提议工件。
这也使得 Engine 更易于调试和复现。CLI 是可供下载的标准接口,也可以本地提供给编码 Agent。如果 Engine 通过 CLI 执行了某些操作,通常也可以在 Engine 之外理解和复现该操作。
2. 大规模筛选追踪数据
构建 Engine 时最大的架构挑战在于追踪数据的体量。
让一个 Agent 每次调查并整理 50 条追踪数据相对容易。但一旦我们将系统连接到生产环境的 Agent,那些在该数据量下有效的技术就开始失效了。生产项目在一个回溯窗口内可能拥有数千甚至数万条追踪数据。
将完整的 trace 内容全部加载到主 agent 的上下文中是不可行的。即便是来自长时间运行 agent 的 10 条 trace,也可能包含数百次工具调用和消息。
因此,我们将问题拆分为两个阶段:
- 一个粗略筛选阶段,快速识别可疑的 trace。
- 一个深入调查阶段,仅对可能重要的 trace 加载完整上下文。

Trajectory 格式
为了实现筛选,我们需要一种压缩后的 trace 表示形式。
核心问题是:
如何在压缩 trace 信息的同时,保留足以回溯导航至原始内容的必要信息?
答案是 agent trajectories(轨迹):即 trace 的精简骨架。

一条 trajectory 中每个 turn 对应一个条目,包含角色、可选的工具名称、延迟时间和内容大小。它不包含完整的内容文本。
{ role: "human", chars: 142 }{ role: "ai", latency_ms: 1820, chars: 89 }{ role: "tool", tool_name: "search_db", latency_ms: 340, chars: 2100 }{ role: "tool", tool_name: "search_db", latency_ms: 312, chars: 1980 }{ role: "tool", tool_name: "search_db", latency_ms: 298, chars: 2040 }{ role: "ai", latency_ms: 2100, chars: 210 }
Trajectory 充当了导航工具。它让筛选器能够快速发现可疑的模式,然后在完整的 trace 中进行 grep 搜索,并仅将所需的信息加载到上下文中。
利用反馈对 Trace 进行优先级排序
Trace 可能已经关联了反馈信息。这些反馈可以来自人工标注、LLM-as-a-judge 评分或终端用户反馈(点赞/点踩)。
Engine 将 trace 上的反馈作为高优先级信号来消费,表明可能存在潜在问题。
Engine 拉取的初始 trace 集合中包含反馈统计数据。Engine 被指示查找带有反馈的 trace,并在分诊时优先处理它们。
反馈不会自动转化为 issue。它只是提高了筛选和调查的优先级。Agent 仍然需要判断该 trace 是否属于真实问题的一部分。
Screener 子 Agent
核心的筛选问题是:
给定这条 trace,其中是否存在值得进一步调查的问题?
Engine 使用一个专用的 screener 子 agent 来处理此任务。Screener 是一个基于 Haiku 的子 agent,由主 agent 分发到每组约 20 条 trace 上执行。
筛选器(Screener)的职责被刻意限定在狭窄范围内。它不会创建问题工单,也不会诊断根本原因。它仅在表层判断一条追踪记录(trace)是干净的,还是可能包含问题。
筛选器会向主智能体返回一个结构化响应。该响应中,每条被标记的追踪记录占一行,包含追踪 ID、类别以及简短的原因说明,最后附上干净追踪记录的计数。
<trace_id> | <category> | <one-line reason>CLEAN: 47
这一步骤缩小了搜索空间。我们不再要求主智能体对每一条追踪记录进行完整推理,而是利用并行运行的筛选器来识别那些值得深入关注的追踪记录。
3. 调查潜在问题
经过筛选后,主智能体会读取筛选器的输出结果,并派发更深入的调查任务。
调查子智能体(Investigator Subagents)
调查员会获取被标记的追踪记录,拉取完整的追踪内容,在可用时读取代码库,并对潜在问题进行更深入的分析。
我们鼓励主智能体在此阶段使用子智能体,因为完整的追踪内容可能非常庞大。如果将多条完整追踪记录及相关代码加载到主智能体的上下文窗口中,会导致其迅速溢出。
与筛选器不同,调查员并不是一个拥有固定系统提示词的专用子智能体。它是一个通用型子智能体,由主智能体针对具体的调查任务进行提示。这赋予了主智能体灵活性:不同类型的问题可能需要不同的调查策略。
调查员的职责是确定被标记的追踪记录是否代表真实问题,追踪记录是否应归为一组,以及应在问题工单上记录哪些信息。
问题类别
Engine 为每个问题引入了“类别”这一概念。
我们预先定义了一组常见的智能体故障模式,并提示 Engine 主要寻找这些类型的问题。该列表包括:
pii_leakagent_loopingincorrect_tool_argsmissing_tool
将 Engine 限制在已知类别内,有助于我们控制它所发现的问题范围,并在向客户推出之前评估这些问题类型。这也使得输出结果更易于用户理解。
用户仍可通过“智能体概览”(Agent Overview)自定义 Engine 的关注重点。如果团队特别关心某些问题类型,可以在那里描述他们的优先级。
随着我们识别并验证新的反复出现的智能体故障模式,我们正在积极扩展这个类别列表。
4. 创建问题工单、评估器和数据集示例
一旦 Engine 识别出真实问题,主代理(main agent)便会创建或更新该问题,并附上证据追踪记录。
主代理负责问题的创建以及围绕该问题的评估工件(evaluation artifacts)。它不直接负责修复底层的代码或提示词(prompt)。
对于每个问题,Engine 可以生成:
- 问题本身,附带证据追踪记录。
- 一个提议的评估器(evaluator)。
- 提议的回归示例(regression examples)。
- 一个
needs_fix标签,如果应启动单独的修复代理的话。
评估器
Engine 被提示为每个问题提议一个评估器。
其理念很简单:一旦发现失败模式,你就需要一个检查机制,以便在未来的追踪记录中捕获相同的模式。
Engine 支持两种类型的评估器。
代码评估器(Code evaluators) 是 JavaScript 函数,用于检查追踪记录的结构——字段值、工具输出、步骤计数、错误模式等。当无需读取内容即可检测失败时,这是正确的选择。
LLM-as-judge 评估器 处理需要理解能力的情况:幻觉、接地失败(grounding failures)、无用的拒绝回答、错误的建议等。
代理根据问题类型选择评估器类型。结构性失败使用代码评估器,语义性失败使用裁判评估器。
在 Engine 向用户展示提议的评估器之前,它会调用 test_evaluator 工具。
test_evaluator 工具
test_evaluator 工具允许 Engine 在向用户建议之前,在证据追踪记录上测试提议的评估器。
这一点至关重要,因为评估器可能看起来合理,但实际上未能捕获真正的问题。Engine 使用该工具传入评估器定义以及希望运行评估器的追踪记录。该工具执行评估器,并返回从追踪 ID 到结果的映射。
def test_evaluator(evaluator, traces) -> {run_id: PASS | FAIL | SKIPPED}
其中:
PASS 捕获了问题FAIL 漏检了问题,或评估器报错SKIPPED 评估器不适用于此追踪记录
如果评估器未能捕获正确的追踪记录,Engine 可以对代码或提示词进行迭代优化。目标是发布最能体现证据追踪记录所代表的失败模式的版本。
回归示例与断言
每当创建新问题或将新追踪记录添加到现有问题时,Engine 会被指示针对每条证据追踪记录调用一次 propose_regression_example。
这会为该追踪记录创建一个提议的回归示例。该示例包含发送给代理的原始输入以及对预期输出的断言。
我们提出使用断言(assertions)而非完整的标准答案(ground-truth output),因为断言更简单且更具灵活性。正确的响应可能有多种不同的表述方式,关键在于它是否满足由执行轨迹(trace)所隐含的核心主张。
每条断言包含:
- key: 反馈标识符,以简短的 slug 形式书写
- comment: 一句人类可读的主张,描述正确响应应满足的条件
{
"key": "must_cite_max_connections_4096",
"comment": "Response cites the max_connections value of 4096 returned by the get_config tool call."
}
{
"key": "must_not_reference_strict_mode_flag",
"comment": "Response must not suggest enabling strict_mode, which was deprecated in this version."
}提议的示例会在前端的问题(issue)中显示。随后,审核人员可以将其提升为数据集的一部分。
这闭合了从生产环境故障到离线测试覆盖率的循环。
5. 将修复任务移交给独立的 Agent
一个关键的设计决策是将问题创建与修复生成分离开来。
在早期版本中,我们曾尝试让主 Agent 同时负责识别问题并提出提示词或代码修复方案。这使得主 Agent 的职责过于宽泛。它需要扫描执行轨迹、判断哪些内容重要、对失败情况进行分组、创建问题、生成评估器(evaluators)、提议数据集示例,还要推理出正确的修复方案。
我们发现,当所有这些工作都在单次处理中完成时,主 Agent 难以可靠地生成修复方案。
因此,我们将工作流拆分如下:
- 主 Engine Agent 识别并记录问题。
- 它创建数据集和评估器工件(artifacts)。
- 如果问题需要修复,它会留下一个
needs_fix标签。 - 启动一个独立的修复 Agent,用于提出实际的代码或提示词变更。
这使得主 Agent 更加简洁,并为修复 Agent 提供了更聚焦的任务。修复 Agent 可以从问题、证据执行轨迹以及关联的代码仓库上下文开始工作,而无需再执行完整的轨迹筛查工作流。
6. 更新记忆以供下次运行使用
Engine 并非每次都是从零开始。
Agent Overview(智能体概览)不仅通过 Engine 的调查进行更新,还会根据用户操作进行更新。当你解决一个问题、关闭一个问题或创建一个评估器时,这些操作都会成为信号。
Engine 可以通过 LangSmith CLI 拉取近期事件,从这些事件中归纳观察结果,并更新 Agent Overview。
它被专门设定为维护一个 用户偏好 部分。该部分记录了 Engine 通过观察用户与 Issue 的交互方式所学习到的内容。
每个团队关注的问题集各不相同。Agent Overview 正是 Engine 随时间推移适应这些偏好的机制。
架构决策与经验教训
有几项架构决策最终显得尤为重要。
将 CLI 作为 LangSmith 的主要接口
Engine 的大部分操作都是通过 LangSmith CLI 完成的。这使得系统比针对每项操作创建狭窄的自定义工具更加灵活。同时也让 Engine 的行为更容易复现和调试。
在读取之前压缩 Trace
完整的 Trace 数据量太大,无法在生产规模下进行筛选。Trajectory 使 Engine 能够基于大量 Trace 的整体形态进行推理,然后有选择地加载关键细节。
将筛选与调查分离
Screener(筛选器)以规模为优化目标。Investigator(调查器)则以更深入的分析为优化目标。
这种分离使得 Engine 能够处理海量的 Trace,而无需对每一条 Trace 都执行昂贵的完整调查。
使用专用的 Screener 但灵活的 Investigator
Screener 的任务狭窄且可重复,因此受益于专用的 Prompt 和结构。
调查任务则更具多样性。有些需要阅读代码,有些需要理解评估器失败的原因,还有些需要对比 Trace。因此,我们使用通用的 Investigator 子代理,由主代理动态地向其发送 Prompt。
限制 Issue 类别
允许代理随意发明 Issue 类别会使输出更难评估,也更难建立信任。预定义的分类体系让我们能够控制质量、衡量性能,并有意识地扩展覆盖范围。
优先使用断言而非完整的预期输出
对于回归测试示例,断言通常比完整的参考答案更合适。它们捕捉了必须为真的条件,同时避免过度约束正确响应的具体措辞。
保持主代理专注于 Issue
主代理仅负责创建 Issue 以及关联的数据集/评估器工件。它不会尝试直接修复 Prompt 或代码。
当某个 Issue 需要修复时,主代理会为其打上 needs_fix 标签。随后,独立的 Fix Agent 负责处理修复方案。
这一分工源于观察到:当同一个代理需要在同一轮中既识别 Issue 又提出修复方案时,表现往往会挣扎。
结论
Engine 是我们尝试自动化更多 Agent 改进循环环节的成果。
Agent 可观测性的难点不仅在于查看单次追踪(trace)中发生了什么,更在于从大量追踪中发现反复出现的模式,判断哪些模式至关重要,并将这些模式转化为问题(issues)、评估器(evaluators)、数据集示例以及修复方案。
其架构体现了这一循环过程:Engine 负责准备上下文、大规模筛选追踪数据、调查潜在问题、创建问题工件(issue artifacts),在需要时将修复工作移交给独立的 Agent,并更新其记忆以用于下一次运行。
它已经改变了我们内部改进自身 Agent 的方式。过去我们需要手动挖掘追踪数据并单独编写评估测试,现在我们可以直接将生产环境中的行为转化为问题、修复方案和测试用例。
你可以在 LangSmith 追踪项目的“Issues”标签页中找到 Engine。如果你希望获得结合代码上下文的修复建议,可以连接一个代码仓库;或者仅基于追踪数据开始使用,看看 Engine 能发现哪些反复出现的模式。
了解你的 Agent 实际在做什么
LangSmith 是我们的 Agent 工程平台,帮助开发者调试每一个 Agent 决策、评估变更,并实现一键部署。