Comet × LangSmith集成指南：把Agent Skill评估与Trace追踪带入企业生产环境
【免费下载链接】cometComet: agent skill harness for turning ideas into evaluated workflows项目地址: https://gitcode.com/rpamis/comet
Comet是一个面向 Agent 的 Skill 评估与运行框架（agent skill harness for turning ideas into evaluated workflows），内置的comet eval评估系统自带LangSmith 集成套件：一次评估运行即可把 Skill 评估结果、Rubric 分数、Token 成本与 Claude Code 完整 Trace 轨迹同步到你的 LangSmith 项目，让 Agent Skill 的质量评估从"本地跑个报告"升级为企业级的可观测、可对比、可回溯的生产实践。
一、为什么要把 Comet 评估接入 LangSmith？
Comet 的comet eval默认使用local 套件，报告写在项目本地的.comet/eval/runs/里，适合日常开发。但进入团队协作或生产环境后，你通常需要：
- 评估数据集中存储，按项目/团队统一审计；
- 对比不同 Skill 版本、不同模型、有无 Skill 注入（
CONTROL对照）的效果差异； - 出问题时逐轮查看 Agent 的工具调用轨迹，而不只是一张汇总表。
这正是 Comet 的langsmith套件要解决的问题：它复用与 local 套件完全相同的任务集、treatment 组合与 Rubric 判据，只把结果上报层切换到 LangSmith，无需重写任何评估定义。官方说明见 docs/operations/EVAL-USAGE.md（中文版本：docs/operations/EVAL-USAGE-ZH.md）。
二、集成后，你的 LangSmith 项目里会有什么？
| LangSmith 概念 | Comet 映射 | 你能看到什么 |
|---|---|---|
| Dataset example | 每个评估任务 | 任务输入 + 预期产物、必需 Skill、Rubric 判据 |
| Experiment | 每个 treatment（Skill 组合） | CONTROL与注入 Skill 的实验并排对比 |
| Run outputs | 每次运行 | 轮次数、工具调用数、耗时、Token、成本、调用的 Skill |
| Feedback scores | Rubric 各维度 + 检查通过率 | rubric.*分项分数与checks_pass_rate |
| 嵌套 Trace | Claude Code 完整轨迹 | 逐轮对话、工具调用细节 |
三、三步完成集成
第 1 步：获取仓库并配置 API Key
git clone https://gitcode.com/rpamis/comet cd comet/eval uv sync --extra langsmith然后在eval/.env或eval/langsmith/.env中配置三个变量即可：
LANGSMITH_API_KEY=lsv2_pt_... LANGSMITH_PROJECT=comet-skill-eval LANGSMITH_TRACING=true💡 Comet 会从这组
LANGSMITH_*配置自动派生Claude Code 官方轨迹插件所需的TRACE_TO_LANGSMITH、CC_LANGSMITH_API_KEY、CC_LANGSMITH_PROJECT，通常你不需要手动设置任何CC_*变量（见 eval/langsmith/README.md）。
第 2 步：运行 LangSmith 评估套件
最简方式——直接用 CLI 的--suite langsmith，它会读取上述环境变量、准备轨迹插件并写入项目本地报告：
comet eval ./my-skill --suite langsmith --html也可以走 pytest 路径做实验对比：一个 treatment 对应一个 experiment，用LANGSMITH_EXPERIMENT命名便于在对比页并排查看：
LANGSMITH_EXPERIMENT=COMET_FULL_040_BETA \ uv run pytest langsmith/tests/tasks/test_tasks.py \ --task=comet-fix-median --treatment=COMET_FULL_040_BETA -v LANGSMITH_EXPERIMENT=CONTROL \ uv run pytest langsmith/tests/tasks/test_tasks.py \ --task=comet-fix-median --treatment=CONTROL -v套件默认通过BENCH_TASKS_DIR等环境变量复用 eval/local/ 中的任务、treatment 与 Skill 库（机制定义在 eval/langsmith/tests/conftest.py），所以你在 LangSmith 里看到的评估口径与本地报告完全一致。CLI 侧的实现入口是 app/commands/eval.ts。
第 3 步：（可选）启用 Claude Code 全链路轨迹
只需保持LANGSMITH_TRACING=true。首次运行时，套件会用node:20容器把官方langsmith-tracing插件一次性构建到eval/.cache/langsmith-cc-plugin缓存目录，之后运行直接复用并只读挂载进任务容器。轨迹会通过CC_LANGSMITH_PARENT_DOTTED_ORDER嵌套在对应的 run 下。
几点行为保证，便于生产环境放心使用：
- 轨迹追踪是best-effort：插件缺失或构建失败时只跳过轨迹，Rubric 与 treatment 对比照常上报，不会弄挂评估；
- 想固定版本或关闭自动构建，可设置
CC_LANGSMITH_PLUGIN_DIR（指向宿主机插件目录）或CC_LANGSMITH_PLUGIN_AUTO_BUILD=false。
四、如何在 LangSmith 里读结果
- 先看实验对比页：同一任务下，
CONTROL与注入 Skill 的实验并排放置，rubric.*分数与checks_pass_rate一眼可见优劣； - 再看单 run 详情：轮次数、工具调用、Token 与成本异常时，下钻到嵌套的 Claude Code Trace 定位具体哪一步走偏；
- 失败归因：本地 HTML 报告同时会给出 harness / workflow / task / model 四级 failure attribution，可用来区分"评估环境问题"和"Skill 真实能力问题"。
五、常见问题速查
| 现象 | 原因与处理 |
|---|---|
| 环境里开了 tracing，LangSmith 却没有任何 experiment | 未加--suite langsmith。Local 套件不会创建 LangSmith 实验，必须显式选择 langsmith 套件 |
| 运行被跳过、提示凭据缺失 | 套件对非单元测试运行强制校验LANGSMITH_API_KEY，配置到eval/.env即可 |
| 只有分数没有轨迹 | 轨迹插件未就绪。等待首次自动构建完成，或用CC_LANGSMITH_PLUGIN_DIR指定已构建插件目录 |
| 只想低成本冒烟 | comet eval ./my-skill --quick --html，使用固定 smoke 任务，不消耗完整评估 |
六、延伸资料
- 评估套件总览与排错指引：docs/operations/EVAL-USAGE-ZH.md
- LangSmith 套件安装、运行与轨迹插件细节：eval/langsmith/README.md
- 套件环境装配与插件自动构建逻辑：eval/langsmith/tests/conftest.py
- 上报封装（inputs / outputs / feedback）实现：eval/langsmith/tests/tasks/test_tasks.py
- 可复用的任务与 treatment 语料库：eval/local/
- LangSmith CLI 命令实现：app/commands/eval.ts
按这套流程走下来，你的 Agent Skill 评估就同时拥有了本地 HTML 报告（快速反馈）与LangSmith 集中观测（生产审计）双通道——同一套任务、同一套 Rubric，数据口径完全一致，可以直接支撑版本回归与模型选型的量化决策。
【免费下载链接】cometComet: agent skill harness for turning ideas into evaluated workflows项目地址: https://gitcode.com/rpamis/comet
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考