Agent 观测与优化 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 官方文档。

• 在容器服务 ACK 或容器计算服务 ACS 中安装 Java 探针，请参见容器服务 ACK 和容器计算服务 ACS 通过 ack-onepilot 组件安装 Java 探针。

• 手动安装 Java 探针，请参见手动安装探针。

• Java 探针接入或数据上报异常时的排查方法，请参见 Java 探针排障文档。