AgentLoop:AgentScope (Java) uygulamalarını entegre etme

Ön koşullar ve sınırlamalar

• JDK sürümü — AgentScope Java uygulamasını JDK 17 veya üzeri bir sürümde çalıştırın.

• JVM belleği — Java probunu yüklerken hedef JVM'in maksimum yığın belleğinin 300 MB'tan büyük olduğundan emin olun.

• AgentLoop hizmeti — AgentLoop etkinleştirilmiş ve bir AgentSpace oluşturulmuştur.

Entegrasyon parametrelerini alma

1. AgentLoop konsolunda oturum açın. Sol gezinme bölmesinde Integration Center seçeneğine tıklayın.

2. AgentScope kartına tıklayın.

3. AgentScope entegrasyon sayfasında Java dilini seçin.

4. Uygulama adını girin. Sayfa, Java probunu entegre etmek için gereken parametreleri ve yükleme talimatlarını oluşturur.

ACK ve ACS ile entegrasyon

Uygulama izleme probu entegrasyon asistanı (ack-onepilot), çeşitli dillerdeki probların entegrasyonu için kilit bir bileşendir. Konteyner ortamlarında uygulama izleme probu paketlerini otomatik olarak hazırlar ve problar için raporlama ortamını kurar. ack-onepilot'un çalışma şekli hakkında daha fazla bilgi için bkz. ack-onepilot bileşenine genel bakış.

Prob entegre edildikten sonra uygulamanız yeniden başlatıldığında yeni bir prob sürümü otomatik olarak uygulanır; böylece ack-onepilot probu en son sürüme yükseltir ve deneyiminizin tutarlı kalmasını sağlar. Yeni prob sürümleri yayınlandıkça monte edilen probun otomatik olarak güncellenmesini istemiyorsanız prob sürümünü kendiniz kontrol edebilirsiniz. Daha fazla bilgi için bkz. Prob sürümünü manuel olarak kontrol etme.

Bu yöntem üç adımdan oluşur: ack-onepilot'u yükleyin, ARMS için gereken erişim izinlerini verin ve ardından uygulamanız için uygulama izlemeyi etkinleştirin.

Manuel entegrasyon

java -jar komutu, Tomcat veya Jetty ile başlatılan uygulamalar gibi ACK veya ACS kümeleri dışındaki ortamlarda Java probunu yüklemek için manuel entegrasyonu kullanın.

1. AgentScope entegrasyon sayfasında Java dilini seçtikten sonra manuel entegrasyon bölümünü bulun ve ekrandaki talimatları izleyerek Java probunu indirin. Sayfa, mevcut AgentSpace için entegrasyon parametrelerini zaten oluşturmuştur.

2. Probu çıkarın.

   Prob paketinin dizinine gidin ve paketi seçtiğiniz bir çalışma dizinine çıkarmak için aşağıdaki komutu çalıştırın.

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

   Not

   {user.workspace} örnek bir dizindir. Bunu kendi gerçek dizininizle değiştirin.

3. AppName ve LicenseKey parametrelerini yapılandırın.

   Daha önce AgentLoop'un Integration Center'ından aldığınız LicenseKey değerini kullanın. AppName, uygulamanın AgentLoop'ta görüntülenen adıdır ve özelleştirilebilir. Dağıtılmış bir mimaride bir uygulama birden çok eş örnek içerebilir.

   Önemli

   Farklı AgentSpace'ler farklı LicenseKey değerleri kullanır. AgentSpace'leri değiştirdikten sonra LicenseKey'i yeniden alın.

   AppName ve LicenseKey değerlerini aşağıdaki yöntemlerden biriyle sağlayın:

   • Yöntem 1 (önerilir): -D başlatma parametrelerini kullanın. 4. Adım başlatma komutundaki {LicenseKey} ve {AppName} yer tutucularını konsoldan aldığınız LicenseKey ve uygulamanın AppName değeri ile değiştirin.

   • Yöntem 2: Prob yapılandırma dosyasını değiştirin. Başlatma betiğini farklı uygulamalar arasında yeniden kullanmak istiyorsanız bu yöntemi kullanın. Aşağıdaki adımları uygulayın:

     1. Önceki adımda çıkarılan sürüm dosyasındaki Java probu sürümünü kontrol edin.

     2. Prob sürümüne göre prob yapılandırma dosyasını değiştirin:

        • 4.0.0 veya sonraki prob sürümleri için prob dizininde bir arms-agent.properties dosyası oluşturun ve aşağıdaki yapılandırmayı ekleyin. Ardından yapılandırma dosyasını etkinleştirmek için başlatma komutuna -Dotel.javaagent.configuration-file=/path/to/arms-agent.properties ekleyin veya OTEL_JAVAAGENT_CONFIGURATION_FILE=/path/to/arms-agent.properties ortam değişkenini ayarlayın.

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

        • 4.0.0'dan önceki bir prob sürümü için prob paketindeki arms-agent.config dosyasına aşağıdaki yapılandırmayı ekleyin.

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

   Not

   • 4.4.0'dan önceki prob sürümleri için bu yöntem varsayılan olarak default workspace adresine bağlanır.

   • Prob yapılandırma dosyasındaki diğer yapılandırma öğeleri hakkında daha fazla bilgi için Java probu yapılandırma dosyasını değiştirme ve varsayılan raporlama bölgesi konusuna bakın.

