langsmith-trace

LangSmith 追踪

为 Agent 添加追踪，并查询追踪记录以进行调试。支持 Python 和 TypeScript。

重要

此技能针对 AgentSeek 模板后端（LangGraph + 中间件栈）进行了调优。有关 LangSmith 概念的一般介绍，请参阅上游 langsmith-skills 仓库。

注意

切勿将 --api-key 作为 CLI 标志传入，也不要在 shell 命令或工具调用中暴露 API 密钥。 CLI 会自动从环境中读取 LANGSMITH_API_KEY。使用 --api-key <value> 会将密钥泄露到 shell 历史记录、进程列表和 Agent 工具调用日志中。务必使用 shell 配置文件或 .env 文件中设置的环境变量。

安装与设置

1. 安装 CLI

curl -sSL https://raw.githubusercontent.com/langchain-ai/langsmith-cli/main/scripts/install.sh | sh

二进制文件会安装到 ~/.local/bin/langsmith。如果安装后找不到 langsmith，请将其添加到 shell 配置文件中：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

2. 设置 API 密钥（仅使用环境变量）

添加到 ~/.zshrc（或模板的 .env 文件）中——用户必须填写自己的密钥：

export LANGSMITH_API_KEY=<your-key-here>  # starts with lsv2_pt_

密钥格式必须以 lsv2_pt_ 开头。请前往 https://smith.langchain.com/settings 获取密钥。

CLI 会自动读取此环境变量——切勿使用 --api-key 标志。 不要在任何 shell 命令或工具调用参数中回显、打印或传递密钥值。

3. 验证

langsmith project list

如果你看到项目的 JSON 数组，就表示设置完成。常见问题：

• command not found —— ~/.local/bin 不在 PATH 中（参见步骤 1）
• 401 Unauthorized —— 密钥错误或已过期；请前往 LangSmith 设置重新生成
• 空数组 [] —— 身份验证有效，但尚无项目；请在 UI 中创建一个项目，或运行已启用追踪的应用

添加追踪

LangGraph / LangChain 应用（自动）

只需设置环境变量，无需更改代码：

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=<your-key-here>  # must be set; do NOT pass via --api-key flag
export LANGSMITH_PROJECT=my-project  # optional, defaults to "default"

对于无服务器环境（Python）：还需设置 LANGCHAIN_CALLBACKS_BACKGROUND=false，以确保函数退出前刷新追踪记录。

非 LangChain 应用

使用 @traceable 装饰器（Python）或 traceable() 包装器（TypeScript），并包装你的大模型客户端：

from langsmith import traceable
from langsmith.wrappers import wrap_openai
from openai import OpenAI

client = wrap_openai(OpenAI())

@traceable
def my_pipeline(question: str) -> str:
    resp = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": question}],
    )
    return resp.choices[0].message.content

import { traceable } from "langsmith/traceable";
import { wrapOpenAI } from "langsmith/wrappers";
import OpenAI from "openai";

const client = wrapOpenAI(new OpenAI());

const myPipeline = traceable(async (question: string) => {
  const resp = await client.chat.completions.create({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: question }],
  });
  return resp.choices[0].message.content || "";
}, { name: "my_pipeline" });

调试追踪记录（分步说明）

这是调查 Agent 行为的推荐工作流：

步骤 1：找到正确的项目

langsmith project list

查看 last_run_start_time，找出近期有活动的项目。不要想当然——LangGraph 应用默认使用 "default" 项目，而不是命名项目。

步骤 2：列出近期追踪记录

langsmith trace list --project default --limit 5

# Or with full hierarchy inline (combines steps 2+3):
langsmith trace list --project default --limit 5 --show-hierarchy

步骤 3：获取追踪层级结构

langsmith trace get <trace-id> --project <name>

这会返回完整的运行树——用它来了解 Agent 的执行流程。

步骤 4：获取追踪记录中所有运行的 IO

langsmith run list --trace-ids <trace-id> --project <name> --include-io

这会提供每次运行（大模型调用、工具调用、中间件）的输入和输出。

步骤 5：深入查看特定运行

langsmith run get <run-id> --include-io

AgentSeek 追踪结构

我们的模板会生成具有以下典型层级结构的追踪记录：

<agent_name> (root chain)
├── SkillsMiddleware.before_agent
├── PatchToolCallsMiddleware.before_agent
├── MemoryMiddleware.before_agent
├── model (chain) ← LLM turn
│   ├── TodoListMiddleware.awrap_model_call
│   ├── SkillsMiddleware.awrap_model_call
│   ├── FilesystemMiddleware.awrap_model_call
│   ├── SubAgentMiddleware.awrap_model_call
│   ├── SummarizationMiddleware.awrap_model_call
│   ├── AnthropicPromptCachingMiddleware.awrap_model_call
│   ├── MemoryMiddleware.awrap_model_call
│   └── ChatOpenAI (llm) ← actual LLM call (inputs/outputs here)
├── TodoListMiddleware.after_model
├── tools (chain) ← tool execution
│   ├── FilesystemMiddleware.awrap_tool_call
│   └── <tool_name> (tool) ← actual tool (inputs/outputs here)
├── model (chain) ← next LLM turn
│   └── ... (same middleware stack)
└── TodoListMiddleware.after_model

要点：

• 实际的大模型调用始终是最内层的 ChatOpenAI 运行
• 工具结果位于 <tool_name> 运行中（例如 generate_cover、execute）
• 中间件包装器是透明的——它们会增加延迟，但你关注的 IO 位于叶节点

注意事项

对单个运行使用 --full 与 --include-io

问题：langsmith run get <id> --full 可能会对输入/输出返回 null，即使数据实际存在也是如此。虽然文档称 --full 等同于 --include-metadata --include-io --include-feedback，但在某些 CLI 版本中，底层 API 对单个运行获取请求的行为有所不同。

**解决方案：**检查特定运行时，始终显式使用 --include-io：

# DO THIS
langsmith run get <run-id> --include-io

# NOT THIS (may return null IO despite docs saying it includes --include-io)
langsmith run get <run-id> --full

--full 在 trace export 和 run list 中工作可靠，但在单个 run get 调用中的表现不一致。如果未来的 CLI 版本修复了此问题，--include-io 仍可正常工作——始终安全可用。

即使使用 --include-io，IO 仍为空

如果输入/输出仍为空，即使使用了 --include-io，说明项目已禁用 IO 日志记录。请检查模板的 .env 中是否有以下环境变量：

LANGCHAIN_HIDE_INPUTS=true    # hides inputs from traces
LANGCHAIN_HIDE_OUTPUTS=true   # hides outputs from traces

移除该变量或将其设为 false，即可启用 IO 捕获以进行调试。

项目混淆

除非显式设置了 LANGSMITH_PROJECT，否则 LangGraph 应用会跟踪到 "default" 项目。请务必先运行 langsmith project list，并检查 last_run_start_time，以确定跟踪数据实际存放的位置。

提示

• 添加 --format pretty，以便在交互式调试期间以易读格式输出
• 如果连接到可自托管的 LangSmith 实例，请使用 LANGSMITH_ENDPOINT 环境变量
• 跟踪树中的中间件顺序可配置 — 你的模板可能与上方的示意图略有不同

CLI 参考

完整命令参考：reference/cli-commands.md