AgentScope Framework Deep Dive: ReActAgent and HarnessAgent Development in Practice

AgentScope's Position in the Java Agent Ecosystem

AgentScope is an agent development framework for Java developers. To understand its value, we first need to clarify its relationship with Spring AI and Spring AI Alibaba. Spring AI provides foundational abstractions such as model integration, prompt templates, and output parsing, while Spring AI Alibaba adds Alibaba Cloud ecosystem adapters and enterprise-grade capabilities on top of that. AgentScope's differentiation lies in its sharper focus on the "agent" itself—how to organize reasoning loops, tool calls, memory, and human confirmation.

Looking at the trend, the base model integration layer is becoming standardized, while the agent behavior orchestration layer remains the main battleground for framework competition. AgentScope chooses to go deep in both the ReAct paradigm and engineering tooling (Harness) simultaneously, which holds real appeal for Java teams that need complex task automation.

ReActAgent: A Unified Loop of Reasoning and Acting

ReActAgent is the core component of AgentScope, and its design follows the classic "reasoning-acting" alternating paradigm. During a single task, the model first outputs its thoughts, then decides which tool to call, and after receiving the result continues reasoning until it produces a final answer. This loop seems simple, but its engineering implementation involves several key modules.

Model Integration and Structured Output

ReActAgent first solves the consistency problem of model invocation. The framework masks the interface differences between model providers and unifies them into a configurable model layer. Structured output is another focus: the tool-calling parameters of an agent require reliable format guarantees, otherwise the loop is prone to interruption. AgentScope uses schema constraints and parsing fallbacks to reduce failure rates caused by output format anomalies.

Tools, Memory, and Middleware

Tools are the action boundary of ReActAgent. The framework provides tool registration and execution mechanisms, and supports multimodal input. The memory module maintains context within the loop, while middleware allows cross-cutting logic to be inserted before and after reasoning steps, such as logging, permission checks, or result caching. The Skills mechanism further encapsulates common capabilities into reusable units.

Messages, Events, and Advanced Capabilities

The message and event system supports asynchronous interaction between the agent and the external environment. On this basis, ReActAgent also covers MCP protocol integration, RAG retrieval augmentation, and interruption and HITL (Human-in-the-loop) capabilities. Together these capabilities form the foundation of a production-grade agent.

ReAct paradigm (Reasoning + Acting) originates from a 2022 academic paper. Its core idea is to let large language models alternate between generating "reasoning traces" and "action instructions" when solving tasks. Unlike directly outputting an answer or doing only chain-of-thought (CoT) reasoning, ReAct requires the model to explicitly output its current thinking at each step, then based on that thinking decide which external tool to call (such as search, calculation, or an API), and use the tool's returned result as input for the next round of reasoning. This alternating loop enables the model to correct its own reasoning biases with external information, significantly improving the accuracy and interpretability of complex tasks. In engineering implementation, the ReAct loop needs to handle details such as tool description injection, call parameter validation, and loop termination condition judgment, and it is the default behavioral paradigm of most current agent frameworks.

MCP (Model Context Protocol) is a standardized protocol proposed and open-sourced by Anthropic, aimed at unifying how large language models connect to external tools and data sources. Before MCP, every agent framework or application needed to write customized integration code for different tools, which was repetitive and hard to reuse. MCP defines a client-server architecture based on JSON-RPC: tool providers implement MCP servers that expose resources, tools, and prompts; agents act as MCP clients, discovering and invoking these capabilities through standard interfaces. For frameworks like AgentScope, integrating MCP means agents can plug into the growing MCP tool ecosystem without adapting to each new tool individually, greatly reducing the engineering cost of tool expansion.

Comprehensive Case: An AI IDE-like File Operation Agent

The tech talk presented a comprehensive case whose interaction form resembles an AI programming tool: the agent can operate on local directories, execute tools, and request human confirmation before critical operations. When the user asks to write some content into a specified file, the agent initiates a tool call and waits for confirmation.

If the user skips confirmation and directly asks to execute again, the system returns an error prompt requiring the confirmation flow to be completed first. After the user clicks confirm, the tool enters the execution state and returns the result; clicking reject explicitly informs that the operation was rejected. This design embodies the core value of HITL: establishing an explicit gate between automation and controllability.

HITL (Human-in-the-loop) refers to a mechanism that pauses at key decision points during an agent's autonomous execution flow and requests human confirmation, correction, or rejection. Its engineering implementation typically relies on an "interrupt-resume" model: when triggering an operation requiring confirmation, the agent suspends its current execution state (including context, pending tools, and parameters) and returns control to the user; after the user makes a choice, the system resumes or terminates that call based on the confirmation or rejection result. The value of HITL lies in setting explicit gates for high-risk operations (such as writing files, sending requests, or executing commands), preventing automated flows from advancing irreversibly in the wrong direction. In the AgentScope case, repeated execution requests without confirmation are directly rejected, which is precisely the state machine constraint that ensures the confirmation flow cannot be bypassed.

HarnessAgent: A Systematic Approach to Harness Engineering

HarnessAgent represents another direction of AgentScope—Harness Engineering. If ReActAgent focuses on the reasoning loop of a single task, HarnessAgent focuses on the engineering environment required for an agent to operate.

Workspace and Storage Structure

HarnessAgent introduces the concept of a workspace, defining the boundary of files and resources the agent can operate on. Within the workspace, the purpose of each file and the storage structure have clear conventions, making the agent's behavior auditable and reproducible. The tech talk explained the workspace directory structure and the meaning of each file item by item, which is a key detail for engineering implementation.

Harness Engineering borrows the metaphor of a "harness" (tack/safety belt), emphasizing the application of controllable engineering constraints to powerful agents. Unlike prompt engineering, which focuses on single-round reasoning quality, harness engineering focuses on the environment that an agent relies on for long-term operation: clear workspace boundaries, auditable file storage conventions, stable message channels, and context trade-off strategies for long tasks. Its goal is to make the agent's behavior reproducible, traceable, and intervenable. In AgentScope, HarnessAgent productizes this approach, converging engineering practices originally scattered across the application layer (such as file purpose conventions and channel abstractions) into built-in framework capabilities, thereby reducing the cost for teams to build their own runtime environments.

File System, Channels, and Context Management

On top of the file system, the framework provides a channel mechanism and context management strategies. Channels handle message flow between the agent and external systems, while context management addresses the problem of information trade-offs in long tasks. Together they determine the agent's stability in complex environments.

Built-in Capabilities and Selection Advice

AgentScope also provides a set of built-in components (the stardust-like capabilities mentioned in the talk) with examples. For Java teams, three points matter when selecting: whether the team already has Spring AI infrastructure, whether the task requires complex tool orchestration, and whether human confirmation must be introduced. If the latter two hold true, the combination of AgentScope's ReActAgent and HarnessAgent is worth evaluating.

From an ecosystem evolution perspective, competition among agent frameworks will shift from model integration to runtime reliability. AgentScope's investment in HITL and engineering workspaces is precisely a response to this trend.