AgentLoop:Integrar aplicaciones de AgentScope (Java)

Requisitos previos y límites

• Versión de JDK: ejecute la aplicación Java de AgentScope sobre JDK 17 o posterior.

• Memoria de la JVM: al instalar la sonda de Java, compruebe que la memoria heap máxima de la JVM de destino supere los 300 MB.

• Servicio AgentLoop: AgentLoop debe estar habilitado y contar con un AgentSpace creado.

Obtener los parámetros de integración

1. Inicie sesión en la consola de AgentLoop. En el panel de navegación izquierdo, haga clic en Integration Center.

2. Haga clic en la tarjeta AgentScope.

3. En la página de integración de AgentScope, seleccione el lenguaje Java.

4. Introduzca el nombre de la aplicación. La página genera los parámetros y las instrucciones de instalación obligatorios para integrar la sonda de Java.

Integración con ACK y ACS

El asistente de integración de sondas de monitoreo de aplicaciones (ack-onepilot) es un componente clave para integrar sondas de diversos lenguajes. Este asistente prepara automáticamente los paquetes de sondas en entornos de contenedores y configura el entorno de reporte correspondiente. Para más información sobre el funcionamiento de ack-onepilot, consulte Overview of the ack-onepilot component.

Después de integrar la sonda, se aplica automáticamente una nueva versión cuando la aplicación se reinicia. De este modo, ack-onepilot actualiza la sonda a la versión más reciente y mantiene una experiencia uniforme. Si prefiere que la sonda montada no se actualice de forma automática con cada nuevo lanzamiento, controle la versión por su cuenta. Para más información, consulte Manually control the probe version.

Este método consta de tres pasos: instalar ack-onepilot, otorgar los permisos de acceso que ARMS requiere y habilitar el monitoreo de aplicaciones.

Integración manual

Utilice la integración manual para instalar la sonda de Java en entornos distintos a los clústeres ACK o ACS. Por ejemplo, en aplicaciones iniciadas con el comando java -jar, Tomcat o Jetty.

1. Después de seleccionar el lenguaje Java en la página de integración de AgentScope, localice la sección de integración manual y descargue la sonda de Java siguiendo las instrucciones en pantalla. La página ya generó los parámetros de integración para el AgentSpace actual.

2. Extraiga la sonda.

   Acceda al directorio del paquete de la sonda y ejecute el siguiente comando para extraerlo en el directorio de trabajo que prefiera.

   unzip AliyunJavaAgent.zip -d /{user.workspace}/

   Nota

   {user.workspace} es un directorio de ejemplo. Reemplácelo con su directorio real.

3. Configure los parámetros AppName y LicenseKey.

   Utilice la LicenseKey que obtuvo previamente en el Integration Center de AgentLoop. AppName es el nombre que se muestra para la aplicación en AgentLoop y se puede personalizar. En una arquitectura distribuida, una aplicación puede contener varias instancias equivalentes.

   Importante

   Cada AgentSpace utiliza una LicenseKey distinta. Después de cambiar de AgentSpace, obtenga nuevamente la LicenseKey.

   Proporcione AppName y LicenseKey mediante uno de los siguientes métodos:

   • Método 1 (recomendado): use los parámetros de inicio -D. Reemplace los marcadores de posición {LicenseKey} y {AppName} en el comando de inicio de Step 4 con la LicenseKey obtenida en la consola y el AppName de la aplicación.

   • Método 2: modifique el archivo de configuración de la sonda. Más indicado cuando desea reutilizar el script de inicio en distintas aplicaciones. Siga estos pasos:

     1. Revise la versión de la sonda de Java en el archivo version extraído en el paso anterior.

     2. Modifique el archivo de configuración de la sonda según su versión:

        • Para la sonda 4.0.0 o posterior, cree un archivo arms-agent.properties en el directorio de la sonda y agregue la siguiente configuración. Luego añada -Dotel.javaagent.configuration-file=/path/to/arms-agent.properties al comando de inicio, o establezca la variable de entorno OTEL_JAVAAGENT_CONFIGURATION_FILE=/path/to/arms-agent.properties para habilitar el archivo de configuración.

          arms.licenseKey={LicenseKey}
          arms.appName={AppName}

        • Para una sonda anterior a la 4.0.0, agregue la siguiente configuración al archivo arms-agent.config incluido en el paquete de la sonda.

          arms.licenseKey={LicenseKey}
          arms.appName={AppName}

   Nota

   • En versiones de la sonda anteriores a la 4.4.0, este método se conecta de forma predeterminada al default workspace.

   • Para más información sobre otros elementos del archivo de configuración de la sonda, consulte Modificar el archivo de configuración de la sonda de Java y la región de reporte predeterminada.

