Managed Agents 与同类开源产品对比：LangGraph、E2B、SWE-agent、OpenHands 各守一层

回路 / The Loop — 提出有价值的问题，比直接获取答案更重要。

这个专题收集和整理我与 Gemini、ChatGPT、Claude 等 AI 的对话记录。每一篇对应一次完整的提问与回答过程。通过留存这些层层追问，还原日常思考的真实轨迹。

概要

the-loop 003 从企业管理者视角拆解了 Managed Agents 的三层架构（Harness 调度 / Session 持久化 / Sandbox 沙箱）以及 SLM 工具剪枝与 Prompt Cache 之间的工程博弈。这一期换一个角度：把 Managed Agents 与开源世界同类产品逐层对照，看每一层都被谁守住了。

• Checkpoint 究竟归哪一层？ —— 存储归 Session、使用归 Harness 的”存储与使用分离”设计
• getEvents() / emitEvent() 到底是什么？ —— 工程博客里出现的内部接口，不是开发者能直接调用的 SDK
• “向量数据库语义召回 + 切片回填”是 Anthropic 原生功能吗？ —— 一场关于”基础设施 vs 上层扩展”边界的较真
• 开发者真正能看到 / 调用什么？ —— Agent / Environment / Session 三个对象，Harness 内部完全黑盒
• 三层架构在开源世界对应什么？ —— LangGraph Checkpointer 守 Session 层、E2B microVM 守 Sandbox 层、SWE-agent / OpenHands 守 Harness 控制循环
• Mastra / Vercel AI SDK / OpenHands 不是替代关系 —— 而是同一个堆栈里的不同层

核心结论：

1. Anthropic 工程博客里的 emitEvent / getEvents 是内部接口设计哲学；SDK 实际暴露给开发者的是更高层的 sessions.events.send 与 sessions.events.stream，开发者不能直接调用底层接口。
2. Session 是纯 Append-only 线性日志，没有内置向量检索——“语义召回 + 切片回填”是开发者基于 Anthropic 留下的扩展点（“any fetched events can also be transformed in the harness”）自行外挂的生态方案。
3. 三层都有成熟的开源对照：LangGraph 的 BaseCheckpointSaver + thread_id / checkpoint_id 已支持 time travel 与 fork；E2B 用 Firecracker microVM 做沙箱；SWE-agent 的 ACI 限制 LLM 看到的上下文宽度；唯独”Anthropic 内部 Harness 编排策略”无开源对照——这是托管基础设施真正的护城河。

Q: 在 Managed Agents 的三层架构里，Checkpoint 到底归哪一层？

存储归 Session 层，使用（恢复 / 回放 / 分叉）归 Harness 层——这是一个”存储与使用分离”的设计，与整个架构”脑（Harness）/手（Sandbox）/账本（Session）“解耦的哲学一脉相承。

Anthropic 工程博客的原话：

“We separated the concerns of recoverable context storage in the session and arbitrary context management in the harness because we can’t predict what specific context engineering will be required in future models.”

翻译过来就是：Session 只保证持久性和可查询性，Harness 负责所有”怎么用”的逻辑。 因为未来模型的上下文工程策略不可预测，把”管理”逻辑放在 Harness 层，模型升级时只需替换 Harness 实现，Session 和 Sandbox 接口完全不动。

具体到 Checkpoint：

• 存储层（Session）：Checkpoint 是 Session 中的一种事件类型，与 user_input、model_response、tool_call、tool_result、file_change 等并列，通过 emitEvent(id, event) 追加写入只追加的事件日志。
• 使用层（Harness）：通过 getEvents() 接口按需取回事件流的切片，决定”从哪个 checkpoint 恢复”、“如何拼装上下文”、“哪些事件需要传给 Claude”。
• 环境层（Sandbox）：Sandbox 自身也支持容器级 checkpoint，但针对的是文件系统状态和代码执行环境，与 Session 层的”Agent 执行逻辑事件账本”是两个粒度。

