AgentLoop:Hermes Agent'ı Entegre Edin

Konteyner ortamı

Bu yöntem, Hermes Agent'ın ACK, ACS, kendi kendine kurulan Kubernetes veya diğer konteyner ortamlarına dağıtıldığı senaryolar için uygundur. Resmi Hermes Agent Docker görüntüsü ve resmi Ubuntu curl kurulum yöntemi, ACK OnePilot otomatik enstrümantasyonu için gereken pip3 aracını içermez. Bu nedenle ACK OnePilot kullanmanızı önermiyoruz. Bunun yerine, görüntüye Cloud Monitor 2.0 Python agent'ını yükleyin ve Hermes Python işlemi başladığında agent'ı otomatik olarak yüklemek için PYTHONPATH ortam değişkenini kullanın.

Adım 1: Entegrasyon parametrelerini alın

1. Cloud Monitor 2.0 konsolu üzerinde oturum açın ve hedef çalışma alanınızı seçin.

2. Sol gezinme bölmesinde Integration Center öğesine tıklayın.

3. AI Application Observability bölümünde Hermes Agent'ı seçin.

4. Parametre yapılandırma bölümünde bir uygulama adı girin, dağıtım ortamınıza göre bir bağlantı yöntemi seçin ve ardından LicenseKey yanındaki Click to obtain düğmesine tıklayın.

5. Endpoint, LicenseKey, Project, workspace ve serviceName dahil olmak üzere oluşturulan entegrasyon parametrelerini kaydedin.

Adım 2: Agent içeren bir görüntü oluşturun

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"

Yukarıdaki PYTHONPATH yolu, resmi Hermes Agent görüntüsündeki Python 3.13 sanal ortamına dayanır. Farklı bir Python sürümüne dayalı bir görüntü oluşturuyorsanız gerçek site-packages yolunu bulmak için /opt/hermes/.venv/bin/python -c "import site; print(site.getsitepackages()[0])" komutunu çalıştırın ve örnekte gösterilen yolu bununla değiştirin.

Hermes Agent için orijinal başlatma komutunu koruyun; örneğin hermes gateway start. Agent başladıktan sonra Hermes Agent hizmet günlüğünde Aliyun python agent is started mesajını arayın. Bu mesaj, ticari Python agent'ının Hermes işlemiyle birlikte yüklendiğini gösterir.

Ticari Python agent

Bu yöntemi, yerel macOS, Linux veya Windows Subsystem for Linux (WSL) geliştirme makinenizde ticari Python agent'ını entegre etmek için kullanın. Yöntem, ticari Python agent'ını ayrı bir dizine yüklemeyi ve Hermes Python işlemi başladığında onu otomatik olarak yüklemek için PYTHONPATH kullanmayı içerir. Bu yaklaşım, Hermes Agent kaynak kodunu değiştirmekten kaçınır ve hermes gateway start gibi uzun süre çalışan işlemler için uygundur.

Adım 1: Entegrasyon parametrelerini alın

1. Cloud Monitor 2.0 konsolu üzerinde oturum açın ve hedef çalışma alanınızı seçin.

2. Sol gezinme bölmesinde Integration Center öğesine tıklayın.

3. AI Application Observability bölümünde Hermes Agent'ı seçin.

4. Parametre yapılandırma bölümünde bir uygulama adı girin, yerel geliştirme makinenizin ağına göre bir bağlantı yöntemi seçin ve ardından RegionId, workspace, LicenseKey ve serviceName dahil olmak üzere entegrasyon parametrelerini kaydedin.

Adım 2: Hermes Agent'ı yükleyin

Makinenizde henüz Hermes Agent yüklü değilse resmi kurulum betiğini çalıştırın. Zaten yüklüyse bu adımı atlayabilirsiniz.

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

Varsayılan olarak resmi betik, Hermes Agent'ı ~/.hermes/hermes-agent konumuna yükler ve ~/.hermes/hermes-agent/venv konumunda bir Python sanal ortamı oluşturur. Agent'ı özel bir dizine yüklerseniz aşağıda HERMES_AGENT_PYTHON içinde Python yorumlayıcısının gerçek yolunu belirtin.

