帮你快速理解、总结文档立即下载
文档中心>日志服务>Agent 可观测>接入指南>接入 Agent 框架和自研应用>接入 LangChain/LangGraph 数据

接入 LangChain/LangGraph 数据

最近更新时间：2026-10-15 17:24:31
我的收藏

本页目录：

操作场景

LangChain 和 LangGraph 是常用的 Agent 应用开发框架，运行时会产生多轮推理、模型调用、工具调用和子 Agent 调用等数据。安装 tencentcloud-agentobs-sdk-langchain 后，只需调用一次 setup()，即可自动拦截 LangChain 回调与 LangGraph 节点事件，还原完整调用链路，并将 Trace 上报。
接入后可以查看以下内容：
每次 invoke() 的完整调用链，以及入口、Agent、推理轮次（Step）、Chain、模型调用和工具调用之间的父子关系。
模型调用的请求模型、响应模型、输入/输出 Token、结束原因（finish_reason）和输入/输出消息。
工具名称、调用参数、返回结果、错误类型和错误信息，错误类型自动分类为超时、限流、鉴权失败、参数校验失败等。
LangChain 内部节点（如 RunnableSequence、Prompt、should_continue）的执行情况，以及 ReAct 推理轮次编号。
并行工具调用、嵌套子 Agent、RunnableParallel 等并发场景下的正确调用归属。
SDK 支持以下两种接入方式：
接入方式
说明
推荐场景
使用支持 Skill 的 AI 工具，由 AI 创建或复用日志主题，并完成 SDK 安装、配置和验证。
希望减少手动配置，并用自然语言分析 Trace
安装 SDK，配置 Endpoint、日志主题和访问凭证，在代码中调用 setup()
需要精细控制参数，或所用工具不支持 Skill

前提条件

已开通 日志服务 CLS。
已准备具备 CLS 写入权限的访问凭证，例如 CAM 子账号、CAM 角色或临时密钥。可前往 API 密钥管理 页面获取，密钥需对目标主题有写入权限，权限模板参见 采集 Agent 可观测数据。
已获取 CLS 地域接入点。以广州地域为例：
方式一填写地域：ap-guangzhou。
方式二填写域名：内网为 ap-guangzhou.cls.tencentyun.com，外网为 ap-guangzhou.cls.tencentcs.com。
已安装 LangChain 或 LangGraph，且应用可以正常运行。版本要求：Python 3.9及以上，langchain-core 0.2及以上。

方式一：通过 Skill 快速接入与分析

在支持 Skill 的 AI 工具中，引用 腾讯云 Agent 可观测助手 Skill，让 AI 将当前 LangChain / LangGraph 项目接入 Agent 可观测。例如输入：
使用 tencentcloud-cls-agent-obs Skill，把当前 LangChain 项目接入腾讯云 Agent 可观测，地域为 ap-guangzhou。
接入完成后，可以直接用自然语言提出分析需求，例如：
分析最近 1 小时内耗时最高、Token 消耗最多和失败最多的调用，并给出可能原因。

方式二：手动配置接入

步骤1：创建 Agent 可观测应用

1. 登录 日志服务控制台，在左侧导航栏中选择 Agent 可观测。
2. 单击应用接入，按页面提示创建应用。
3. 在应用右侧单击编辑，复制 Trace 日志主题 ID，用作后续的 CLS_TOPIC_ID。

步骤2：安装 SDK

执行以下命令安装 SDK。安装时会自动安装 langchain-core、CLS SDK 等依赖。
macOS / Linux
Windows（PowerShell）
pip install tencentcloud-agentobs-sdk-langchain
py -m pip install tencentcloud-agentobs-sdk-langchain
说明：
如果使用 LangGraph 构建 Agent，需要额外安装 langgraph；调用模型时需要安装对应的模型集成包，例如 langchain-openai。
如果使用 Deep Agents，可以通过 pip install 'tencentcloud-agentobs-sdk-langchain[deepagents]' 一并安装可选依赖。

步骤3：配置环境变量

