JARVIS/docs/superpowers/specs/2026-03-20-langsmith-integration-design.md

LangSmith 集成设计文档

日期: 2026-03-20 状态: 设计中 范围: 后端 LangGraph Agent 追踪

---

1. 背景与目标

Jarvis 后端基于 LangGraph 构建了多智能体系统（Master/Planner/Executor/Librarian/Analyst），目前没有可观测性能力。

本次集成目标：

1. 调用追踪 — 在 LangSmith Dashboard 查看完整的 Agent 执行轨迹
2. 对话历史管理 — 按 run_id 聚合对话，自动存储到 LangSmith
3. 评估支持 — 积累的对话数据可用于 LangSmith Evaluation

---

2. 集成方案（方案 A：最小集成）

2.1 核心思路

LangGraph 内置对 LangSmith 的支持，只需三步即可完成集成：

1. 在 .env 中配置 LangSmith 环境变量
2. 在 pyproject.toml 中添加 langsmith 为直接依赖
3. 在 llm_service.py 中为 LLM 调用注入 LangSmith Callback

LangGraph 的 compile() 会自动将 Callback 传递到所有节点，无需修改 graph.py。

2.2 环境变量

在 backend/.env.example 中新增：

# LangSmith Tracing
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=your-langsmith-api-key
LANGSMITH_PROJECT=jarvis-agent

2.3 依赖

在 backend/pyproject.toml 的 dependencies 中添加：

"langsmith>=0.1.0",

2.4 配置类变更

在 backend/app/config.py 中新增配置字段：

# LangSmith
LANGSMITH_TRACING: bool = False
LANGSMITH_API_KEY: str = ""
LANGSMITH_PROJECT: str = "jarvis-agent"

2.5 实现变更

2.5.1 Config 层

在 backend/app/config.py 中新增配置字段：

LANGSMITH_TRACING: bool = False
LANGSMITH_API_KEY: str = ""
LANGSMITH_PROJECT: str = "jarvis-agent"

创建 backend/app/config_tracing.py 作为独立的 callback 工厂模块：

from langchain_core.callbacks import LangChainTracer
from app.config import settings

def get_langsmith_callbacks() -> list:
    if not settings.LANGSMITH_TRACING or not settings.LANGSMITH_API_KEY:
        return []
    return [LangChainTracer(project_name=settings.LANGSMITH_PROJECT)]

2.5.2 Graph 层

在 backend/app/agents/graph.py 中：

1. create_agent_graph() 新增 callbacks 参数，透传给 graph.compile(callbacks=...)
2. get_agent_graph() 内部调用 get_langsmith_callbacks() 并与传入参数合并后传给 create_agent_graph()

LangGraph 的 compile(callbacks=...) 会自动将 callbacks 传播到所有节点的 LLM 调用，覆盖 Master/Planner/Executor/Librarian/Analyst 全部 5 个节点。

2.6 Streaming 兼容性

当前 streaming 通过 graph.astream_events() 实现。LangSmith Callback 会异步记录追踪数据，不影响流式输出的实时性。

如果需要在 streaming 过程中实时展示 trace URL，可以在 on_chat_model_end 事件中从 run.id 生成链接：

async for event in graph.astream_events(...):
    if event["event"] == "on_chat_model_end":
        run_id = event["data"]["output"].id  # 从 response 中获取 run_id
        trace_url = f"https://smith.langchain.com/runs/{run_id}"

---

3. 文件变更清单

文件	变更类型
backend/.env.example	新增 3 行环境变量
backend/pyproject.toml	新增 langsmith 依赖
backend/app/config.py	新增 3 个配置字段
backend/app/config_tracing.py	新建，callback 工厂函数
backend/app/agents/graph.py	create_agent_graph/get_agent_graph 支持 callbacks
backend/app/services/agent_service.py	get_agent_graph() 调用签名对齐

---

4. 风险与限制

• LangSmith 免费版有追踪数量限制（详见 LangSmith 定价）
• Streaming 模式下 trace 数据在调用结束后才完整展示
• 需要用户自行在 langchain.com 注册并获取 API Key

---

5. 测试验证

集成完成后通过以下方式验证：

1. 设置 LANGSMITH_TRACING=true 并配置 API Key
2. 发起一次 Agent 对话
3. 在 LangSmith Dashboard 中查看对应的 trace，确认包含：
   • 5 个节点的执行记录
   • 每个节点的 LLM 输入/输出
   • 工具调用记录
   • Token 消耗统计