AgentLoop：接入 AgentScope（Java） 應用

架構與監控資料

AgentScope 是阿里巴巴開源的多 Agent 應用開發架構，提供 ReActAgent 等多種 Agent 類型，內建 DashScope 等模型適配器，支援工具調用、記憶管理和多 Agent 協作。AgentScope Java 是該架構的 Java 實現，適用於在 JVM 生態中構建大語言模型應用。

AgentScope Java 應用接入 AgentLoop 後，將自動監控以下內容：

• Agent 執行鏈路。

• LLM 調用：模型調用的 Token 用量、輸入和輸出內容。

• 工具調用鏈路：Toolkit 中各工具的調用詳情。

• ReAct Step：每一輪迴圈的行動與觀察。

接入方式

AgentScope Java 應用通過 Java 探針接入 AgentLoop，先在 AgentLoop 控制台擷取接入參數，再根據部署環境選擇一種探針安裝方式。

  armsPilotAutoEnable: "on"
  armsPilotCreateAppName: "deployment-name" # 請將deployment-name替換為您的應用程式名稱。
  armsPilotAppWorkspace: "workspace" # 替換為當前智能體空間（Workspace）的名稱。
  aliyun.com/app-language: java
  one-agent.jdk.version: "OpenJDK18" # JDK 版本，配合 JDK 17 及以上版本使用。

範例程式碼

以下樣本基於 AgentScope Java 2.0.1 構造一個最小可運行 Agent，包含一次模型調用和一次工具調用。運行前請確認已安裝 JDK 17 及以上版本，並在環境變數中設定 DASHSCOPE_API_KEY。

在 Maven 專案的 pom.xml 中引入 AgentScope Java 2.0.1 依賴：使用 ReActAgent 等基礎能力時引入 agentscope-core；通過 DashScope 調用模型時引入 agentscope-extensions-model-dashscope；需要 Harness 能力時額外引入 agentscope-harness。

<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>
  <!-- 需要 Harness 能力時引入 -->
  <dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-harness</artifactId>
    <version>2.0.1</version>
  </dependency>
</dependencies>

編寫一個帶工具調用的最小 Agent：模型適配器 DashScopeChatModel 從 io.agentscope.extensions.model.dashscope 匯入，訊息通過 Msg、MsgRole 和 TextBlock 構造，工具通過 Toolkit 註冊。

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

構造完成後，可以按照手動接入的步驟為應用掛載探針並啟動。

查看監控詳情

1. 登入 AgentLoop 控制台，選擇目標智能體空間，在左側導覽列單擊 AI Agent 可觀測。

2. 在 AI 應用列表頁面找到已接入的 AgentScope Java 應用，單擊應用程式名稱進入詳情頁。

   在應用詳情頁可查看該應用的調用鏈路（Trace）詳情：

• 概覽資訊：包括 Trace ID、開始時間、總耗時和 Total tokens 等。

• 鏈路時序圖：按層級展示完整的 Agent 調用鏈以及各 Span 的耗時。根 Span 為 AGENT 類型，對應一次 Agent 執行，其耗時即本次調用的總耗時；其下依次為 STEP 類型（對應 ReAct 迴圈的每一輪）、LLM 類型（模型調用，包含輸入和輸出 Token 數）和 TOOL 類型（工具調用，例如樣本中的 get_time）。

• Span 類型篩選：支援按 AGENT、STEP、LLM、TOOL 篩選 Span，快速定位目標節點。

• Span 詳情：單擊某個 Span，在右側詳情面板查看具體資訊。例如 LLM Span 展示 Input Messages（system 提示詞和 user 問題）和 Output Messages（模型響應及工具調用詳情）。

  如果應用或資料未出現在監控頁面，請參見 Java 探針排障文檔進行排查。

更多參考

• AgentScope Java 2.0.1 的 API 與更多用法，請參見 AgentScope 官方文檔。

• 在Container Service ACK 或容器計算服務 ACS 中安裝 Java 探針，請參見Container Service ACK 和容器計算服務 ACS 通過 ack-onepilot 組件安裝 Java 探針。

• 手動安裝 Java 探針，請參見手動安裝探針。

• Java 探針接入或資料上報異常時的排查方法，請參見 Java 探針排障文檔。