# LangChain/LangGraph框架智能体接入 大模型可观测支持通过Python探针对LangChain/LangGraph智能体进行观测，Python探针是华为云AgentArts产品自研的Python语言的可观测采集探针，其基于OpenTelemetry标准实现了自动化埋点能力。 本章节针对使用LangChain/LangGraph框架开发的第三方智能体应用，通过Python探针实现自动化埋点和数据上报。 #### 前提条件 - Python 环境版本 \>= 3.9 - LangChain 版本 \>= 0.1.0（如使用 LangChain） - LangGraph 版本 \>= 0.0.20（如使用 LangGraph） 探针初始化需要在应用启动时完成，建议在导入LangChain/LangGraph模块之前初始化。 ![](https://support.huaweicloud.com/ops-agentarts/public_sys-resources/note_3.0-zh-cn.png) 在观测界面展示数据不收取任何费用，但智能体数据上报产生的指标及调用链数据将分别上报至AOM和APM服务，会产生相应的管理费用，请在开启前评估成本。具体计费场景如下： - **调用链** ：开启后，调用链数据会上报到应用性能管理APM，费用明细请参考[APM计费说明](https://support.huaweicloud.com/price-apm2/apm_07_0019.html)。 - **指标** ：开启后，指标数据会上报到应用运维管理AOM，费用明细请参考[AOM计费说明](https://support.huaweicloud.com/price-aom2/aom_07_0004.html)。 AOM和APM服务采用按需计费，并提供一定量的免费额度，超出免费额度部分按实际使用量计费。详细计费规则可参考对应服务的计费说明。 #### 框架介绍 [LangChain](https://python.langchain.com/docs/introduction/)是一个面向大语言模型应用开发的框架，提供了模型调用、Prompt组织、工具接入、检索增强生成（RAG）、Agent构建等能力，帮助开发者快速搭建复杂的LLM应用。 [LangGraph](https://langchain-ai.github.io/langgraph/)是LangChain生态中的Agent编排框架，基于图结构构建多步推理和多Agent协作的LLM应用，支持循环控制流、状态管理和工具调用。 接入后，以下能力将被自动监控： - LangChain Chain/Agent的执行链路 - LLM调用（模型名称、Token用量、输入/输出内容） - 工具调用（Tool name、参数、返回结果） - Retriever/RAG相关调用链路 - LangGraph图节点执行和状态流转 #### 接入方式 #### 接入探针 1. 安装探针。 探针下载地址： 探针下载到本地项目后执行安装。 ``` pip install huaweicloud_opentelemetry_instrumentation-0.60b1.post20260920145311-py3-none-any.whl --force-reinstall pip install opentelemetry-instrumentation-langchain==0.60 ``` 2. 配置环境变量。 您需要手动为 Python 应用添加以下环境变量，环境变量的具体值可以在平台中获取。 - Linux ``` # 为本 SHELL 中所有进程添加环境变量 export agentarts_agentops_otel_agent_apm_enable=true # 启用 APM Trace，默认false不开启 export agentarts_agentops_otel_agent_aom_enable=true # 启用 AOM Metrics，默认false不开启 # 智能体信息配置 export agent_domain_id= # 账号 domain ID export agentarts_project_id= # 账号 Project ID export agent_resource_id= # 智能体 ID export resource_type=agent # 智能体类型：agent，multiagents，workflow # APM 配置 export agentarts_agentops_apm_token= # APM 接入凭证 Token export agentarts_agentops_apm_exporter_endpoint= # APM 数据上报地址 # AOM 配置 export agentarts_agentops_aom_access_code= # AOM 接入凭证 export agentarts_agentops_aom_exporter_endpoint= # AOM 数据上报地址 export agentarts_agentops_aom_prometheus_id= # Prometheus 实例 ID ``` - Windows cmd ``` # 为本 SHELL 中所有进程添加环境变量 set agentarts_agentops_otel_agent_apm_enable=true set agentarts_agentops_otel_agent_aom_enable=true # 智能体信息配置 set agent_domain_id= set agentarts_project_id= set agent_resource_id= set resource_type=agent # APM 配置 set agentarts_agentops_apm_token= set agentarts_agentops_apm_exporter_endpoint= # AOM 配置 set agentarts_agentops_aom_access_code= set agentarts_agentops_aom_exporter_endpoint= set agentarts_agentops_aom_prometheus_id= ``` - Windows PowerShell ``` # 为本 SHELL 中所有进程添加环境变量 $env:agentarts_agentops_otel_agent_apm_enable="true" $env:agentarts_agentops_otel_agent_aom_enable="true" # 智能体信息配置 $env:agent_domain_id="" $env:agentarts_project_id="" $env:agent_resource_id="" $env:resource_type="agent" # APM 配置 $env:agentarts_agentops_apm_token="" $env:agentarts_agentops_apm_exporter_endpoint="" # AOM 配置 $env:agentarts_agentops_aom_access_code="" $env:agentarts_agentops_aom_exporter_endpoint="" $env:agentarts_agentops_aom_prometheus_id="" ``` 图1获取环境变量信息 ![](https://support.huaweicloud.com/ops-agentarts/zh-cn_image_0000002698401742.png "点击放大") 3. 启动应用。 将上方示例代码保存为app.py，在项目目录下打开终端，通过Python探针启动应用： ``` opentelemetry-instrument python app.py ``` opentelemetry-instrument命令会自动发现并加载所有已安装的插桩组件，对LangChain/LangGraph智能体进行无侵入式自动化埋点，无需修改业务代码。 #### 环境变量说明 表1环境变量说明 | 环境变量 | 说明 | 是否必填 | 示例值 | |:---|:---|:---|:---| | agent_domain_id | 账号domain ID | 是 | your-domain-id | | agentarts_project_id | 华为云项目ID | 是 | your-project-id | | agent_resource_id | 智能体ID | 是 | your-agent-id | | resource_type | 智能体类型：agent，multiagents，workflow | 是 | agent | | agentarts_agentops_otel_agent_apm_enable | 是否启用APM Trace | 是 | 默认false | | agentarts_agentops_otel_agent_aom_enable | 是否启用AOM Metrics | 是 | 默认false | | agentarts_agentops_apm_token | APM接入凭证Token | APM启用时必填 | your-apm-token | | agentarts_agentops_apm_exporter_endpoint | APM OTLP数据上报地址 | APM启用时必填 | apm-endpoint | | agentarts_agentops_aom_access_code | AOM接入凭证 | AOM启用时必填 | your-aom-access-code | | agentarts_agentops_aom_exporter_endpoint | AOM OTLP数据上报地址 | AOM启用时必填 | aom-endpoint | | agentarts_agentops_aom_prometheus_id | Prometheus实例ID | AOM启用时必填 | your-prometheus-id | 表2可选环境变量 | 环境变量 | 说明 | 默认值 | |:---|:---|:---| | OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT | 是否采集LLM 输入/输出内容 | true | | OTEL_DEPLOYMENT_ENV | 部署环境 | production | | OTEL_EXPORTER_OTLP_PROTOCOL | OTLP协议，必须使用grpc | grpc | | OTEL_BSP_SCHEDULE_DELAY | Span批量上报延迟（毫秒） | 30000 | | OTEL_BSP_MAX_QUEUE_SIZE | Span队列最大长度 | 4096 | | OTEL_METRIC_EXPORT_INTERVAL | Metrics上报间隔（毫秒） | 60000 | | resource_version | 智能体版本 | default | | agent_name | 智能体名称 | default | #### 示例代码 以下示例展示了一个基于LangGraph的Agent应用，包含工具调用和多步推理： 示例中使用华为云MaaS服务提供的大模型接口，可登录华为云[MaaS服务控制台](https://console.huaweicloud.com/modelarts/#/model-studio/homepage)，创建API Key。 图2创建API Key ![](https://support.huaweicloud.com/ops-agentarts/zh-cn_image_0000002728125221.png "点击放大") ``` import os from langchain_openai import ChatOpenAI from langchain.agents import create_agent from langchain_core.tools import tool @tool def search_product(keyword: str) -> str: """根据关键词搜索华为云产品信息""" products = { "ECS": "弹性云服务器，提供安全可靠、弹性伸缩的云服务器，支持多种规格按需选购", "RDS": "关系型数据库服务，支持 MySQL/PostgreSQL/SQL Server，提供高可用和自动备份", "OBS": "对象存储服务，海量、安全、高可靠的云存储，适用于数据湖、备份归档等场景", } return products.get(keyword.upper(), f"未找到 '{keyword}' 相关产品") @tool def get_product_usecase(service_name: str) -> str: """查询华为云产品的典型使用场景""" usecases = { "ECS": "适用场景：Web应用托管、开发测试环境搭建、企业应用迁移上云、高性能计算任务", "RDS": "适用场景：电商交易系统、金融业务数据库、企业ERP/CRM系统、移动应用后端存储", "OBS": "适用场景：静态网站托管、大数据分析存储、备份与归档、音视频内容分发", } return usecases.get(service_name.upper(), f"暂无 '{service_name}' 的场景信息") # 创建 LLM 实例（使用华为云 MaaS OpenAI 兼容接口） llm = ChatOpenAI( model="deepseek-v4-flash", base_url="https://api.modelarts-maas.com/openai/v1", api_key="", # 替换为在华为云 MaaS 控制台申请的 API Key ) # 创建 Agent agent = create_agent(llm, tools=[search_product, get_product_usecase]) # 运行 Agent result = agent.invoke({ "messages": [{"role": "user", "content": "帮我介绍一下 ECS 和 OBS，以及它们分别适合用在哪些场景？"}] }) for msg in result["messages"]: if msg.content: print(msg.content) ``` #### 查看监控详情 数据上报成功后，可在 AgentArts 智能体平台的"智能体观测"页面查看监控数据。 1. 登录[AgentArts 智能体平台](https://console.huaweicloud.com/agentarts/)。 2. 在左侧导航栏选择"观测与优化 \> 观测"。 3. 在"智能体列表"页面，找到已接入的智能体，单击智能体名称进入详情页面。 **查看业务指标** 在"指标分析"页签中，可以查看关键业务指标： - Tokens消耗：Input Tokens和Output Tokens的消耗总量 - 模型调用次数：应用调用大模型的累计次数 - 模型调用平均耗时：模型调用的平均响应时间 - 模型调用成功率：大模型调用成功的比例 - 会话数：应用产生的会话总数 - 响应成功率：服务响应的成功率 **查看调用链信息** 在"调用链分析"页签中，可以查看完整的Trace调用链路： - 查看各Span类型的层级关系及各节点耗时 - 点击具体Span查看详细信息： - LLM节点：可查看模型名称、输入/输出消息（Input/Output Messages）、Token消耗（Total tokens） - Tool节点：可查看工具名称、输入参数、返回结果 - LangGraph节点：可查看图节点执行顺序、状态转换 **查看会话分析** 在"会话分析"页签中，可以查看智能体与用户对话的历史数据： - 追踪对话上下文 - 分析模型响应耗时 - 统计Token消耗 - 快速定位对话异常问题 #### 更多参考 **传递session_id与user_id** 在调用agent.invoke时，可通过OTel Baggage传递会话信息，传入session_id和user_id，探针自动关联到span用于会话分析和用户分析： ``` from opentelemetry.baggage import set_baggage from opentelemetry import context as ctx_api context = set_baggage("session_id", "session-01") context = set_baggage("user_id", "langgraph_user", context) token = ctx_api.attach(context) try: result = agent.invoke( {"messages": [{"role": "user", "content": "你好"}]} ) finally: ctx_api.detach(token) ``` - session_id：会话标识，用于关联同一会话内的多轮调用。 - user_id：用户标识，用于按用户维度统计和过滤。 **控制内容采集** 默认情况下，探针会采集LLM的输入/输出内容。如需关闭： ``` export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false ``` **代码手动插桩** 如果无法使用opentelemetry-instrument命令自动插桩，也可以在通过创建sitecustomize.py手动初始化： ``` import os os.environ["OTEL_PYTHON_LOG_CORRELATION"] = "True" os.environ["OTEL_PYTHON_LOG_LEVEL"] = "debug" # 设置日志级别，可根据情况调整 os.environ["OTEL_PYTHON_LOG_FORMAT"] = "%(asctime)s [%(levelname)s] [trace_id=%(otelTraceID)s span_id=%(otelSpanID)s] %(message)s" import logging from opentelemetry.instrumentation.logging import LoggingInstrumentor root_logger = logging.getLogger() root_logger.handlers.clear() root_logger.setLevel(logging.DEBUG) # 设置日志级别，可根据情况调整 LoggingInstrumentor().instrument( set_logging_format=True, log_level=logging.DEBUG # 设置日志级别，可根据情况调整，确保 OTel 的 Handler 也接受对应日志级别 ) from opentelemetry.instrumentation.huawei_auto_instrumentation import initialize initialize() ``` #### 常见问题 **无数据上报** 1. 检查环境变量是否正确配置，特别是agentarts_agentops_apm_token、agentarts_agentops_apm_exporter_endpoint等关键参数是否完整且无多余空格。 2. 确认agentarts_agentops_otel_agent_apm_enable和agentarts_agentops_otel_agent_aom_enable已设置为true，默认值为false不会上报数据。 3. 检查网络连接，确保运行环境能访问APM/AOM端点地址。可通过curl \命令验证连通性。 4. 检查凭证是否有效且未过期，可在AgentArts平台的接入指南页面重新获取最新凭证。 5. 查看应用启动日志，搜索opentelemetry或instrument关键字，排查探针初始化是否报错。 **部分Span缺失** 1. 确认是否通过opentelemetry-instrument python app.py命令启动应用。直接使用python app.py启动将无法触发自动插桩，需改用探针命令启动或参考[代码手动插桩]进行初始化。 2. 确认LangChain/LangGraph版本满足最低要求（LangChain \>= 0.1.0，LangGraph \>= 0.0.20），低版本框架的内部调用结构可能与探针不兼容。 3. 如使用手动插桩方式，确认探针初始化代码在import langchain之前执行。若LangChain模块先于探针加载，插桩将无法生效，导致相关Span丢失。 **Token统计不准确** 1. 确保使用最新版本的探针。 2. 流式场景下确认已开启stream_usage=True。 3. 模型在响应中不返回usage字段或返回的Token数为近似值，此为模型侧行为，非探针问题。如遇此情况，可在AgentArts调用链详情中确认模型节点的usage字段是否为空。