公众号名称：Fox爱分享

作者名称：Fox爱分享

发布时间：2026-05-29 08:33

大家好，我是Fox，今天我们来聊聊AgentScope-Java。

做 Agent 框架的人都清楚，当系统从「跑一个 Agent 试试」变成「跑一群 Agent 协作」，复杂度是指数级上升的。工具怎么注册、沙箱怎么管理、对话一长模型就爆 token 怎么办、子 Agent 之间怎么通信、状态怎么跨会话恢复……这些问题不会因为你用了某个框架就消失，只会看你把复杂性放在了哪里。

AgentScope-Java 的做法是：把这些全部收进一个独立模块，叫 agentscope-harness。本文就深入这个模块的核心设计，看它到底解决了什么问题，又是怎样解决的。

1. 从 ReActAgent 到 HarnessAgent：不是包装，是升维

HarnessAgent 并不是 ReActAgent 的简单包装。它在构造阶段就完成了所有复杂初始化：文件系统选型、工具注册、Hook 编排、子代理声明解析、技能加载。它的 build() 方法是一个超过 240 行的大型工厂方法，是整个模块最核心的构造枢纽。

简单说，ReActAgent 告诉你「Agent 能做什么」，而 HarnessAgent 告诉你「生产级 Agent 系统需要什么」。

HarnessAgent
├── 包装 ReActAgent（代理转发大部分接口）
├── WorkspaceManager（工作区生命周期管理）
├── CompactionHook（上下文压缩）
├── SandboxManager（沙箱生命周期管理）
└── 8 条 Hook 链（按优先级串联）

2. 三种文件系统模式：隔离策略的精髓

harness 定义了三种正交的文件系统后端，通过 Builder 的 filesystem(spec) 方法注入，三种模式互斥，不可同时启用。

Mode 1 — 复合文件系统（RemoteFilesystemSpec）

本地磁盘 + 共享键值存储的混合视图。这种模式下 Shell 执行不可用，但通过前缀路由实现跨副本内存一致性：

MEMORY.md        → RemoteFilesystem（共享）
memory/         → RemoteFilesystem（共享）
agents/.../sessions/ → RemoteFilesystem（共享）
其他文件        → LocalFilesystem

Mode 2 — 沙箱文件系统（SandboxFilesystemSpec）

最复杂的模式。运行在真实容器中（Docker / Kubernetes / e2b / Daytona），通过快照机制实现跨发行实例的状态恢复。所有 Shell 操作路由到沙箱内执行，主 Agent 和子 Agent 可以按需共享或隔离沙箱状态。

Mode 3 — 本地文件系统（LocalFilesystemSpec）

单进程、单副本部署，直接读写本地目录，Shell 在宿主机执行。

三种模式由 AbstractFilesystem 统一抽象接口，ls/read/write/edit/grep/glob/upload/download/delete/move/exists 全部通过 RuntimeContext 注入 session/user 级别的隔离语义。

3. 沙箱生命周期： acquire → start → stop → shutdown

SandboxManager 负责沙箱的完整生命周期，获取优先级从高到低：

优先级	来源	是否需要 guard
1	用户外部提供的 Sandbox	跳过
2	用户外部提供的 SandboxState	跳过
3	从 stateStore 恢复已持久化状态	需要 scope key
4	全新创建沙箱	—

SandboxLifecycleHook 在 priority=50 插入 Hook 链，在 PreCallEvent 做 acquire + start，在 PostCallEvent / ErrorEvent 做 persistState + release：

PreCall:  acquire → start() → 注入 sandbox 到 SandboxBackedFilesystem
PostCall: persistState → release(stop + shutdown) → 清理 filesystem 引用

一个值得注意的细节：用 AtomicReference 而非 ThreadLocal 保存 acquire 结果，因为 Reactor 可能在不同线程恢复 Hook 阶段。

4. 四级隔离作用域

沙箱状态和远程文件系统的命名空间隔离级别由 IsolationScope 枚举控制：

作用域	语义
`SESSION`	每个 session 独立（默认）
`USER`	同一用户的全部 session 共享
`AGENT`	全部用户和 session 按 agent name 共享
`GLOBAL`	全局共享（慎用）

另外需要区分 stop() 和 shutdown()：stop() 只持久化快照，不销毁资源；shutdown() 才真正销毁容器。只有自管理的沙箱（非用户外部提供）才在 release 阶段调用 shutdown。

5. 对话压缩：宽度与深度的组合拳

context 爆掉不是单一原因导致的——有的是单次工具返回太长（宽度问题），有的是对话历史累积太深（深度问题），还有的是工具参数本身太大（另一个宽度问题）。harness 为此部署了三套相互独立的机制，各自从自己的触发条件出发，互不依赖。

机制 A：参数截断

在非 LLM 调用通道完成，扫描所有 ToolUseBlock 的参数值，对超长字符串做截断（保留前 20 字符 + 占位符）。速度最快，可以配置为比其他机制更早触发。

机制 B：上下文摘要（ConversationCompactor）

完整的对话历史压缩。通过二分查找定位「安全截断点」，保证 ASSISTANT 的 tool_call 从不被与其 TOOL_RESULT 分离。然后执行：

1. 定位截断位置（二分查找 token budget）
2. 过滤掉已有摘要消息，避免重复归档
3. 可选：flushMemories() 写入长期记忆
4. 可选：offloadMessages() 落盘原始对话 JSONL
5. 单次 LLM 调用对前缀做摘要
6. 返回 [summaryUserMsg] + preservedTail

机制 C：工具结果逐出（ToolResultEvictionHook）