配置 CLS 连接信息和模型服务的 API Key。
macOS / Linux
Windows（PowerShell）
# 以广州地域外网接入点为例
export CLS_ENDPOINT=ap-guangzhou.cls.tencentcs.com
export CLS_TOPIC_ID=<Trace 日志主题 ID>
export CLS_SECRET_ID=<SecretId>
export CLS_SECRET_KEY=<SecretKey>
export OPENAI_API_KEY=<模型服务 API Key>
# 以广州地域外网接入点为例
$env:CLS_ENDPOINT = "ap-guangzhou.cls.tencentcs.com"
$env:CLS_TOPIC_ID = "<Trace日志主题ID>"
$env:CLS_SECRET_ID = "<SecretId>"
$env:CLS_SECRET_KEY = "<SecretKey>"
$env:OPENAI_API_KEY = "<模型服务API Key>"
环境变量
必填
说明
CLS_ENDPOINT
是
CLS 地域接入点域名，不含协议前缀和路径，须与 Trace 日志主题位于同一地域。
CLS_TOPIC_ID
是
步骤1中获取的 Trace 日志主题 ID，不是应用 ID。
CLS_SECRET_ID
是
访问凭证 SecretId，需具备目标日志主题的写入权限。请前往 API 密钥管理 获取。
CLS_SECRET_KEY
是
访问凭证 SecretKey。请前往 API 密钥管理 获取。
OPENAI_API_KEY
否
模型服务 API Key，由 LangChain 模型集成包读取，与 SDK 无关。使用其他模型服务时，按对应集成包要求配置。
注意：
访问凭证属于敏感信息，建议通过环境变量注入，并使用最小权限、可轮换的临时凭证，避免将 SecretKey 写入代码或提交到代码仓库。

步骤4：初始化采集

在首次调用 invoke() 之前导入并调用 setup()，原有 LangChain / LangGraph 业务代码无需修改。
from tencentcloud_agentobs_sdk_langchain import setup

# 从环境变量读取 CLS 配置，须在运行任何 Agent 之前调用
setup()

# 以下为原有 LangChain / LangGraph 代码，无需修改
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

@tool
def get_weather(city: str) -> str:
    """查询城市天气。"""
    return {"北京": "晴 26℃"}.get(city, "晴 25℃")

agent = create_react_agent(ChatOpenAI(model="gpt-4o-mini"), tools=[get_weather])
result = agent.invoke({"messages": [("user", "北京天气怎么样？")]})
print(result["messages"][-1].content)
如果需要在代码中显式指定参数，可以传入 CLSConfig，未填写的字段会回退读取环境变量：
import os
from tencentcloud_agentobs_sdk_langchain import setup, CLSConfig

setup(CLSConfig(
    endpoint=os.environ["CLS_ENDPOINT"],
    topic_id=os.environ["CLS_TOPIC_ID"],
    secret_id=os.environ["CLS_SECRET_ID"],
    secret_key=os.environ["CLS_SECRET_KEY"],
    service_name="my-langchain-app",
    content_mode="truncate",
))
注意：
setup() 必须在首次运行 Agent 前调用。建议只在应用启动入口调用一次，避免重复注册导致重复 Trace。
CLSConfig 支持的参数如下，优先级为：CLSConfig 显式传入的值 > 环境变量 > 默认值。
参数
环境变量
默认值
说明
endpoint
CLS_ENDPOINT
无
CLS 地域接入点域名，必填。
topic_id
CLS_TOPIC_ID
无
Trace 日志主题 ID，必填。
secret_id
CLS_SECRET_ID
无
访问凭证 SecretId，必填。
secret_key
CLS_SECRET_KEY
无
访问凭证 SecretKey，必填。
service_name
CLS_SERVICE_NAME 或 OTEL_SERVICE_NAME
langchain-app
服务或应用名称。
content_mode
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT
full
内容采集策略，取值为 full、truncate、off，详见下文 内容采集策略。
batch_size
CLS_BATCH_SIZE
32
每批上报的 Span 数量，取值范围为1 - 1000。
debug
CLS_DEBUG
false
是否输出详细的 SDK 日志。
local_dump
CLS_LOCAL_DUMP
false
是否同时将每批上报数据写入本地 JSONL 文件，便于排查问题。
local_dump_file
CLS_LOCAL_DUMP_FILE
cls_spans.jsonl
本地 JSONL 文件路径。
user_id
CLS_USER_ID
无
终端用户 ID，写入 gen_ai.user.id 字段。
说明：
SDK 运行日志默认写入 cls_sdk.log 并自动轮转，可通过环境变量 CLS_SDK_LOG_FILE 和 CLS_SDK_LOG_LEVEL 修改日志文件路径和日志级别。

步骤5：运行 Agent 并验证结果