一句话：Session 是账本（存什么），Harness 是会计（怎么用）。Checkpoint 和分叉的能力横跨两层——数据在 Session 里，控制逻辑在 Harness 里。

Q: 一次”分叉（Fork）“具体在三层之间是怎么联动的？

因为 Session 是 Append-only（只允许追加，不修改不删除） 的，所以”时光倒流”或”分叉”并不是把旧记录删掉重写，而是重新拼装上下文。当 Harness 决定回滚到 Checkpoint A 时：

1. 控制面决策（Harness 层）

Harness 发现当前模型陷入死循环或偏离目标，决定回滚。它通过 getEvents() 取回从任务开始到 Checkpoint A 的事件切片，重新拼装一份”干净”的上下文 Prompt 发给 Claude。Checkpoint A 之后的失败尝试没有被删除，只是从这次给模型看的上下文里被略过。

2. 数据源支持（Session 层）

Session 作为冷存储，默默执行 Harness 的查询请求，把历史数据吐出来。原本在 Checkpoint A 之后的失败分支依然完整保存在账本里，未来 Harness 如果需要 debug，可以跳回那些失败分支重新审视。这是 Append-only 设计的好处之一。

3. 环境重置（Sandbox 层）

光有”记忆回滚”不够。如果 Agent 之前在容器里删除了一个文件，光改 Prompt 没法让文件复原。Harness 还要通知 Sandbox：把文件系统和运行状态也恢复到 Checkpoint A 对应的快照。Sandbox 利用底层的容器/microVM 快照技术，丢弃当前实例并瞬间恢复磁盘和内存状态。

类比理解：Session 是”导演剧本的完整历史录像”（什么都没剪掉），Harness 是”导演”（决定从哪一幕重拍），Sandbox 是”片场”（剧组真的得把道具摆回那个状态）。

Q: getEvents() 这个接口到底有什么能力？开发者真的能直接调用它吗？

Anthropic 工程博客对 getEvents() 的原话定义是纯粹的位置切片（positional slices）：

“The interface, getEvents(), allows the brain to interrogate context by selecting positional slices of the event stream. The interface can be used flexibly, allowing the brain to pick up from wherever it last stopped reading, rewinding a few events before a specific moment to see the lead up, or rereading context before a specific action.”

这段话直接对应三种使用模式：

• 从断点恢复（pick up from wherever it last stopped reading） —— Harness 崩溃重启后，新进程读取最新位置继续
• 回放（rewinding a few events before a specific moment） —— 看一个动作发生前的来龙去脉
• 重读上下文（rereading context before a specific action） —— 决策前再确认一次相关历史

重要的边界澄清：开发者看不到 getEvents() 这个函数

getEvents() 是 Anthropic 工程博客里描述内部架构哲学时使用的术语，不是 SDK 暴露给开发者的函数名。

官方 Quickstart 文档里，开发者实际调用的是更高层的 SDK：

# 开发者通过 SDK 创建 session、发送事件、订阅事件流
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="Quickstart session",
)

with client.beta.sessions.events.stream(session.id) as stream:
    client.beta.sessions.events.send(
        session.id,
        events=[{
            "type": "user.message",
            "content": [{"type": "text", "text": "..."}],
        }],
    )
    for event in stream:
        # 处理 agent.message / agent.tool_use / session.status_idle 等事件
        ...

也就是说：开发者能 send 事件、能订阅事件流、能查询会话状态，但无法用任意的 (start, end) 索引去切片读取一段历史。 这种切片能力是 Anthropic 内部 Harness 在用，不直接对外开放。

可见性的分界线：博客谈”我们内部是怎么设计的”（哲学），SDK 给”你能拿来用的”（界面）。两者描述的是同一套东西的不同层。

Q: 那 emitEvent() 又是什么？

emitEvent() 是写入 Session 账本的”那支笔”——Anthropic 内部 Harness 在每发生一件事时，调用它把事件追加到只追加日志里。同样，它也是内部接口，开发者不直接调。工程博客对它的原话定义：

