实现 MediX Agent Swarm，先抓住这条主线

做 Agent 项目时，最容易掉进去的坑，就是一上来先盯每个 Agent 的 prompt、工具和分工。

这样当然也能做，但很容易越做越碎。因为看到的是一堆局部能力，却不知道整套系统到底要怎么把一个问题接住、拆开、做完、再把结果存回去。

实现 MediX Agent Swarm 时，更自然的切法不是先盯某个 Agent，而是先把整条主线拉出来。仓库地址放这里：yongfufuufu-ops/medix-agent-swarm。

先把主流程顺一遍

把它压成一句话，大概就是：

用户问题先进 SwarmCoordinator，系统先做记忆检索，再交给 LeadAgent 判断该单 Agent 处理还是走 Swarm，多 Agent 执行完以后再统一汇总，最后把这次会话写回记忆。

这条主线里最重要的几个点是：

• SwarmCoordinator 不是干活的人，它更像入口和调度者
• 记忆检索发生在真正处理问题之前，而不是回答完以后才补记
• LeadAgent 决定要不要拆任务、怎么拆、分给谁
• 单任务就走普通 AgentLoop
• 多任务就走 SharedContext + 多 Agent 并行
• 最终回答出来以后，还会保存短期和长期记忆

所以这套系统本质上不像“一个超级 Agent”，而更像“一个会诊系统”。

真正把系统托住的，不是业务 Agent，而是 Harness

MediX Agent Swarm 里有个很值得记住的词叫 Harness。

它不是医疗能力本身，也不是某个业务 Agent 的 prompt。它更像一组护栏，确保 Agent 在可控范围内工作。

一句话记就够了：

Context 喂信息，Constraints 设边界，Feedback 做纠错，Entropy 控体积。

很多 Agent 项目真正难的地方，不是“会不会调模型”，而是有没有这些护栏。没有护栏，系统刚开始可能很灵，跑久了就会越来越飘。

记忆这块，关键在“读取时压缩”

MediX Agent Swarm 的记忆分两层：

• 短期记忆保存当前会话里的历史、工具结果和最终回答
• 长期记忆保存的是会话总结，而不是整段原始对话

短期记忆的用途，是让当前会话还能接得上。长期记忆的用途，是下一次用户再来时，系统能先去搜相似历史，把曾经发生过的东西捞回来。

这里有个很关键的设计点：压缩不是写入时覆盖，而是读取时压缩。

也就是说，流程更像这样：

1. ShortTermMemory.get_history() 先取原始历史
2. MemoryEntropyManager.auto_clean() 先去重
3. 超过阈值后，再把更早的部分压成摘要
4. 摘要只进入当前 prompt，不会回写覆盖原始记录

这个设计很实用，因为它同时满足了两件事：

• 给 LLM 的上下文变短了
• 原始消息还保留着，没有被不可逆改写

很多系统一说“压缩记忆”，大家会以为数据库里的老消息被直接重写了。这里不是。它更像“给模型看的临时瘦身版”。

约束和反馈，才是它真正的安全带

MediX Agent Swarm 里的约束主要落在：

• constraints/agent_constraints.yaml
• constraints/swarm_constraints.yaml
• constraints/validator.py

它们约束的不是一个点，而是整条执行链：

• 工具能不能调
• 输出是不是越界
• 医疗免责声明有没有带上
• 任务拆分是不是合理
• 某些问题是不是必须交给特定 Agent

更重要的是，约束不是“写在那里看着安心”，而是会在运行时真的检查。

在 AgentLoop 里，工具调用前会校验，最终输出前也会校验，必要时还能自动修复。再往外一层，还有 examples/test_all.py 这种回归测试，帮你确认记忆、约束和 Swarm 协作到底有没有按设计串起来。

这部分很像工程系统里的双保险：

• 运行时护栏负责当场拦
• 测试反馈负责事后验证整个链路有没有坏

它叫 Swarm，但核心其实不是“去中心化”

很多人看到 swarm 这个词，会先想到 Agent 之间彼此讨论、动态抢任务、持续协商。

MediX Agent Swarm 不是这个路子。

它更像：

• 中心化拆分
• 并行执行
• 集中汇总

具体来说就是：

1. SwarmCoordinator.process() 先做记忆检索
2. LeadAgent 用 LLM 把问题拆成带 assigned_agent 的子任务
3. 如果子任务只有一个，就直接走单 Agent
4. 如果子任务足够多且开启 enable_swarm，就创建 SharedContext
5. 每个 worker 只拿自己的子任务去做
6. 完成结果写回 SharedContext
7. 最后再由 LeadAgent 汇总成最终回答

所以它更准确的理解方式，不是“完全自治的 Agent 群体”，而是“多 Agent 并行会诊框架”。

这个区别很重要，因为它决定了实现时该把注意力放在哪里：

• 不要先找 Agent 之间怎么互相辩论
• 先找任务是谁拆的
• 再找任务是怎么分配出去的
• 最后看结果是怎么被汇总回来的

如果顺着实现往下拆，顺序可以这样走

更自然的顺序是先抓主线，再补局部：

1. main.py
2. swarm/swarm_coordinator.py
3. swarm/lead_agent.py
4. swarm/shared_context.py
5. core/agent_loop.py
6. agents/base_agent.py
7. memory/short_term.py
8. memory/long_term.py
9. memory/entropy_manager.py
10. constraints/validator.py

这个顺序的好处是，你先看见“系统怎么跑”，再回头看“某个 Agent 会什么”，不会一开始就淹死在细节里。

如果你想进一步练手，也可以直接跑两种问题：

• 先问一个简单问题，看它走单 Agent 路径
• 再问一个复杂问题，看它怎么进 LeadAgent 拆分，再走 Swarm 汇总

对照日志去追，会特别清楚：

• 记忆从哪来
• 任务怎么拆
• 工具怎么调
• 结果怎么汇总
• 会话最后怎么存回长期记忆

最后记住一个判断

做这类项目时，最好一直区分两件事：

• 设计目标想实现什么
• 当前仓库实际上已经跑通了什么

MediX Agent Swarm 这套实现最值钱的地方，就在于它把这条主线提前拉直了。这样就不用一开始掉进每个子目录，而是先知道系统到底靠什么串起来。

如果只留一句总结，可以写成：

MediX Agent Swarm 真正的核心，不是 Agent 多不多，而是它有没有把“入口调度、记忆检索、任务拆分、并行执行、结果汇总、会话沉淀”连成一条闭环。