AgentLoop:Integrar aplicações AgentScope (Java)

Pré-requisitos e limites

• Versão do JDK — Execute a aplicação Java AgentScope no JDK 17 ou posterior.

• Memória da JVM — Ao instalar o probe Java, certifique-se de que a memória heap máxima da JVM de destino seja superior a 300 MB.

• service AgentLoop — O AgentLoop está ativado e um AgentSpace foi criado.

Obter parâmetros de integração

1. Faça login no console do AgentLoop. No painel de navegação à esquerda, clique em Integration Center.

2. Clique no cartão AgentScope.

3. Na página de integração do AgentScope, selecione a linguagem Java.

4. Insira o nome da aplicação. A página gera os parâmetros e as instruções de instalação necessários para integrar o probe Java.

Integração com ACK e ACS

O assistente de integração de probes de monitoramento de aplicações (ack-onepilot) é um componente essencial para integrar probes de várias linguagens. Ele prepara automaticamente pacotes de probes de monitoramento de aplicações em ambientes de contêiner e configura o ambiente de relatório para os probes. Para mais informações sobre o funcionamento do ack-onepilot, consulte Visão geral do componente ack-onepilot.

Após a integração do probe, uma nova versão é aplicada automaticamente quando a aplicação é reiniciada. Assim, o ack-onepilot atualiza o probe para a versão mais recente e mantém sua experiência consistente. Caso não deseje que o probe montado seja atualizado automaticamente conforme novas versões forem lançadas, controle a versão do probe manualmente. Para mais informações, consulte Controlar manualmente a versão do probe.

Este método consiste em três etapas: instalar o ack-onepilot, conceder as permissões de acesso exigidas pelo ARMS e ativar o monitoramento de aplicações para sua aplicação.

Integração manual

Utilize a integração manual para instalar o probe Java em ambientes diferentes de clusters ACK ou ACS, como aplicações iniciadas com o comando java -jar, Tomcat ou Jetty.

1. Após selecionar a linguagem Java na página de integração do AgentScope, localize a seção de integração manual e baixe o probe Java seguindo as instruções na tela. A página já gerou os parâmetros de integração para o AgentSpace atual.

2. Extraia o probe.

   Acesse o diretório do pacote do probe e execute o comando a seguir para extrair o pacote em um diretório de trabalho de sua escolha.

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

   Nota

   {user.workspace} é um diretório de exemplo. Substitua-o pelo seu diretório real.

3. Configure os parâmetros AppName e LicenseKey.

   Use a LicenseKey obtida anteriormente no Integration Center do AgentLoop. AppName é o nome exibido para a aplicação no AgentLoop e pode ser personalizado. Em uma arquitetura distribuída, uma aplicação pode conter múltiplas instâncias pares.

   Importante

   Diferentes AgentSpaces usam LicenseKeys diferentes. Após trocar de AgentSpace, obtenha a LicenseKey novamente.

   Forneça AppName e LicenseKey usando um dos métodos a seguir:

   • Método 1 (recomendado): Use parâmetros de inicialização -D. Substitua os placeholders {LicenseKey} e {AppName} no comando de inicialização da Etapa 4 pela LicenseKey obtida no console e pelo AppName da aplicação.

   • Método 2: Modifique o arquivo de configuração do probe. Use este método se quiser reutilizar o script de inicialização em diferentes aplicações. Execute as etapas a seguir:

     1. Verifique a versão do probe Java no arquivo de versão extraído na etapa anterior.

     2. Modifique o arquivo de configuração do probe com base na versão do probe:

        • Para probe 4.0.0 ou posterior, crie um arquivo arms-agent.properties no diretório do probe e adicione a configuração a seguir. Em seguida, adicione -Dotel.javaagent.configuration-file=/path/to/arms-agent.properties ao comando de inicialização ou defina a variável de ambiente OTEL_JAVAAGENT_CONFIGURATION_FILE=/path/to/arms-agent.properties para habilitar o arquivo de configuração.

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

        • Para um probe anterior à versão 4.0.0, adicione a configuração a seguir ao arquivo arms-agent.config no pacote do probe.

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

   Nota

   • Para versões de probe anteriores a 4.4.0, este método conecta-se ao default workspace por padrão.

   • Para mais informações sobre outros itens de configuração no arquivo de configuração do probe, consulte Modificar o arquivo de configuração do probe Java e a região de relatório padrão.

4. Adicione o comando de integração ao comando de inicialização.

   Substitua {user.workspace} pelo diretório real de extração do pacote do probe e substitua demoApp.jar pelo caminho real do pacote JAR.

   Nota

   • Se a versão do probe for anterior a 2.7.3.5, substitua AliyunJavaAgent/aliyun-java-agent.jar neste tópico por ArmsAgent/arms-bootstrap-1.7.0-SNAPSHOT.jar. Recomendamos atualizar o probe para a versão mais recente o quanto antes.

   • Em sistemas operacionais Windows, substitua / no script por \ e substitua arquivos .sh por arquivos .bat.

   • A versão 2.7.1.4 e posteriores do probe suporta a ativação do Application Security durante a integração do monitoramento de aplicações. Para ativar o Application Security, adicione -Darms.appsec.enable=true ao script. Para mais informações sobre as regras de faturamento do Application Security, consulte Regras de faturamento.

   Adicione o parâmetro -javaagent com base no seu ambiente de execução:

   Ambiente de execução	Etapas
   Spring Boot ou outras aplicações Java iniciadas com o comando java -jar	Anexe o parâmetro -javaagent ao comando de inicialização. Certifique-se de que o parâmetro -javaagent esteja posicionado antes do 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	Adicione a configuração a seguir ao arquivo {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} " Se a sua versão do Tomcat não possuir o arquivo de configuração setenv.sh, abra o arquivo {TOMCAT_HOME}/bin/catalina.sh e adicione a configuração acima após JAVA_OPTS. Para um exemplo específico, consulte a linha 256 de catalina.sh.
   Jetty	Adicione a configuração a seguir ao arquivo de configuração {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 implantar múltiplas instâncias da mesma aplicação em um único servidor, use o parâmetro -Darms.agentId (um número lógico) para distinguir os processos JVM a serem integrados. Por exemplo:

   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 a aplicação 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"));
    }
}