AgentLoop:Integrate AgentScope (Java) applications

Framework introduction

AgentScope is an open-source multi-agent application development framework from Alibaba. It provides multiple agent types such as ReActAgent, includes built-in model adapters such as DashScope, and supports tool calling, memory management, and multi-agent collaboration. AgentScope Java is the Java implementation of the framework and is suitable for building LLM applications in the JVM ecosystem.

After integration, the following data is monitored automatically:

• Agent execution traces.

• LLM invocations: token usage and the input and output content of model invocations.

• Tool calling traces: the call details of each tool in the Toolkit.

• ReAct steps: the action and observation of each loop iteration.

  AgentLoop reports this data as Trace and Metric data.

Integration methods

To integrate an AgentScope Java application into AgentLoop, first get the integration parameters in the AgentLoop console, and then install the Java probe based on your deployment environment.

Install the Java probe

Choose one of the following installation methods based on your deployment environment:

• Integrate with Container Service for Kubernetes (ACK) and Container Compute Service (ACS) — For applications deployed in ACK or ACS clusters. The ack-onepilot component automatically installs and maintains the Java probe in container environments.

• Manual integration — For applications that run outside ACK or ACS clusters, such as applications started with the java -jar command, Tomcat, or Jetty. You download the Java probe and add it to the application startup process yourself.

  After you complete the integration and restart your application, you can verify that data is reported in the View monitoring details section.

Sample code

The following sample uses AgentScope Java 2.0.1 to build a minimal runnable agent that contains one model invocation and one tool invocation. Before you run the sample, make sure that JDK 17 or later is installed and that DASHSCOPE_API_KEY is set as an environment variable.

Add the AgentScope Java 2.0.1 dependencies to the pom.xml of your Maven project:

• Add agentscope-core to use basic features such as ReActAgent.

• Add agentscope-extensions-model-dashscope to call models through DashScope.

• Add agentscope-harness if Harness features are required.

<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>

Write a minimal agent with tool calling: the model adapter DashScopeChatModel is imported from io.agentscope.extensions.model.dashscope, messages are constructed with Msg, MsgRole, and TextBlock, and tools are registered with 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"));
    }
}

To run this sample with monitoring enabled, package the sample as a JAR file and start it by using the integration command in Step 4 of the manual integration procedure. Replace demoApp.jar with the path of the sample JAR file. If you deploy the sample in an ACK or ACS cluster, add the monitoring labels described in Step 3 to the Deployment of the sample.

View monitoring details

1. Log on to the AgentLoop console and select the target AgentSpace. In the left-side navigation pane, click AI Agent Observability.

2. On the AI Application List page, find the integrated AgentScope Java application and click Application Name to go to the details page.

   On the application details page, you can view the call traces of the application:

• Overview — Includes the Trace ID, start time, total duration, Total tokens, and so on.

• Trace timeline — Shows the complete agent call chain by level and the duration of each span. The root span is of the AGENT type and corresponds to one agent execution. Its duration is the total duration of the call. The levels below are the STEP type (each iteration of the ReAct loop), the LLM type (model invocations, including the input and output token counts), and the TOOL type (tool calling, such as get_time in the sample).

• Span type filtering — Filters spans by AGENT, STEP, LLM, or TOOL to quickly locate the target node.

• Span details — Click a span and view the details in the details panel on the right. For example, an LLM span shows Input Messages (the system prompt and the user question) and Output Messages (the model response and tool call details).

References

• For the API and more usage of AgentScope Java 2.0.1, see the AgentScope official documentation.

• To install the Java probe in Container Service for Kubernetes (ACK) or Container Compute Service (ACS), see Install the Java probe in ACK and ACS clusters by using the ack-onepilot component.

• To install the Java probe manually, see Manually install the probe.

• For troubleshooting methods when the Java probe integration or data reporting is abnormal, see the Java probe troubleshooting documentation.