langsmith-trace

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

LangSmith Trace

LangSmith 追踪

Add tracing to your agent and query traces for debugging. Supports Python and TypeScript.

[!IMPORTANT] This skill is tuned for AgentSeek template backends (LangGraph + middleware stacks). For general LangSmith concepts, see the upstream langsmith-skills repo.

[!CAUTION] Never pass
--api-key
as a CLI flag or expose API keys in shell commands / tool calls. The CLI reads
LANGSMITH_API_KEY
from the environment automatically. Using
--api-key <value>
leaks secrets into shell history, process listings, and agent tool-call logs. Always rely on the environment variable set in your shell profile or
.env
file.

为你的Agent添加追踪功能，并通过查询追踪记录进行调试。支持Python和TypeScript。

[!IMPORTANT] 此技能专为AgentSeek模板后端（LangGraph + 中间件栈）优化。如需了解通用LangSmith概念，请查看上游的langsmith-skills仓库。

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

Installation & Setup

安装与配置

1. Install the CLI

1. 安装CLI

bash

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

The binary installs to

~/.local/bin/langsmith

. If

langsmith

is not found after install, add to your shell profile:

bash

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

bash

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

二进制文件将安装到

~/.local/bin/langsmith

。如果安装后找不到

langsmith

命令，请将其添加到你的shell配置文件中：

bash

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

2. Set your API key (environment variable only)

2. 设置API密钥（仅通过环境变量）

Add to

~/.zshrc

(or the template's

.env

file) — the user must fill in their own key:

bash

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

Key format must start with

lsv2_pt_

. Get yours at https://smith.langchain.com/settings.

The CLI reads this env var automatically — never use
--api-key
flags. Do not echo, print, or pass the key value in any shell command or tool call argument.

将以下内容添加到

~/.zshrc

（或模板的

.env

文件）中——用户需自行填写密钥：

bash

export LANGSMITH_API_KEY=<your-key-here>  # 以lsv2_pt_开头

密钥格式必须以

lsv2_pt_

开头。可前往https://smith.langchain.com/settings获取你的密钥。

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

3. Verify

3. 验证

bash

langsmith project list

If you see a JSON array of projects, you're set. Common failures:

command not found
—
```
~/.local/bin
```
not in PATH (see step 1)
401 Unauthorized — key is wrong or expired; regenerate at LangSmith settings
Empty array
[]
— valid auth but no projects yet; create one in the UI or run a traced app

bash

langsmith project list

如果看到项目的JSON数组，则配置完成。常见失败原因：

command not found
——
```
~/.local/bin
```
未加入PATH（请查看步骤1）
401 Unauthorized —— 密钥错误或过期；请在LangSmith设置页面重新生成
空数组
[]
—— 认证有效但暂无项目；可在UI中创建一个，或运行已添加追踪的应用

Adding Tracing

添加追踪功能

LangGraph / LangChain apps (automatic)

LangGraph / LangChain应用（自动追踪）

Just set environment variables — no code changes needed:

bash

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"

For serverless (Python): also set

LANGCHAIN_CALLBACKS_BACKGROUND=false

to ensure traces flush before function exit.

只需设置环境变量——无需修改代码：

bash

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=<your-key-here>  # 必须设置；请勿通过--api-key参数传递
export LANGSMITH_PROJECT=my-project  # 可选，默认值为"default"

对于无服务器（Python）场景：还需设置

LANGCHAIN_CALLBACKS_BACKGROUND=false

，确保在函数退出前完成追踪记录的刷新。

Non-LangChain apps

非LangChain应用

Use the

@traceable

decorator (Python) or

traceable()

wrapper (TypeScript) and wrap your LLM client:

python

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

typescript

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" });

使用

@traceable

装饰器（Python）或

traceable()

包装器（TypeScript）来包裹你的LLM客户端：

python

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

typescript

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" });

Debugging a Trace (Step-by-Step)

追踪记录调试（分步指南）

This is the recommended workflow for investigating agent behavior:

以下是排查Agent行为的推荐工作流：

Step 1: Find the right project

步骤1：找到目标项目

bash

langsmith project list

Look at

last_run_start_time

to find which project has recent activity. Don't assume — LangGraph apps default to the

"default"

project, not a named one.

bash

langsmith project list

查看

last_run_start_time

以找到有近期活动的项目。不要想当然——LangGraph应用默认会追踪到

"default"

项目，而非命名项目。

Step 2: List recent traces

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

bash

langsmith trace list --project default --limit 5

bash

langsmith trace list --project default --limit 5

Or with full hierarchy inline (combines steps 2+3):

或直接显示完整层级结构（合并步骤2+3）：

langsmith trace list --project default --limit 5 --show-hierarchy

undefined

langsmith trace list --project default --limit 5 --show-hierarchy

undefined

Step 3: Get the trace hierarchy

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

bash

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

This returns the full run tree — use it to understand the agent's execution flow.

bash

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

此命令会返回完整的运行树——可用于理解Agent的执行流程。

Step 4: Get IO for all runs in a trace

步骤4：获取追踪中所有运行的IO数据

bash

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

This gives you inputs and outputs for every run (LLM calls, tool calls, middleware).

bash

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

此命令会返回每个运行（LLM调用、工具调用、中间件）的输入和输出数据。

Step 5: Drill into a specific run

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

bash

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

bash

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

AgentSeek Trace Structure

AgentSeek追踪记录结构

Our templates produce traces with this typical hierarchy:

<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

Key points:

