ratel-langsmith-integrate

/ratel-langsmith-integrate — 为 Agent 配置 LangSmith 追踪并规划仪表板

像 Ratel 团队那样，将 LangSmith 接入客户的代码库，并规划能证明它物有所值的仪表板。这项技能分为两部分：埋点配置（追踪应放在哪里、如何命名、如何设置）和仪表板构建规范（在 Monitor 和自定义仪表板中构建哪些图表，以及具体配置）。交付成果是计划。不要修改 Agent 代码，也不要调用 LangSmith API——客户会通过 LangSmith UI 点击构建仪表板，这是有意为之。

这是可观测性流程中的 LangSmith 分支。通用技能 /ratel-observability-assessment 以不依赖供应商的方式决定捕获什么以及哪些仪表板很重要，并检测供应商。当供应商是 LangSmith 时，它会转到这里，将计划具体落实为 LangSmith 的原生功能。追踪数据开始流入后，后续步骤是 /ratel-langsmith-analyze，它会读取本计划产生的实时数据。

理念：追踪思维模型，而非调用图

一种常见的失败模式是“把每个函数都包装成一次运行”。这样生成的运行树与代码的调用图一致，却无法告诉你 Agent 试图做什么。当 LangSmith 追踪的结构与一次交互轮次的概念结构一致时，最有用：

• 追踪（根运行） = 一个对外有意义的工作单元（一次聊天轮次、一个任务、一个 webhook）。如果一个请求包含多个 Agent 轮次，就不是“一次 HTTP 请求”；如果一个轮次包含多次模型调用，就不是“一次模型调用”。
• 子运行 = Agent 在该工作单元内执行的一个步骤。子 Agent 调用（chain 运行）、工具调用（tool 运行）、模型调用（llm 运行）、检索步骤（retriever 运行）。嵌套结构应体现委派关系，而非源文件布局。
• 线程 = 一组相关追踪，它们共享同一个线程元数据键（session_id、thread_id 或 conversation_id）。通常对应一次用户对话、一个 Agent 运行 ID，或一个任务关联 ID。

完整的原理只在 ../ratel-observability-assessment/references/instrumentation-philosophy.md 中说明。LangSmith 对这套术语的具体映射——即哪个通用概念对应哪种运行类型和元数据键——见 references/langsmith-mapping.md。

为什么仪表板要分为两组

这项技能的仪表板部分始终构建两组仪表板，因为合作初创公司希望通过同一份数据讲述两种不同的故事：

1. “Ratel 正在推动指标改善”（Ratel 价值组）——降低 Token 开销、提升检索质量、减少“未找到工具”错误、降低每个会话的成本。这些指标能证明合作的价值。只有在已引入或计划引入 Ratel 时才纳入。
2. “我们的 Agent 运行良好”（Agent 健康组）——延迟百分位数、各工具的错误率、会话放弃率、反馈评分分布。无论是否使用 Ratel，这些指标都很有用；它们能帮助客户自己的工程师发现自身问题，从而建立信任。

只有 Ratel 仪表板会显得像是在推销；只有 Agent 健康仪表板则会让人觉得我们忘了此行的目的。只要涉及 Ratel，就应同时纳入两组。LangSmith 内置的 Monitor 标签页已经涵盖了许多项目级的 Agent 健康情况——不要重复构建已有的免费功能（见步骤 5）。

工作流

步骤 0 — 阅读上游可观测性评估（优先输入）

查找 <repo>/.ratel/ratel-observability-assessment.md——这是 /ratel-observability-assessment 的交付物。如果该文件存在，它就是优先输入：读取其中检测到的技术栈、拓扑结构、与厂商无关的埋点策略，以及推荐的仪表板列表。确认检测到的厂商是 LangSmith；如果文件中写的是 Langfuse（或其他厂商），请停止并告知用户：这是 LangSmith 技能，他们需要使用匹配的 *-integrate 技能。

如果文件存在，可以跳过步骤 1–2 中繁琐的检测，直接进入渲染阶段：直接使用其中的技术栈和拓扑结构，然后转到步骤 3。

如果文件不存在，不要直接拒绝。自行快速检测技术栈和厂商（步骤 1–2），并且像构建仪表板需要一套术语体系一样，先询问几个问题，而不是拒绝：

1. 一轮聊天／一项任务的规范根运行名称是什么？
2. 正在使用（或计划使用）哪些 env、stack 和 agent_version 标签值？
3. Ratel 是否以任何形式接入了埋点（网关、SDK 或计划接入）？

根据用户的回答继续操作。基于猜测的术语构建的图表看起来没问题，但分组会出错。