“The harness writes to the session with emitEvent(id, event) in order to keep a durable record of events.”

每条被 emitEvent 写入的记录都会获得一个递增的位置索引（Positional Index）——0、1、2、3……这个索引就是后来 getEvents() 切片的参数基础。事件类型涵盖：

• 高信号交互事件：user.message、agent.message、agent.tool_use、session.status_idle
• 工具与环境执行事件：tool_call、tool_result、file_change、error、retry
• 决策标记事件：checkpoint、approval

开发者一侧的等价 API 是 client.beta.sessions.events.send(...)——你提交一个 user.message 这种类型的事件，Anthropic 后端的 Harness 实际去调用 emitEvent 把它写入 Session 账本。

Q: AI 给我描述了一套”向量数据库语义召回 + getEvents 切片回填上下文因果链”的方案，这是 Anthropic 原生功能，还是 AI 自己拼凑的？

这是这一期最值得记住的一次”打破幻觉”——AI 在解释技术架构时，最容易把”官方原生基础设施”和”业界基于该架构的扩展方案”混在一起讲，听起来都很合理，但真要落地时会踩坑。

官方原生：Session 是纯线性 Append-only 日志

Anthropic 工程博客对 Session 层的接口定义只有三个：

• getSession(id) —— 取回 session 元数据
• getEvents() —— 按位置切片读取事件流
• emitEvent(id, event) —— 追加写入事件

官方原生的 Session 是纯粹的、线性的 Append-only 日志，自身不内置向量检索功能。 光靠 Anthropic 原生 API，无法直接通过一句自然语言去模糊搜索历史事件。

生态扩展：向量召回是开发者基于”扩展点”自己接的

那”向量数据库 + 语义召回 + getEvents 切片回填上下文”这套描述从哪里来？这是开发者基于 Anthropic 留出的两个钩子设计的扩展方案：

1. emitEvent 触发时同步把事件向量化并存到外挂向量数据库；
2. Anthropic 博客原话——“any fetched events can also be transformed in the harness before being passed to Claude’s context window” ——明确允许 Harness 在喂给模型之前对事件做自定义变换。

业界（包括 Milvus、Pinecone 等向量数据库厂商及其用户）普遍观察到：纯线性日志在任务步骤超过几百步时会出现检索效率瓶颈——顺序读取和语义搜索是完全不同的工作负载，getEvents() 只服务前者。要在长跨度任务里做相关历史的快速召回，开发者必须自己外挂向量库。

类比一句：向量数据库是”书后的索引关键词表”，能查到你想看的内容在第 125 页；getEvents() 是”翻开书把第 120 到第 130 页整章拿出来”。两者都不是 Anthropic 内置的，是开发者把它们组合到 Anthropic 留出的接口上。

教训：警惕 AI 把”基础设施”和”上层扩展”混着说

这是 AI 在做技术解答时反复出现的失真模式——它会把官方文档明确写的东西，和”业界基于这套设计衍生的标准做法”混在同一段叙述里，且都说得很笃定。 要破解只能靠两步：

1. 直接抓官方原文（这里是工程博客 + Quickstart）
2. 把那些”听起来很合理但官方没说”的部分当作”业界扩展模式”另立分支，不要写进基础事实层

Q: 那 Anthropic 真正开放给开发者的核心能力到底有哪些？

Quickstart 里把整个框架抽象为三个核心对象，对应三个核心 SDK 端点：

会话运行起来后，开发者通过事件流接口与 Agent 互动：

• client.beta.sessions.events.send() —— 向 Session 推入用户消息或控制信号
• client.beta.sessions.events.stream() —— 订阅 Agent 实时输出（agent.message、agent.tool_use、session.status_idle 等事件）

所有 Managed Agents API 请求都需要 managed-agents-2026-04-01 这个 beta header，SDK 会自动带上。

哪些是黑盒？

这些能力是完全不可见的：

