大模型可观测支持通过 Java 探针，为基于 AgentScope 框架构建的 Java 应用采集可观测数据。Java 探针基于 OpenTelemetry 标准自动采集应用调用链路，将 AgentScope Java 应用中的 Agent 执行、模型调用和工具调用数据上报至云监控 2.0。本文介绍如何将 AgentScope Java 应用接入云监控 2.0，实时掌握 AI 应用的运行状态。
框架介绍
AgentScope 是阿里巴巴开源的多 Agent 应用开发框架，提供 ReActAgent 等多种 Agent 类型，内置 DashScope 等模型适配器，支持工具调用、记忆管理和多 Agent 协作。AgentScope Java 是该框架的 Java 实现，适用于在 JVM 生态中构建大语言模型应用。
接入后，自动监控以下内容：
Agent 执行链路。
LLM 调用：模型调用的 Token 用量、输入和输出内容。
工具调用链路：
Toolkit中各工具的调用详情。ReAct Step：每一轮循环的行动与观察。
接入方式
AgentScope Java 应用通过 Java 探针接入云监控 2.0：先在云监控 2.0 控制台获取接入参数，再根据部署环境选择一种探针安装方式。
前提条件与使用限制
JDK 版本：建议使用 JDK 17 及以上版本运行 AgentScope Java 应用。
JVM 内存：安装 Java 探针时，建议目标 JVM 最大堆内存大于 300 MB。
云监控服务：已开通云监控 2.0 服务，并创建工作空间。
数据类型：当前主要上报 Trace 和 Metric 数据。
获取接入参数
登录云监控 2.0 控制台，选择目标工作空间。
在左侧导航栏单击接入中心。
在AI 应用可观测区域选择 AgentScope Java 接入项。
输入应用名，根据部署环境选择连接方式，然后单击LicenseKey右侧的点击获取。
请记录以下参数，安装探针时需要使用：
LicenseKey：数据写入鉴权的 LicenseKey。
工作空间：云监控 2.0 工作空间标识。
RegionId：应用上报数据所在地域，例如
cn-hangzhou。应用名：应用在云监控 2.0 中展示的名称。
安装 Java 探针
根据部署环境选择对应页签，按页签内步骤安装 Java 探针：
容器服务 ACK 和容器计算服务 ACS 接入
ack-onepilot组件说明
应用监控探针接入助手（ack-onepilot）是用于接入各语言探针的重要组件，可以帮助用户在容器环境中自动准备好应用监控探针包并构建好探针的上报环境。应用监控探针接入助手（ack-onepilot）的基本原理请参见ack-onepilot组件基本原理说明。
探针接入后，为了确保您的使用体验，在新版本探针发布后，当应用重启时，ack-onepilot将会自动将探针升级到最新版本，如果您不需要跟随应用监控探针的版本发布自动更新挂载的探针，可以自主控制探针版本。具体操作，请参见自主控制探针版本。
步骤一：安装探针接入助手（ack-onepilot）
登录容器服务管理控制台，在集群列表页面单击目标集群名称。
-
在左侧导航栏单击组件管理，搜索并定位ack-onepilot。
重要ack-onepilot版本需在5.1.0或以上。
在ack-onepilot卡片上单击安装。
说明ack-onepilot组件默认支持1000个pod规模，集群pod每超过1000个，ack-onepilot资源对应的CPU请增加0.5核、内存请增加512 MB。
如果在ACS集群中安装ack-onepilot，请在安装卡片的最下方配置accessKey与accessKeySecret，阿里云账号的AccessKey ID和AccessKey Secret。获取方法，请参见创建AccessKey。请确认对应的阿里云账号已包含AliyunARMSFullAccess和AliyunSTSAssumeRoleAccess权限。
在弹出的页面中可以配置相关的参数，建议使用默认值，单击确认。
说明安装完成后，您可以在组件管理页面升级、配置或卸载ack-onepilot组件。
步骤二：授予ARMS资源的访问权限
ACK托管集群
如果ACK托管集群中不存在ARMS Addon Token，请执行以下操作手动为集群授予ARMS资源的访问权限。如果已经存在ARMS Addon Token，请跳转至步骤三。
集群存在ARMS Addon Token时，ARMS会进行免密授权。Kubernetes托管版集群默认存在ARMS Addon Token，但对于部分早期创建的Kubernetes托管版集群，可能会存在没有ARMS Addon Token的情况，因此，对于Kubernetes托管版集群，建议首先检查ARMS Addon Token是否存在。若不存在，需进行手动授权。
专有版集群/注册集群
如果需要监控ACK专有版集群和ACK One注册集群应用，请确认对应的阿里云账号已包含AliyunARMSFullAccess和AliyunSTSAssumeRoleAccess权限。添加权限的操作，请参见管理RAM用户的权限。
安装ack-onepilot组件后，还需要在ack-onepilot中填写有ARMS权限的阿里云账号AK/SK。
方式一：Helm中直接填写AK/SK
登录容器服务管理控制台，在左侧导航栏选择集群列表。
-
在集群列表页面，单击目标集群名称，然后在左侧导航栏选择页面，单击ack-onepilot组件右侧的更新。
-
将
accessKey和accessKeySecret替换为当前账号的AccessKey，然后单击确定。说明获取AccessKey的操作，请参见创建AccessKey。
在YAML配置编辑器的
controller配置段中，找到accessKey: __ACCESSKEY__和accessKeySecret: __ACCESSKEY_SECRET__，将占位符替换为实际的AccessKey信息。 -
重启应用Deployment。
方式二：通过K8s Secret引入AK/SK
-
登录容器服务管理控制台，在左侧导航栏选择集群列表。
-
在集群列表页面，单击目标集群名称，然后在左侧导航栏选择。
-
选择ack-onepilot命名空间，然后创建Secret，添加AK/SK信息。
说明获取AccessKey的操作，请参见创建AccessKey。
Secret 名称设置为
ack-onepilot-aksk，类型选择 Opaque，在数据区域添加两行：名称分别为ak和sk，值分别填入对应的 AccessKey ID 和 AccessKey Secret，然后单击确定。 -
在左侧导航栏选择，单击ack-onepilot组件（一般在ack-onepilot命名空间下，名称为ack-onepilot-ack-onepilot）。
-
在ack-onepilot-ack-onepilot页面右上角单击编辑，然后在环境变量区域添加
ONE_PILOT_ACCESSKEY和ONE_PILOT_ACCESSKEY_SECRET，通过保密字典引用的方式替换为Secret中保存的值，单击确定。保密字典选择 ack-onepilot-aksk，ONE_PILOT_ACCESSKEY 的键名选择 ak，ONE_PILOT_ACCESSKEY_SECRET 的键名选择 sk。
ASK/ECI集群
如果需监控ACK Serverless集群或对接了ECI的集群应用，请在云资源访问授权页面完成授权，然后重启ack-onepilot组件下的所有Pod。
步骤三：为Java应用开启应用监控
创建一个无状态（Deployment）应用并开启应用监控的完整YAML示例模板如下：
登录容器服务管理控制台，在左侧导航栏选择集群列表。
在集群列表页面，单击目标集群名称，然后在左侧导航栏，选择。
在无状态页面的目标应用右侧选择
> YAML 编辑。如需创建一个新应用，单击使用YAML创建资源。
-
在YAML文件中将以下
labels添加到spec.template.metadata层级下。labels: armsPilotAutoEnable: "on" armsPilotCreateAppName: "deployment-name" # 请将deployment-name替换为您的应用名称。 armsPilotAppWorkspace: "workspace" # 替换为当前Workspace名称。 aliyun.com/app-language: javaapiVersion: v1 kind: Namespace metadata: name: arms-demo --- apiVersion: apps/v1 # for versions before 1.8.0 use apps/v1beta1 kind: Deployment metadata: name: arms-springboot-demo namespace: arms-demo labels: app: arms-springboot-demo spec: replicas: 2 selector: matchLabels: app: arms-springboot-demo template: metadata: labels: app: arms-springboot-demo armsPilotAutoEnable: "on" armsPilotCreateAppName: "arms-k8s-demo" armsPilotAppWorkspace: "workspace" spec: containers: - resources: limits: cpu: 0.5 image: registry.cn-hangzhou.aliyuncs.com/arms-docker-repo/arms-springboot-demo:v0.1 -
单击更新。
手动接入
安装探针
登录云监控2.0控制台，选择目标工作空间，在左侧导航栏单击接入中心。
单击Java应用监控卡片，然后单击手动安装。
下载探针。
方法一：手动下载。在Java应用监控面板根据提示下载对应的探针。
方法二：使用wget命令下载。根据您的地域下载对应的探针安装包。
解压探针。
进入探针安装包所在目录，并执行以下命令将安装包解压到任意工作目录下。
unzip AliyunJavaAgent.zip -d /{user.workspace}/说明{user.workspace}是示例目录，请替换为真实的目录。
添加AppName和LicenseKey参数。
在Java应用监控面板获取到对应的LicenseKey。AppName代表接入到ARMS的哪一个应用中，您可以根据需要自定义您的应用名，在分布式架构中，同一个应用内可以包含多个对等的实例。
重要不同的workspace的LicenseKey不同，新workspace的LicenseKey需要单独获取。
请通过下列两种方式，添加AppName与LicenseKey。
方法一（推荐）：将接入脚本中的
{LicenseKey}与{AppName}替换为您从控制台获得的LicenseKey以及该应用对应的AppName。方法二：如果您希望在不同应用中重用启动脚本，可以通过修改探针配置文件来填写 LicenseKey 和 AppName 的相关信息。具体步骤如下：
说明4.4.0以下版本探针通过该方式默认接入default workspace空间。
在上一步解压出的 version 文件中查看 Java 探针版本。
修改探针配置文件。
4.0.0及以上探针
在探针目录下创建一个 arms-agent.properties 文件，并添加以下配置，然后在启动命令中添加
-Dotel.javaagent.configuration-file=/path/to/arms-agent.properties或添加环境变量OTEL_JAVAAGENT_CONFIGURATION_FILE=/path/to/arms-agent.properties来启用该配置文件。arms.licenseKey={LicenseKey} arms.appName={AppName}4.0.0以下探针
在探针包的arms-agent.config文件中添加以下配置。
arms.licenseKey={LicenseKey} arms.appName={AppName}说明探针配置文件的其他配置项说明，请参见修改 Java 探针配置文件及默认上报地域。
将接入命令添加到启动命令中。
将
{user.workspace}替换成实际探针安装包的解压目录，将demoApp.jar替换为真实的JAR包地址。说明如果您使用的探针版本在2.7.3.5以下，请将本文中的AliyunJavaAgent/aliyun-java-agent.jar替换为ArmsAgent/arms-bootstrap-1.7.0-SNAPSHOT.jar。建议您尽快将探针升级至最新版本。
在Windows操作系统中，请将脚本中的
/替换为\，并将.sh文件替换为.bat文件。v2.7.1.4及以上版本探针已支持在接入应用监控时开通应用安全，如果需要开通应用安全，请在脚本中添加
-Darms.appsec.enable=true。应用安全的计费规则，请参见计费说明。
运行环境
步骤
Spring Boot或其他通过
java -jar命令启动的Java应用在启动命令后加上-javaagent参数。请确保-javaagent参数写在-jar参数之前。
java -javaagent:/{user.workspace}/AliyunJavaAgent/aliyun-java-agent.jar -Darms.licenseKey={LicenseKey} -Darms.appName={AppName} -Darms.workspace={workspace} -jar demoApp.jarTomcat
在{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} "如果您的Tomcat版本没有setenv.sh配置文件，请打开{TOMCAT_HOME}/bin/catalina.sh文件，并在JAVA_OPTS后添加上述配置，具体示例，请参见catalina.sh的第256行。
Jetty
在{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}如需在一台服务器上部署同一应用的多个实例，可以通过-Darms.agentId参数（逻辑编号）来区分接入的JVM进程，例如：
java -javaagent:/{user.workspace}/AliyunJavaAgent/aliyun-java-agent.jar -Darms.licenseKey={LicenseKey} -Darms.appName={AppName} -Darms.workspace={workspace} -Darms.agentId=001 -jar demoApp.jar重启Java应用。
示例代码
以下示例基于 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"));
}
}查看监控详情
登录云监控 2.0 控制台，选择目标工作空间，在左侧导航栏选择所有功能 > AI 应用可观测。
在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（模型响应及工具调用详情）。
更多参考
AgentScope Java 2.0.1 的 API 与更多用法，请参见 AgentScope 官方文档。
在容器服务 ACK 或容器计算服务 ACS 中安装 Java 探针，请参见容器服务 ACK 和容器计算服务 ACS 通过 ack-onepilot 组件安装 Java 探针。
手动安装 Java 探针，请参见手动安装探针。
Java 探针接入或数据上报异常时的排查方法，请参见 Java 探针排障文档。