AgentScope Java Documentation

Agent middleware allows you to inject custom logic (logging, tracing, input rewriting, etc.) at key lifecycle points without modifying agent or model code. There are two types of hooks:

• Onion hooks (onAgent, onReasoning, onActing, onModelCall): These wrap the next handler. You can execute logic before or after next.apply(input) and observe the intermediate event stream.
• Transformer hooks (onSystemPrompt): These form a pipeline where the output of one middleware is the input to the next. There is no "inner layer."

Hook Positions

Execution Order

• Onion hooks: The first middleware in the list is the outermost. For [mw1, mw2], the order is: mw1 pre → mw2 pre → inner → mw2 post → mw1 post.
• Transformer hooks: Processed left-to-right. For [mw1, mw2], the order is: originalPrompt → mw1.onSystemPrompt() → mw2.onSystemPrompt() → final.

The AgentScope Training Extension enables online training for Agents by creating a closed loop between production interaction data and model optimization. It allows developers to leverage real user interaction data and production toolchains (APIs, databases, etc.) to continuously improve Agent performance through methods like Supervised Fine-Tuning (SFT), knowledge distillation, and Reinforcement Learning (e.g., PPO).

Key Characteristics

• Reuse Production Toolchains: Agents use real tools instead of mocks, reducing the 'Reality Gap'.
• Incremental Learning: Supports fast cold starts using small amounts of real interaction data.

Safety and Modeling Constraints

• Tool Safety: By default, the system supports read-only tools. Write operations (e.g., 'place order') require sandboxing, idempotency, or manual review to prevent repeated execution during training replays.
• Multi-Turn Scenarios: Developers must explicitly model state management or trajectory sampling for complex, multi-turn dialogues.

The workspace is a directory-based foundation for a HarnessAgent. It stores persona, long-term memory, domain knowledge, subagent declarations, and session history as a directory structure of Markdown files. This allows agent state to be managed as files rather than being hardcoded.

Directory Layout

workspace/                           ← default: .agentscope/workspace
├── AGENTS.md                        ← persona / behavior guidelines (injected each turn)
├── MEMORY.md                        ← curated long-term memory (injected each turn, token-budgeted)
├── knowledge/
│   ├── KNOWLEDGE.md                 ← domain knowledge entry point
│   └── *                            ← other reference files
├── memory/
│   ├── YYYY-MM-DD.md                ← daily fact log
│   └── .consolidation_state         ← MemoryConsolidator internal state
├── skills/<skill-name>/SKILL.md     ← custom skills
├── subagents/<id>.md                ← subagent declarations
└── agents/<agentId>/
    ├── workspace/                   ← runtime root for isolated subagents
    └── sessions/
        ├── sessions.json            ← session index (id / summary / updatedAt)
        ├── <sessionId>.jsonl        ← LLM-visible compacted context
        └── <sessionId>.log.jsonl    ← full conversation log (append-only)

HarnessAgent is a wrapper around ReActAgent designed for long-running, complex tasks. Unlike a standard ReActAgent which follows a simple "one request → reason → tool → reply" loop, HarnessAgent adds engineering capabilities like workspace-driven personas, long-term memory, subagent orchestration, and sandbox isolation.

Key architectural principles:

1. Capabilities layer onto the reasoning loop: Capabilities (like Plan Mode or Workspace injection) hook into the ReAct loop without modifying the core algorithm.
2. Shared objects: Capabilities cooperate via three shared objects:
   • RuntimeContext: Contains sessionId, userId, and arbitrary extras (not persisted).
   • The workspace: The location for file reads/writes (local disk, sandbox, or KV store).
   • AgentStateStore: Manages how runtime state is restored across calls.
3. Middleware execution order: Built-in Harness middleware runs in a fixed order, but any custom middleware added via .middleware(...) runs before the built-ins.