• emitEvent 与 getEvents 的底层实现——你无法直接对 Session 数据库执行任意切片读
• Harness 编排策略——模型陷入循环时具体重试几次、退避算法（backoff）、循环判断逻辑都封装在云端
• Sandbox 销毁与恢复瞬间——除非用自托管沙箱，否则容器崩溃后如何瞬间用快照拉起新实例对开发者透明且不可控

Managed Agents 的核心定位是”免运维的 Agent 生产级基础设施”——它把工程团队最痛的”沙箱安全隔离 / 长周期死循环控制 / 任务记忆持久化”封装成云服务，但同时也意味着 Harness 这一层的代码看不到、改不了。

Q: 三层架构里，每一层对应的开源同类产品是什么？

每一层都有成熟开源方案，且都能在 GitHub 上读源码。

Session 层（账本）→ LangGraph Checkpointer

LangGraph 持久化文档定义了一套通过 BaseCheckpointSaver 接口实现的检查点机制——文档原话：“a snapshot of the graph state is saved at every step of execution, organized into threads”，每一步执行后都会原子化保存图状态，按 thread 组织。

关键概念：

• Thread ID —— 每条 checkpoint 序列的唯一标识（“a unique ID or thread identifier assigned to each checkpoint saved by a checkpointer”）
• Checkpoint ID —— 一个 thread 内部某个具体快照的标识
• Time Travel —— “Checkpointers allow for time travel, allowing users to replay prior graph executions to review and / or debug specific graph steps”
• Fork —— “fork the graph state at arbitrary checkpoints to explore alternative trajectories”，通过 update_state 在任意 checkpoint 派生新分支

具体实现可选 InMemorySaver（开发期）、SqliteSaver（本地）或 PostgresSaver（生产）。这套机制完美对应 Anthropic 的”Session + Harness 时光倒流”语义——只是数据落在你自己的 Postgres 里，而不是 Anthropic 的云端账本里。

Sandbox 层（手）→ E2B（Firecracker microVM）

E2B 自我定义为 “Open-source, secure environment with real-world tools for enterprise-grade agents”，底层用 AWS 开源的 Firecracker microVM：

“Each sandbox is powered by Firecracker, a microVM made to run untrusted workflows.”

它能在毫秒级为 Agent 拉起一个完全隔离、具备完整网络与文件系统的 Ubuntu 环境。Agent 在里面执行 Bash、Python、改文件、跑测试都不会污染宿主机。E2B 同时提供 Node.js 与 Python SDK，并已被多个主流 Agent 框架（LangChain、LlamaIndex、Vercel AI SDK）原生集成。

Harness 层（控制循环）→ SWE-agent ACI / OpenHands SDK

SWE-agent（最初由普林斯顿 NLP 组发起，Yang et al., 2024, arXiv:2405.15793，一作 John Yang，普林斯顿博士生）的核心贡献是 Agent-Computer Interface (ACI) 概念：把 LLM 视为一类”独特的终端用户”，给它专门设计的接口而不是裸露的 Linux 终端。

ACI 的具体设计（详见官方文档）：

• 滚动文件查看器 —— 不是 cat 整个文件，而是每次显示约 100 行，支持上下滚动和文件内搜索
• 编辑前的语法 linter —— 编辑命令发出时先跑 linter，语法不通过不允许写入
• 目录搜索工具 —— 简洁列出匹配文件名，避免 grep 输出爆炸把模型上下文撑爆
• 空输出反馈 —— 命令无输出时返回明确提示信息，避免模型把空响应误解为某种隐含成功

全套整合 → OpenHands SDK

OpenHands（前身 OpenDevin，截至本文成稿前 GitHub ~75k stars）走的是”全包平台”路线，官方文档列出的 state-of-the-art 特性包括：

• Task planning and decomposition
• Automatic context compression
• Security analysis
• Strong agent-computer interfaces

它把”Harness + Sandbox + 工具调用”打包在一起，开箱即用，是不少 SWE-bench 刷榜方案的底层。

三层对照地图

