How Harness Engineering Turns an Agent from Running to Staying Stable

HarnessAgent = ReActAgent + engineering hooks

HarnessAgent adds engineering capabilities by attaching hook implementations around the ReActAgent reasoning loop without modifying the loop itself. The architecture consists of four independent components: Model Fault‑Tolerance, Context Engineering, Middleware, and Workspace/Sandbox.

Middleware – onion‑style hooks for the reasoning loop

MiddlewareBase defines five hook methods that wrap each stage of the ReActAgent execution: onAgent – whole call onReasoning – reasoning step onActing – action/tool step onModelCall – model invocation onSystemPrompt – system‑prompt changes

Implementations can add logging, tracing, permission checks, context injection, or business policies while leaving the core engine untouched.

public class MonitoringMiddleware implements MiddlewareBase {
    @Override
    public Flux<AgentEvent> onAgent(Agent agent, RuntimeContext ctx,
            AgentInput input, Function<AgentInput, Flux<AgentEvent>> next) {
        System.out.println("[enter] agent=" + agent.getName() + ", msgs=" + input.msgs().size());
        return next.apply(input)
            .doOnComplete(() -> System.out.println("[complete] agent execution finished"));
    }

    @Override
    public Flux<AgentEvent> onActing(Agent agent, RuntimeContext ctx,
            ActingInput input, Function<ActingInput, Flux<AgentEvent>> next) {
        String tools = input.toolCalls().stream()
            .map(ToolUseBlock::getName).collect(Collectors.joining(", "));
        System.out.println("[tool call] " + tools);
        return next.apply(input);
    }
}

Mount the middleware with a single builder call:

ReActAgent agent = ReActAgent.builder()
        .name("HookAgent")
        .model("dashscope:qwen-plus")
        .toolkit(toolkit)
        .middleware(new MonitoringMiddleware()) // mount middleware
        .build();

Workspace and sandbox – decoupling "what" from "where"

Persona, skills, and long‑term memory are stored as files in a workspace (e.g., AGENTS.md, skills/, MEMORY.md). The execution environment can be the host filesystem or an isolated Docker container, selected with one configuration line.

HarnessAgent agent = HarnessAgent.builder()
        .name("sandbox-agent")
        .model("dashscope:qwen-plus")
        .workspace(workspace) // persona / skills / memory
        .filesystem(new DockerFilesystemSpec()
            .image("ubuntu:24.04")
            .isolationScope(IsolationScope.USER)) // per‑user isolated sandbox
        .build();

Omitting filesystem runs files and commands on the host.

Providing DockerFilesystemSpec runs everything inside a container; the host is untouched. IsolationScope.USER gives each user an independent sandbox that can be reused across calls or restored from a snapshot, while different users cannot see each other's files.

For distributed deployments, a DistributedStore such as Redis can share sandbox state, providing a security wall for untrusted code execution.

Context engineering – preventing context overflow

Long conversations can exceed the model window due to (1) excessive dialogue length and (2) oversized tool results. HarnessAgent mitigates both with two mechanisms:

Conversation compression – CompactionConfig automatically compresses old messages once a threshold is reached, keeping only recent context.

Tool result eviction – ToolResultEviction offloads large tool outputs to disk, leaving a placeholder in the context and retrieving the data on demand.

HarnessAgent agent = HarnessAgent.builder()
        .compaction(CompactionConfig.builder()
            .triggerMessages(30)
            .keepMessages(10)
            .build()) // compress old dialogue
        .toolResultEviction(/* large result off‑load + placeholder */)
        .build();

Combined, these keep the context bounded, avoiding token waste and model‑window overflow.

Model fault‑tolerance – keeping the system running when the model fails

Production model APIs may timeout, be rate‑limited, or behave erratically. HarnessAgent provides fault‑tolerance through:

Timeout and retry – modelExecutionConfig sets a per‑call timeout and a maximum number of retry attempts.

Fallback model – automatically switches to a secondary model if the primary is unavailable.

Unified abstraction – a single Credential + ChatModel pair covers providers such as Qwen, OpenAI, Anthropic, Gemini, DeepSeek, and Ollama.

ReActAgent agent = ReActAgent.builder()
        .modelExecutionConfig(ExecutionConfig.builder()
            .timeout(Duration.ofMinutes(2)) // per‑call timeout
            .maxAttempts(3) // retry up to 3 times
            .build())
        .build();

Key concepts

HarnessAgent : ReActAgent with engineering hooks (no loop modification).

Middleware : onion‑style hooks onAgent / onReasoning / onActing / onModelCall / onSystemPrompt for logging, tracing, permission checks, context injection, etc.

Workspace : files store persona, skills, and memory; execution location is decoupled.

Sandbox filesystem : DockerFilesystemSpec provides container isolation; IsolationScope controls granularity.

Context engineering : CompactionConfig compresses old dialogue; ToolResultEviction offloads large tool results.

Model fault‑tolerance : modelExecutionConfig adds timeout, retries, and automatic fallback model.

Related links

AgentScope Java documentation: https://java.agentscope.io/v2/zh/intro.html
Harness architecture: https://java.agentscope.io/v2/zh/docs/harness/architecture.html
GitHub repository: https://github.com/agentscope-ai/agentscope-java