用 LangSmith 构建 Agent…

在 LangSmith 上为 Agent 搭建离线/在线评测时，如何创建评测器、定义 run 函数、上传并运行评测。

适用场景

解决思路

1. 配置环境变量：LANGSMITH_API_KEY、LANGSMITH_ENDPOINT、LANGSMITH_PROJECT、LANGSMITH_WORKSPACE_ID（可选，用于组织级 key）、OPENAI_API_KEY（本地执行 OpenAI 评委时用）。
2. 优先用 CLI 保存的 profile 认证：运行 `langsmith auth login`，再用 `langsmith auth info` 确认；也可设置 LANGSMITH_API_KEY。不要用隐藏的 `--api-key` 标志，也不要把 key 写进命令或日志；多 profile 时用 `--profile` 或 LANGSMITH_PROFILE 选择。
3. 注意 LANGSMITH_PROJECT 只决定 trace/run 查询的默认项目，不决定评测器目标；创建和上传评测器必须显式指定 `--dataset` 或 `--project`。
4. CLI 与 SDK 认证相互独立：CLI 的 OAuth profile 只认证 `langsmith ...` 命令，Python/TypeScript SDK 不会自动复用。做 SDK 版 CRUD 前，先确认 LANGSMITH_ENDPOINT、LANGSMITH_API_KEY、LANGSMITH_WORKSPACE_ID 与 `langsmith auth info` 指向同一环境和工作区，不一致就停止。
5. SDK 操作前先做只读预检：`from langsmith import Client; client = Client(); client.read_dataset(dataset_name="My Dataset")`。
6. 安装依赖：Python 用 `pip install langsmith langchain-openai python-dotenv`；JS 用 `npm install langsmith openai`；CLI 用 `curl -fsSL https://cli.langsmith.com/install.sh | sh` 后 `langsmith self-update`。
7. 黄金法则——先检查再实现：写任何评测器或抽取逻辑前，先在样本输入上跑一遍 Agent 并捕获真实输出，打印输出或查询 LangSmith trace 弄清确切结构，然后才写处理该输出的代码。输出结构随框架、Agent 类型和配置差异很大，绝不假设形状。
8. 区分离线与在线评测器：离线评测器挂在 dataset 上，函数签名 `(run, example)`，接收 run 输出和数据集样本，用 `--dataset "Dataset Name"` 上传；在线评测器挂在 project 上，签名 `(run)`，只接收 run 输出、无 example，用于生产实时质量检查，用 `--project "Project Name"` 上传。
9. 每个评测器只返回一个指标，返回 `{"score": value, "comment": "..."}`；不要返回 `{"metric_name": value}` 或指标列表，否则会报错。多指标就写多个评测器函数。
10. 处理本地与上传的差异：本地 `evaluate()` 时 Python 列名由函数名自动推导，TypeScript 必须带 `key` 字段否则列无标题；上传后列名来自上传时设置的评测器名，不要再带 `key`（会产生重复列）。Python 本地 run 是 RunTree 对象用 `run.outputs` 属性，上传后是 dict 用 `run["outputs"]` 下标，需兼容两者：`run.outputs if hasattr(run, "outputs") else run.get("outputs", {})`；TypeScript 始终用属性访问 `run.outputs?.field`。Python 返回 `{"score": value, "comment": "..."}`，TypeScript 本地返回 `{ key: "name", score: value, comment: "..." }`、上传后返回 `{ score: value, comment: "..." }`。
11. 选择评测器类型：LLM as Judge 用 LLM 打分，适合主观质量（准确性、有用性、相关性）；Custom Code 用确定性逻辑，适合客观检查（精确匹配、轨迹校验、格式合规）。
12. 用 `langsmith evaluator create-llm` 创建服务端托管的 LLM-as-judge run rule，需要 `--model-config` 加恰好一个目标（`--dataset` 或 `--project`），并提供 `--prompt` 和 `--schema` JSON 文件，或用 `--hub-ref owner/prompt:latest` 引用 Prompt Hub。
13. `--model-config` 必须是服务端支持的序列化模型配置，不要用本地 LangChain 模型构造器臆造 model.json；从已知可用的 LangSmith 评测器、LangSmith 评测器 UI 或其他目标环境的文档来源获取，并确认目标服务端允许该序列化模型类。若创建失败报 `Deserialization ... is not allowed`，说明配置含服务端禁止的类，不要用猜测的序列化对象重试，去获取受支持的配置或询问环境管理员。
14. 读取评测器：`langsmith evaluator list --format json` 列出所有挂载的规则；`langsmith evaluator get "Accuracy Judge"` 按显示名获取全部同名规则；`langsmith evaluator get "Accuracy Judge" --session-id <project-session-id>` 缩小到某个项目规则。注意 `get` 基于显示名可能返回多条，且不导出完整的内联 prompt、schema 和模型配置。
15. 更新/替换：没有单独的 `update` 子命令，用相同名称和目标重跑 `create-llm` 并加 `--replace`，CLI 会在 PATCH 匹配规则前提示确认，需再次提供完整的 LLM 配置。
16. 删除：先 `langsmith evaluator get "Accuracy Judge"` 检查所有匹配项，再 `langsmith evaluator delete "Accuracy Judge"`。注意 delete 基于名称，会删除工作区内所有该显示名的 run rule（可能跨不同 dataset/project）；若匹配多条而只想删一条，应停止，因为 `langsmith evaluator` 尚未暴露按 ID 精确删除。
17. 需要快速本地开发或评委依赖本地包时，改为定义本地评测器并传给 `evaluate(evaluators=[...])`。
18. 写 LLM 评委时用结构化输出（如 Python 的 `with_structured_output(Grade, method="json_schema", strict=True)`，TypeScript 用 `response_format: { type: "json_object" }`），比解析自由文本更可靠；用 async 让评委并行执行。
19. 写自定义代码评测器前：先检查数据集了解期望字段名，测试 run 函数并确认输出结构与数据集 schema 一致，再查询 LangSmith trace 排查不匹配。注意轨迹数据可能不在默认输出里，务必对照 trace 验证。
20. 定义 run 函数：执行 Agent 并返回用于评测的输出。先测试 run 函数并检查真实输出结构——跑一次样本输入、查询 trace 看执行结构、打印原始输出并与 trace 核对、按需调整、确认输出匹配数据集 schema。尽量让 run 函数输出匹配数据集 schema，这样评测器简单可复用；若无法匹配，评测器必须知道如何从两侧抽取和比较正确字段。
21. 捕获轨迹：LangGraph Agent（LangChain OSS）用 `stream_mode="debug"` 配合 `subgraphs=True` 捕获嵌套子 Agent 的工具调用，先打印 chunk 理解结构再写抽取逻辑，跑完后查询 LangSmith trace 验证轨迹数据完整（默认输出可能缺少 trace 中出现的工具调用）。
22. 自定义/非 LangChain Agent 捕获轨迹：先检查输出结构（轨迹数据可能已在 `result.tool_calls`、`result.steps` 等中）；若框架支持执行回调，注册钩子在每次调用时记录工具名；最后才从结构化日志或 trace 数据解析工具名。关键是在执行时捕获工具名，而非定义时。
23. 上传评测器：`langsmith evaluator upload --name "Trajectory Match" --function trajectory_evaluator --dataset "My Dataset" my_evaluators.py`（离线），或 `--project "Production Agent"`（在线）。注意上传到 dataset 的评测器在该数据集上跑实验时会自动运行，无需传给 `evaluate()`。
24. 上传的评测器在沙箱环境运行、包访问极其有限：只用内置/标准库导入，并把所有 import 放在评测器函数体内。dataset（离线）评测器优先先用 `evaluate(evaluators=[...])` 本地跑，以获得完整包访问。
25. 区分代码评测器与结构化评测器：代码评测器用 `langsmith evaluator upload` 上传，在无外部包的受限环境运行，适合确定性逻辑；结构化评测器（LLM-as-Judge）用 `langsmith evaluator create-llm` 配合模型配置和 prompt/schema 文件或 `--hub-ref` 创建。
26. 替换上传：`langsmith evaluator upload --name "Trajectory Match" --function trajectory_evaluator --dataset "My Dataset" --replace my_evaluators.py`。注意 `upload --replace` 和 `create-llm --replace` 会先提示再 patch 匹配规则；`delete NAME` 会删除工作区内所有同名规则；除非用户明确要求，绝不用 `--yes` 标志。
27. CRUD 验证：只验证用户要求的生命周期操作——确认 CLI 和 SDK 调用指向同一环境和工作区；用 `list` 和 `get` 验证创建；在被要求时用 `--replace` 验证替换；仅在唯一一次性名称且明确授权时测试删除；若名称解析出多条规则且无法安全确定目标就停止。
28. 运行评测：上传的评测器在跑实验时自动运行，无需代码；本地评测器直接传入。Python：`evaluate(run_agent, data="My Dataset", experiment_prefix="eval-v1")` 或加 `evaluators=[my_evaluator]`；TypeScript：`evaluate(runAgent, { data: "My Dataset", experimentPrefix: "eval-v1" })` 或加 `evaluators: [myEvaluator]`。
29. 最佳实践：LLM 评委用结构化输出；按数据集类型匹配评测器（最终回答用 LLM as Judge 评质量，轨迹用 Custom Code 校验序列）；LLM 评委用 async 并行；先独立测试评测器（在已知好/坏样本上验证）；按语言选择——Python 用于 Python Agent 和 langchain 集成，JavaScript 用于 TypeScript/Node.js Agent。
30. 排查常见问题：输出不符预期时查询 LangSmith trace 对比每步确切输入输出；一个评测器只返回一个指标；字段名不匹配时先用 `client.read_example(example_id)` 检查数据集，run 函数输出必须与数据集 schema 完全一致；Python 中本地 `evaluate()` 传 RunTree、上传后传 dict，需用 `run.outputs if hasattr(run, "outputs") else run.get("outputs", {})` 兼容，TypeScript 始终用 `run.outputs?.field`。
31. CLI 反馈：遇到真实 CLI 失败、未文档化的 workaround、令人困惑的输出或缺失能力时，每个不同问题提交一条简洁的产品反馈（`langsmith feedback --category feature-request --format json "..."`），需 CLI v0.2.58 及以上（用 `langsmith --version` 检查）。不要报告常规成功或与 CLI 无关的低分/应用失败。反馈发往 LangSmith Cloud（含 BYOC 中继），独立自托管跳过；尊重用户/组织限制，权限不明先询问。用自己的话总结预期与实际行为及 workaround，绝不发送密钥、客户数据、评测器 prompt、数据集内容、trace 载荷、完整堆栈、复制的命令输出、原始参数、环境变量值、本地路径或资源标识符；无法安全脱敏就跳过。类别选 bug、feature-request、usability、documentation 或 other。不要重试失败或限流的反馈提交，不要切换凭据/端点绕过失败，也不要因反馈阻塞原任务。

适用边界 · 注意事项

• 未安装 LangSmith CLI 或没有 LangSmith 账号/API key 时无法使用（属于特定工具依赖）。
• 独立自托管环境不支持 CLI 反馈功能。
• 评测器需要外部包或本地依赖时，不要上传到沙箱环境，应改用本地 `evaluate(evaluators=[...])`。