4. Entegrasyon komutunu başlatma komutuna ekleyin.

   {user.workspace} değerini prob paketinin gerçek çıkarma dizini ile, demoApp.jar değerini ise JAR paketinin gerçek yolu ile değiştirin.

   Not

   • Prob sürümü 2.7.3.5'ten önceyse bu konudaki AliyunJavaAgent/aliyun-java-agent.jar ifadesini ArmsAgent/arms-bootstrap-1.7.0-SNAPSHOT.jar ile değiştirin. Probu en kısa sürede en son sürüme yükseltmenizi öneririz.

   • Windows işletim sistemlerinde betikteki / karakterini \ ile, .sh dosyalarını ise .bat dosyaları ile değiştirin.

   • 2.7.1.4 ve sonraki prob sürümleri, uygulama izlemeyi entegre ederken Uygulama Güvenliğinin etkinleştirilmesini destekler. Uygulama Güvenliğini etkinleştirmek için betiğe -Darms.appsec.enable=true ekleyin. Uygulama Güvenliğinin faturalandırma kuralları hakkında daha fazla bilgi için bkz. Faturalandırma kuralları.

   Çalışma zamanı ortamınıza göre -javaagent parametresini ekleyin:

   Çalışma zamanı ortamı	Adımlar
   Spring Boot veya java -jar komutuyla başlatılan diğer Java uygulamaları	Başlatma komutuna -javaagent parametresini ekleyin. -javaagent parametresinin -jar parametresinden önce yer aldığından emin olun. java -javaagent:/{user.workspace}/AliyunJavaAgent/aliyun-java-agent.jar -Darms.licenseKey={LicenseKey} -Darms.appName={AppName} -Darms.workspace={workspace} -jar demoApp.jar
   Tomcat	Aşağıdaki yapılandırmayı {TOMCAT_HOME}/bin/setenv.sh dosyasına ekleyin. JAVA_OPTS="$JAVA_OPTS -javaagent:/{user.workspace}/AliyunJavaAgent/aliyun-java-agent.jar -Darms.licenseKey={LicenseKey} -Darms.appName={AppName} -Darms.workspace={workspace} " Tomcat sürümünüzde setenv.sh yapılandırma dosyası yoksa {TOMCAT_HOME}/bin/catalina.sh dosyasını açın ve önceki yapılandırmayı JAVA_OPTS ifadesinden sonra ekleyin. Belirli bir örnek için catalina.sh dosyasının 256. satırına bakın.
   Jetty	Aşağıdaki yapılandırmayı {JETTY_HOME}/start.ini yapılandırma dosyasına ekleyin. aliyun-java-agent.jar --exec -javaagent:/{user.workspace}/AliyunJavaAgent/aliyun-java-agent.jar -Darms.licenseKey={LicenseKey} -Darms.appName={AppName} -Darms.workspace={workspace}

   Aynı uygulamanın birden çok örneğini bir sunucuya dağıtmak için entegre edilecek JVM süreçlerini ayırt etmek üzere -Darms.agentId parametresini (mantıksal bir numara) kullanın. Örnek:

   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. Java uygulamasını yeniden başlatın.

<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"));
    }
}