Adım 3: Ticari Python agent'ını yükleyin

Aşağıdaki komutları yürütmek için Hermes Agent çalışma zamanınızın gerçekten kullandığı Python yorumlayıcısını kullanın. Bu komutlar Cloud Monitor 2.0 Python agent paketini indirir, agent wheel dosyasını ayrı bir dizine yükler ve PYTHONPATH aracılığıyla otomatik enjeksiyon için bir sitecustomize.py dosyası oluşturur.

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

Kurulum tamamlandıktan sonra agent dizini sitecustomize.py ve aliyun-loongsuite-instrumentation-hermes-agent dosyalarını içermelidir.

Adım 4: Hermes Agent'ı başlatın

Başlatmadan önce Cloud Monitor 2.0 entegrasyon parametrelerini yapılandırın ve ticari Python agent dizinini PYTHONPATH değişkenine ekleyin:

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

Hermes Agent zaten çalışıyorsa durdurun ve yeniden başlatın. Başlatma günlüğündeki Aliyun python agent is started mesajı, ticari Python agent'ının Hermes işlemiyle birlikte yüklendiğini gösterir.

Açık kaynaklı LoongSuite

Bu yöntem, özellikle açık kaynaklı LoongSuite Python Agent'ı kullanmayı tercih ediyorsanız yerel geliştirme, kavram kanıtı (PoC) doğrulama veya sorun yeniden üretme senaryoları için uygundur. LoongSite site bootstrap ve Hermes Agent gözlemlenebilirlik eklentisini yüklemek için resmi bir bash betiği kullanır ve hafif bir kurulum süreci sunar. LoongSuite Python Agent açık kaynaklıdır ve şu adreste bulunabilir: https://github.com/alibaba/loongsuite-python-agent.

Adım 1: Entegrasyon komutunu alın

1. Cloud Monitor 2.0 konsolu üzerinde oturum açın ve hedef çalışma alanınızı seçin.

2. Sol gezinme bölmesinde Integration Center öğesine tıklayın.

3. AI Application Observability bölümünde Hermes Agent'ı seçin.

4. Parametre yapılandırma bölümünde bir uygulama adı girin, açık kaynaklı LoongSuite entegrasyon yöntemini seçin ve ardından oluşturulan kurulum komutunu kopyalayın. Komut Endpoint, LicenseKey, Project, workspace ve serviceName gibi bilgileri içerir.

Adım 2: Gözlemlenebilirlik eklentisini yükleyin

Kurulum komutunu Hermes Agent'ın bulunduğu makinede çalıştırın. Hermes Agent bir conda veya sanal ortamda çalışıyorsa öncelikle Hermes için genellikle kullandığınız Python ortamına geçiş yapın.

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"

Başarılı bir kurulumdan sonra terminalde aşağıdakine benzer bir mesaj görüntülenir:

hermes-agent-cms-plugin installed successfully!

Eklenti, hermes-cms komutunu yerel olarak kaydeder. Eğer ~/.local/bin dizini PATH değişkeninize eklenmemişse aşağıdaki komutu kullanabilirsiniz:

~/.loongsuite/bin/hermes-cms enable

Adım 3: Hermes Agent'ı başlatın

Gözlemlenebilirlik eklentisini etkinleştirin:

hermes-cms enable

Hermes Agent'ı ön planda başlatın:

hermes

Açık kaynaklı LoongSuite entegrasyon yöntemi, ağ geçidi senaryosundaki uzun süre çalışan arka plan işlemleri için önerilmez. Hermes Agent'ı hermes gateway start ile kalıcı bir hizmet olarak çalıştırmanız gerekiyorsa, başlangıçta agent'ı PYTHONPATH aracılığıyla otomatik olarak yükleyen ticari Python agent veya konteyner ortamı entegrasyon yöntemlerini kullanın.

Hermes Agent zaten çalışıyorsa gözlemlenebilirlik eklentisini etkinleştirmek için durdurun ve yeniden başlatın.