Integrate Hermes Agent

Container environment

This method is for scenarios where Hermes Agent is deployed in ACK, ACS, self-built Kubernetes, or other container environments. The official Hermes Agent Docker image and the official Ubuntu curl installation method do not include pip3, which is required for ACK OnePilot auto-instrumentation. Therefore, we do not recommend using ACK OnePilot. Instead, install the Cloud Monitor 2.0 Python agent in the image and use the PYTHONPATH environment variable to automatically load the agent when the Hermes Python process starts.

Step 1: Obtain integration parameters

1. Log in to the Cloud Monitor 2.0 console and select your target workspace.

2. In the left navigation pane, click Integration Center.

3. In the AI Application Observability section, select Hermes Agent.

4. In the parameter configuration section, enter an application name, select a connection method based on your deployment environment, and then click Click to obtain next to LicenseKey.

5. Record the generated integration parameters, including Endpoint, LicenseKey, Project, workspace, and serviceName.

Step 2: Build an image with the agent

FROM nousresearch/hermes-agent:latest

USER root

# Install basic tools required to download the agent package.
# The official Hermes image already includes Python, uv, and the Hermes virtual environment, so pip is not installed separately.
RUN apt-get update \
  && apt-get install -y --no-install-recommends curl ca-certificates \
  && rm -rf /var/lib/apt/lists/*

# Download the Cloud Monitor 2.0 Python agent package and install the agent wheel into the Python virtual environment built into the official Hermes image.
# /opt/hermes/.venv/bin/python is the Python interpreter currently used by Hermes Agent.
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

# Configure the application name, region, workspace, and LicenseKey.
# Replace the following placeholders with the actual parameters generated on the integration page in the Cloud Monitor 2.0 console.
ENV ARMS_APP_NAME="hermes-agent-demo"
ENV ARMS_REGION_ID="<RegionId>"
ENV ARMS_WORKSPACE="<Your-Workspace>"
ENV ARMS_LICENSE_KEY="<Your-LicenseKey>"

# Use PYTHONPATH to automatically load the agent when the Hermes Python process starts.
# The first path triggers auto-instrumentation initialization, and the second path helps Python find the agent and its dependencies.
# If the Python version in your Hermes image is not 3.13, replace the path with your actual site-packages path.
ENV PYTHONPATH="/opt/hermes/.venv/lib/python3.13/site-packages/aliyun/opentelemetry/instrumentation/auto_instrumentation:/opt/hermes/.venv/lib/python3.13/site-packages"

The PYTHONPATH path above is based on the Python 3.13 virtual environment in the official Hermes Agent image. If you are building an image based on a different Python version, run /opt/hermes/.venv/bin/python -c "import site; print(site.getsitepackages()[0])" to find the actual site-packages path and replace the path shown in the example.

Keep the original startup command for the Hermes Agent, such as hermes gateway start. After the agent starts, look for the Aliyun python agent is started message in the Hermes Agent service log. This message indicates that the commercial Python agent is loaded with the Hermes process.

Commercial Python agent

Use this method to integrate the commercial Python agent on a local macOS, Linux, or Windows Subsystem for Linux (WSL) development machine. It involves installing the commercial Python agent into a separate directory and using PYTHONPATH to load it automatically when the Hermes Python process starts. This approach avoids modifying the Hermes Agent source code and is suitable for long-running processes such as hermes gateway start.

Step 1: Obtain integration parameters

1. Log in to the Cloud Monitor 2.0 console and select your target workspace.

2. In the left navigation pane, click Integration Center.

3. In the AI Application Observability section, select Hermes Agent.

4. In the parameter configuration section, enter an application name, select a connection method based on your local development machine's network, and then record the integration parameters, including RegionId, workspace, LicenseKey, and serviceName.

Step 2: Install Hermes Agent

If you have not yet installed Hermes Agent on your machine, run the official installation script. You can skip this step if it is already installed.

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

By default, the official script installs Hermes Agent to ~/.hermes/hermes-agent and creates a Python virtual environment at ~/.hermes/hermes-agent/venv. If you install the agent in a custom directory, specify the actual path to the Python interpreter in HERMES_AGENT_PYTHON below.

Step 3: Install the commercial Python agent

Use the Python interpreter that your Hermes Agent runtime actually uses to execute the following commands. These commands download the Cloud Monitor 2.0 Python agent package, install the agent wheel into a separate directory, and create a sitecustomize.py file for automatic injection via 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

After the installation is complete, the agent directory should contain sitecustomize.py and aliyun-loongsuite-instrumentation-hermes-agent.

Step 4: Start Hermes Agent

Before starting, configure the Cloud Monitor 2.0 integration parameters and add the commercial Python agent directory to 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
# Or run as a long-running process:
# hermes gateway start

If Hermes Agent is already running, stop and restart it. The message Aliyun python agent is started in the startup log indicates that the commercial Python agent has been loaded with the Hermes process.

Open-source LoongSuite

This method is suitable for local development, proof-of-concept (PoC) validation, or issue reproduction, especially if you prefer using the open-source LoongSuite Python Agent. It uses an official bash script to install the LoongSuite site bootstrap and the Hermes Agent observability plugin, offering a lightweight installation process. The LoongSuite Python Agent is open-source and available at: https://github.com/alibaba/loongsuite-python-agent.

Step 1: Get the integration command

1. Log in to the Cloud Monitor 2.0 console and select your target workspace.

2. In the left navigation pane, click Integration Center.

3. In the AI Application Observability section, select Hermes Agent.

4. In the parameter configuration section, enter an application name, select the open-source LoongSuite integration method, and then copy the generated installation command. The command contains information such as Endpoint, LicenseKey, Project, workspace, and serviceName.

Step 2: Install the observability plugin

Run the installation command on the machine where Hermes Agent is located. If Hermes Agent runs in a conda or virtual environment, first switch to the Python environment that you typically use for Hermes.

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"

After a successful installation, the terminal displays a message similar to the following:

hermes-agent-cms-plugin installed successfully!

The plugin registers the hermes-cms command locally. If ~/.local/bin is not added to your PATH, you can use the following command:

~/.loongsuite/bin/hermes-cms enable

Step 3: Start Hermes Agent

Enable the observability plugin:

hermes-cms enable

Start Hermes Agent in the foreground:

hermes

The open-source LoongSuite integration method is not recommended for long-running background processes in a gateway scenario. If you need to run Hermes Agent as a persistent service with hermes gateway start, use the commercial Python agent or container environment integration methods, which automatically load the agent via PYTHONPATH at startup.

If Hermes Agent is already running, stop and restart it to activate the observability plugin.