1. 按原方式启动应用，发起一次包含模型调用的请求，建议同时触发工具调用，并等待一个刷新周期。
2. 登录 日志服务控制台，进入 Agent 可观测，打开步骤1中创建的应用。
3. 打开调用链页面，选择包含测试请求的时间范围，打开最新的 Trace。
4. 确认 Trace 中包含 Entry、Agent、Step、Chain、Chat、Tool 等 Span，并点开具体 Span，检查耗时、状态、输入输出、Token 用量和请求参数。
以上述示例代码为例，一次 invoke() 会产生如下调用树：
entry  enter_application                 本轮请求根节点
└ agent  invoke_agent                    Agent 执行区间
  ├ step  react round_1                  第 1 轮推理
  │ ├ chain  call_model                  LangGraph 节点
  │ ├ chain  RunnableSequence            Prompt + LLM 管道
  │ │ ├ chain  Prompt
  │ │ └ chat   gpt-4o-mini               模型调用
  │ ├ chain  should_continue             路由判断
  │ └ tool   get_weather                 工具调用（并行调用时每个工具一个 Span）
  └ step  react round_2                  第 2 轮推理
    └ chat   gpt-4o-mini                 模型调用

采集数据说明

Span 层级与采集属性

SDK 按 LangChain 真实的回调嵌套关系还原调用树，层级为 entry → agent → step → chain → chat / tool。每次进入 LangGraph 的 Agent 节点会开启一个新的 ReAct 推理轮次（Step）。各类 Span 采集的主要属性如下：
Span 类型
说明
采集属性
entry
本轮请求的根节点
整次请求的耗时和状态。
agent
Agent 执行区间
Agent 名称、会话 ID（session_id）、轮次 ID（turn_id），汇总 Token 用量和调用次数。
step
ReAct 推理轮次
推理轮次编号（react.round）、轮次结束原因（react.finish_reason）。
chain
LangChain 内部节点
节点名称（chain.name）、节点类型（chain.type），例如 RunnableSequence、Prompt、should_continue。
chat
模型调用
请求模型、响应模型、结束原因、输入 Token、输出 Token，以及输入/输出消息（受内容采集策略控制）。
tool
工具调用
工具名称、调用参数、返回结果、错误类型和错误信息。错误类型自动分类为 timeout、rate_limit、auth_error、validation_error 等。

内容采集策略

通过 content_mode 参数或环境变量 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT 控制是否采集对话内容和工具参数：
取值
行为
适用场景
full
完整记录对话内容，不截断。默认值。
开发调试
truncate
记录对话内容，超长字段截断并添加截断标记。
生产环境
off
不记录对话内容，仅上报调用树、Token、耗时和状态等指标。
强合规场景

常见问题

CLS 中没有 Trace 数据

请依次检查以下内容：
setup() 是否在首次运行 Agent 之前调用。
CLS_ENDPOINT 是否不含协议前缀或路径，且与日志主题位于同一地域。
填写的是否为 Trace 日志主题 ID，而不是主题名称或应用 ID。
SecretId / SecretKey 是否有效，且具备写入目标日志主题的权限。
当前网络能否访问该接入点。使用内网域名时，需确保应用运行在同地域的腾讯云内网环境中。
是否已等待至少一个刷新周期。
如仍无法定位，可设置 CLS_DEBUG=true 查看 SDK 日志，或设置 CLS_LOCAL_DUMP=true 开启本地落盘：如果本地 JSONL 文件中有 Span 数据，说明采集正常，问题出在上报环节；如果本地也没有数据，说明问题出在采集环节。

Trace 中缺少输入输出或工具参数

检查 content_mode 或环境变量 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT 是否设置为 off。关闭内容采集后，调用树、Token、耗时和状态仍会正常上报。

Trace 中缺少 Token 或部分模型属性

Token 用量、结束原因等数据来自模型服务的返回结果。如果模型服务或对应的 LangChain 集成包未返回 Usage、结束原因等字段，SDK 无法采集。

同一个请求出现重复 Trace

可能重复调用了 setup()，或同时启用了本 SDK 与 LangSmith、Langfuse 等其他 Tracing 组件并上报到同一日志主题。建议同一进程只初始化一次，并且每个应用只保留一条上报路径。

并行工具调用或子 Agent 的父子关系是否准确

准确。SDK 根据 LangChain 回调中的 parent_run_id 推导父子关系，不依赖全局状态，并行工具调用、嵌套子 Agent 和 RunnableParallel 都能正确归属到对应的父节点。

SDK 异常是否会影响 Agent 运行

不会。配置缺失或初始化异常时，SDK 会自动降级并输出诊断信息；遇到网络或服务端异常时，5xx 错误会自动重试，4xx 错误会丢弃对应数据，并通过缓冲区背压保护避免占用过多内存。
中国站