SuperAPI AI 工具集
合作ENAI 行业资讯收藏
全部工具AI智能体agent-coherence

agent-coherence

agent-coherence 是一个面向多智能体（Multiplayer AI）的协调层，旨在解决多个 AI 智能体共享同一文件、存储键或记忆时发生的“静默覆盖”问题。当两个智能体同时操作同一个产物（如 plan.md、memory.json 或某个存储键）时，若一方基于旧版本写回，就可能悄无声息地抹掉另一方的更新，而且系统不会报错，模型还会误报“任务完成”。该库通过 MESI 风格的归属与失效机制、乐观并发提交（commit-CAS）以及读代际栅栏，把这种静默覆盖变成显式的、可重试的拒绝：过期的写入会被拒绝或返回类型化冲突，绝不会被静默应用。它提供与模型供应商无关、与框架无关的统一协调行为，支持 LangGraph、CrewAI、AutoGen、OpenAI Agents SDK、跨进程的普通文件（CoherentVolume）以及任意 MCP 客户端（stale-write-guard-fs 服务器）。其核心安全不变量已用 TLA+/TLC 进行机器校验，通过约 12 token 的失效信号代替全量重播，为读密集的多智能体场景节省 token。

访问官网

工具介绍

用途

agent-coherence 是面向多智能体协作的协调层（coordination layer），解决的核心问题是“共享状态下的丢失更新”：当多个智能体共享同一个产物（如 plan.md、某个 store key、memory.json）时，一个智能体基于旧版本写回，就会静默覆盖另一个智能体已提交的新版本。这类问题通常不会报错，模型还会叙述成“任务完成”“计划已更新”，导致下游决策建立在错误版本上，并且常被误诊为模型问题。

该库把这种静默覆盖转变为显式的、可重试的类型化拒绝：陈旧写入会被拒绝（denied）或返回可重试冲突，而不会被静默应用。

主要能力

  • MESI 风格的所有权与失效：对共享产物做归属和失效管理，配合乐观提交的 commit-CAS 处理并发写入者。
  • 读代际栅栏（read-generation fence）：用于崩溃后回收的场景，回收某个停滞授权会递增产物的 ownership epoch，使被回收的写入者即使版本未变，在提交时也会被拒绝。
  • 两种写入纪律：悲观方式（获取 EXCLUSIVE 后提交，视图过期则被拒绝并需 reacquire()）与乐观方式（write_cas：读、计算、commit-CAS，竞争失败方获得类型化冲突和有界重试）。
  • 五种同步策略：lazy（默认）、eager、lease（基于 TTL）、access_count、broadcast，按读写比与刷新激进度选择。
  • 读侧一致性：CCSStore 作为 langgraph.store 的替代，对端提交会使用户缓存的视图失效，下次读取会重新获取。它不拒绝陈旧的写回（put 不是版本 CAS），写侧的丢失更新防护需通过 CoherentVolume 或 write_cas 路由。
  • 框架适配：ccs.adapters 提供 LangGraph、CrewAI、AutoGen（各约 100 行）的集成，以及实验性的 OpenAI Agents SDK 适配器。
  • CoherentVolume：数据平面设备（out-of-process coordinator client），为磁盘上的普通文件带来同样的保证，无需框架；通过 SQLite-WAL 与本地协调器交互，协调器仅保存 MESI 状态、内容哈希和版本。
  • MCP 服务器：stale-write-guard-fs 以 stdio 服务器形式，通过十个 swg_* 工具向任意 MCP 客户端暴露同样的保证。
  • 其他组件：effect 顺序门 gate()、多产物快照会话（无撕裂读）、原子多文件发布 atomic_publish、定向授权交接、ccs-diagnose CLI、冲突结果计数器、Claude Code 插件、外部编辑守卫等。
  • 形式化验证：九个 TLA+/TLC 规范在 CI 中运行，每个规范带有一个必须失败的变异体，保证不变量非装饰性。

使用方式

  • 作为库引入：使用 ccs.core（协议）、ccs.coordinator（协调器）、ccs.strategies（同步策略）、ccs.adapters（框架适配）等模块。协议与协调器不依赖框架。
  • store 的 API（store.get()、store.put()、store.search()）可继续使用；CCSStore 增加读侧一致性。
  • 单 import 替换假定 store 命名空间在 namespace[0] 中携带智能体身份（如 (user_id, "memories") 形状会把用户合并到同一共享产物上）。
  • 事件总线：目前提供内存/进程内 InMemoryEventBus；面向网络的多主机传输（Redis、Kafka、NATS、gRPC）在路线图中，按需推进。
  • 可运行演示：python -m examples.coherent_volume.main，离线、无需密钥，先复现文档中的丢失更新，再展示如何预防。
  • 成本复现：python tools/run_cost_sweep.py；预注册指标与结论见 benchmarks/cost_preregistration.md（PASS at n=50，交叉点 r≈0.31），v0.9.3 发布。
  • TLA 检查：make tla-check 运行全部九个规范。

适用场景

  • 多智能体共享同一文件、存储键或记忆（plan.md、store key、memory.json）的协作场景。
  • RAG 语料与智能体记忆：这两个都是共享可变状态，两个智能体读取同一记录 v1，一方写 v2，另一方仍基于 v1 写回就会覆盖 v2。CCSStore 保持读者最新（读侧一致性），写侧防护通过 CoherentVolume 或 write_cas。
  • 跨进程共享普通文件的场景（CoherentVolume）。
  • 任意 MCP 客户端需要过期写入防护的场景（stale-write-guard-fs）。
  • 需要为任何 CoherenceAdapterCore 中介的智能体系统做不变量重放（agent-coherence-replay；LangGraph 采集已在 v1 通过 CCSStore.record_to(path) 验证；CrewAI/AutoGen 已接入同一接缝但未验证）。
  • 需要原子多文件发布、多产物一致快照、效果顺序门、定向授权交接等能力的场景。

限制

  • 保证仅对经过协调器的写入成立，且限定单个协调器、单一主机。
  • 存在一个公开缺口（#248）：在对端 write_cas_at 已提交但字节尚未落盘时，普通 write() 可能丢失；具体条件涉及写入卷不持有该文件的活动视图、仅在窗口内读取过、或运行中的 write_cas / write_cas_at 以 ViewWedged 结束。
  • 跨主机 fencing 在路线图中，按需推进，尚未提供。
  • 绕过协调器的编辑（人类在编辑器中、格式化器、重新生成脚本）由 read()/write() 边界的内容哈希检查捕获；批量 CAS 路径边界较窄。
  • 自动监视未经协调器写入的外部来源变化（手工编辑文件、带外重新索引）属于 source-watcher 场景，在路线图中，按需推进，当前未提供。
  • 它不验证智能体在外部世界的行为（如发出邮件、触发 webhook），那属于 outbox 和幂等层的职责。
  • 单 import 替换有命名空间约定要求。
  • 效果门 gate() 等部分能力经 MCP（swg_gate）和 HTTP（POST /hooks/effect-fence），仅由 Python 协调器提供。
  • 预注册基准的指标 re-fetches-avoided 是代理指标、模式地图，不是 token/美元账单。
  • 部分未验证的能力（如 CrewAI / AutoGen 的重放）已明确标注未验证。

未提供的信息

  • 具体收费方式、价格未在资料中提供。
  • 具体安装命令（pip/uv 等）未在资料中给出完整清单。
  • 兼容的模型供应商列表仅提及 Anthropic、OpenAI、Google、Mistral 及开源模型与提供商无关，未列出完整支持矩阵。
  • 平台限制（操作系统等）未在资料中明确说明。

同类工具

查看分类