The actual LLM call is always the innermost
```
ChatOpenAI
```
run
Tool results are in the
```
<tool_name>
```
run (e.g.,
```
generate_cover
```
,
```
execute
```
)
Middleware wrappers are transparent — they add latency but the IO you care about is at the leaf nodes

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

<agent_name> (根链)
├── SkillsMiddleware.before_agent
├── PatchToolCallsMiddleware.before_agent
├── MemoryMiddleware.before_agent
├── model (chain) ← LLM轮次
│   ├── 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) ← 实际LLM调用（输入/输出在此处）
├── TodoListMiddleware.after_model
├── tools (chain) ← 工具执行
│   ├── FilesystemMiddleware.awrap_tool_call
│   └── <tool_name> (tool) ← 实际工具（输入/输出在此处）
├── model (chain) ← 下一个LLM轮次
│   └── ...（相同的中间件栈）
└── TodoListMiddleware.after_model

关键点：

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

Gotchas

常见陷阱

--full

--include-io

on individual runs

单个运行中的

--full

与

--include-io

差异

Problem:

langsmith run get <id> --full

can return null for inputs/outputs, even though the data exists. Despite

--full

being documented as equivalent to

--include-metadata --include-io --include-feedback

, the underlying API behavior differs for individual run fetches in some CLI versions.

Solution: Always use

--include-io

explicitly when inspecting specific runs:

bash

undefined

问题：

langsmith run get <id> --full

可能会返回输入/输出为空值，即使数据实际存在。尽管文档说明

--full

等同于

--include-metadata --include-io --include-feedback

，但在某些CLI版本中，底层API在获取单个运行时的行为有所不同。

解决方案： 查看特定运行时，请始终显式使用

--include-io

：

bash

undefined

DO THIS

NOT THIS (may return null IO despite docs saying it includes --include-io)

不推荐（尽管文档说明包含--include-io，但可能返回空IO）

langsmith run get <run-id> --full


`--full` works reliably on `trace export` and `run list`, but has inconsistent behavior on individual `run get` calls. If this is fixed in a future CLI version, `--include-io` still works correctly — it's always safe.

langsmith run get <run-id> --full


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

Null IO even with

--include-io

使用

--include-io

仍返回空IO

If inputs/outputs come back null even with

--include-io

, the project has IO logging disabled. Check for these environment variables in the template's

.env

bash

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

Remove or set to

false

to enable IO capture for debugging.

如果使用

--include-io

后输入/输出仍为空，说明项目已禁用IO日志记录。请检查模板

.env

文件中的以下环境变量：

bash

LANGCHAIN_HIDE_INPUTS=true    # 在追踪记录中隐藏输入
LANGCHAIN_HIDE_OUTPUTS=true   # 在追踪记录中隐藏输出

删除这些变量或设置为

false

，以启用调试所需的IO捕获功能。

Project confusion

项目混淆

LangGraph apps trace to the

"default"

project unless

LANGSMITH_PROJECT

is explicitly set. Always run

langsmith project list

first and check

last_run_start_time

to find where your traces actually landed.

除非显式设置

LANGSMITH_PROJECT

，否则LangGraph应用会将追踪记录发送到

"default"

项目。请始终先运行

langsmith project list

，并查看

last_run_start_time

以确认追踪记录实际所在的项目。

Tips

提示

Add
```
--format pretty
```
for human-readable output during interactive debugging
Use
```
LANGSMITH_ENDPOINT
```
env var if connecting to a self-hosted LangSmith instance
The middleware ordering in the trace tree is configurable — your template may differ slightly from the diagram above

在交互式调试时，添加
```
--format pretty
```
参数以获得人类可读的输出
如果连接到自托管的LangSmith实例，请使用
```
LANGSMITH_ENDPOINT
```
环境变量
追踪树中的中间件顺序是可配置的——你的模板可能与上述示意图略有不同

CLI Reference

CLI参考

Full command reference: reference/cli-commands.md

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

langsmith-trace

Original

Translation

LangSmith Trace

LangSmith 追踪

Installation & Setup

安装与配置

1. Install the CLI

1. 安装CLI

2. Set your API key (environment variable only)

2. 设置API密钥（仅通过环境变量）

3. Verify

3. 验证

Adding Tracing

添加追踪功能

LangGraph / LangChain apps (automatic)

LangGraph / LangChain应用（自动追踪）

Non-LangChain apps

非LangChain应用

Debugging a Trace (Step-by-Step)

追踪记录调试（分步指南）

Step 1: Find the right project

步骤1：找到目标项目

Step 2: List recent traces

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

Or with full hierarchy inline (combines steps 2+3):

或直接显示完整层级结构（合并步骤2+3）：

Step 3: Get the trace hierarchy

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

Step 4: Get IO for all runs in a trace

步骤4：获取追踪中所有运行的IO数据

Step 5: Drill into a specific run

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

AgentSeek Trace Structure

AgentSeek追踪记录结构

Gotchas

常见陷阱

--full vs --include-io on individual runs

单个运行中的--full与--include-io差异

DO THIS

推荐用法

NOT THIS (may return null IO despite docs saying it includes --include-io)

不推荐（尽管文档说明包含--include-io，但可能返回空IO）

Null IO even with --include-io

使用--include-io仍返回空IO

Project confusion

项目混淆

Tips

提示

CLI Reference

CLI参考

`--full`
vs
`--include-io`
on individual runs

单个运行中的
`--full`
与
`--include-io`
差异

Null IO even with
`--include-io`

使用
`--include-io`
仍返回空IO