SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场langsmith-trace

langsmith-trace

智能体与模型

查看项目

更新于 10-15 15:15

技能介绍

LangSmith Trace 是一个用于 AgentSeek 模板的 LangSmith 追踪与调试技能，支持 Python 和 TypeScript。它帮助开发者为智能体添加追踪能力，并通过查询 trace 来调试智能体行为。该技能针对 AgentSeek 模板后端（LangGraph + 中间件栈）进行了调优；如需了解通用 LangSmith 概念，可参考上游的 langsmith-skills 仓库。

安全注意：切勿将 --api-key 作为 CLI 标志传递，也不要在 shell 命令或工具调用中暴露 API key。CLI 会自动从环境变量读取 LANGSMITH_API_KEY。使用 --api-key <value> 会将密钥泄露到 shell 历史、进程列表和智能体工具调用日志中。请始终依赖 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

  1. 设置 API key（仅通过环境变量）

添加到 ~/.zshrc（或模板的 .env 文件）——用户需自行填写自己的 key：

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

Key 格式必须以 lsv2_pt_ 开头。可在 https://smith.langchain.com/settings 获取。CLI 会自动读取该环境变量——切勿使用 --api-key 标志。不要在任何 shell 命令或工具调用参数中回显、打印或传递 key 值。

  1. 验证

langsmith project list

如果看到 JSON 项目数组，说明配置成功。常见失败情况：

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

添加追踪

LangGraph / LangChain 应用（自动）

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

export LANGSMITH_TRACING=true export LANGSMITH_API_KEY=<your-key-here> # 必须设置；不要通过 --api-key 标志传递 export LANGSMITH_PROJECT=my-project # 可选，默认为 "default"

对于无服务器（Python）：还需设置 LANGCHAIN_CALLBACKS_BACKGROUND=false，以确保 trace 在函数退出前刷新。

非 LangChain 应用

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

调试 Trace（分步）

这是调查智能体行为的推荐工作流：

步骤 1：找到正确的项目

langsmith project list

查看 last_run_start_time 以确定哪个项目有最近活动。不要假设——LangGraph 应用默认使用 "default" 项目，而非命名项目。

步骤 2：列出最近的 trace

langsmith trace list --project default --limit 5

或内联显示完整层级（合并步骤 2+3）：

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

步骤 3：获取 trace 层级

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

返回完整的 run 树——用于理解智能体的执行流程。

步骤 4：获取 trace 中所有 run 的 IO

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

这会给出每个 run（LLM 调用、工具调用、中间件）的输入和输出。

步骤 5：深入特定 run

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

AgentSeek Trace 结构

我们的模板生成的 trace 具有以下典型层级：

<agent_name> (root chain) ├── 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 run
  • 工具结果位于 <tool_name> run 中（例如 generate_cover、execute）
  • 中间件包装器是透明的——它们增加延迟，但你关心的 IO 在叶子节点

注意事项

单个 run 上 --full 与 --include-io 的差异

问题：langsmith run get <id> --full 可能返回 null 的输入/输出，即使数据存在。尽管文档称 --full 等同于 --include-metadata --include-io --include-feedback，但在某些 CLI 版本中，底层 API 对单个 run 获取的行为不同。

解决方案：检查特定 run 时始终显式使用 --include-io：

这样做

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

不要这样做（尽管文档说包含 --include-io，但可能返回 null IO）

langsmith run get <run-id> --full

--full 在 trace 导出和 run list 上可靠，但在单个 run get 调用上行为不一致。如果未来 CLI 版本修复了此问题，--include-io 仍然有效——它始终安全。

即使使用 --include-io 仍为 Null IO

如果即使使用 --include-io，输入/输出仍返回 null，说明项目禁用了 IO 日志记录。检查模板 .env 中的这些环境变量：

LANGCHAIN_HIDE_INPUTS=true # 从 trace 中隐藏输入 LANGCHAIN_HIDE_OUTPUTS=true # 从 trace 中隐藏输出

移除或设为 false 以启用 IO 捕获以便调试。

项目混淆

除非显式设置 LANGSMITH_PROJECT，否则 LangGraph 应用会追踪到 "default" 项目。始终先运行 langsmith project list 并检查 last_run_start_time，以找到 trace 实际落地的位置。

提示

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

CLI 参考

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