每次工具执行完立即检查结果文本长度，超过阈值就写到文件系统，替换为内联占位符引用。这是解决 context 宽度问题的即时机制，与 B 的深度问题互补。

三套机制各自由自己的条件独立触发：A 在 CompactionHook 的 PreReasoningEvent 之前运行；B 在 CompactionHook 内部运行；C 监听 PostActingEvent，优先级=50。任何时候只有一个被触发，不代表递进关系。

6. 子 Agent 编排：精细的任务分发

SubagentsHook 负责管理子 Agent 的生命周期和任务分发，核心工具：

工具	用途
`agent_spawn`	派生隔离子 Agent
`agent_send`	向已存在的子 Agent 发消息
`agent_list`	列出活跃子 Agent
`task_output`	获取异步任务结果
`task_cancel`	取消后台任务
`task_list`	列出所有后台任务

每个 PreReasoningEvent 会注入当前会话中最多 10 个异步任务的状态摘要，确保模型在任何时刻（包括压缩后）都能拿到最新的任务 ID 和状态。这里有个关键设计：历史状态会过期，所以必须每次重新从持久化存储读取，不能依赖对话上下文。

子 Agent 的工作区隔离级别由 WorkspaceMode 控制：SHARED 复用主 Agent 的文件系统后端；ISOLATED 在 agents//workspace/ 下创建独立目录。

7. Hook 优先级架构：一套精心设计的执行序列

Hook 在同一个事件上可以挂很多个，执行顺序靠 priority 数字决定——越小越先执行。harness 为每个 Hook 分配了严格的固定优先级：

priority=0    AgentTraceHook             ← 最早：捕获所有事件日志
priority=5    MemoryFlushHook            ← PostCall 后写长期记忆 + 落盘对话 JSONL
priority=6    MemoryMaintenanceHook      ← 定期压缩 / 老化 / 清理会话文件
priority=10   CompactionHook             ← PreReasoning 前：触发上下文压缩
priority=50   SandboxLifecycleHook      ← PreCall 前：acquire sandbox session
priority=50   ToolResultEvictionHook     ← PostActing 后：逐出过大的工具结果
priority=80   SubagentsHook             ← 注册子 Agent 工具 + 注入提示词
priority=900  WorkspaceContextHook      ← 注入 AGENTS.md / KNOWLEDGE.md
priority=900  SessionPersistenceHook    ← 最晚：将会话状态写入持久化层

每个 Hook 只做一件专注的事，组合起来构成完整的 Agent 运行时基础设施。

8. 架构哲学：把复杂性封装进可配置模块

读到这里，你会发现 harness 模块的设计始终贯彻一个原则：将生产级 Agent 系统所需的全部复杂性封装为可配置的模块，向上暴露简洁的 Builder API。

当你写：

HarnessAgent agent = HarnessAgent.builder()
    .name("my-agent")
    .model("openai:gpt-4o")
    .workspace("/path/to/workspace")
    .filesystem(new DockerSandboxSpec())
    .compaction(CompactionConfig.builder()
        .triggerTokens(6000)
        .keepTokens(4000)
        .build())
    .build();

背后自动完成的事：沙箱容器创建、会话状态 Redis 持久化、工作区内 AGENTS.md 注入、子 Agent 工具注册、异步任务追踪、工具结果逐出、上下文压缩触发……全部在数行配置后由框架搞定。

运行时的实际日志长这样

以下是 harness 各组件实际工作时的日志片段（INFO 级别，部分截断）：

# 沙箱获取
[sandbox-hook] Priority 4: creating new sandbox
[sandbox-hook] Acquired sandbox sess-abc-123

# Agent 推理 trace
[my-agent] PRE_REASONING  | model=gpt-4o, messages=12
[my-agent] POST_REASONING | tool_call: id=call_xyz, name=read_file
[my-agent] POST_ACTING   | id=call_xyz, name=read_file, result_len=4821

# 工具结果逐出（单次工具结果太长，触发 eviction）
[my-agent] Tool result evicted: call_xyz → /eviction/my-agent/call_xyz.txt
[my-agent] POST_ACTING   | id=call_xyz, name=read_file, result_len=284

# 上下文压缩触发
Compaction triggered: total=47 msgs / 8921 tokens, cutoff=31, keeping=16 msgs
Memory flush before compaction done
Compaction complete: 47 msgs → 1 summary + 16 tail = 17 total

# 子 Agent 派生
[my-agent] POST_ACTING | tool_call: id=call_sub1, name=agent_spawn
Spawned subagent general-purpose (agent_key=agent:sess-def-456:general-purpose)

# 异步任务状态注入（每次 PreReasoning 前自动追加）
### Async tasks (current session)
- task_id: task-789  agent: general-purpose  status: running  started: 14:23Z
- task_id: task-790  agent: code-reviewer    status: pending  started: 14:24Z

# 会话状态持久化
Auto-saved session state for agent 'my-agent'

这些日志散落在各个组件里，正常运行时不会引起注意，但当你在调试台翻日志、或者线上出了问题需要复盘时，它们就是最好的线索来源。

AgentScope-Java 的 harness 模块，本质上是一套经过生产验证的 Agent 运行时架构。它的价值不在于让你少写代码，而在于让你不用自己处理那些，稍有不慎就会让整个系统崩溃的细节。

如果你觉得这篇有收获，我最近在陆续更新 AgentScope 系统指南，目前已完成 18 节，从基础概念到 harness 深度解析都有覆盖。

关注公众号 Fox爱分享，回复 agentscope 即可领取全套课程。

cover_image

Original Fox爱分享 Fox爱分享

内容效果不满意？点此反馈