AgentLoop：接入 Hermes Agent 應用

容器環境內接入

適用於 Hermes Agent 部署在 ACK、ACS、自建 Kubernetes 或其他容器環境中的情境。Hermes Agent 官方 Docker 鏡像和官方 Ubuntu curl 安裝方式均未提供 ack-onepilot Python 自動接入所需的 pip3，因此不推薦使用 ACK OnePilot 自動接入。請在鏡像中安裝CloudMonitor 2.0 Python 探針，並通過 PYTHONPATH 讓 Hermes Python 進程啟動時自動載入探針。

步驟一：擷取接入參數

1. 登入CloudMonitor 2.0 控制台，選擇目標工作空間。

2. 在左側導覽列單擊接入中心。

3. 在AI 應用可觀測地區選取項目 Hermes Agent 接入項。

4. 在參數配置地區輸入應用程式名稱，根據部署環境選擇串連方式，然後單擊LicenseKey右側的點擊擷取。

5. 記錄頁面產生的 Endpoint、LicenseKey、Project、Workspace 和 serviceName 等接入參數。

步驟二：構建內建探針的 Hermes Agent 鏡像

FROM nousresearch/hermes-agent:latest

USER root

# 安裝下載探針包所需的基礎工具。
# Hermes 官方鏡像已包含 Python、uv 和 Hermes 虛擬環境，這裡不額外安裝 pip。
RUN apt-get update \
  && apt-get install -y --no-install-recommends curl ca-certificates \
  && rm -rf /var/lib/apt/lists/*

# 下載CloudMonitor 2.0 Python 探針包，並將探針 wheel 安裝到 Hermes 官方鏡像內建的 Python 虛擬環境中。
# /opt/hermes/.venv/bin/python 為 Hermes Agent 當前使用的 Python 解譯器。
RUN curl -fsSL https://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/aliyun-python-agent/aliyun-python-agent.tar.gz \
    -o /tmp/aliyun-python-agent.tar.gz \
  && mkdir -p /tmp/aliyun-python-agent \
  && tar -zxf /tmp/aliyun-python-agent.tar.gz -C /tmp/aliyun-python-agent \
  && uv pip install --python /opt/hermes/.venv/bin/python /tmp/aliyun-python-agent/target/*.whl \
  && rm -rf /tmp/aliyun-python-agent /tmp/aliyun-python-agent.tar.gz

# 配置應用程式名稱、地區、工作空間和 LicenseKey。
# 請將以下預留位置替換為CloudMonitor 2.0 控制台接入頁面產生的實際參數。
ENV ARMS_APP_NAME="hermes-agent-demo"
ENV ARMS_REGION_ID="<RegionId>"
ENV ARMS_WORKSPACE="<Your-Workspace>"
ENV ARMS_LICENSE_KEY="<Your-LicenseKey>"

# 通過 PYTHONPATH 在 Hermes Python 進程啟動時自動載入探針。
# 第一個路徑用於觸發自動埋點初始化，第二個路徑用於讓 Python 找到探針及其依賴。
# 如果 Hermes 鏡像中的 Python 版本不是 3.13，請按實際 site-packages 路徑替換。
ENV PYTHONPATH="/opt/hermes/.venv/lib/python3.13/site-packages/aliyun/opentelemetry/instrumentation/auto_instrumentation:/opt/hermes/.venv/lib/python3.13/site-packages"

上述 PYTHONPATH 路徑基於 Hermes Agent 官方鏡像當前的 Python 3.13 虛擬環境。如果您基於其他 Python 版本構建鏡像，請使用 /opt/hermes/.venv/bin/python -c "import site; print(site.getsitepackages()[0])" 查詢實際 site-packages 路徑，並替換樣本中的路徑。

保持 Hermes Agent 原有啟動命令不變，例如繼續使用 hermes gateway start。啟動後在 Hermes Agent 服務日誌中尋找 Aliyun python agent is started，表示商業化 Python 探針已經隨 Hermes 進程載入。

商業版 Python 探針接入

適用於本地 macOS、Linux、Windows WSL 或個人開發機上希望接入CloudMonitor 2.0 商業版 Python 探針的情境。該方式將商業版 Python 探針安裝到獨立目錄，並通過 PYTHONPATH 在 Hermes Python 進程啟動時自動載入探針，無需修改 Hermes Agent 源碼，也可用於 hermes gateway start 等長期運行方式。

步驟一：擷取接入參數

1. 登入CloudMonitor 2.0 控制台，選擇目標工作空間。

2. 在左側導覽列單擊接入中心。

3. 在AI 應用可觀測地區選取項目 Hermes Agent 接入項。

4. 在參數配置地區輸入應用程式名稱，根據本地開發機所在網路選擇串連方式，然後記錄 RegionId、Workspace、LicenseKey 和 serviceName 等接入參數。

步驟二：安裝 Hermes Agent

如果本機尚未安裝 Hermes Agent，請先使用 Hermes Agent 官方安裝指令碼完成安裝。已安裝可跳過本步驟。

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

官方指令碼預設將 Hermes Agent 安裝到 ~/.hermes/hermes-agent，並建立 Python 虛擬環境 ~/.hermes/hermes-agent/venv。若通過自訂目錄安裝，請在下方 HERMES_AGENT_PYTHON 中填寫實際 Python 解譯器路徑。

步驟三：安裝商業版 Python 探針

請使用 Hermes Agent 運行時實際使用的 Python 解譯器執行以下命令。命令會下載CloudMonitor 2.0 Python 探針包，將探針 wheel 安裝到獨立目錄，並寫入 sitecustomize.py 以便後續通過 PYTHONPATH 自動注入。

export ALIYUN_PYTHON_AGENT_HOME="$HOME/.aliyun-python-agent/hermes"
export HERMES_AGENT_PYTHON="${HERMES_AGENT_PYTHON:-$HOME/.hermes/hermes-agent/venv/bin/python}"
mkdir -p "$ALIYUN_PYTHON_AGENT_HOME" /tmp/aliyun-python-agent
curl -fsSL https://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/aliyun-python-agent/aliyun-python-agent.tar.gz -o /tmp/aliyun-python-agent.tar.gz
tar -zxf /tmp/aliyun-python-agent.tar.gz -C /tmp/aliyun-python-agent
"$HERMES_AGENT_PYTHON" -m pip install --target "$ALIYUN_PYTHON_AGENT_HOME" --no-cache-dir /tmp/aliyun-python-agent/target/*.whl
"$HERMES_AGENT_PYTHON" -c 'from pathlib import Path; import os; Path(os.environ["ALIYUN_PYTHON_AGENT_HOME"], "sitecustomize.py").write_text("from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize\n")'
rm -rf /tmp/aliyun-python-agent /tmp/aliyun-python-agent.tar.gz

安裝完成後，探針目錄中應包含 sitecustomize.py，並包含 aliyun-loongsuite-instrumentation-hermes-agent。

步驟四：啟動 Hermes Agent

啟動前配置CloudMonitor 2.0 接入參數，並將商業版 Python 探針目錄加入 PYTHONPATH：

export ARMS_APP_NAME="hermes-agent-demo"
export ARMS_REGION_ID="<RegionId>"
export ARMS_WORKSPACE="<Your-Workspace>"
export ARMS_LICENSE_KEY="<Your-LicenseKey>"
export PYTHONPATH="$HOME/.aliyun-python-agent/hermes:${PYTHONPATH:-}"

hermes
# 或常駐運行：
# hermes gateway start

如果 Hermes Agent 已經在運行，請先停止後重新啟動。開機記錄中出現 Aliyun python agent is started，表示商業版 Python 探針已經隨 Hermes 進程載入。

開源 LoongSuite 接入

適用於本地開發、PoC 驗證、問題複現，或希望使用開源 LoongSuite Python Agent 的情境。該方式通過官方 bash 指令碼安裝 LoongSuite site bootstrap 和 Hermes Agent 可觀測外掛程式，安裝步驟較輕量。LoongSuite Python Agent 開源地址：https://github.com/alibaba/loongsuite-python-agent。

步驟一：擷取開源接入命令

1. 登入CloudMonitor 2.0 控制台，選擇目標工作空間。

2. 在左側導覽列單擊接入中心。

3. 在AI 應用可觀測地區選取項目 Hermes Agent 接入項。

4. 在參數配置地區輸入應用程式名稱，選擇開源 LoongSuite 接入方式後複製頁面產生的安裝命令。命令中包含 Endpoint、LicenseKey、Project、Workspace 和 serviceName 等資訊。

步驟二：安裝可觀測外掛程式

在 Hermes Agent 所在機器上執行安裝命令。如果 Hermes Agent 運行在 conda 或 venv 環境中，請先切換到 Hermes 日常使用的 Python 環境。

curl -fsSL https://arms-apm-cn-hangzhou-pre.oss-cn-hangzhou.aliyuncs.com/hermes-agent-cms-plugin/hermes-cms.sh | bash -s -- install \
  --x-arms-license-key "<Your-LicenseKey>" \
  --x-arms-project "<Your-Project>" \
  --x-cms-workspace "<Your-Workspace>" \
  --serviceName "hermes-agent-demo" \
  --endpoint "https://<Endpoint>/apm/trace/opentelemetry"

安裝成功後，終端會輸出類似如下內容：

hermes-agent-cms-plugin installed successfully!

外掛程式會在本地註冊 hermes-cms 命令。如果當前環境沒有將 ~/.local/bin 加入 PATH，可以使用以下命令：

~/.loongsuite/bin/hermes-cms enable

步驟三：啟動 Hermes Agent

啟用可觀測外掛程式：

hermes-cms enable

前台啟動 Hermes Agent：

hermes

開源 LoongSuite 接入不建議用於 Gateway 後台長期運行情境。如果需要通過 hermes gateway start 常駐運行 Hermes Agent，請使用商業版 Python 探針接入或容器環境內接入，通過 PYTHONPATH 在 Python 進程啟動時自動載入探針。

如果 Hermes Agent 已經在運行，請先停止後重新啟動，使可觀測外掛程式生效。