步骤 1 — 检测技术栈

（如果上游评估已指出技术栈，则跳过。）阅读清单文件，识别语言和框架。根据对应技术栈的特定模式，选择匹配的参考文档。

# TypeScript / Node detection
test -f package.json && cat package.json | jq -r '.dependencies // {}, .devDependencies // {} | keys[]' | sort -u

# Python detection
test -f pyproject.toml && cat pyproject.toml | grep -A 200 '^\[' || true
test -f requirements.txt && cat requirements.txt
test -f uv.lock && head -50 uv.lock

将依赖项映射到以下某个技术栈配置：

清单中的信号	技术栈	参考文档
ai、@ai-sdk/*	Vercel AI SDK	references/stack-vercel-ai-sdk.md
@mastra/core、直接调用 openai／@anthropic-ai/sdk 的手写循环	TypeScript 通用	references/stack-typescript-generic.md
langsmith + openai／anthropic／langchain／llama_index	Python 通用	references/stack-python-generic.md
langgraph、crewai、agno、autogen	Python Agent	references/stack-python-agentic.md

如果信号存在重叠（例如，同时包含 LangGraph 主管流程和原始 OpenAI 调用），请优先选择 Agent 参考文档，并在计划中注明混合技术栈的情况。

如果完全无法识别任何 Agent 层（没有 LLM 客户端导入、Agent 框架或模型调用），请使用诚实跳过路径。

要确认当前的准确标识符（SDK 名称、wrapAISDK 是否可用、环境变量），请在编写时获取最新文档——docs.langchain.com/langsmith（annotate-code、threads、dashboards），或通过 Context7 查阅 langchain-ai/langsmith-sdk 文档。不要臆造 API。

步骤 2 — 绘制 Agent 拓扑图

（如果上游评估已有拓扑图，则跳过／复用。）启动一个 Explore Agent（对于非常小的仓库，也可以直接完成），回答以下四个问题，并注明文件路径：

1. 一轮对话从哪里开始？ — 入口点：HTTP 处理器、CLI 动词、队列使用者、聊天平台 Webhook。线程键（session_id）的来源就在这里。
2. Agent 单元有哪些？ — 主管函数、子 Agent 工厂、按角色专门化的循环。任何接收用户消息并返回响应的单元都包括在内。这些单元将成为根／子运行边界。
3. 工具在哪里定义和调用？ — 工具注册表（tools: [...]）、@tool 装饰器、MCP 服务接线。每个工具都需要呈现为一个 tool 类型的运行。
4. 子 Agent 在哪里将任务交给其他子 Agent？ — 主管 → 工作器、并行分发、图节点转换。这些位置需要重新附加线程键和元数据，因为 LangSmith 不会将元数据或标签从父运行传播到子运行。

在计划中用简短的拓扑图（ASCII 或 Mermaid）呈现这些信息。图不必详尽，但要让客户能在实施期间用一张图概览全局。

步骤 3 — 绘制 LangSmith 命名／映射表

阅读 references/langsmith-mapping.md，并将其应用到拓扑图中：

• 每个具有外部意义的单元对应一个根运行名称（chat-turn、job.summarise-thread、cron.nightly-research），run_type="chain"。
• 每个角色对应一个子运行名称（supervisor、research-agent、writer-agent），每个工具对应一个子运行名称（tool.<tool-id>、run_type="tool"）；模型调用命名为 llm.<model-shortname>，run_type="llm"；检索命名为 retrieve.<store>，run_type="retriever"。
• 每个运行都要包含线程键（session_id，或 thread_id／conversation_id）——在根运行上设置，并在每个子运行上重新附加，因为元数据不会继承。
• 标签：技术栈标识符、环境（dev／staging／prod）、Agent 版本，以及适用时的功能标志分组。
• 元数据键：一组简洁且一致的键，以便图表进行分组 — agent_role、tool_id、model_id、prompt_version、user_tier、gateway_origin（存在 Ratel 时）。

计划应在一个表格中列出引入的每个运行名称／标签／元数据键，供客户粘贴到共享文档中，并引用 references/langsmith-mapping.md。仪表板规范（步骤 5）和 /ratel-langsmith-analyze 都会读取此表；缺少该表时，它们将无法运行。映射会将供应商中立的约定 ../ratel-observability-assessment/references/semantic-conventions.md 映射到 LangSmith 基本元素上 — 不要重新推导这些规则。

步骤 4 — 规划逐文件插桩变更

对于每个需要接线的文件，引用技术栈参考资料（references/stack-*.md）中的匹配模式，而不是重新推导。每项应包括：文件路径、需要包装的内容、要使用的运行类型（chain／tool／llm／retriever），以及根据步骤 3 表格要附加的名称／标签／元数据 — 包括必须出现在每个运行中的线程键。

第 5 步 — 规划仪表板（两组）

打开 references/langsmith-value-map.md 和 ../ratel-observability-assessment/references/general-agent-dashboards.md。首先，记下内置的 Monitor 标签页已按项目提供的内容（Traces、LLM Calls、Cost & Tokens、Tools、Run Types、Feedback Scores）——不要将它们重新规划为自定义图表。然后，选择与实际已埋点数据相匹配的自定义图表子集。

默认选择：

• Ratel 价值组（仅当已采用或即将采用 Ratel 时）：Token Cost & Savings、Retrieval Quality、Gateway Origin Split、Upstream Health、Skill Retrieval Health（v0.1.6 系列中发布的技能）。仅当客户使用包含该功能的 Ratel 预发布版本，或已明确表示将采用该功能时，才添加路线图中有条件的项目（例如，v0.1.9 的 Suggestion Adoption）。名称和图表规格见 references/langsmith-value-map.md。
• Agent 健康状况组：Latency & Cost Overview、Error Surface、Tool Usage、Session Quality、Model & Prompt Drift。内容来自 ../ratel-observability-assessment/references/general-agent-dashboards.md——但跳过 Monitor 标签页已涵盖该项目的内容，其余部分则创建为 LangSmith 自定义图表（Langfuse 的“observation”筛选条件改为 run type/run name 筛选条件；Langfuse 的“trace”筛选条件改为 is_root）。

每个仪表板部分按以下顺序编写：

1. 名称 — 简短且以行动为导向（Token Cost & Savings，而不是 Dashboard 1）。
2. 重要性 — 用通俗英语写一段话；客户的 PM 应能判断该仪表板是否适用于他们。
3. 所需数据 — 依赖的运行名称、运行类型、标签和元数据键。第 3 步表格中缺少的任何内容，都是此处列出的 TODO 阻塞项。
4. 图表 — 对每张图表，填写 references/langsmith-value-map.md 中图表词汇表的五个字段：指标（y 轴）；筛选条件（运行名称 / 运行类型 / 标签 / 元数据 / is_root）；分组方式（标签 / 元数据 / 运行名称 / 运行类型——前 5 项）或明确的数据系列；图表类型（折线图 / 柱状图）。当分组方式的前 5 项限制不足以满足需求时，使用数据系列明确展示 A/B 对比。
5. 分析切入点 / 深入查看 — 图表显示异常时应点击什么，以及深入查看的位置（图表创建后，客户可重复使用的已保存运行表筛选条件）。
6. 路线图脚注（仅限 Ratel 仪表板）— 如果某个仪表板能从尚未发布的 Ratel 功能中受益，请注明功能名称和目标版本。复用 ../ratel-observability-assessment/references/ratel-value-map.md 中的版本映射，确保信息保持最新。

如果某个仪表板依赖的数据尚未埋点，请将其删除。宁可跳过，也不要造假。

步骤 6 — 决定是否添加 Ratel 感知钩子（仅当 Ratel 已存在或即将接入时）

检查清单中的任何位置是否出现 @ratel-ai/sdk、Python ratel-ai 包、ratel-ai-core 或 ratel-mcp / @ratel-ai/mcp-server 包。如果出现，或者客户计划在此次合作中接入 Ratel，请阅读 references/ratel-hooks.md，并在计划中添加一个章节，涵盖：

• 将每个 Ratel 跟踪事件映射到一个 LangSmith 运行（search → run_type: tool，名称为 ratel.search_capabilities；skill_search → ratel.skill_search；get_skill_content → ratel.get_skill_content；InvokeStart/InvokeEnd → run_type: tool，名称为 ratel.invoke_tool；等等）。名称已在 references/langsmith-value-map.md 中预留。
• 每次运行都必须包含的元数据：gateway_origin（direct 与 agent）、top_k、hit_count、replace_mode、最高命中项的得分、延迟，以及线程键（由于元数据不会继承，因此需要重新附加）。
• “前 / 后”标注策略，以便客户接入 Ratel 后进行 A/B 对比（通过分组或 Data Series 绘制图表的 feature_flag 标签划分，就是 A/B 对比界面）。

如果 Ratel 不存在且没有接入计划，请完全跳过本节。不要在客户自有文档中预先植入 Ratel 的销售宣传——保持计划实事求是。

步骤 7 — 编写计划

将计划写入 <repo>/.ratel/ratel-langsmith-integrate.md（如果 .ratel/ 目录不存在，则创建该目录；如果仓库已采用其他文档规范，请先询问用户确认路径）。

计划必须按以下顺序包含：

1. 摘要 — 一个段落：检测到的技术栈、Agent 拓扑、已完成的埋点（如有）、本计划要添加的内容（接线和仪表板），以及各组仪表板的数量。
2. 设置 — SDK 安装命令（Python / JS 的 langsmith）、环境变量（LANGSMITH_TRACING=true、LANGSMITH_API_KEY、LANGSMITH_PROJECT、LANGSMITH_ENDPOINT）、LangSmith MCP 服务注册步骤（为客户的 Claude Code / Cursor 配置 langsmith-mcp-server，以便 /ratel-langsmith-analyze 之后能读取运行数据），以及可粘贴并验证的有效“hello trace”代码片段。
3. 拓扑 — 步骤 2 中的图示。
4. LangSmith 命名 / 映射表 — 步骤 3 中的表格，并引用 references/langsmith-mapping.md。
5. 逐文件埋点变更 — 步骤 4 中的内容，并引用对应的 references/stack-*.md。
6. 仪表板构建规范 — 步骤 5 中的两组（Ratel 价值 + Agent 健康度），注明内置的 Monitor 标签页已涵盖哪些内容，并引用 references/langsmith-value-map.md 和 ../ratel-observability-assessment/references/general-agent-dashboards.md。
7. Ratel 钩子（根据步骤 6 条件决定是否添加），并引用 references/ratel-hooks.md。
8. 验证清单 — 从 references/verification-checklist.md 复制：埋点完成后，客户可以勾选的六个项目。
9. 暂不纳入范围 — 客户采用路线图中的 Ratel 功能（版本为 v<X.Y.Z>）后要添加的仪表板；以及需要目前尚无数据的仪表板。

在聊天中内联打印目录——列出各章节，以及带有一句“为何重要”说明的编号仪表板清单，并告知用户文件路径。不要在聊天中粘贴完整计划正文或完整图表规范；文件本身就是交付成果。

告知用户跟踪数据开始流入后的下一步：运行 /ratel-langsmith-analyze，读取实时数据并提出修复建议。

诚实的跳过路径

遇到以下几种情况时，请停止并说明原因；绝不可编造交付成果：

1. 未检测到 Agent 入口。 如果完成步骤 1 后，仍找不到任何 LLM 客户端导入、Agent 循环或模型调用，请停止。不要编写计划。告诉用户：

   未检测到 Agent 入口 — 仅检查了 <files looked at>。如果此代码库中的 Agent 代码位于非常规位置，请告诉我在哪里，我会重新检查。

   在非 Agent 代码库中强行制定埋点计划，只会产出无用文档并损害合作伙伴的信任。

2. 我们没有参考资料的技术栈（例如 Ruby、Go 或小众框架）。仍然要制定计划，但需将特定于技术栈的章节标记为“参照 Python 通用参考资料类比编写”，并询问用户是否要启动后续工作来编写新的参考资料。不要假装有把握。

3. 客户只想要 Ratel 价值仪表板，但没有使用 Ratel。 Ratel 仪表板至少需要接通网关链路。建议先小规模试用 Ratel（仅接入网关只需半天），再设计依赖它的仪表板。不要把 Ratel 钩子塞进未使用 Ratel 的 Agent 中 — 应改为呈现 Agent 健康状况组，并注明 Ratel 价值组因尚未采用 Ratel 而无法启用。

4. 需要埋点/仪表板，但还没有实时数据。 制定计划，但将每个仪表板标记为“受阻：无数据 — 首次生产流量到来后重新评估”。空仪表板会打击团队士气。

参考文件

• references/stack-vercel-ai-sdk.md
• references/stack-typescript-generic.md
• references/stack-python-generic.md
• references/stack-python-agentic.md
• references/langsmith-mapping.md — 通用语义约定在 LangSmith 中的呈现方式
• references/langsmith-value-map.md — Ratel 运行名称、Ratel 价值图表规范及 LangSmith 图表术语
• references/ratel-hooks.md — Ratel 事件 → LangSmith 运行
• references/verification-checklist.md

共享的、与供应商无关的参考资料（由 /ratel-observability-assessment 维护，仅链接，不重复收录）：

• ../ratel-observability-assessment/references/instrumentation-philosophy.md
• ../ratel-observability-assessment/references/semantic-conventions.md
• ../ratel-observability-assessment/references/general-agent-dashboards.md
• ../ratel-observability-assessment/references/ratel-value-map.md