# OpenJiuwen框架
观测功能支持通过Python探针对基于OpenJiuwen框架的JiuwenSwarm智能体应用进行观测，JiuwenSwarm是基于openJiuwen框架构建的多智能体协作平台。
#### 前提条件
- Python环境版本 \>= 3.11，\<3.14
- Node.js环境版本 \>= 18.x
- 已安装JiuwenSwarm，版本 \>= 0.2.4
![](https://support.huaweicloud.com/ops-agentarts/public_sys-resources/note_3.0-zh-cn.png)
- 在AgentArts观测界面查看数据不收费。
- 但数据上报会产生费用：
  - 调用链上报到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都是按需计费，并有一定量的免费额度，超出后按实际使用量收费。
 
#### 框架介绍
JiuwenSwarm是基于OpenJiuwen框架构建的多智能体协作平台，提供开箱即用的智能体应用，包含Web前端界面、多智能体协作（Agent Team）、记忆管理、技能系统、工具调用等能力。用户安装后通过jiuwenswarm-start命令即可启动服务，在浏览器中访问Web界面与智能体交互。
JiuwenSwarm内部基于openJiuwen的Runner运行Agent，探针通过Runner.callback_framework回调机制自动采集观测数据。
接入后，以下能力将被自动监控：
- Agent执行链路（invoke_agent，根Span）
- LLM调用（chat）：模型名称、Token用量、输入/输出内容、推理内容（reasoning_content）
- 工具调用（execute_tool）：工具名称、输入参数、返回结果
- 流式响应场景的TTFT（首Token时延）和TPOT（Token间时延）
- Skill调用：技能名称、调用次数、耗时、成功率
- 会话数、响应成功率等业务指标
 
#### 接入步骤
 #### 步骤一：获取接入参数
1. 登录[AgentArts 智能体平台](https://console.huaweicloud.com/agentarts/)。
2. 在左侧导航栏选择"观测与优化 \> 观测"。
3. 在"智能体列表"页面，单击"接入智能体"，按照页面指引填写名称、智能体类型，创建一个"OpenJiuwen"框架的智能体，并获取各配置参数。 
   图1获取配置参数   
   ![](https://support.huaweicloud.com/ops-agentarts/zh-cn_image_0000002804728481.png "点击放大")
   
   
 
#### 步骤二：安装探针
1. 安装探针。 
   下载[OpenJiuwen探针](https://obs-apm2-cn-southwest-2.obs.cn-southwest-2.myhuaweicloud.com/PYTHON/version.26.9.7/huaweicloud_opentelemetry_instrumentation_jiuwen-1.0.0-py3-none-any.whl)，探针下载到本地项目后执行安装。
   ```
   pip install huaweicloud_opentelemetry_instrumentation_jiuwen-1.0.0-py3-none-any.whl --force-reinstall
   ```
   安装OpenTelemetry依赖包：
   ```
   pip install opentelemetry-distro==0.60b1
   pip install opentelemetry-api==1.39.1
   pip install opentelemetry-exporter-otlp==1.39.1
   pip install opentelemetry-exporter-otlp-proto-grpc==1.39.1
   pip install opentelemetry-semantic-conventions==0.60b1
   pip install opentelemetry-semantic-conventions-ai==0.5.1
   ```
   
   
2. 配置环境变量。 
   您需要手动为Python应用添加以下环境变量，将参数值替换为[步骤一：获取接入参数]中获取的实际值。
   Windows PowerShell
   ```
   # 为本 SHELL 中所有进程添加环境变量
   $env:agentarts_agentops_otel_agent_apm_enable="true"     # 启用 APM Trace，默认false不开启
   $env:agentarts_agentops_otel_agent_aom_enable="true"     # 启用 AOM Metrics，默认false不开启
   # 智能体信息配置
   $env:agent_domain_id="<your-domain-id>"                  # 账号 domain ID
   $env:agentarts_project_id="<your-project-id>"            # 账号 Project ID
   $env:agent_resource_id="<your-resource-id>"              # 智能体 ID
   $env:resource_type="agent"                               # 智能体类型：agent，multiagents，workflow
   # APM 配置
   $env:agentarts_agentops_apm_token="<your-apm-token>"              # APM 接入凭证 Token
   $env:agentarts_agentops_apm_exporter_endpoint="<endpoint>"        # APM 数据上报地址
   # AOM 配置
   $env:agentarts_agentops_aom_access_code="<your-aom-access-code>"      # AOM 接入凭证
   $env:agentarts_agentops_aom_exporter_endpoint="<endpoint>"            # AOM 数据上报地址
   $env:agentarts_agentops_aom_prometheus_id="<your-prometheus-id>"      # Prometheus 实例 ID
   # Jiuwen 探针框架识别（推荐显式指定，避免 auto 模式加载全部框架探针）
   $env:AGENTARTS_AGENTOPS_FRAMEWORK="openjiuwen"
   ```
   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=<your-domain-id>          # 账号 domain ID
   export agentarts_project_id=<your-project-id>    # 账号 Project ID
   export agent_resource_id=<your-resource-id>      # 智能体 ID
   export resource_type=agent                       # 智能体类型：agent，multiagents，workflow
   # APM 配置
   export agentarts_agentops_apm_token=<your-apm-token>             # APM 接入凭证 Token
   export agentarts_agentops_apm_exporter_endpoint=<endpoint>       # APM 数据上报地址
   # AOM 配置
   export agentarts_agentops_aom_access_code=<your-aom-access-code>         # AOM 接入凭证
   export agentarts_agentops_aom_exporter_endpoint=<endpoint>               # AOM 数据上报地址
   export agentarts_agentops_aom_prometheus_id=<your-prometheus-id>         # Prometheus 实例 ID
   # Jiuwen 探针框架识别（推荐显式指定，避免 auto 模式加载全部框架探针）
   export AGENTARTS_AGENTOPS_FRAMEWORK=openjiuwen
   ```
   
   
3. 启动JiuwenSwarm。 
   如果尚未安装JiuwenSwarm，可通过以下命令安装：
   ```
   # 创建虚拟环境（推荐）
   python -m venv jiuwenswarm-env
   # 激活虚拟环境
   # Windows:
   jiuwenswarm-env\Scripts\activate
   # macOS/Linux:
   source jiuwenswarm-env/bin/activate
   # 安装 JiuwenSwarm
   ## 方式一：默认安装
   pip install jiuwenswarm
   ## 方式二：使用国内镜像源（推荐）
   # 清华源
   pip install jiuwenswarm -i https://pypi.tuna.tsinghua.edu.cn/simple
   # 阿里源
   pip install jiuwenswarm -i https://mirrors.aliyun.com/pypi/simple/
   ```
   首次使用JiuwenSwarm需执行初始化命令，系统会自动创建配置目录（Windows为C:\\Users\\\<用户名\>\\.jiuwenswarm\\，Linux/Mac为\~/.jiuwenswarm/）：
   ```
   # 初始化 JiuwenSwarm（首次启动）
   jiuwenswarm-init
   ```
   启动JiuwenSwarm服务，在配置好探针环境变量的终端中执行以下命令启动服务：
   ```
   # 启动 JiuwenSwarm
   jiuwenswarm-start
   ```
   配置模型并开始对话。
   在浏览器中访问http://localhost:5173进入JiuwenSwarm Web界面。配置模型信息后，与智能体对话交互即可产生观测数据。
   
   
 
#### 步骤三：验证数据上报
OpenJiuwen应用启动并产生调用后，可通过以下方式确认数据上报是否成功。
**确认探针安装**
执行以下命令，确认探针已正确安装：
```
pip show huaweicloud-opentelemetry-instrumentation-jiuwen
```
输出中应包含探针名称和版本号，且entry point信息完整。
**日志确认**
JiuwenSwarm启动时的日志会直接输出到启动jiuwenswarm-start命令的终端窗口中，同时也会保存到日志文件（位于\~/.jiuwenswarm/logs/目录下）。在这些日志中搜索OTEL_PROBE关键字，确认探针已成功初始化。日志中应出现以下标识：
```
OTEL_PROBE | jiuwen instrumentor loaded
OTEL_PROBE | jiuwen callback handler registered 11 callbacks
OTEL_PROBE | SysOperation log handler installed on root logger
```
如果日志中出现OTEL_PROBE \| jiuwen instrumentor loaded，说明探针已正常装配。如果未出现，请参考[常见问题]进行排查。
**AgentArts平台确认**
登录[AgentArts智能体平台](https://console.huaweicloud.com/agentarts/)，在"观测与优化 \> 观测"页面中找到已接入的智能体，查看各指标与会话数据。
#### 环境变量说明
表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 | 是       | multiagents           |
| agentarts_agentops_otel_agent_apm_enable  | 是否启用APM Trace                   | 是         | 默认true              |
| agentarts_agentops_otel_agent_aom_enable | 是否启用AOM Metrics                 | 是          | 默认true                |
| 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        |
| agent_name                                          | 智能体名称                                                        | jiuwen-agent |
| agent_version                                      | 智能体版本                                                        | default      |
| resource_version                                  | 资源版本                                                          | default    |
| JIUWENSWARM_SESSION_ID                             | 会话ID（未从Agent输入解析到时回退使用）                                      | 空            |
| JIUWENSWARM_DEBUG                                  | 是否输出探针调试日志（含result结构dump）                                   | false     |
| AGENTARTS_AGENTOPS_FRAMEWORK                       | 指定要加载的框架探针：langchain/langgraph/agentscope/openjiuwen/all/auto | auto       |
   
#### 查看监控数据
数据上报成功后，可在AgentArts智能体平台的观测功能中查看监控数据。
1. 登录[AgentArts 智能体平台](https://console.huaweicloud.com/agentarts/)。
2. 在左侧导航栏选择"观测与优化 \> 观测"。
3. 在"智能体列表"页面，找到已接入的智能体，单击智能体名称进入详情页面。
**查看业务指标**
在"指标分析"页签中，可以查看关键业务指标：
- Tokens消耗：Input Tokens和Output Tokens的消耗总量
- 模型调用次数：应用调用大模型的累计次数
- 模型调用平均耗时：模型调用的平均响应时间
- 模型调用成功率：大模型调用成功的比例
- 会话数：应用产生的会话总数
- 响应成功率：服务响应的成功率
- Skill调用次数/耗时/成功率：Skill技能的调用指标。
**查看调用链信息**
在"调用链分析"页签中，可以查看完整的Trace调用链路：
- 查看**AGENT** （根Span）、**LLM** 、**TOOL**等Span类型的层级关系及各节点耗时
- 单击具体Span查看详细信息：
  - Agent根节点：可查看整体会话的输入/输出、Token消耗总量（子Span自动累计）
  
  - LLM节点：可查看模型名称、输入/输出内容、推理内容（reasoning_content）、Token消耗等
  
  - Tool节点：可查看工具名称、输入参数、返回结果
   
- 同一会话的多轮调用通过gen_ai.conversation.id关联
**查看会话分析**
在"会话分析"页签中，可以查看智能体与用户对话的历史数据：
- 追踪对话上下文
- 分析模型响应耗时
- 统计Token消耗
- 快速定位对话异常问题
 
#### 更多参考
**控制内容采集**
默认情况下，探针会采集LLM的输入/输出内容。如需关闭：
```
export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false
```
**探针初始化日志**
探针初始化成功后，应用日志中会出现以下标识（用于确认探针已生效）：
```
OTEL_PROBE | jiuwen instrumentor loaded
OTEL_PROBE | jiuwen callback handler registered 11 callbacks
OTEL_PROBE | SysOperation log handler installed on root logger
```
 #### 常见问题
**无数据上报**
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 \<endpoint\>命令验证连通性。
4. 检查凭证是否有效且未过期，可在AgentArts平台的接入指南页面重新获取最新凭证。
5. 查看JiuwenSwarm启动日志，搜索OTEL_PROBE关键字，排查探针初始化是否报错。正常情况下应出现OTEL_PROBE \| jiuwen instrumentor loaded。
**探针未加载**
1. 确认已安装探针whl（site-packages中存在huawei_auto_instrumentation.pth）。
2. 确认JiuwenSwarm已正确安装。
3. 确认AGENTARTS_AGENTOPS_FRAMEWORK=openjiuwen或auto模式下主脚本导入了openjiuwen。
4. 确认环境变量在启动jiuwenswarm-start的终端中已正确设置。
**JiuwenSwarm启动失败**
1. 确认Python版本 \>= 3.11。
2. 确认已执行jiuwenswarm-init初始化配置目录。
3. 如端口被占用，JiuwenSwarm会自动切换到备用端口，查看终端输出的实际端口信息。
4. 确认已正确配置JiuwenSwarm的模型API，模型配置错误会导致智能体无法响应。
**模型连接错误（Connection error / ProxyError: 504 Gateway Time-out）**
1. JiuwenSwarm内部使用httpx调用模型，httpx默认trust_env=True会读取系统代理，若代理无法访问模型端点会返回504。
2. 确认在JiuwenSwarm中填写的模型地址正确。
3. 确认model_provider选择了正确的提供商类型（如OpenAI、DeepSeek等），不同提供商的API格式不同。
4. 内网模型端点可能被公司代理拦截，需确认端点对当前网络放行。
**探针重复加载警告（Attempting to instrument while already instrumented）**
1. 此为探针已知问题（opentelemetry-instrument CLI的distro机制与.pth sitecustomize两条路径均触发pre_custom_instrument）。
2. 升级到最新探针版本（_apply_instrumentation_patches.py已加幂等保护），或重新执行pip install --force-reinstall命令安装探针。
3. 警告不影响业务，但会产生重复span/指标。确认日志中只出现一次OTEL_PROBE \| openjiuwen instrumentor loaded。
**部分Span缺失**
1. 确认通过jiuwenswarm-start命令启动服务时，环境变量已在当前终端中正确设置。探针通过.pth → sitecustomize机制自动加载，需确保环境变量在启动前已生效。
2. 如使用opentelemetry-instrument jiuwenswarm-start启动，可获得更完整的自动插桩支持。
3. 确认JiuwenSwarm已正确安装且openjiuwen模块可用（jiuwenswarm依赖openjiuwen框架）。
4. 流式场景确认LLM返回usage（某些模型可能不返回）。
**Token统计不准确**
1. 确保使用最新版本的探针。
2. 流式场景下确认模型返回了usage字段，探针只在携带usage_metadata的final chunk记录Token。
3. 模型在响应中不返回usage字段或返回的Token数为近似值，此为模型侧行为，非探针问题。可在AgentArts调用链详情中确认模型节点的usage字段是否为空。
4. 设置JIUWENSWARM_DEBUG=true查看result结构与usage提取情况。