OpenJiuwen框架

步骤一：获取接入参数

1. 登录AgentArts 智能体平台。
2. 在左侧导航栏选择“观测与优化 > 观测”。
3. 在“智能体列表”页面，单击“接入智能体”，按照页面指引填写名称、智能体类型，创建一个“OpenJiuwen”框架的智能体，并获取各配置参数。
   图1 获取配置参数
   

步骤二：安装探针

1. 安装探针。

   下载OpenJiuwen探针，探针下载到本地项目后执行安装。

   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智能体平台，在“观测与优化 > 观测”页面中找到已接入的智能体，查看各指标与会话数据。

环境变量说明