┌─────────────────────────────────────────────┐
│ Session 层（账本） → LangGraph Checkpointer │
│ - thread_id / checkpoint_id                 │
│ - time travel + fork                        │
│ - PostgresSaver / SqliteSaver               │
└─────────────────────────────────────────────┘
              ▲ getEvents/emitEvent 等价层
              │
┌─────────────────────────────────────────────┐
│ Harness 层（控制循环） → SWE-agent ACI       │
│   或 OpenHands SDK 全包                      │
│ - 文件 100 行滚动窗口                         │
│ - 编辑前 linter                              │
│ - stop hooks / 循环上限                      │
└─────────────────────────────────────────────┘
              │ execute(name, input)
              ▼
┌─────────────────────────────────────────────┐
│ Sandbox 层（执行环境） → E2B microVM         │
│ - Firecracker 毫秒级拉起                      │
│ - 文件系统监听器实时回流                      │
│ - 容器崩溃自动重建                            │
└─────────────────────────────────────────────┘

关键差距：Anthropic Harness 内部的”循环判断、退避、错误恢复策略”无开源对照——这是托管基础设施的真正护城河。

Q: 在 Harness 这条赛道上，OpenHands 和 SWE-agent 各自的定位是什么？

两者都统治着 SWE-bench 榜单，但定位完全不同。

OpenHands 文档里的 “Strong agent-computer interfaces”——这个 ACI 概念最初就是 SWE-agent 团队 2024 年通过论文定义并广泛传播的；OpenHands 把它产品化、平台化了。

如果做学术对比测试新模型，用 SWE-agent，控制变量最干净；如果业务落地需要稳定运行，用 OpenHands。

Q: Mastra 与 Next.js / Astro / Hono 这些前端/后端框架是什么关系？

Mastra 是一个纯 TypeScript 编写的 AI 智能体框架，不像早期的 LangChain 那样要求你单独跑一个 Python 后端服务。它的设计是直接寄生在你现有的 TS/JS 技术栈里——它提供 AI 智能体的”灵魂”（模型路由、工作流、记忆、工具），这些框架提供让智能体与外界通信的”肉体”。

集成方式有两种：

1. 嵌入式函数调用（Next.js / SvelteKit / Astro / React 生态）

Mastra 只是项目里的一个普通 TS 模块。在 Next.js 的 app/api/chat/route.ts 这种后端路由里直接 import { mastra } from '@/src/mastra'，把用户消息传过去，把流式响应吐回前端。

2. 服务器适配器注入（Express / Hono）

Mastra 提供写好的”全包马甲”（如 @mastra/hono），把 Express 或 Hono 实例传给 Mastra，调用 init() 后会自动在你原有服务器上生成一堆 API 路由（如 /api/agents/weather-agent），开发者不用手写路由。

各框架的”性格”差异：

注：API Key 绝对不能暴露给浏览器端，所以纯 React 项目必须配一个后端代理（Express/Hono/Next.js API route）。

Q: Vercel AI SDK / Mastra / OpenHands 三者是替代关系吗？

不是。它们处于同一堆栈的不同层，可以相互嵌套。

Vercel AI SDK 在做长任务 Agent 时的真实局限

如果只是做”网页里的聪明聊天对话框”，Vercel AI SDK 绰绰有余。但用它构建长周期复杂 Agent 时会遇到几个痛点：

1. 没有内置代码执行 sandbox —— 模型生成的 Bash/Python 要执行，必须自己外挂 E2B 之类的服务
2. Serverless 运行时长上限 —— Vercel Functions 对单次函数执行有时长上限：官方文档给出的数字是 Hobby 档默认/最大都是 300 秒（5 分钟），Pro 与 Enterprise 档默认 300 秒、最大 800 秒（约 13 分钟）。长任务 Agent 跑数十分钟到数小时的场景会撞墙；Vercel 也明确推荐这种工作负载用 Vercel Workflows 而不是 Functions
3. 记忆系统简陋 —— 它只负责把 messages 数组传给前端，向量化、持久化、RAG 检索都要自己接数据库
4. 难以处理非线性工作流 —— 它的 Tool Loop 模式（用 maxSteps 控制连续工具调用次数）面对”分叉、人工审批、多 Agent 协作”的图状路由会迅速恶化成 if-else 浆糊
5. 生态隐性绑定 —— 大量优化是为 Next.js 与 Vercel 平台量身定制的，部署到企业自建的 EKS/VPC 时会显得别扭

