Harness 架构 Multi‑Agent（多智能体）完整深度解析

核心铁律：Agent 负责业务智能；Harness 负责全局编排、生命周期管控、资源隔离、通信、安全护栏 CSDN博...。 Harness 不是大模型 Prompt 层面的调度，是底层工程外壳，负责多 Agent 整套运行基础设施。

一、核心概念：主 Agent / 子 Agent (Sub‑Agent)

1）主 Agent（Manager / Orchestrator 管理者）

用户直接交互入口
拥有spawn（孵化 / 派生）子 Agent权限
负责任务拆解、分发、汇总子 Agent 结果、冲突决策
独占顶层 Harness 实例

2）子 Agent Worker（专家工作代理）

子 Agent 由 Harness 通过 sessions_spawn 创建独立会话，天然上下文隔离 GitHub： ✅ 独立上下文窗口（Token 预算互不抢占） ✅ 独立 System Prompt、角色身份 ✅ 可单独配置模型（子任务可用廉价模型降本） ✅ 独立工具白名单、权限、最大步数、超时限制 ✅ 子 Agent 默认不能互相直接发消息，只能与主 Agent 通信

⚠️最关键：文件后端 (File‑Backend) 是全局共享资源 所有子 Agent 共用一套沙箱 Workspace、file:/// 文件空间。 👉 文件就是多 Agent 之间最核心的协作白板。

二、多 Agent 在六层 Harness 架构所处位置

plaintext

复制代码

1.交付接入层
2.Bundle插件组装层
3.Agent控制层 ------👉【Multi‑Agent 多Agent调度模块】
4.能力层：文件后端 + Shell沙箱 + 搜索工具
5.事件日志层
6.LLM模型调用层

多 Agent 调度模块与文件后端平级，调度层负责 Agent 生命周期；文件后端负责 Agent 之间数据交换。

三、4 种标准协作拓扑模式（Harness 原生支持）GitHub

模式 1： Supervisor 主管‑串行模式（最常用）

plaintext

复制代码

主Agent(主管)
    ↓
任务1 → 子AgentA → 返回结果
    ↓
任务2 → 子AgentB → 返回结果
    ↓
主Agent合并输出

特点：一步一步执行，可根据上一步结果动态决定下一步派谁干活；适合长链路复杂任务。

模式 2：Dispatcher‑并行扇出 Fan‑Out

plaintext

复制代码

            ┌─>子AgentA
主调度器 ───┼─>子AgentB
            └─>子AgentC
                 ↓
          Merger(合并器/主Agent)汇总

特点：多个子 Agent同时并发执行；子 Agent 之间零交互；适合互不依赖、可并行拆分任务，例如多份资料调研、多维度评审。

模式 3：收件箱消息总线 IPC（对等协作）

每个 Agent 分配独立收件箱目录（沙箱内文件夹），消息本质就是沙箱文件：

plaintext

复制代码

workspace/inbox/agent_a
workspace/inbox/agent_b

Agent 每轮思考循环前，Harness 自动读取收件箱消息。通信原语 3 种（操作系统 IPC 思路）：消息队列 / 共享内存 (文件) / 信号量锁，Harness 做权限校验、熔断、限流。

模式 4：动态委派 Delegation（任务可层层转包）

A Agent → 委派任务给 B Agent → B 还可以继续派给 C Harness 维护委派链，自动检测循环委派环路 (A→B→C→A)，直接拦截报错，防止死循环任务栈溢出GitHub。

四、Harness 多 Agent 五大核心底层能力

1. Agent 生命周期管理器

负责完整状态机： spawn创建 → running运行 → pause暂停 → await等待子任务 → complete完成 → terminate销毁 提供超时熔断：max_steps最大推理步数、max_tool_calls工具调用上限、ttl最长运行时间，硬终止，不由大模型自律CSDN博...。

2. 上下文隔离 + 共享资源分离（最重要设计）

表格

资源类型	隔离 / 共享	说明
LLM 对话上下文	✅隔离	每个 Agent 独立会话，互不污染
memory:// 内存后端	✅会话私有隔离	子 Agent 内存其他 Agent 看不见
file:/// 沙箱文件后端	🔒全局共享	所有 Agent 读写同一个工作目录，协作白板
store:// 持久存储后端	🔒全局共享	长期记忆跨 Agent 可读

这就是 Harness 区别于普通 AutoGen/CrewAI 的标志性设计：内存隔离、文件共享。

3. 文件驱动协作机制（无消息也可协作）

不需要发消息 API，Agent 之间通过读写文件间接通信：

主 Agent 写入任务文件：file:///tasks/task‑research.md
子 Agent 轮询读取，开始干活
子 Agent 产出结果：file:///output/report.md
主 Agent 读取报告，完成汇总 👉 文件 = 异步解耦通道，任务中断重启后协作状态不会丢失，完美支持断点续跑。

4. 差异化权限与能力配置

每个子 Agent 可拥有独立 Harness 护栏配置（YAML 声明式配置，无需修改代码）

yaml

复制代码

agent_id: coder
system_prompt: 代码工程师
max_tool_calls: 100
tools: [python_sandbox,read_file,write_file]
guard: allow

研究员 Agent：开放网页搜索
财务 Agent：禁止执行 Shell 高危命令
支付 Agent：开启 HITL 人工审批关卡

5. 全链路事件审计

Harness 捕获所有 Agent 派生、消息收发、文件读写、工具调用，写入统一事件日志流；可回溯完整多 Agent 协作轨迹。

五、多 Agent 典型完整运行流程示例

用户下发需求：完成竞品分析报告
Harness 唤醒主 Agent
主 Agent 规划：任务拆分为「市场调研 Agent」+「数据分析 Agent」+「文档撰写 Agent」
Harness 调用spawn()孵化 2 个并行子 Agent，分配独立会话上下文
子 Agent 读取共享沙箱 file:///input/requirement.md任务文档
调研 Agent 搜索资料，写入file:///output/research_result.md
数据分析 Agent 读取调研结果文件，产出分析数据
两个子 Agent 完成，退出会话，释放资源
主 Agent 读取两份产出，交给撰写 Agent 生成最终报告
所有子 Agent 销毁；主 Agent 返回成品报告给用户

六、Harness Multi‑Agent 架构代码骨架（TS 极简版）

typescript

运行

复制代码

// 多Agent调度器 Orchestrator
interface AgentSession{
    sessionId:string
    harness:HarnessInstance //每个子Agent自带独立Harness外壳
    status:"running"|"done"|"error"
}
class MultiAgentOrchestrator{
    sessions:Map<string,AgentSession>
    fileBackend:CompositeBackend //全局共享文件后端

    async spawnSubAgent(label:string,taskPrompt:string):Promise<AgentSession>{
        // 创建隔离会话
        const subHarness=new HarnessInstance({
            isolatedContext:true,
            sharedFileBackend:this.fileBackend //注入全局共享文件系统
        })
        const session= await subHarness.run(taskPrompt)
        this.sessions.set(session.sessionId,session)
        return session
    }
}

七、常见坑点

子 Agent 互相直接修改同一个文件 → 并发读写冲突 解决：Harness 加文件锁（信号量），或者给每个 Agent 分配独立产出子文件夹
子 Agent 生成超大结果，传回主 Agent 撑爆上下文 ✅最佳实践：结果写入共享文件，只传回文件路径字符串，而不是返回完整大文本
子 Agent 忘记退出，后台僵尸 Agent 不断消耗 Token 解决：Harness 强制超时、最大步数硬终止，会话完成自动销毁