Overview

​

Quick Start

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-harness</artifactId>
    <version>${agentscope.version}</version>
</dependency>

public class QuickstartExample {

    public static void main(String[] args) throws Exception {
        // 1. Prepare workspace: generate AGENTS.md on first run, reuse afterwards
        Path workspace = Paths.get(".agentscope/workspace");
        initWorkspaceIfAbsent(workspace);

        // 2. Build model
        Model model = DashScopeChatModel.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .modelName("qwen-max")
                .stream(true)
                .build();

        // 3. Build HarnessAgent: workspace injection, session persistence, and trace logging
        //    are enabled by default; compaction is explicitly configured here
        HarnessAgent agent = HarnessAgent.builder()
                .name("quickstart-agent")
                .sysPrompt("You are a note-taking assistant.")
                .model(model)
                .workspace(workspace)
                .compaction(CompactionConfig.builder()
                        .triggerMessages(30)
                        .keepMessages(10)
                        .flushBeforeCompact(true)   // extract facts to daily log before compacting
                        .build())
                .build();

        // 4. Two conversation turns with the same RuntimeContext
        //    Same sessionId → turn 2 auto-restores state from turn 1
        RuntimeContext ctx = RuntimeContext.builder()
                .sessionId("demo-session")
                .userId("alice")
                .build();

        Msg turn1 = agent.call(
                Msg.builder().role(MsgRole.USER)
                        .textContent("My name is Alice, and I'm preparing a tech talk on ReAct today.")
                        .build(),
                ctx).block();
        System.out.println("[turn1] " + turn1.getTextContent());

        Msg turn2 = agent.call(
                Msg.builder().role(MsgRole.USER)
                        .textContent("What is my name? What am I doing today?")
                        .build(),
                ctx).block();
        System.out.println("[turn2] " + turn2.getTextContent());
    }

    private static void initWorkspaceIfAbsent(Path workspace) throws Exception {
        Files.createDirectories(workspace);
        Path agentsMd = workspace.resolve("AGENTS.md");
        if (Files.exists(agentsMd)) return;
        Files.writeString(agentsMd, """
                # Note-taking Assistant

                You are an assistant that helps users organize notes and knowledge.

                ## Behavior Guidelines
                - Actively record key facts the user mentions (names, plans, preferences, etc.)
                - Reply concisely, using bullet lists when helpful
                - For uncertain information, say so clearly rather than guessing
                """);
    }
}

export DASHSCOPE_API_KEY=your_key_here

# First run: install dependency modules to local repo (skip javadoc and spotless)
mvn -pl agentscope-examples/agents/harness-examples/harness-quickstart -am install \
    -DskipTests -Dspotless.check.skip=true -Dmaven.javadoc.skip=true -q

# Execute main
mvn -pl agentscope-examples/agents/harness-examples/harness-quickstart exec:java \
    -Dexec.mainClass=io.agentscope.harness.example.QuickstartExample \
    -Dspotless.check.skip=true -q

• .agentscope/workspace/AGENTS.md is auto-created — this is the source of the agent’s persona
• Turn 2 “What is my name?” gets the right answer because the second call() with the same sessionId=demo-session auto-restored turn 1’s state via bindRuntimeContext at the start
• After a few more turns that trigger compaction (≥30 messages), you can see LLM-extracted facts in workspace/memory/YYYY-MM-DD.md; the background MemoryMaintenanceScheduler will continue merging these into MEMORY.md
• On the next process restart, as long as sessionId is unchanged, the agent still remembers everything

​

Core Capabilities

• Workspace context injection — answers where does the agent’s identity come from. Before every reasoning turn, WorkspaceContextHook injects AGENTS.md, MEMORY.md, today’s memory, and KNOWLEDGE.md into the system prompt. The workspace is the agent’s “persona and knowledge base”.
• Two-layer persistent memory — answers how do conversation facts persist across sessions. MemoryFlushHook uses an LLM to distill conversation into a daily fact log before compaction; MemoryConsolidator runs in the background to merge and deduplicate daily logs into the long-term MEMORY.md. Still available on next startup.
• Compaction and overflow recovery — answers what to do when history gets too long. CompactionHook summarizes history and keeps a recent tail when message/token thresholds are exceeded; when the model actually reports a context overflow, HarnessAgent catches the error, forces compaction, and retries automatically.
• Large tool result offloading — answers what to do when a single tool call returns too much. ToolResultEvictionHook writes oversized results to the filesystem and keeps only a head+tail preview with a placeholder in context; the agent can re-read on demand.
• Session persistence — answers how to preserve state across processes. SessionPersistenceHook writes agent state to the workspace by sessionId; the next call automatically resumes from where it left off.
• Subagent orchestration — answers how to decompose complex tasks. SubagentsHook injects task / task_output tools; the parent agent can delegate synchronously or in the background. Subagents can be declared via workspace spec files, programmatic specs, or custom factories.
• Pluggable filesystem — answers how to isolate and control the agent’s environment. All file tools go through AbstractFilesystem. Choose from three declarative modes (local+shell, composite+store, sandbox) or abstractFilesystem for self-managed stores. Multi-tenant / session-level isolation is handled via RuntimeContext.userId and IsolationScope.

​

How Capabilities Work Together

• Identity continuity — workspace context injection re-feeds persona and knowledge to the model each turn; two-layer persistent memory distills valuable facts from conversation back into the workspace; skill auto-loading keeps reusable capabilities tied to the workspace. The agent’s persona and knowledge do not disappear when a single call ends — they accumulate in the workspace over time.
• Bounded context — conversation compaction controls depth, tool result offloading controls width, and overflow recovery is the final safety net. Together they ensure that even in arbitrarily long sessions, the context never overwhelms the model — and if it does, recovery is seamless.
• Recoverable state — session persistence ensures a process restart can continue from where it left off; RuntimeContext threads the call’s identity (sessionId/userId) through all hooks and tools; pluggable filesystem makes “where state actually lives” (local disk, sandbox, remote) a configuration choice.

​

How Capabilities Are Injected

• Hook channel: hooks are assembled in priority order and passed to ReActAgent (including SandboxLifecycleHook in sandbox mode, see Architecture)
• Toolkit channel: filesystem, memory_search, memory_get, session_search are appended to the user’s Toolkit; sandbox stores additionally add shell_execute; SubagentsHook itself registers task / task_output
• SkillBox channel: SkillBox is auto-constructed from workspace/skills/ or a custom AgentSkillRepository

Detailed behavior, trigger timing, and sequence diagrams for each component are in Architecture.

​

Related Pages

• Architecture — component definitions, lifecycle sequence diagrams, collaboration relationships
• Workspace — workspace directory structure and context injection
• Memory — two-layer memory, compaction configuration, and full-text search
• Filesystem — three declarative modes and the AbstractFilesystem hierarchy
• Sandbox — isolated execution, sandbox state, and distributed options
• Subagent — subagent specs and orchestration
• Subagent Streaming — stream() mode child-agent event forwarding, EventSource fields, and multi-level nesting
• Tooling — built-in tool reference
• Session — session persistence and state recovery