AgentLoop:Integrar Hermes Agent

Entorno de contenedores

Este método es adecuado para escenarios donde Hermes Agent se despliega en ACK, ACS, Kubernetes administrado por usted u otros entornos de contenedores. La imagen oficial de Docker de Hermes Agent y el método de instalación oficial de Ubuntu con curl no incluyen pip3, el cual es obligatorio para la instrumentación automática de ACK OnePilot. Por lo tanto, no se recomienda usar ACK OnePilot. En su lugar, instale el agente de Python de Cloud Monitor 2.0 en la imagen y utilice la variable de entorno PYTHONPATH para cargar automáticamente el agente cuando inicie el proceso de Python de Hermes.

Paso 1: Obtener los parámetros de integración

1. Inicie sesión en la consola de Cloud Monitor 2.0 y seleccione el espacio de trabajo de destino.

2. En el panel de navegación izquierdo, haga clic en Integration Center.

3. En la sección AI Application Observability, seleccione Hermes Agent.

4. En la sección de configuración de parámetros, introduzca un nombre de aplicación, elija un método de conexión según su entorno de despliegue y luego haga clic en Click to obtain junto a LicenseKey.

5. Registre los parámetros de integración generados, que incluyen Endpoint, LicenseKey, Project, workspace y serviceName.

Paso 2: Compilar una imagen con el agente

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"

La ruta de PYTHONPATH anterior se basa en el entorno virtual de Python 3.13 de la imagen oficial de Hermes Agent. Si compila una imagen con una versión distinta de Python, ejecute /opt/hermes/.venv/bin/python -c "import site; print(site.getsitepackages()[0])" para obtener la ruta real de site-packages y sustituya la ruta que aparece en el ejemplo.

Conserve el comando de inicio original de Hermes Agent, como hermes gateway start. Una vez iniciado el agente, busque el mensaje Aliyun python agent is started en el registro del servicio de Hermes Agent. Este mensaje indica que el agente comercial de Python se cargó junto con el proceso de Hermes.

Agente comercial de Python

Utilice este método para integrar el agente comercial de Python en una computadora de desarrollo local con macOS, Linux o Windows Subsystem for Linux (WSL). Consiste en instalar el agente comercial de Python en un directorio independiente y usar PYTHONPATH para cargarlo automáticamente cuando inicie el proceso de Python de Hermes. Este enfoque evita modificar el código fuente de Hermes Agent y resulta útil para procesos de larga duración como hermes gateway start.

Paso 1: Obtener los parámetros de integración

1. Inicie sesión en la consola de Cloud Monitor 2.0 y seleccione el espacio de trabajo de destino.

2. En el panel de navegación izquierdo, haga clic en Integration Center.

3. En la sección AI Application Observability, seleccione Hermes Agent.

4. En la sección de configuración de parámetros, introduzca un nombre de aplicación, elija un método de conexión según la red de su computadora de desarrollo local y registre los parámetros de integración, que incluyen RegionId, workspace, LicenseKey y serviceName.

Paso 2: Instalar Hermes Agent

Si aún no ha instalado Hermes Agent en su máquina, ejecute el script de instalación oficial. Puede omitir este paso si ya está instalado.

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

De forma predeterminada, el script oficial instala Hermes Agent en ~/.hermes/hermes-agent y crea un entorno virtual de Python en ~/.hermes/hermes-agent/venv. Si instala el agente en un directorio personalizado, especifique la ruta real del intérprete de Python en HERMES_AGENT_PYTHON más adelante.

Paso 3: Instalar el agente comercial de Python

Use el intérprete de Python que utiliza realmente el entorno de ejecución de Hermes Agent para ejecutar los siguientes comandos. Estos comandos descargan el paquete del agente de Python de Cloud Monitor 2.0, instalan el archivo wheel del agente en un directorio independiente y crean un archivo sitecustomize.py para la inyección automática mediante 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

Una vez finalizada la instalación, el directorio del agente debe contener sitecustomize.py y aliyun-loongsuite-instrumentation-hermes-agent.

Paso 4: Iniciar Hermes Agent

Antes de iniciar, configure los parámetros de integración de Cloud Monitor 2.0 y agregue el directorio del agente comercial de Python a 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

Si Hermes Agent ya se está ejecutando, deténgalo y reinícielo. El mensaje Aliyun python agent is started en el registro de inicio indica que el agente comercial de Python se cargó junto con el proceso de Hermes.

LoongSuite de código abierto

Este método es ideal para el desarrollo local, la validación de pruebas de concepto (PoC) o la reproducción de problemas, sobre todo si prefiere usar LoongSuite Python Agent de código abierto. Utiliza un script de bash oficial para instalar el bootstrap de sitio de LoongSuite y el plugin de observability de Hermes Agent, lo que ofrece un proceso de instalación ligero. LoongSuite Python Agent es de código abierto y está disponible en: https://github.com/alibaba/loongsuite-python-agent.

Paso 1: Obtener el comando de integración

1. Inicie sesión en la consola de Cloud Monitor 2.0 y seleccione el espacio de trabajo de destino.

2. En el panel de navegación izquierdo, haga clic en Integration Center.

3. En la sección AI Application Observability, seleccione Hermes Agent.

4. En la sección de configuración de parámetros, introduzca un nombre de aplicación, elija el método de integración de LoongSuite de código abierto y copie el comando de instalación generado. El comando contiene información como Endpoint, LicenseKey, Project, workspace y serviceName.

Paso 2: Instalar el plugin de observability

Ejecute el comando de instalación en la máquina donde se encuentra Hermes Agent. Si Hermes Agent se ejecuta en un entorno conda o virtual, cambie primero al entorno de Python que suele utilizar para 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"

Tras una instalación correcta, la terminal muestra un mensaje similar al siguiente:

hermes-agent-cms-plugin installed successfully!

El plugin registra el comando hermes-cms de forma local. Si ~/.local/bin no está agregado a su variable PATH, puede usar el siguiente comando:

~/.loongsuite/bin/hermes-cms enable

Paso 3: Iniciar Hermes Agent

Habilite el plugin de observability:

hermes-cms enable

Inicie Hermes Agent en primer plano:

hermes

No se recomienda usar el método de integración de LoongSuite de código abierto para procesos en segundo plano de larga duración en un escenario de gateway. Si necesita ejecutar Hermes Agent como un servicio persistente con hermes gateway start, utilice los métodos de integración del agente comercial de Python o del entorno de contenedores, ya que cargan automáticamente el agente mediante PYTHONPATH durante el inicio.

Si Hermes Agent ya se está ejecutando, deténgalo y reinícielo para activar el plugin de observability.