4. Agregue el comando de integración al comando de inicio.

   Reemplace {user.workspace} con el directorio real donde extrajo el paquete de la sonda, y sustituya demoApp.jar por la ruta real del paquete JAR.

   Nota

   • Si la versión de la sonda es anterior a la 2.7.3.5, reemplace AliyunJavaAgent/aliyun-java-agent.jar en este documento por ArmsAgent/arms-bootstrap-1.7.0-SNAPSHOT.jar. Se recomienda actualizar la sonda a la versión más reciente lo antes posible.

   • En sistemas operativos Windows, reemplace / en el script por \, y cambie los archivos .sh por archivos .bat.

   • La versión 2.7.1.4 de la sonda y posteriores permiten habilitar Application Security durante la integración del monitoreo de aplicaciones. Para habilitarlo, agregue -Darms.appsec.enable=true al script. Para más información sobre las reglas de facturación de Application Security, consulte Billing rules.

   Agregue el parámetro -javaagent según su entorno de ejecución:

   Entorno de ejecución	Pasos
   Spring Boot u otras aplicaciones Java iniciadas con el comando java -jar	Agregue el parámetro -javaagent al comando de inicio. Asegúrese de colocarlo antes del parámetro -jar. java -javaagent:/{user.workspace}/AliyunJavaAgent/aliyun-java-agent.jar -Darms.licenseKey={LicenseKey} -Darms.appName={AppName} -Darms.workspace={workspace} -jar demoApp.jar
   Tomcat	Agregue la siguiente configuración al archivo {TOMCAT_HOME}/bin/setenv.sh. JAVA_OPTS="$JAVA_OPTS -javaagent:/{user.workspace}/AliyunJavaAgent/aliyun-java-agent.jar -Darms.licenseKey={LicenseKey} -Darms.appName={AppName} -Darms.workspace={workspace} " Si su versión de Tomcat no incluye el archivo de configuración setenv.sh, abra el archivo {TOMCAT_HOME}/bin/catalina.sh y agregue la configuración anterior después de JAVA_OPTS. Para ver un ejemplo específico, consulte la línea 256 de catalina.sh.
   Jetty	Agregue la siguiente configuración al archivo {JETTY_HOME}/start.ini. aliyun-java-agent.jar --exec -javaagent:/{user.workspace}/AliyunJavaAgent/aliyun-java-agent.jar -Darms.licenseKey={LicenseKey} -Darms.appName={AppName} -Darms.workspace={workspace}

   Para desplegar varias instancias de la misma aplicación en un solo servidor, utilice el parámetro -Darms.agentId (un número lógico) para distinguir los procesos JVM que se van a integrar. Por ejemplo:

   java -javaagent:/{user.workspace}/AliyunJavaAgent/aliyun-java-agent.jar -Darms.licenseKey={LicenseKey} -Darms.appName={AppName} -Darms.workspace={workspace} -Darms.agentId=001 -jar demoApp.jar

5. Reinicie la aplicación Java.

<dependencies>
  <dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-core</artifactId>
    <version>2.0.1</version>
  </dependency>
  <dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-model-dashscope</artifactId>
    <version>2.0.1</version>
  </dependency>
  <!-- Add this dependency if Harness features are required -->
  <dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-harness</artifactId>
    <version>2.0.1</version>
  </dependency>
</dependencies>

import io.agentscope.core.agent.ReActAgent;
import io.agentscope.core.message.Msg;
import io.agentscope.core.message.MsgRole;
import io.agentscope.core.message.TextBlock;
import io.agentscope.core.tool.Tool;
import io.agentscope.core.tool.ToolParam;
import io.agentscope.core.tool.Toolkit;
import io.agentscope.extensions.model.dashscope.DashScopeChatModel;

public class QuickStart {
    public static void main(String[] args) {
        Toolkit toolkit = new Toolkit();
        toolkit.registerTool(new SimpleTools());

        DashScopeChatModel model = DashScopeChatModel.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .modelName("qwen-plus")
                .build();

        ReActAgent agent = ReActAgent.builder()
                .name("TravelAgent")
                .sysPrompt("You are a travel assistant. Use tools when needed.")
                .model(model)
                .toolkit(toolkit)
                .build();

        Msg msg = Msg.builder()
                .role(MsgRole.USER)
                .content(TextBlock.builder()
                        .text("What time is it in Hangzhou? Give me one travel tip.")
                        .build())
                .build();

        Msg response = agent.call(msg).block();
        System.out.println(response.getTextContent());
    }
}

class SimpleTools {
    @Tool(name = "get_time", description = "Get current local time")
    public String getTime(
            @ToolParam(name = "city", description = "City name") String city) {
        return city + ": " + java.time.LocalDateTime.now()
                .format(java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"));
    }
}