现代全栈推荐组合

┌─────────────────────────────────────────────┐
│ 前端展示层 → React + Vercel AI SDK          │
│ 流式 UI、useChat Hook、打字机效果            │
└─────────────────────────────────────────────┘
                  ▲ 流式对接
┌─────────────────────────────────────────────┐
│ 后端编排层 → Mastra (Hono / Next.js)        │
│ 工作流引擎、多层 memory、RAG 检索            │
└─────────────────────────────────────────────┘
                  ▼ 触发代码执行
┌─────────────────────────────────────────────┐
│ 物理执行层 → OpenHands SDK / E2B microVM    │
│ 安全 Linux 沙箱、文件系统监听、容器恢复      │
└─────────────────────────────────────────────┘

一句话总结：网页聊天框用 Vercel AI SDK；带工作流的后台 Agent 用 Mastra；要替代初级程序员去改 Bug、跑命令的全能体用 OpenHands。

Q: Mastra 的 memory 系统真的有”4 层”吗？官方原话是什么？

有，但具体名字与坊间转述不一样。官方文档 里 Mastra memory 的实际四个组件是：

1. Message History —— 原始用户消息、Agent 回复、工具结果的存储
2. Observational Memory —— 后台 agent 维护的密集观察日志，“replaces raw message history”
3. Working Memory —— 持久化的结构化用户数据（姓名、偏好、目标等）
4. Semantic Recall —— 基于语义相似度而非精确关键词的过往消息检索

注意它没有沿用认知科学的”episodic / semantic / document”四分法——Sebastian Lund 在 LLM Memory 指南 里那套四分（详见 the-loop 005）是另一种独立的工程视角，不是 Mastra 实际使用的术语。

这是又一个具体的 fact-check 教训：AI 在介绍 memory 系统时容易把”业界经常用的术语集”和”具体框架的官方命名”混着说。要写进文档前必须翻一遍各自的 /docs/memory/overview 页面对名字。

参考资料

Anthropic 官方

• Anthropic Engineering Blog: Managed Agents —— emitEvent / getEvents / “存储与使用分离” 等核心概念的权威来源
• Managed Agents Quickstart —— 开发者实际能调用的 SDK API（agents / environments / sessions / events.send / events.stream）
• Managed Agents Dreams 文档 —— 离线记忆巩固管道（在 the-loop 005 详细讨论）

三层架构对照的开源项目

• LangGraph Persistence 文档 —— BaseCheckpointSaver / thread_id / checkpoint_id / time travel / fork 的官方说明
• LangGraph GitHub
• E2B 官网 + E2B GitHub —— Firecracker microVM 沙箱基础设施
• SWE-agent 官网 + ACI 文档 + GitHub
• SWE-agent 论文: Yang et al. (2024), “SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering,” arXiv:2405.15793
• OpenHands SDK 文档 + OpenHands GitHub

上层 Agent 框架

• Mastra 文档 + Mastra Memory Overview + GitHub
• Vercel AI SDK 文档 + GitHub
• Goose（Block 出品）GitHub —— 个人开发者 CLI 效率工具方向的 Agent
• Letta GitHub —— 长期记忆与 sleep-time compute（在 the-loop 005 详细讨论）

互补阅读

• Picrew/awesome-agent-harness —— “Agent 马甲工程”主题资源合集
• walkinglabs/learn-harness-engineering —— Harness 工程从 0 到 1 的入门教程
• withastro/flue —— Astro 团队的 “The Agent Harness Framework”，TypeScript 阵营 Agent 运行时