AgentScope Java: Alibaba’s Enterprise‑Grade AI Agent Framework for Java

Motivation for AgentScope Java

Java teams adopting Python‑centric AI frameworks encounter four major obstacles: fragmented technology stack, security concerns in financial scenarios, incompatibility with existing operations tooling (monitoring, tracing, configuration), and the complexity of coordinating multiple agents. AgentScope Java 1.0 provides a production‑grade solution that integrates with the Java ecosystem.

Core paradigm – ReAct (Reasoning + Acting)

AgentScope adopts the ReAct paradigm, which gives the large model control over a reasoning‑action loop. Unlike a static Workflow model that hard‑codes each step (e.g., query DB → call API → assemble response), ReAct lets the agent think, act, and observe iteratively, enabling handling of unknown or complex tasks.

Real‑time interruption

// Real‑time interruption example
AgentRuntime runtime = AgentRuntime.builder()
    .agent(customerServiceAgent)
    .build();

CompletableFuture<AgentResponse> future = runtime.executeAsync(request);

if (needInterrupt()) {
    runtime.interrupt(); // immediate termination
    AgentState snapshot = runtime.saveState(); // auto‑save context
    // can resume later
}

Secure interrupt : pause the agent and automatically preserve context and tool state.

Real‑time break : abort tasks that deviate from expectations or exceed time limits.

Customizable handling : plug in fine‑grained interrupt logic.

Five‑minute first agent

1. Add dependency

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

2. Configure application.yml

agentscope:
  core:
    model:
      dashscope:
        api-key: ${DASHSCOPE_API_KEY}
        model-name: qwen-plus
    agent:
      max-steps: 10
    sandbox:
      enabled: true

3. Define agent and tools

@AgentComponent("order-assistant")
public class OrderAssistant {
    @Autowired
    private OrderService orderService;
    @Autowired
    private RefundService refundService;

    @Tool("根据订单号查询订单状态")
    public String queryOrderStatus(String orderId) {
        Order order = orderService.findByOrderId(orderId);
        if (order == null) {
            return "未找到订单";
        }
        return String.format("订单状态：%s，金额：%s元，下单时间：%s",
                order.getStatus(), order.getAmount(), order.getCreateTime());
    }

    @Tool("执行退款操作（需要权限验证）")
    public String executeRefund(String orderId, String reason) {
        boolean success = refundService.processRefund(orderId, reason);
        return success ? "退款成功" : "退款失败";
    }
}

4. Invoke the agent

@RestController
public class AgentController {
    @Autowired
    private AgentRuntime runtime;

    @PostMapping("/chat")
    public String chat(@RequestBody String message) {
        AgentResponse response = runtime.execute("order-assistant", message);
        return response.getFinalAnswer();
    }
}

Running this code creates an agent capable of querying orders and processing refunds with only a few dozen lines of core code.

Security sandbox & context engineering

Sandbox configuration

@Configuration
public class SandboxConfig {
    @Bean
    public Sandbox sandbox() {
        return Sandbox.builder()
            .fileSystem(FileSystemSandbox.builder()
                .allowedPaths("/tmp/agentscope", "/data/temp")
                .readOnly(true)
                .build())
            .network(NetworkSandbox.builder()
                .whitelist("internal-api.example.com", "api.weather.com")
                .build())
            .docker(DockerSandbox.builder()
                .memoryLimit("512m")
                .cpuLimit(1)
                .build())
            .build();
    }
}

GUI sandbox : full desktop environment with mouse, keyboard, and screen interaction.

File‑system sandbox : restricts read/write to designated directories.

Mobile sandbox : Android emulator supporting clicks, swipes, and screenshots.

Context engineering

RAG (retrieval‑augmented generation) : built‑in embedding‑based retrieval, supports private knowledge bases and integration with Alibaba Cloud Bailei enterprise knowledge base.

Memory management : short‑term and long‑term memory abstractions with semantic search and multi‑tenant isolation, provided by the ReMe project.

A2A protocol + RocketMQ

AgentScope implements an Agent‑to‑Agent (A2A) protocol on Apache RocketMQ to enable multi‑agent cooperation.

Million‑scale lightweight resource management with private channels per session.

Session state persistence across process restarts.

Breakpoint resume for seamless continuation.

Strict ordering guarantees to keep conversational context coherent.

Multi‑agent service example

@Service
public class MultiAgentService {
    @Autowired
    private AgentClient agentClient;

    public String handleRefund(String orderId) {
        // 1. Risk assessment
        RiskAssessmentAgent riskAgent = agentClient.find("risk-assessment");
        boolean safe = riskAgent.evaluate(orderId);
        if (!safe) {
            return "退款申请被风控拦截";
        }
        // 2. Finance agent executes refund
        FinanceAgent financeAgent = agentClient.find("finance-agent");
        String result = financeAgent.refund(orderId);
        // 3. Notification agent sends success message
        NotificationAgent notifyAgent = agentClient.find("notification-agent");
        notifyAgent.sendRefundSuccess(orderId);
        return result;
    }
}

Visual debugging – AgentScope Studio

# Install Studio
npm install -g @agentscope/studio
# Launch
as_studio

agentscope.init(
    modelConfigs = "config.json",
    studioUrl = "http://localhost:3000" // connect to Studio
);

Real‑time chat interface.

Process observation of reasoning steps, tool invocations, and intermediate results.

Request tracing with token usage monitoring.

Breakpoint debugging with pause, state view, and resume.

Comparison with other Java AI frameworks

LangChain4j : best for quick PoC and idea validation.

Spring AI : best for standardized Spring‑style integration.

AgentScope Java : best for production use, especially in finance, e‑commerce, and government systems requiring high security and reliability.

Selection guide

Core business systems (finance, e‑commerce, government) that demand strict security and reliability.

Scenarios requiring cooperation of multiple agents (e.g., customer service, risk control, finance).

Java‑centric stacks that need deep Spring Cloud integration.

Hundreds of tools that need organized management via ToolGroup.

Human‑in‑the‑loop approval for high‑risk operations.

Open‑source repository

https://github.com/agentscope-ai/agentscope-java

Documentation: https://agentscope.io/docs/java