Agent Orchestration on 扎塔-Zata

E2B 迁到阿里云云沙箱：能跑通，但别急着上生产

Mon, 21 Sep 2026 19:00:00 +0800

写《Agent 沙箱选型指南》那篇时，我把 E2B 放在「要做 Code Interpreter 就优先试」那一档。文章发出去以后有人在评论里追问：国内有没有对应的方案，网络和合规能不能绕过去。

当时我的回答挺敷衍的，大意是自托管虽然开源，但底下压着 Firecracker、快照、调度、对象存储和一整套控制面，不是周五下午 docker compose up 一下就能收工的。

后来才发现，阿里云函数计算（FC）已经把这件事做完了，而且做法相当取巧。

它没有另起一套 SDK，而是直接兼容了 E2B 的数据面协议。

于是问题就变成了一个特别诱人的形式：已有 E2B 应用，能不能只改几个环境变量就接上去？

我把一个跑在 E2B 上的小 Runtime 搬了一遍。结论是：能跑通，而且真的就三个环境变量。但「跑通」和「能上生产」之间，隔着一页清单。

这一页清单才是这篇想讲的东西。

本文对应的官方文档共 38 页，逐页的对照表放在最后一节「文档地图」，你可以按需跳转。

一、先把它跑起来

对象是阿里云函数计算的云沙箱（FC Agent Sandbox）——面向 AI Agent 和代码执行场景的云端隔离运行环境，按需创建，任务完成后释放。

它的产品简介写得挺克制：适合承载「不应该直接运行在业务服务进程内」的任务。举的例子是 AI 生成代码执行、数据分析、自动化脚本、依赖复杂的工具调用、临时 Web 服务。这句话其实已经划出了它的边界——它不是一个通用计算平台，是一个给不可信代码用的执行槽。

官方把可做的事分成五类：

场景	说明
运行 Agent 工具	给 Agent 一个独立执行环境，运行命令、处理文件、调用工具链
构建代码解释器	执行 Python / Shell 等代码，返回 stdout、stderr、文本结果或文件产物
处理临时数据任务	上传数据文件，在 Sandbox 内清洗、转换、分析、生成报告
启动临时服务	在 Sandbox 内起 HTTP 服务或开发服务器，通过端口访问地址调用
固化运行环境	用模板预装依赖、运行时和工具链，减少每次任务的初始化成本

核心对象先认一遍

迁移之前值得先花十分钟把这几个对象对上号，因为后面所有的兼容性讨论都是围绕它们展开的：

对象	作用
Sandbox	一次远端隔离执行环境。创建、用、销毁
Template	定义 Sandbox 启动时的运行环境（基础镜像、语言运行时、依赖、工具链）
Commands	在 Sandbox 中执行命令或进程
Filesystem	管理 Sandbox 内的文件
Code Interpreter	执行代码片段并在多次执行间保持上下文，常用模板 `code-interpreter-v1`
Network	访问 Sandbox 暴露的端口（`getHost(port)`）
Storage	本地文件系统只服务当前任务；长期数据走 NAS / OSS
FC Extensions	云上扩展：VPC、OSS 挂载、自定义域名、日志监控、Team 配额

先分清：Team、API Key 和 RAM 权限是三件事

这张表建议在看任何配置步骤之前先过一遍，因为它能省掉一段弯路：

	Team	API Key	RAM 权限策略
是什么	资源隔离单元	数据面凭据	控制台 / OpenAPI 的操作授权
绑在谁身上	账号下的资源组	一个 Team	RAM 用户 / 用户组 / Role
用在哪	划分项目和环境	E2B SDK、CLI、兼容 HTTP API	控制台、OpenAPI
在哪里建	控制台	控制台	RAM 控制台

Team 是「项目 × 环境」的边界，不是随便起的名字。Template、Sandbox、API Key、Volume 全都挂在 Team 下面，共用一个 Team 就等于这些资源互相全都可见，所以官方建议不同项目、测试和生产各用一个 Team，资源组则留给部门当边界。

然后是这次真正卡住我的地方。

我一开始以为要跑通沙箱，得先把 RAM 权限配齐。 这个判断是错的——但我错得挺有迷惑性，因为它「看起来」更安全。官方在配置 RAM 用户权限里把两套鉴权分得很干脆：

通过 E2B SDK、E2B CLI 或兼容 HTTP API 创建和访问 Sandbox 时，使用 API Key，不需要配置 RAM 权限。

再换个说法：RAM 权限管控制台和 OpenAPI，API Key 管数据面。 RAM 权限能让你在控制台管 Team、管 API Key、管 Volume；但你想创建一个 Sandbox 并往里跑代码，只认 API Key。文档的「常见误区」里专门点了这一条——混淆 RAM 权限和 API Key。

顺带一句，这份文档现在挂在 help.aliyun.com/zh/agent-sandbox/ 下（产品名从「云沙箱」往「智能体沙箱 Agent Sandbox」上靠了），旧链接仍然能打开，但搜的时候别只按老名字搜。

但如果你确实要用 OpenAPI 建模板，就会撞上我撞的那面墙。

我在 RAM 控制台里翻权限策略，按 fcsandbox 搜，什么都搜不到；换「服务」下拉列表一个个翻，也没有。第一反应是「是不是我的账号权限太小，看不见这一项」——不是。

原因很朴素：fcsandbox 不在可视化编辑器的服务下拉列表里。 那个列表只收录注册过 RAM 元数据的服务，这个新产品没进去。而 RAM 创建策略时并不校验 action 白名单——你写什么它就存什么。所以正路是根本不要走可视化编辑：

RAM 控制台 → 权限策略 → 创建权限策略
编辑方式选 脚本编辑，不要选可视化编辑
手写 JSON

{
 "Version": "1",
 "Statement": [
 {
 "Effect": "Allow",
 "Action": "fcsandbox:*",
 "Resource": "*"
 }
 ]
}

这一份是「管理账号下全部 Agent Sandbox 资源」，不含函数计算或其他云服务权限。想收紧到指定地域，Resource 改成 acs:fcsandbox:<region>:<account-id>:*。

Action 的命名规则是 fcsandbox:<接口名>——你要找的「建模板、查模板、列模板、删模板」就是这四个字符串，在控制台里是搜不到的，得直接写进策略：

"Action": [
 "fcsandbox:CreateTemplate",
 "fcsandbox:GetTemplate",
 "fcsandbox:ListTemplates",
 "fcsandbox:DeleteTemplate"
]

接口名去哪儿查？去 Agent Sandbox 的 OpenAPI 文档找到业务要调的那个接口，页面上「授权信息」一节会直接告诉你对应的 action 名。别猜名字——写错不会报错，只会在调用时静默变成 403。

想收紧到单个 Team 的话：

"Resource": [
 "acs:fcsandbox:cn-beijing:<account-id>:teams/<team-id>",
 "acs:fcsandbox:cn-beijing:<account-id>:teams/<team-id>/*"
]

两条 Resource 都要写，少一条会出那种「看得见但动不了」的怪状态（文档专门提醒了这一条）：teams/<team-id> 是 Team 本身，teams/<team-id>/* 才是它下面的 Template / Sandbox / API Key。只给前者，用户能看见 Team，但建模板、建 Key 全都失败。

ARN 的完整形态是 acs:fcsandbox:<region>:<account-id>:<resource-path>，层级比想象的深一层：Sandbox 没有带自己 ID 的 ARN，它挂在 Template 下面，某个模板创建的沙箱是 teams/<team-id>/templates/<template-id>/*。所以「只允许用某个模板」这种粒度是能做出来的。

还有一条：fcsandbox 没有配套的系统策略，只能自定义。 如果你在「系统策略」里也搜不到，那是对的，不是漏配了什么。文档在「常见误区」里也点名了别图省事挂 AdministratorAccess——那会把函数计算和其他云服务的权限一起给出去。

所以回到开头：先确认你走哪条路。 只是拿 SDK / CLI 跑沙箱，这一节可以整段跳过，去控制台建 Team 和 API Key 就行；要在 OpenAPI 侧管 Team、Template、API Key 或 Volume，才需要上面这段策略。两种都做的话，记住它俩是平行的两套凭据，权限模型、轮换节奏和泄露影响面都不一样。

前置：先把 API Key 建出来

这一步没有捷径，必须去控制台。按创建 API Key的步骤，创建时有两个字段要填：

描述：用来标识用途（开发环境 / 生产环境 / 某个应用 / 某个团队）。文档特别点了一句「不要只写 test 或 default」——因为后面要按描述筛 Key。
过期时间：可以选永不过期，也可以自定义。生产环境建议设明确的过期时间并建立轮换机制。

创建完把完整 Key 复制出来存好。那句「不要写入代码仓库、镜像、模板、日志、截图、工单或前端页面」我不重复了，只说一个容易忽略的：不要写进模板——模板是会被复用和分发的。

Key 的管理操作有四个：编辑（改描述、改过期时间、启停）、重置（生成新值，旧值立刻失效，用旧值的应用会认证失败）、删除（必须先禁用，建议禁用后观察一段时间再删）。

三个环境变量

export E2B_API_KEY="<your-api-key>"
export E2B_API_URL="https://api.<region>.e2b.fc.aliyuncs.com"
export E2B_DOMAIN="<region>.e2b.fc.aliyuncs.com"

关于这三个变量，有几件事值得单独说清楚（接入参数说明里有完整对应关系）：

第一，SDK 会自动读它们。 所以你会看到官方示例里有的显式传参、有的什么都不传——两种都对。显式传参的好处是排查时一眼能看到连的是哪个 endpoint，我在迁移阶段是坚持显式传的。

第二，E2B_API_URL 和 E2B_DOMAIN 必须显式配置。 官方 E2B 的示例代码通常不写这两个，因为默认就走 E2B 自己的服务。云沙箱是 FC 侧提供的兼容端点，不配就是连到 E2B 官方去了——你的阿里云 Key 在那边自然认不出来。

E2B_API_URL 是 SDK 访问云沙箱 API 的地址，E2B_DOMAIN 是 SDK 拼接沙箱服务访问地址时用的基础域名。两个都要给，因为控制链路和数据链路是分开的。

第三，地域必须四处一致。 E2B_API_URL、E2B_DOMAIN、模板、Sandbox，任意一个不在同一账号或同一地域，现象都是「认证失败 / 模板不可见 / 创建失败 / 连接失败」。按使用约束，当前支持这八个：

地域	region 值
华北 2（北京）	`cn-beijing`
华东 2（上海）	`cn-shanghai`
华东 1（杭州）	`cn-hangzhou`
华南 1（深圳）	`cn-shenzhen`
中国（香港）	`cn-hongkong`
新加坡	`ap-southeast-1`
美国（弗吉尼亚）	`us-east-1`
美国（硅谷）	`us-west-1`

第四，鉴权细节。 如果你不走 SDK、直接调数据面 HTTP 接口，API Key 是放在 X-API-KEY 请求头里的。走 SDK 或 CLI 时，同一个 Key 传给 api_key 参数或设成 E2B_API_KEY 就行。

最小验证：Python

import os
from e2b_code_interpreter import Sandbox


def require_env(name: str) -> str:
 value = os.environ.get(name, "").strip()
 if not value:
 raise RuntimeError(f"缺少环境变量: {name}")
 return value


sandbox = None

try:
 sandbox = Sandbox.create(
 template="code-interpreter-v1",
 api_key=require_env("E2B_API_KEY"),
 api_url=require_env("E2B_API_URL"),
 domain=require_env("E2B_DOMAIN"),
 )

 result = sandbox.commands.run("python3 -c \"print('hello from sandbox')\"")
 print(result.stdout.strip())
finally:
 if sandbox is not None:
 sandbox.kill()

最小验证：TypeScript

import { Sandbox } from "@e2b/code-interpreter";

async function main() {
 const sandbox = await Sandbox.create("code-interpreter-v1", {
 apiKey: process.env.E2B_API_KEY,
 apiUrl: process.env.E2B_API_URL,
 domain: process.env.E2B_DOMAIN,
 timeoutMs: 300_000,
 });

 try {
 const result = await sandbox.commands.run("python3 -c \"print('hello from sandbox')\"");
 console.log(result.stdout.trim());
 } finally {
 await sandbox.kill();
 }
}

main();

看到 hello from sandbox，说明 SDK、API Key、Endpoint、域名和内置模板这五样东西全都通了。

版本会被钉住

通过 SDK 使用云沙箱里明说了：方法名和参数形态以你正在使用的 E2B SDK 版本为准。 Python 和 TypeScript 的命名风格还不一样。所以「兼容」这两个字是有版本前提的。

快速入门验证过的固定组合是：

语言	安装命令	运行时要求
Python	`pip install e2b==2.31.0 e2b-code-interpreter==2.8.1`	Python 3.10+
TypeScript	`npm install e2b@^2.31.0 @e2b/code-interpreter@^2.6.1`	Node.js 20.18.1+

别用 latest。 生产项目应该把 lockfile 提交上去，升级依赖后重新跑一遍验证脚本。

还有一个具体的差异必须记住：Python 的参数是 snake_case，TypeScript 是 camelCase。 Python 是 api_key / api_url，TypeScript 是 apiKey / apiUrl；Python 的 timeout 单位通常是秒，TypeScript 的 timeoutMs 是毫秒。排查时以当前语言 SDK 的类型定义为准，别把另一个语言的字段名复制过来——这种错不报错，只是悄悄用了默认值。

顺带一句：E2B_ACCESS_TOKEN 是 E2B 已经废弃的旧认证变量。新版本 CLI 和 SDK 统一用 E2B_API_KEY。如果旧版 CLI 还在要求那个变量，先升级 CLI 再重试。

二、这套兼容比我想的更深

一开始我以为所谓「兼容」就是照着 E2B 的接口抄了一遍，包一层自家 API。

不是的。它兼容的是 E2B 的数据面协议。 这句话的分量在于：只要协议对得上，第三方完全可以自己写 SDK。接入参数说明里写得很清楚：云沙箱数据面以兼容 E2B SDK / CLI 为主，未提供独立的数据面 SDK；而 Team、API Key、Quota 这些控制面资源可以走原生 OpenAPI、阿里云 SDK 或阿里云 CLI。

阿里云函数计算团队就顺手把 Java 和 Go 的 SDK 写了——因为 E2B 官方只出 Python 和 TypeScript。见 E2B SDK（Java 与 Go）：

Java：aliyun-fc/e2b-java-sdk
Go：aliyun-fc/e2b-go-sdk

两个都还处于「以源码形式提供」的阶段，接入方式有点原生态：

<!-- Java：2.1.0 还没发到 Maven Central，得先克隆并 mvn clean install 到本地仓库 -->
<dependency>
 <groupId>com.alibaba.serverless</groupId>
 <artifactId>e2b-java-sdk</artifactId>
 <version>2.1.0</version>
</dependency>

git clone https://github.com/aliyun-fc/e2b-java-sdk.git
cd e2b-java-sdk
mvn clean install -DskipTests

# Go：go.mod 里声明的还是旧模块路径 github.com/e2b-dev/e2b-go-sdk，
# 该路径已经取不到了，得用 replace 指到本地目录
git clone https://github.com/aliyun-fc/e2b-go-sdk.git
cd myapp
go mod edit -replace=github.com/e2b-dev/e2b-go-sdk=../e2b-go-sdk

Go 这边有个细节挺反直觉：虽然有本地替换，import 路径仍然要写旧模块路径，才能和 SDK 当前 go.mod 的声明对齐。

import e2b "github.com/e2b-dev/e2b-go-sdk"

Java 版有个挺讨喜的设计：Sandbox 实现了 AutoCloseable，退出 try 块就自动 kill()。

ConnectionConfig config = ConnectionConfig.builder()
 .apiKey(System.getenv("E2B_API_KEY"))
 .apiUrl(System.getenv("E2B_API_URL"))
 .domain(System.getenv("E2B_DOMAIN"))
 .build();

try (Sandbox sandbox = Sandbox.create("code-interpreter-v1", config)) {
 CommandResult result = sandbox.getCommands().run(
 "python3 -c \"print('hello from sandbox')\""
 );
 System.out.println(result.getStdout().trim());
}

Go 版则是 defer sandbox.Kill(...)。两边都在用语言本身的机制替你兜住「忘记释放」这件事——这其实是一个挺重要的信号：写这两个 SDK 的人知道，真正的生产事故里，「忘了 kill」比「调不通接口」更常见。

但官方也提示了一句：两个 SDK 实现的是 E2B 数据面协议，接口和默认值与 Python / TypeScript 并不完全一致。 协议兼容不等于 API 表面对齐，接入前还是得看各自仓库的版本说明。

三、一页清单：什么能用，什么别用

这是我建议在动手之前先读完的东西——E2B 兼容说明。它把能力分成四档，其中最有价值的不是「兼容」，而是后面三档。

能力模块	状态	关键说明
Sandbox	兼容	创建、连接、查询、超时、终止、上传下载地址、端口访问；暂停/恢复与 Snapshot 需白名单
Commands	兼容	命令执行、进程管理、标准输入、PTY
Filesystem	部分兼容	读写、目录管理、重命名、删除、存在性检查、目录监听；不支持文件自定义元数据
Code Interpreter	兼容	代码执行、上下文管理、流式输出、跨次执行状态保持；不支持 Java 和 R；上下文管理仅 Python SDK
Template	兼容	模板 CRUD、构建、标签、别名
CLI	部分兼容	常用 Sandbox / Template 命令
Metrics	兼容	CPU、内存可用；磁盘/页缓存字段是占位值，按 1 分钟粒度
Logs / Network Config Update	受限	接口可调用，但返回结果或实际效果存在限制
Snapshots	兼容（需白名单）	仅第二代运行时可用，默认保留 7 天
Volume / Access Token	暂不兼容	不建议作为接入路径；Team 请在控制台管理

方法级的完整清单在 E2B SDK 兼容 API 清单里。下面按模块展开，方便你对着自己的代码库勾一遍。

Sandbox：覆盖了完整生命周期

Sandbox.create() 创建
Sandbox.connect(sandboxId) 连接已有 Sandbox（已暂停时自动恢复）
Sandbox.list() 列出 Sandbox
Sandbox.getInfo(sandboxId) 查询指定 Sandbox 信息
sandbox.getInfo() 查询当前 Sandbox 信息
sandbox.isRunning() 判断是否运行中
Sandbox.setTimeout(sandboxId, ms) 调整指定 Sandbox 超时
sandbox.setTimeout(ms) 调整当前 Sandbox 超时
sandbox.pause() 暂停（需白名单）
sandbox.kill() / Sandbox.kill(id) 终止
sandbox.uploadUrl(path) 获取上传地址
sandbox.downloadUrl(path) 获取下载地址
sandbox.getHost(port) 获取端口访问地址

Sandbox.create() 支持的常用参数（创建沙箱）：

参数	说明
`template`	模板名 / 模板 ID / Snapshot ID / 命名 Snapshot 全名
`timeout` / `timeoutMs`	沙箱超时，Python 秒 / TS 毫秒
`envs`	写入沙箱运行环境的环境变量
`metadata`	写入沙箱控制面的自定义元数据
`secure`	控制端点访问保护强度，见第四节

沙箱实例在生命周期内只有三个状态（code-interpreter-v1 模板）：running（就绪）、paused（已暂停，可恢复）、terminated（已终止）。

关于超时（超时）：可以在创建时设，也可以创建后用 setTimeout() 调。文档的提醒很短但很实在——设置过短任务会被提前回收，设置过长则增加资源占用和费用风险。以及老规矩：超时不是释放。 任务做完就 kill()，别指望超时回收，那个窗口期里资源一直在计费。

Commands：批处理走 run，交互走 pty，长任务走后台

sandbox.commands.run() 启动进程并等待结果
sandbox.commands.list() 列出运行中的进程
sandbox.commands.connect() 连接到已有进程
sandbox.commands.sendStdin() 发送标准输入
sandbox.commands.kill() 终止进程

三类任务三种走法（运行命令 / 后台命令 / PTY）：

批处理用 commands.run()，同步拿结果。这是我见过的 95% 场景。

后台进程加 background=True，SDK 立刻返回进程对象，之后可以继续访问端口、连接进程或终止进程：

try:
 process = sandbox.commands.run(
 "python3 -m http.server 8000",
 background=True,
 timeout=10 * 60,
 )

 host = sandbox.get_host(8000)
 print(f"https://{host}")

 running = sandbox.commands.list()
 print(running)

 process.kill()
finally:
 sandbox.kill()

这里有个必须知道的默认值：命令执行超时默认通常只有 60 秒。 后台进程不会因为 SDK 调用返回就自动结束，但仍受命令超时约束。所以起个长跑服务而不显式设 timeout / timeoutMs，它会在 60 秒后被掐。

另外文档的建议也值得照做：需要持续读取输出的任务，用后台进程 + 连接进程，别用长超时的同步命令阻塞主流程。

交互式终端用独立的 sandbox.pty：

from e2b import PtySize, Sandbox

terminal = sandbox.pty.create(PtySize(rows=24, cols=80), timeout=0)
sandbox.pty.send_stdin(terminal.pid, b"python3 - <<'PY'\nimport sys\nprint(sys.stdout.isatty())\nPY\n")
sandbox.pty.send_stdin(terminal.pid, b"exit\n")
result = terminal.wait(on_pty=lambda data: print(data.decode(), end=""))
print(result.exit_code)

pty.create() 开一个伪终端会话，TypeScript 用 sendInput()、Python 用 send_stdin()，terminal.wait() 等退出。要断开后重连就保存 terminal.pid，再用 sandbox.pty.connect(pid)；窗口大小变了用 resize()。

PTY 的取舍文档列得很干脆：

适合 PTY	不适合 PTY
需要模拟真实终端行为的命令	只需要稳定解析 stdout/stderr 的批处理
工具在非 TTY 环境下会关掉颜色/进度/交互	需要严格区分 stdout 和 stderr 的任务
需要给交互式进程发标准输入	大量结构化日志输出（PTY 会改格式，解析成本变高）

一句话：默认用 commands.run()，只有命令明确依赖终端行为时才升到 PTY。 我见过有人为了「保险」全部走 PTY，结果输出里混进一堆 ANSI 控制字符，正则全废。

Filesystem：够用，但不要当存储

sandbox.files.list() 列出目录内容
sandbox.files.exists() 判断路径是否存在
sandbox.files.getInfo() / get_info() 元信息
sandbox.files.read() 读文件（默认文本，可读为 bytes / 流）
sandbox.files.write() 写文件（文本 / bytes / 流；TS 支持批量）
sandbox.files.makeDir() / make_dir() 创建目录
sandbox.files.remove() 删除
sandbox.files.rename() 移动或重命名
sandbox.files.watchDir() / watch_dir() 目录监听

细节见读写文件。几个实用行为值得记：

write() 会自动创建缺失的父目录，写入已存在文件时直接覆盖。所以 Python 那边写两个文件其实不用先 make_dir——官方示例里先建目录只是习惯。
TypeScript 支持一次写入多个文件，适合把 Agent 生成的代码、测试文件、配置一起丢进去：

await sandbox.files.write([
 { path: "/tmp/project/main.py", data: "print('hello')\n" },
 { path: "/tmp/project/README.md", data: "# Demo\n" },
]);

二进制也支持：Python 写 bytes 和文件对象，读的时候 format="bytes"；TypeScript 写 ArrayBuffer、Blob、ReadableStream。

目录监听是个被低估的能力——等 Agent 输出文件、同步任务产物，比轮询 exists() 优雅得多。只等单个文件时，可以退回 exists() 做有限次数轮询。

Code Interpreter：核心能力齐全，但减法不止一个

sandbox.runCode() / run_code()
sandbox.createCodeContext() / create_code_context()
sandbox.listCodeContexts() / list_code_contexts()
sandbox.restartCodeContext() / restart_code_context()
sandbox.removeCodeContext() / remove_code_context()

输出侧有 stdout、stderr、execution count、裸表达式结果，以及 execution.results 富结果；流式场景下还有 stdout / stderr / 结果回调。同一 Context 内变量和执行状态会保持——这也是 Code Interpreter 和「每次新起一个进程跑脚本」的本质区别。

但code-interpreter-v1 模板那页列出的减法比兼容说明里写的更多：

一是不支持 Java 和 R。 language 参数只认 Python、JavaScript、TypeScript、Bash；run_code 的 language 默认是 python。

二是图表只有降级方案。 官方原话是「在 Sandbox 内生成图片文件后，通过 Filesystem 或下载 URL 取回」。没有「直接返回一个图片对象」那条路。如果你原来的实现依赖 SDK 直接吐出 png，这里要改。

三是上下文管理当前只有 Python SDK 能用。 这条我觉得是整页里最容易被忽略的：TypeScript 的 runCode 能正常执行代码，但 createCodeContext / listCodeContexts / restartCodeContext / removeCodeContext 当前在本平台不可用，需要管理独立上下文只能换 Python SDK。做跨语言迁移的话，这一条会直接把方案卡住。

四是 logs.stdout / logs.stderr 是字符串列表，不是字符串。要 "".join(...)（Python）或 .join("")（TypeScript）拼起来才是完整文本。

run_code 的主要参数和默认值：

参数	说明
`code`	要执行的代码
`language`	`python` / `javascript`，未指定默认 `python`；与 `context` 互斥
`context`	指定在哪个代码上下文执行；与 `language` 互斥
`timeout` / `timeoutMs`	执行超时，Python 默认 300 秒，TypeScript 默认 60000 毫秒
`envs`	自定义环境变量
`on_stdout` / `onStdout` 等	流式回调，逐行接收 stdout / stderr / 结果 / 错误

执行结果 Execution 包含：logs（stdout / stderr 列表）、results（末表达式结果，含 text 文本表示）、error（执行异常）、执行计数（Python execution_count / TS executionCount）。

上下文隔离的行为也很直观：默认上下文里 x = 42 之后另一个 run_code("print(x)") 能读到；但你 create_code_context() 出来的独立上下文里定义的变量，默认上下文读不到（会拿到 NameError）；restart_code_context() 之后变量被清空。

ctx = sbx.create_code_context(language="python", cwd="/home/user")
sbx.run_code("y = 100", context=ctx)
sbx.run_code("print(y)", context=ctx) # 100

sbx.run_code("print(y)") # NameError：默认上下文看不到 ctx 的变量

create_code_context 需要指定 language，cwd 默认 /home/user。run_code 的 context 参数要传 Context 对象；restart_code_context / remove_code_context 传对象或 ID 字符串都行。

另外从构建模板的官方脚本里还能看到更细的返回值形态，注意这里有两个超时参数：

execution = sandbox.run_code("print('hello')", timeout=60, request_timeout=120)

stdout = "".join(execution.logs.stdout or [])
stderr = "".join(execution.logs.stderr or [])
print(execution.error)

timeout 管代码执行，request_timeout 管这次请求本身。这两个别混。 后面讲 Snapshot 的时候会看到，混了会很贵。

Template 与 CLI

模板侧支持 CRUD、构建、标签、别名。CLI 侧的兼容表（通过 CLI 使用云沙箱）：

命令	状态	说明
`sandbox create <template>`	支持	创建沙箱并连接交互式终端，退出终端后自动终止该沙箱
`sandbox list`	支持	默认返回运行中的；可用 `--state`、`--metadata`、`--limit`、`--format`
`sandbox kill`	支持	按 ID 终止，也支持 `--all` 批量终止
`sandbox connect`	支持	连接已有沙箱；退出终端不会自动终止
`sandbox exec`	支持	在运行中的沙箱内执行命令，输出回到本地终端
`sandbox metrics`	支持	CPU、内存，分钟级粒度
`template list`	云沙箱扩展	E2B 官方 CLI 文档未单独说明该命令

create 和 connect 在退出终端时的行为是相反的，这一点特别容易咬人：e2b sandbox create 退出就把沙箱杀了，e2b sandbox connect 退出则留着。调试时用错一个，要么白等一遍启动，要么留下一堆僵尸沙箱在账单上。

CLI 的安装与配置：

brew install e2b # macOS
npm i -g @e2b/cli@2.20.0 # 或者用 npm
e2b --version # 装完先确认版本

export E2B_API_KEY="<your-api-key>"
export E2B_API_URL="https://api.<region>.e2b.fc.aliyuncs.com"
export E2B_DOMAIN="<region>.e2b.fc.aliyuncs.com"

e2b sandbox list # 用一条只读命令验证配置
e2b template list # 看当前账号有哪些模板

CLI 不固定单一版本，官方建议用最新兼容版本。如果命令行为和文档不一致，先跑 e2b --version 和对应命令的 --help，确认本机 CLI 的版本和参数形态，而不是先怀疑文档。

四、五个会静默骗你的坑

这部分是我觉得最有信息量的。它们有的抛异常、有的不抛，但共同点是：都不会告诉你「你要的功能其实没生效」。

坑一：`files.write()` 的 `metadata` 参数

云沙箱当前不支持文件自定义元数据。但 SDK 的方法签名是接受 metadata 的——Python SDK 会在请求发出去之前自己拦下来，报的错长这样（自定义元数据）：

e2b.exceptions.TemplateException:
File metadata requires envd 0.6.2 or later.

原因写得很清楚：Sandbox 当前上报 envd 0.5.2，而文件自定义元数据需要 envd 0.6.2 或以上。普通文件读写完全不受影响。

那页文档还补了一句很关键的：「升级 SDK 或仅修改 envd 版本号声明无法绕过限制」——该能力需要运行环境完整支持元数据校验、键名小写化和扩展属性持久化。所以这不是一个「等版本」的问题，是后端还没实现。

顺手澄清一个容易混的概念，这个混淆我自己也犯过：

	文件自定义元数据	Sandbox `metadata`
挂在哪	单个文件上	沙箱控制面
写入方式	`files.write(..., metadata=...)`	`Sandbox.create(..., metadata=...)`
当前可用	否	是
典型用途	给文件打业务标签	标记任务、用户、场景、版本，便于列表过滤和审计

控制面 metadata 的用法是这样的（元数据），创建时写、getInfo() 读，也能用来过滤 Sandbox.list()：

sandbox = Sandbox.create(
 template="code-interpreter-v1",
 metadata={"task_id": "task-001", "agent": "code-reviewer"},
)

info = sandbox.get_info()
print(info.metadata)

有个细节文档专门强调了：元数据不会自动变成沙箱内的环境变量。 如果同一个字段既要管理面可见、又要沙箱内进程能读到，得同时写进 metadata 和 envs。

元数据的取值建议用短字符串，只放可索引的关联 ID。大段上下文、用户隐私、凭证都不要塞进去。

那文件标签怎么做？ 文档给了三条替代路径，我按推荐度排了一下：

标签存业务库或对象存储，用「Sandbox ID + 文件路径」做关联键。这是最干净的。
同目录写一个 JSON 清单文件，记录文件路径和业务标签。需要跨 Sandbox 保留时，把文件和清单一起写进 NAS / OSS。
如果只是想标记 Sandbox 本身，直接用控制面 metadata——但别把它当文件元数据用。

坑二：`run_code` 用错了 SDK

这个坑卡了我一会儿。现象是：Sandbox 创建成功，commands.run() 正常，但 run_code 就是不行。

原因是 SDK 装错了。通用 e2b SDK 只能使用文件、命令和进程这些基础能力——即使你指定了 code-interpreter-v1 模板，也一样调不了 runCode / run_code。

而这个坑有一半责任在默认值上。官方模板文档列得很清楚：

SDK	`template` 要不要传	不传时的默认模板
`e2b_code_interpreter`（Python）/ `@e2b/code-interpreter`（TS）	不用传	`code-interpreter-v1`
`e2b`（通用）	必须传	`base`

通用 SDK 不传模板拿到的是 base，而 base 不提供 Code Interpreter 服务。 所以「我用通用 SDK + 不指定模板 + 调 run_code」和「我用通用 SDK + 指定 code-interpreter-v1 + 调 run_code」，失败原因其实不同：前者连模板都不对，后者模板对了但 SDK 不对。

判断顺序也简单：先用内置 code-interpreter-v1 模板跑通代码执行、命令执行、文件读写。内置模板正常而自定义模板不行，再去查自定义模板的 Code Interpreter 依赖、启动命令、监听端口和就绪条件。

坑三：上传下载 URL 需要 `secure=false`

这个坑不报错，但它会让一个「看起来已经写好的」浏览器直传链路在最后一跳 403。见上传和下载文件。

sandbox.downloadUrl(path) 和 sandbox.uploadUrl(path) 生成的是带签名的访问地址，适合浏览器直传、把结果文件交给未持有 SDK 鉴权信息的环境，或者交给后续系统处理。但文档里有一句加粗的注意：

如果要使用 downloadUrl() 和 uploadUrl() 返回的 URL 上传下载文件，确保在创建 Sandbox 时显式设置了 secure=false。否则，通过 URL 上传下载文件仍需要请求方携带 X-Access-Token。

sandbox = Sandbox.create(..., secure=False)

而 secure=false 的代价文档也写得很直白：会降低 Sandbox 暴露端点的访问保护强度。 所以要配合「控制 Sandbox 生命周期、文件路径、数据敏感性」一起用。

我自己的取舍是：如果只是后端之间传文件，宁可不省这一下，直接用 files.write() / files.read()。只有「浏览器直传」这种真的拿不到 SDK 凭证的场景，才开 secure=false，并且把路径写死在业务侧、不让它由模型决定。

选型标准文档给得也挺清楚，直接抄：

场景	用什么
小文件、文本、二进制、流式内容、Agent 生成代码	`files.write()` / `files.read()`
浏览器直传、下载结果文件、交给无 SDK 鉴权环境	`uploadUrl()` / `downloadUrl()` + `secure=false`
目录遍历、重命名、删除	Filesystem API

浏览器直传的接收端用 multipart/form-data，字段名是 file：

import requests
with open("input.csv", "rb") as f:
 requests.post(upload_url, files={"file": f}).raise_for_status()

大文件上传后建议用 sandbox.files.exists() 或命令确认文件可读——文档专门提了这句，说明「上传成功但文件不可读」是有过的。

坑四：Logs 和 Network Config Update

这两个是官方明确标记为「受限」的：

Sandbox Logs：当前返回空数组。
Network Config Update：当前返回成功，但不进行实际的网络变更。

官方对它们的定位说得很坦诚——「用于保持 SDK 调用兼容」。所以它们可以留着，让老代码不至于跑挂；但不能作为生产日志采集或网络治理的控制面依赖。接入参数说明那页也把它们列进了「不作为接入参数的能力」。

第二个尤其阴。返回 success 的操作什么都不做，这种设计在本地联调时完全看不出来，只有到线上要改网络策略、发现改了没生效的时候才会撞上。

正路是：日志走函数计算日志采集 + 日志服务，网络变更走云沙箱控制面（监控与日志）。而且更进一步——「生产排查应依赖业务侧结构化日志、函数计算日志采集、云监控和日志服务中的数据」。

配合这个结论，文档给了一段挺实用的日志约定：在业务侧记录 sandbox_created / command_finished 这类事件，字段带上 taskId、sandboxId、exitCode、stdout / stderr 摘要，并且业务系统要保存任务 ID 与 sandboxId 的映射。

print(json.dumps({
 "event": "command_finished",
 "taskId": task_id,
 "sandboxId": sandbox.sandbox_id,
 "exitCode": result.exit_code,
 "stdout": result.stdout.strip(),
 "stderr": result.stderr.strip(),
}))

如果希望沙箱内的程序日志也能被日志服务检索，就让程序直接输出结构化 JSON、并带上 sandboxId 和任务 ID。两条日志流最后在日志服务里能按 taskId 关联起来。

关于日志采集配置，文档提醒了三件事要先确认：配置入口（以云沙箱控制台 / 函数计算控制台 / 日志服务为准，控制台没展示入口就联系产品支持）、生效范围（对账号 / 地域 / 模板 / Sandbox / 会话生效，以及是否只影响新建的 Sandbox）、日志目标（Project、Logstore、索引字段、保存时间和费用策略）。第三项最容易被忽略——日志费用是那种平时不痛、月底很痛的东西。

坑五：Metrics 的磁盘字段

e2b sandbox metrics <sandbox-id> 能看 CPU 和内存，但磁盘 / 页缓存字段返回的是占位值，不能用来判断容量。数据按 1 分钟粒度返回。

官方给的建议是：计费、告警、容量治理都要以函数计算控制台、云监控或日志服务里的正式数据为准。指标接口适合调试和看趋势，别拿去搭容量大盘——1 分钟粒度配占位字段，做成大盘只会得到一条看起来很有道理、实际上是假的曲线。

五、Snapshot 和 pause：白名单能力，别写进架构

Snapshot 比「兼容」两个字复杂得多

我一开始是照「不兼容」处理的，后来翻快照（邀测）发现已经变了。Snapshots 现在兼容，但要加白名单，而且仅限第二代运行时（micro-sandbox）。

它的心智模型很好理解：保存运行中沙箱在某一时刻的文件系统与内存状态，之后用这份快照秒级启动一个同样状态的新沙箱，不必重新构建模板。 典型场景就是 Agent 任务断点续跑、环境预热、并行克隆探索。

几个关键属性：

Snapshot 独立于源沙箱和源模板。 删除源沙箱或源模板不会删掉 Snapshot；删 Snapshot 也不会影响它们。创建成功后即使源模板被删，仍能用该 Snapshot 恢复沙箱。
默认保留 7 天，到期自动过期，过期后不出现在列表里、也不能用于创建沙箱。
留存独立于源沙箱生命周期——源沙箱终止或超时回收后，未过期的 Snapshot 仍可用。

API 表（注意 Python 和 TypeScript 的名字差异）：

操作	TypeScript	Python
创建	`sandbox.createSnapshot({ name? })` / `Sandbox.createSnapshot(sandboxId, { name? })`	`sandbox.create_snapshot(name=...)` / `Sandbox.create_snapshot(sandbox_id, name=...)`
列表	`Sandbox.listSnapshots({ sandboxId?, name?, limit?, nextToken? })`	`Sandbox.list_snapshots(sandbox_id=..., name=..., limit=..., next_token=...)`
从快照建沙箱	`Sandbox.create(snapshotId \| "<TeamName>/<短名>")`	`Sandbox.create(template=snapshot_id \| "<TeamName>/<短名>")`
删除	`Sandbox.deleteSnapshot(snapshotId \| qualifiedName)`	`Sandbox.delete_snapshot(snapshot_id \| qualified_name)`

实例方法和静态方法语义相同——实例方法隐含当前沙箱，不用再传 ID；列表和删除只提供静态方法。

返回字段里有两个：snapshotId / snapshot_id 是 UUID，创建、删除、恢复时优先用它；names 是有名快照的全名列表，无名快照是空数组。两者相互独立——全名只出现在 names 字段和按名解析里，不替代 ID。

命名规则是这里最容易踩的地方。 全名格式是 <当前 Team 名>/<短名>:<tag>：

短名和 tag 的规则是 ^[_a-zA-Z][-_a-zA-Z0-9]*$，最长 64，必须以字母或下划线开头。
Team 名前缀与 Team 展示名相同，最长 32，允许数字开头和空格、点、下划线、连字符（例如默认 Team 的数字名、My Team）。
段内不能含 / 或 :，所以「含且仅含一个 / 的字符串」只可能是 Snapshot 全名，不会和模板名冲突。

传入的 `name`	结果
省略 / 空	无名，`names = []`，只能通过 Snapshot ID 访问
`deps-ready`	`<当前 Team 名>/deps-ready:default`
`deps-ready:v1`	`<当前 Team 名>/deps-ready:v1`
`demo-team/deps-ready`	`demo-team/deps-ready:default`（前缀必须等于当前 Team 名，大小写不敏感）

省略 tag 等价于 default。同一 Team 内同一个 (短名, tag) 同时只能存在一份可用 Snapshot，名称冲突时创建失败，不覆盖已有快照，删除后名称立即释放。Team 没有名字时只能创建无名 Snapshot。

然后是那个我觉得最实用的坑：请求超时。

创建可能持续数分钟。文档明确建议 SDK 请求超时不少于 300 秒（TypeScript requestTimeoutMs: 300_000；Python request_timeout=300）。并且特意点破了那个容易混的点：

timeoutMs / timeout 控制的是沙箱生命周期，不是 Snapshot 请求超时；默认请求超时通常为 60 秒，不加大时可能在创建完成前失败。

60 秒默认值 + 数分钟的实际耗时 = 一个会间歇性失败的接口。而更麻烦的是它失败之后的处理：

创建超时：创建失败，但服务端可能已建成 Snapshot。先增大超时。有名 Snapshot 按 name 或全名列表确认后再决定是否重试；无名 Snapshot 的 name 过滤无效，应先按源沙箱 sandboxId 列表核对；若已存在目标 Snapshot，直接使用其 ID，不要无条件重试。

「不要无条件重试」这六个字是整篇文档里我最想圈出来的一句。它意味着一个朴素的重试装饰器在这里会持续制造垃圾快照，而每一份都在算存储费。

还有个更隐蔽的：创建成功后立即调用列表接口，由于索引延迟，可能暂时看不到刚写入的记录。 但按 ID 或全名恢复、删除都不受影响，可以直接用创建接口返回的值——所以别用「列表里没有」来判断创建失败。

失败条件我整理成表：

条件	结果
源沙箱不存在或不属于当前调用方	创建失败
沙箱运行时不是 `MicroVM`	创建失败
名称非法，或全名前缀不是当前 Team 名	创建失败
Team 无名却传了 `name`	创建失败
同名同 tag 已存在	创建失败，不覆盖
源沙箱已暂停 / 正在创建 Snapshot / 被其他操作占用	创建失败
从 Snapshot 创建时覆盖环境变量、挂载或镜像	创建失败
Snapshot 仍被已恢复沙箱占用	删除失败
按全名恢复或删除但 Snapshot 不存在	失败，不回退为模板

创建过程中源沙箱的 state 是 snapshotting，此时不能删除该沙箱；失败则是 snapshot_failed，这个状态默认不出现在沙箱列表里，得显式按状态过滤才看得到。这一点挺关键——排查「为什么快照没建出来」时，默认列表里是找不到线索的。失败后源沙箱仍可使用或删除。

从 Snapshot 创建沙箱时，哪些参数能覆盖也有明确清单：

允许覆盖：超时、空闲超时、secure、allowInternetAccess、用户 metadata、autoPause、autoResume、网络、自定义沙箱 ID。
不允许覆盖（传入即失败）：环境变量、卷 / 文件系统挂载、函数配置、构建 / 镜像、fc. 前缀的系统 metadata。

以及一个 TS 特有的坑：listSnapshots / createSnapshot / deleteSnapshot 的静态调用要走环境变量配 E2B_API_URL，不要传不被支持的 apiUrl 字段。

最后一条使用建议我觉得挺值得照做：没用的 Snapshot 及时删，避免持续产生存储费用；能短时暂停就优先用暂停与恢复，不要动不动就快照。 7 天保留期是一个「会悄悄花钱」的默认值。

pause：只为短期保留上下文

sandbox.pause() 同样需要白名单（暂停与恢复）。它的语义是「在一段时间内保留状态，之后连同一个 Sandbox 继续用」。Sandbox.connect(sandboxId) 连一个已暂停的沙箱时会自动恢复。

sandbox.pause()
# 之后
sandbox = Sandbox.connect(
 sandbox_id,
 api_key=os.environ["E2B_API_KEY"],
 api_url=os.environ["E2B_API_URL"],
 domain=os.environ["E2B_DOMAIN"],
)

文档里有三句提醒，我原样保留，因为它们都很容易忽略：

恢复后要重新确认长连接、进程状态和业务层状态是否符合预期。暂停期间那些东西的存活不能想当然。
暂停不等于终止。 任务完成后仍然要 kill()。
对需要短期保留上下文的任务才用暂停，不要拿它替代资源释放。

我的整体判断是：白名单能力不要写进架构。 白名单是账号级的开关，今天开了明天能关，把它当成设计前提，等于把系统的可用性挂在一个后台配置上。Snapshot 可以当作「运维手段」和「性能优化」，但不要把「断点续跑」做成唯一路径——至少留一条「重建环境」的兜底。

六、模板：三个档位，和一个必须自己构建的

模板是这次迁移里我改动最大的一块。内置模板不是「一堆可选镜像」，而是三个能力档位，而且默认值会咬人。

内置模板清单

内置模板一共三个，另有若干需要自行构建：

模板	需要构建	适用场景	说明
`base`	否，开通即用	基础命令、文件访问、SDK 连通性验证	不提供 Code Interpreter 服务
`code-interpreter-v1`	否，开通即用	AI Agent 代码执行、数据分析、文件处理	快速入门和代码解释器示例默认用它
`browser`	是	浏览器自动化、截图、动态页面抓取	要从官方 browser 镜像构建
All-In-One	是	浏览器 + 代码执行协同	要从官方 all-in-one 镜像构建
其他（Desktop、Claude Code、OpenClaw 等）	是	桌面环境、编码 Agent	从对应官方镜像自行构建

base 和 code-interpreter-v1 在账号开通云沙箱后自动就绪，直接用模板名创建沙箱即可。

三者的默认配置对比

这部分我建议直接抄进自己的容量规划里：

配置项	`base`	`code-interpreter-v1`	`browser`	All-In-One
CPU	2 vCPU（最低要求）	2 vCPU（最低要求）	4 vCPU（推荐起始）	4 vCPU（推荐规格）
内存	2048 MB（最低要求）	2048 MB（最低要求）	8192 MB（推荐起始）	8192 MB（推荐规格）
磁盘	10240 MB	10240 MB	10240 MB	10240 MB
端口	无业务端口（只有 envd 基础服务）	5000（沙箱服务监听）	3000（browser 服务）	3000（浏览器）+ 5000（代码/文件）
Code Interpreter	不支持	支持 Python / JavaScript	不支持	支持

base 的定位写得很清楚：提供最小化运行环境，内置 E2B envd 兼容基础服务，是 code-interpreter-v1、browser、All-In-One 三个模板的共同能力基础。它不预装数据科学库，也不预置浏览器自动化服务。

回到坑二那句话——通用 e2b SDK 不传 template 时默认创建的就是 base 沙箱。而 base 的 TypeScript 写法还不太一样，没有模板时 options 是第一个参数：

const sbx = await Sandbox.create({ timeoutMs: 600_000 });

Code Interpreter 的硬限制

code-interpreter-v1 那页除了能力介绍，还给了一组迁移时一定会用到的数字：

限制项	约束
沙箱生命周期	单个实例最长 24 小时（`timeout` 上限 86400 秒）
空闲超时	`sandboxIdleTimeoutSeconds`，有效下限 60 秒（低于 60 秒按 60 秒生效）
代码执行超时	单次同步执行默认 Python 300 秒 / TypeScript 60000 毫秒，可通过 `timeout` / `timeoutMs` 调整
语言支持	Python、JavaScript（`language` 默认 `python`）

24 小时这个上限值得单独记住。 如果你的 Runtime 设计里有一个「常驻沙箱」的角色，它在这里是有天花板的。

Code Interpreter Sandbox 的生产形态

使用 Code Interpreter Sandbox那页其实在讲一件更重要的方法论：交互式 run_code 适合开发，固定脚本入口适合生产。

它建议把分析任务拆成四步：

写入输入数据和分析脚本。
使用固定入口执行脚本，例如 python3 analyze.py。
要求脚本输出 JSON 摘要，必要时生成文件产物。
读取结果并销毁沙箱。

理由说得很直白：固定脚本入口更容易做审计、超时和输出校验，因为脚本版本、输入目录、超时时间和输出格式都更容易固化。run_code 更适合模型逐步生成和修正代码的交互式任务。

它还顺手给了一份上线建议，我挑几条最实用的：

输入文件要限制大小、类型和路径，避免一次任务占用过多内存或磁盘。
输出优先用 JSON 摘要，图表、表格、报告文件写 /tmp 后再下载。
对 stdout、stderr、退出码和结果文件做统一封装，避免上层 Agent 直接解析非结构化日志。
对分析代码做版本化——「生产系统不要只保存模型生成的自然语言解释」，这句挺重的。
常用依赖（pandas、openpyxl、绘图库、业务 SDK）放进模板。
用户可见结果和排障日志分开处理，别把完整堆栈或敏感数据直接返回。

browser 模板：不是开通即用，CDP 之外还要过鉴权

browser 模板提供云原生浏览器环境，通过标准 Chrome DevTools Protocol（CDP）over WebSocket 远程控制，原生兼容 Puppeteer、Playwright。它内置 VNC 服务，可以实时看浏览器桌面。但它的使用分两个阶段：先构建模板，再运行模板。

默认配置：

配置项	值
容器镜像	`fc-e2b-registry.cn-beijing.cr.aliyuncs.com/runtime/browser:v0.0.44`
默认端口	3000
CPU	4 vCPU（推荐起始）
内存	8192 MB（推荐起始）
磁盘	10240 MB（建议 10 GB）

第一步：构建。 从官方镜像固化出一个带名称的模板：

from dotenv import load_dotenv
from e2b import Template, default_build_logger

load_dotenv()

FROM_IMAGE = "fc-e2b-registry.cn-beijing.cr.aliyuncs.com/runtime/browser:v0.0.44"

build = Template.build(
 Template().from_image(FROM_IMAGE),
 name="my-browser-template",
 cpu_count=4,
 memory_mb=8192,
 on_build_logs=default_build_logger(),
)
print(f"template_id: {build.template_id}")

第二步：运行。 创建沙箱后先轮询 /health 等 browser 服务就绪，再连 CDP：

sbx = Sandbox.create(template="my-browser-template", timeout=900)
host = sbx.get_host(BROWSER_PORT) # BROWSER_PORT = 3000
token = sbx._envd_access_token # 公网网关要求 X-Access-Token，否则 403
headers = {"X-Access-Token": token} if token else {}

wait_until_healthy(sbx, host, token)

with sync_playwright() as p:
 browser = p.chromium.connect_over_cdp(f"wss://{host}/ws/automation", headers=headers)
 ...

三个 WebSocket 端点，全部需要在请求头带 X-Access-Token 鉴权：

端点	路径	用途
健康检查	`https://<sandbox-host>/health`	判断 browser 服务是否启动完成
CDP 自动化	`wss://<sandbox-host>/ws/automation`	浏览器自动化，兼容 Puppeteer 和 Playwright
VNC 实时流	`wss://<sandbox-host>/ws/livestream`	实时查看浏览器桌面，可用 noVNC 客户端

这里的坑密度比前面几个模块高，我总结成四条：

① X-Access-Token 的取法是非公开 API。 Python 用 sbx._envd_access_token（下划线前缀，说明是内部属性），TypeScript 用 sbx.envdAccessToken。文档自己标注了「后续版本可能重命名或移除」。这意味着这条链路在 SDK 升级时是有断裂风险的，值得在代码里加一层封装并写测试。

② noVNC 这种纯浏览器客户端连不上。 原因很实在：浏览器 WebSocket API 不支持在握手时设置自定义请求头，所以带不了 X-Access-Token，直连就是 403。要看画面得换支持自定义 header 的客户端（wscat、Python websockets）。如果只是想看结果，用 CDP 连接后 page.screenshot() 截图更省事——我觉得这是官方给的最务实的一句建议。

③ 改窗口尺寸要重新烤镜像，envs 不管用。 浏览器窗口和虚拟屏幕由镜像里三个环境变量控制：

环境变量	作用	默认值
`RESOLUTION`	Xvfb 虚拟屏幕分辨率（宽x高x色深）	`1680x1050x24`
`BROWSER_WINDOW_SIZE`	Chrome 启动窗口大小（`--window-size`）	取 `RESOLUTION` 的宽高
`VNC_CLIP`	VNC 实时流的画面裁剪区域	与窗口大小一致

而 Sandbox.create 的 envs 只注入沙箱内的命令执行进程，不会影响浏览器栈。所以想改尺寸，得先用 Dockerfile 把环境变量烤进自定义镜像：

FROM fc-e2b-registry.cn-beijing.cr.aliyuncs.com/runtime/browser:v0.0.44

ENV RESOLUTION=1920x1080x24
ENV BROWSER_WINDOW_SIZE=1920x1080
ENV VNC_CLIP=1920x1080

推送到镜像仓库后，再用 from_image 构建模板。注意窗口尺寸同时决定 VNC 实时流的画面范围，但页面内视口仍由 Playwright / Puppeteer 通过 CDP 自己设。

④ 探测 WebSocket 时会「假失败」。 在沙箱内用 curl 测 CDP 握手：

curl -sS -m 4 -i \
 -H 'Connection: Upgrade' -H 'Upgrade: websocket' \
 -H 'Sec-WebSocket-Version: 13' -H 'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==' \
 http://localhost:3000/ws/automation

收到 101 Switching Protocols 之后，服务端会继续发 WebSocket 数据帧，curl 会一直等到 -m 4 超时并以退出码 28 结束。文档专门解释了这不代表握手失败——判断依据是响应里有没有 101，不是 curl 的退出码。

All-In-One：浏览器 + 代码执行，同一沙箱

All-In-One 就是在 browser 的基础上叠加 Code Interpreter 服务。差异很简洁：

对比项	browser	All-In-One
核心定位	轻量浏览器自动化环境	浏览器自动化 + 代码执行一体化
Code Interpreter	不支持	支持 Python / JavaScript，含上下文保持
端口	3000	3000（浏览器）+ 5000（代码与文件）
默认镜像	`runtime/browser`	`runtime/all-in-one`

默认镜像示例是新加坡地域：fc-e2b-registry.ap-southeast-1.cr.aliyuncs.com/runtime/all-in-one:v0.0.44。注意跨地域镜像构建会失败——镜像地址里的地域必须换成云沙箱接入地域。

浏览器部分（建沙箱、等 /health、CDP、截图）和 browser 模板完全一致，只是多了一段：浏览器阶段产生的截图、HTML、下载文件，可以直接在同一沙箱里交给 Code Interpreter 处理。

# 承接 browser 流程中的同一个 sbx
execution = sbx.run_code(
 "import json\n"
 "print(json.dumps({'status': 'ok', 'source': 'all-in-one'}, ensure_ascii=False))"
)
print("".join(execution.logs.stdout))

用 Code Interpreter 时，SDK 要换回 e2b_code_interpreter / @e2b/code-interpreter，沙箱由你自己的 All-In-One 模板创建。

选型标准文档给得很清楚，我直接抄（使用 Browser Use Sandbox / 使用 AIO Sandbox）：

任务形态	选择
只访问网页、点击、截图、下载、轻量提取	Browser Use Sandbox（browser 模板）
浏览器产物还要在同一会话里清洗、分析、生成报告	AIO Sandbox（All-In-One 模板）
只有代码执行	Code Interpreter Sandbox（code-interpreter-v1）
只要基础命令和文件	base

AIO 那两页的「推荐流程」都是 8 步，结构很像，我合并一下：构建业务模板 → 建沙箱并设足够超时 → get_host(3000) 拿 host → 轮询 /health → 连 CDP 执行操作 → 产物写入沙箱文件系统 → 交给 Code Interpreter 或命令继续处理 → 下载结果、销毁沙箱。

中间有个细节值得抄：用固定的任务目录，例如 /tmp/aio-task/<task-id>，把截图、HTML、下载文件、脚本和结果文件放同一目录。另外官方明确提了**「浏览器阶段和代码阶段分别记录输入、输出、日志和错误」**——排查时先确认是页面操作失败，还是后续脚本处理失败，否则这两种错在同一个沙箱里长得一模一样。

BrowserUse 这类框架怎么接

这块是很多 Agent 框架落地的关键：让 BrowserUse 连接沙箱暴露的 CDP 地址。

browser_session = BrowserSession(
 cdp_url=f"wss://{host}/ws/automation",
 browser_profile=BrowserProfile(headless=False, keep_alive=True),
 headers={"X-Access-Token": sandbox._envd_access_token},
)

agent = Agent(
 task="访问 https://example.com，提取页面标题并总结首屏正文",
 llm=ChatOpenAI(model=..., api_key=..., base_url=...),
 browser_session=browser_session,
 use_vision=True,
)

职责划分很清楚：业务服务负责创建和销毁沙箱，BrowserUse 只连接这个沙箱中的浏览器会话。 用 Puppeteer Core 也一样，browserWSEndpoint 填 wss://<host>/ws/automation，headers 带 token。

上线建议里有两条我特别认同，顺便呼应了前面沙箱选型那篇的老话题：

页面内容可能包含 prompt injection。不要让 Agent 未经校验地执行网页中的指令。
登录态、Cookie、账号凭证和业务 Token 应按任务隔离，通过运行时注入，不写进模板。
每个浏览器任务限制在明确的 URL 范围内，必要时加域名白名单；限制下载文件类型、单文件大小、总输出大小和任务生命周期。

自定义模板：从自己的镜像构建

内置模板满足不了时（业务依赖、系统库、运行时版本、企业标准化），才做自定义镜像模板。生产模板还有几条纪律（构建和管理模板）：

模板名称应唯一、可读，便于灰度和回滚。
基础镜像来自云沙箱可访问的镜像仓库。
镜像仓库、网络配置和云沙箱要在同一地域。
构建依赖不宜过大，否则可能构建超时或失败。
生产环境不应覆盖正在使用的模板，建议新建模板、验证后再切换。

构建流程本身很短——定义模板、提交构建、拿 template_id 建沙箱（快速开始）：

build = Template.build(
 Template().from_image(os.environ["FROM_IMAGE"]),
 name=f"template-{int(time.time())}",
 cpu_count=2,
 memory_mb=2048,
 on_build_logs=default_build_logger(),
)

sandbox = Sandbox.create(template=build.template_id, timeout=900)

如果你要用自己的 ACR EE 镜像，前置条件比较硬：

ACR EE 实例要和云沙箱在同一 UID、同一地域（经济版不支持）。
ACR EE 实例要至少绑定一个 VPC，且该 VPC 下至少有一个 vSwitch 在函数计算支持的可用区。
镜像仓库、VPC、vSwitch 与云沙箱同地域，且访问控制已放通。
推送时用 VPC 内网地址，例如 test-registry-vpc.cn-beijing.cr.aliyuncs.com/runtime/python:3.12-v1。
不要给不同内容的镜像推同一个 tag。 每个不同镜像都要有新且唯一的 tag（版本号、日期或 commit ID），模板引用那个具体 tag。

镜像本身也有一张要求表，违反任何一条都会让构建或运行失败：

级别	要求	不满足的后果
必须	架构为 `linux/amd64`（多架构镜像的 manifest list 要包含 amd64）	模板转换立即失败
必须	不要开启镜像加速	模板转换立即失败
必须	`/etc/passwd`、`/etc/group` 是标准文件且可写	gatewayd 无法初始化默认用户，容器启动失败
条件	固定路径 `/bin/bash` 存在（不能只是能从 PATH 解析到）	`commands.run` 和 PTY 失败
条件	PATH 中有 `python3` 或 `python`	Python `run_code` 不可用
条件	PATH 中有 `node`	JavaScript `run_code` 不可用
按需	`git`、`openssh-client`、CA 证书、构建工具链	对应的 Git / SSH / HTTPS / 源码构建操作不可用
建议	系统 PATH 至少包含 `/usr/local/bin`、`/usr/bin`、`/bin`	登录 shell 里可能缺常用命令

/bin/bash 那一条我建议特别留意：它说的是固定路径存在，不是 PATH 里能找到。很多精简基础镜像（busybox / distroless 派生）会把 bash 放在别处或者干脆没有。还有「不要开镜像加速」这条也挺反直觉——那是个平时看起来纯占便宜的开关。

模板的定位也说得很清楚：模板固化的是系统依赖、语言运行时、工具链和基础代码；用户数据、临时文件和频繁变化的业务状态要在运行时写入；密钥、Token 这类敏感凭证不要写进模板，创建沙箱时用环境变量注入。最后这句我在前面提过一次，这里再强调一遍，因为它是最容易被「顺手固化一下」的操作。

一次真的跑通：从跨地域失败到新加坡模板可用

上面的要求表看起来像文档摘录，直到我真的推了一次镜像，才发现它更适合当成一条排错顺序。这次镜像里要固化的是 Node.js、openpyxl、pandas、NumPy 和 SciPy；最终跑通的路径不是「把 Dockerfile 写对」这么简单，而是连续解决了地域、账号、API Key、镜像 manifest 和登录 Shell 五层问题。

先给结论：自定义模板构建至少有五个必须同时对齐的坐标：Sandbox 地域、E2B Endpoint、E2B API Key 的归属地域、镜像仓库地域、镜像仓库所属账号。 Dockerfile 只是第六个变量。

第一步永远用官方镜像建立基线

不要一上来就拿私有镜像测试。先用同地域官方镜像构建模板并创建 Sandbox：

E2B_API_KEY=
E2B_API_URL=https://api.<region>.e2b.fc.aliyuncs.com
E2B_DOMAIN=<region>.e2b.fc.aliyuncs.com
OFFICIAL_IMAGE=fc-e2b-registry.<region>.cr.aliyuncs.com/runtime/code-interpreter-v1:<published-tag>

这一步成功，才能证明 Team、API Key、Endpoint、Domain 和模板服务链路都正常。否则后面看到 401、模板不可见或构建失败时，很容易把凭证问题误判成镜像问题。

API Key 是地域级凭据。最安全的只读探测是查询 Sandbox 列表，而不是创建 Sandbox：

import httpx

response = httpx.get(
 "https://api.ap-southeast-1.e2b.fc.aliyuncs.com/sandboxes",
 headers={"X-API-KEY": api_key},
 timeout=15,
)
print(response.status_code)

我们这次就碰到过一种很有迷惑性的状态：Endpoint 和 Domain 已经换成新加坡，但 Key 仍然属于北京。结果是新加坡返回 401，北京返回 200。Endpoint 改了，不代表 Key 跟着迁移；目标地域必须重新创建 Team/API Key。

地域不一致不是“慢一点”，而是构建器根本不存在

第一次自定义镜像放在河源 ACR，Sandbox 在北京。构建请求已经被接受，但注入 envd 时失败：

envd inject failed
lookup <account>.cn-heyuan.fc.aliyuncs.com: no such host

这不是 DNS 偶发故障。河源不是 FC 云沙箱支持地域，平台根据镜像仓库地域准备 Builder，最终指向了不存在的河源 FC 服务。后来把镜像和 Sandbox 一起迁到新加坡，这一层才消失。

所以地域检查不要只看 Endpoint。完整矩阵应该是：

对象	必须检查的值
E2B API URL	`api.<region>.e2b.fc.aliyuncs.com`
E2B Domain	`<region>.e2b.fc.aliyuncs.com`
API Key	在目标地域 Team 下创建
源镜像仓库	与 Sandbox 同地域
Template / Sandbox	与前三者同地域
VPC / vSwitch / 安全组（ACR EE）	与仓库和 Sandbox 同地域

“账号一致”可以从错误信息里反推

镜像迁到新加坡后，第一次仍然失败：

get personal ACR authorization token
AUTHENTICATION_FAILED
user jurisdiction error

当时地域、镜像地址、仓库用户名密码都没错。真正的问题是 E2B API Key 所属账号与 ACR 仓库所属账号不一致。换成镜像仓库所在账号、同一新加坡 Team 下创建的 Key 后，构建日志依次变成：

template build accepted
starting image conversion
registry resolved
builder prepared
image conversion completed
template function created

这条日志序列很有用：registry resolved 之前失败，先查仓库类型、账号归属和凭证；builder prepared 之前失败，先查地域和 FC Builder；镜像转换完成但 Sandbox 起不来，再查镜像内部结构与运行依赖。

官方文档把受支持的私有 ACR 主路径写成 ACR 企业版、同 UID、同地域、绑定 VPC。这次实测中，同账号同地域的 ACR 个人版也通过 E2B Template.build() 跑通了镜像转换和 Sandbox 创建，但这只能记作当前实测行为，不应提升为生产承诺。生产仍然应按官方支持路径使用 ACR EE；否则平台调整授权或构建策略时，没有稳定性保证。

镜像要同时满足构建器和登录 Shell

最终镜像采用 Node 22 slim 作为基础，再安装 Python 3 虚拟环境和数据依赖。这样比在 Python 镜像里通过 Debian 安装 npm 少拉数百个系统包。核心结构如下：

FROM node:22-bookworm-slim

RUN apt-get update \
 && apt-get install -y --no-install-recommends \
 bash ca-certificates curl git openssh-client \
 python3 python3-pip python3-venv \
 && rm -rf /var/lib/apt/lists/*

RUN python3 -m venv /opt/venv
ENV PATH="/opt/venv/bin:${PATH}"

COPY requirements-image.txt /tmp/requirements-image.txt
RUN python -m pip install --no-cache-dir -r /tmp/requirements-image.txt

这里又踩了一个只有运行时才出现的坑：Docker 构建阶段用 python 导入依赖正常，但 Sandbox 的 bash -lc 会重置 PATH，python3 最后指向系统 Python，报 ModuleNotFoundError。

单纯把 /usr/local/bin/python3 软链接到虚拟环境也不够。Python 会根据启动路径判断虚拟环境，跨目录软链接可能让它重新落回系统环境。最后用一个明确的包装器解决：

RUN printf '%s\n' '#!/bin/sh' 'exec /opt/venv/bin/python3 "$@"' \
 > /usr/local/bin/python3 \
 && chmod +x /usr/local/bin/python3

Docker build 中能 import，不代表 Sandbox 登录 Shell 中也能 import。 验收必须用和 Sandbox 接近的命令：

docker run --rm --platform linux/amd64 <image> bash -lc '
python3 -c "import openpyxl, pandas, numpy, scipy"
node --version
test -w /etc/passwd
test -w /etc/group
'

推送时关闭附加 manifest

FC 模板排错文档明确建议使用单一 linux/amd64 并关闭 provenance / SBOM。否则 Buildx 可能同时推送一个 unknown/unknown 的 attestation manifest，模板构建器可能把它当成镜像平台异常。

docker buildx build \
 --platform linux/amd64 \
 --provenance=false \
 --sbom=false \
 --tag "<registry>/<namespace>/<image>:<unique-tag>" \
 --push \
 .

这里的 <unique-tag> 是纪律，不是装饰。不要把不同内容覆盖到已经被模板引用的 tag；使用日期、版本号或 commit ID，让镜像、模板和一次验证结果能够互相追溯。

最后的验收必须发生在云端 Sandbox

本地镜像测试只证明容器能跑，不能证明 envd 注入、模板函数和 Sandbox 生命周期正常。最终验收应当创建一次临时 Sandbox，实际导入依赖，然后在 finally 中释放：

sandbox = Sandbox.create(template=template_id, timeout=300)
try:
 result = sandbox.commands.run(
 "python3 -c \""
 "import openpyxl, pandas, numpy, scipy; "
 "print(openpyxl.__version__, pandas.__version__, "
 "numpy.__version__, scipy.__version__)\" "
 "&& node --version"
 )
 if result.exit_code != 0:
 raise RuntimeError(result.stderr)
 print(result.stdout)
finally:
 sandbox.kill()

这次云端最终验证通过的组合是 Python 3.11、Node.js 22、openpyxl 3.1.5、pandas 2.3.2、NumPy 2.3.3、SciPy 1.16.2。版本号不是推荐清单，只是一次可复现构建的证据；真正值得复用的是验收顺序：

官方镜像验证控制链路；
只读探测 API Key 地域；
单平台、唯一 tag 推送自定义镜像；
观察构建日志停在哪一阶段；
在云端 Sandbox 里导入全部关键依赖；
无论成功失败都释放临时 Sandbox。

这轮实测最后留下的判断是：自定义模板最难排查的不是 Dockerfile，而是“地域 × 账号 × 凭据 × 仓库类型”共同决定的构建控制面。 先把这四个坐标钉死，再谈镜像内部依赖，排错会快很多。

模板的版本管理：名称 + 标签

发布纪律这块，官方给的做法是名称标识运行环境，标签标记某次构建的阶段或版本（prod、staging、v1），用来做灰度和回滚（模板名称与版本）。

名称建议带上业务场景、语言或基础镜像、关键依赖版本和日期：

agent-python313-20260704
code-review-node22-20260704
data-analysis-py313-v1

标签操作有三个：assignTags 分配、getTags 查询、removeTags 移除。有两个坑值得记：

不能删除 default 标签（返回 400）。
Python 查询标签要用模板 ID，不是模板名；TypeScript 用模板名就行。分配和移除倒是都按模板名。

Template.assign_tags("agent-python313-20260704", ["staging", "v1"])
tags = Template.get_tags("<template-id>") # 注意这里是 ID

分配和移除标签都是幂等的，重复分配、删不存在的标签都不会报错。assignTags 第一个参数用 name:tag 格式指定从哪个构建打标签，不带 :tag 时默认指向 default 构建。

沙箱内的环境变量

环境变量分两层，用途不同（环境变量）：

沙箱级 envs：创建时传入，适合多次命令都会用到的配置。
命令级 envs：commands.run() 时传入，适合单次执行参数，会覆盖沙箱级。

sandbox = Sandbox.create(..., envs={"NODE_ENV": "production", "TASK_ID": "task-001"})

result = sandbox.commands.run("echo $TASK_ID", envs={"TASK_ID": "task-002"})

官方建议是环境变量只放非敏感开关、任务参数和工具配置，密钥和 Token 由业务侧控制访问范围。以及一条和 metadata 呼应的边界：不要依赖环境变量保存业务状态，跨沙箱的持久状态写外部存储。

七、FC Extensions：云沙箱不是 E2B 的镜像

如果只是纯「E2B 兼容，换个 endpoint」，那云沙箱的价值就只是「国内有个能连上的 E2B」。但它其实还多了一层 E2B 原生接口里没有的东西：FC Extensions（云上扩展）（概览）。

扩展	作用
VPC 网络配置	让 Sandbox 访问 VPC 内的数据库、内网 API、镜像仓库或其他云资源
自定义域名	用固定域名和自有证书访问云沙箱 API 及沙箱内服务
动态挂载 OSS	通过 metadata 把 OSS 路径挂进 Sandbox，按本地路径读写对象
监控与日志	查看运行状态与资源指标，把 stdout / stderr 采集到日志服务
Team 配额管理	给指定 Team 设置 CPU 和内存配额
OSS Volume / AgenticFS Volume	保存可复用的挂载配置，创建沙箱时按名称挂载

它的接入方式有一个很重要的性质：FC Extensions 不是 E2B SDK 的新方法，不需要改导入方式。 应用侧还是照常 Sandbox.create()，VPC、OSS、日志、监控这些是在函数计算控制台或云沙箱控制面配好、然后生效的。

而且它的实际机制比「控制台点一下」更有意思：VPC 和 OSS 挂载都是通过 Sandbox 的保留 metadata 字段传进去的。

VPC 配置：一个保留 metadata 字段

云沙箱通过 fc.sandbox.network.vpc 传 VPC 配置——把 vpcId、securityGroupId、vSwitchIds 序列化成 JSON 字符串：

{
 "vpcId": "vpc-xxxxxxxx",
 "securityGroupId": "sg-xxxxxxxx",
 "vSwitchIds": ["vsw-xxxxxxxx"]
}

sandbox = Sandbox.create(
 **conn_opts,
 metadata={
 "fc.sandbox.network.vpc": json.dumps(vpc_config),
 },
)

字段	必填	说明
`vpcId`	是	要接入的专有网络 ID
`securityGroupId`	是	安全组 ID，用于控制出方向访问范围
`vSwitchIds`	是	vSwitch ID 列表，建议配两个或更多，提高可用性并降低单网段 IP 不足的风险

前置条件比想象中多，漏一个就是「创建成功但连不上」：

vSwitch 要在函数计算支持的可用区（同 VPC 内不同 vSwitch 默认可私网互通）。
安全组要是非云服务托管的，且出方向规则允许访问目标资源的协议和端口。
目标资源自己有白名单的（RDS 白名单、自建服务 ACL），要把 vSwitch 网段加进去。

「网络可达不等于业务鉴权通过」——数据库账号、API Token、RAM Role 这些都还得单独配。这句话文档写得很明白，我觉得是这一节最有价值的一句。

验证方式也很实在，而且给了一个我觉得很聪明的判别实验：

用 socket.create_connection((host, port), timeout=5) 在沙箱内测 TCP 连通性，可以拿去测 NAS 2049、RDS 3306、Redis 6379 或内网 HTTP 端口。
先建一个不带 fc.sandbox.network.vpc 的 Sandbox，确认同一个内网地址不可达；再建一个带 VPC metadata 的，确认可达。 这样才能证明是 VPC 配置生效，而不是网络本来就通。

常见问题那张表也能当排错清单用：

现象	可能原因
创建 Sandbox 失败	资源 ID 不存在，或与沙箱不在同一地域 / 账号
创建成功但内网地址不可达	安全组出方向未放行、目标资源白名单未含 vSwitch 网段、目标服务未监听
提示 vSwitch 可用区不支持	vSwitch 不在函数计算当前地域支持的可用区内
偶发创建 / 连接失败	vSwitch 网段可用 IP 不足，或只配了单个可用区
需要访问公网和 VPC	只配 VPC 不代表固定公网出口，公网能力以云沙箱和函数计算网络策略为准

还有个表述细节：fc.sandbox.network.vpc 的值必须是 JSON 字符串，不能直接传 Python dict 或 JavaScript object。

OSS 挂载：两个 metadata 字段

OSS 动态挂载要传两个字段（动态挂载 OSS）：

fc.sandbox.storage.oss：挂载配置，JSON 字符串。
fc.sandbox.auth.role：用于访问 OSS 的 RAM Role ARN。

sandbox = Sandbox.create(
 api_key=api_key,
 timeout=300,
 **conn_opts,
 metadata={
 "fc.sandbox.storage.oss": json.dumps(oss_config),
 "fc.sandbox.auth.role": role_arn,
 },
)

挂载点配置：

{
 "mountPoints": [
 {
 "bucketName": "example-bucket",
 "mountDir": "/mnt/oss",
 "bucketPath": "/e2b-test",
 "endpoint": "https://oss-cn-hangzhou.aliyuncs.com",
 "readOnly": false
 }
 ]
}

字段	必填	说明
`bucketName`	是	OSS Bucket 名称
`mountDir`	是	Sandbox 内挂载目录，必须是绝对路径
`endpoint`	是	OSS Endpoint，应与 Bucket 所在地域匹配
`bucketPath`	否	Bucket 内子目录，建议绝对路径；`/` 或留空表示根目录
`readOnly`	否	`true` 时只能读挂载目录

几个容易踩的点：

挂载必须同时配 fc.sandbox.auth.role，否则沙箱拿不到 OSS 权限。 两者缺一不可。
RAM Role 要授予函数计算服务可扮演权限，并具备访问目标 Bucket 或子目录的 OSS 权限。
mountDir 推荐 /mnt/oss 或 /home/user/oss，避免与模板内已有系统目录冲突。
跨地域 endpoint 会导致延迟升高或访问失败。

权限建议是这一页最值得抄的部分，因为它正好把之前沙箱选型那篇讲的「最小权限」落到了具体 policy 上：

用 readOnly: true 挂输入数据目录，避免任务误写或删除源数据。
写入结果用独立前缀，例如 tenants/<tenant-id>/tasks/<task-id>/outputs/。
RAM Policy 只授权任务需要的对象前缀：只读任务给 oss:ListObjects + oss:GetObject；读写任务再按需加 oss:PutObject、oss:DeleteObject、oss:AbortMultipartUpload、oss:ListParts。
不要在代码、模板或 metadata 中写长期 AK/SK，访问 OSS 走 fc.sandbox.auth.role。
临时产物配 OSS 生命周期清理规则。

自定义域名：证书要求比想象中严格

自定义域名解决的是「生产环境要固定域名 + 自有证书」。它把域名分成两条链路：

用途	示例	说明
控制链路域名	`api.example.com`	创建、查询、删除云沙箱等 API 请求
数据链路域名	`*.example.com`	访问沙箱内指定端口的服务

对应到 SDK 参数就是 apiUrl = https://api.example.com、domain = example.com。之后 sandbox.getHost(8000) 返回的就变成 8000-<sandbox-id>.example.com，https://{port}-{sandboxId}.example.com 这种形式。

限制条件我列一下，因为这几条挺容易在配置阶段反复：

必须选云沙箱所在地域，否则域名解析和证书校验可能不生效。
控制链路只支持 api. 开头的单域名；数据链路是控制链路去掉 api. 前缀后的泛域名。
必须 HTTPS。
证书必须覆盖数据链路泛域名（例如 *.example.com）——只覆盖 api.example.com 的单域名证书不满足要求。
私钥必须是未加密的 RSA PEM 格式。 如果你的私钥是 PKCS#8 的 -----BEGIN PRIVATE KEY-----，要先转换：

openssl rsa -in pkcs8.key -out pkcs1.key

不支持中文域名。
同一主账号默认最多绑 5 个云沙箱自定义域名。
自定义域名需要完成备案或接入备案，以控制台校验结果为准。

配置要动两个控制台：云沙箱控制台加域名拿 CNAME，再去云解析 DNS 配解析（控制链路主机记录 api，数据链路主机记录 *）。配完用 dig +short CNAME api.example.com 和 dig +short CNAME test.example.com 验证——第二条是专门用来验证泛域名解析的，这个细节挺贴心。

还有一个实用提醒：sandbox.getHost(port) 返回的是 host，访问时通常要自己拼 https://。

Team 配额管理：注意鉴权通道不一样

这块的文档里有一条我认为最容易被忽略、也最容易配错的信息：

Team 配额管理使用 POP SDK 和阿里云 AK/SK，不使用云沙箱 API Key 鉴权。

也就是说，你的系统在这里会同时持有两套凭证：沙箱的 API Key 和阿里云的 AK/SK。这两套东西的权限模型、轮换策略、泄露影响面都不一样，值得在密钥管理上分开对待。文档也重申了「云沙箱 API Key 仍通过函数计算控制台创建和管理」「不要把 AK/SK、API Key 写入代码仓库、镜像、模板、日志、截图、工单或前端页面」。

前置条件里有一条挺关键：「已在阿里云控制台联系客服完成加白」——所以 Team 配额同样是白名单能力。

配额模型很简单，以 Team ID 作为 TagValue，两个配额项：

字段	类型	约束	说明
`TagValue`	`*string`	匹配 `[A-Za-z0-9_-]{1,64}`	填 Team ID
`CpuCores`	`*int32`	≥ 0	CPU 核数配额
`MemoryGB`	`*int32`	≥ 0	内存 GB 配额

设为 0 表示禁止该 Team 使用对应资源（不是「无限制」，别理解反）。UpdateQuota 是覆盖式更新，同一 TagValue 多次调用后一次覆盖前一次。

四个接口和对应的 RAM Action：

操作	Go 方法	RAM Action
创建或更新配额	`UpdateQuota`	`fcsandbox:UpdateQuota`
查询配额	`DescribeQuota`	`fcsandbox:DescribeQuota`
列出配额	`ListQuota`	`fcsandbox:ListQuota`
删除配额	`DeleteQuota`	`fcsandbox:DeleteQuota`

服务的 RAM 授权码是 fcsandbox。如果要按地域和账号收敛范围，把 Resource 从 * 改成 acs:fcsandbox:<region>:<account-id>:*。

这也是我和第一节那段绕了一圈的地方：配额走的是 RAM 这条路，不是 API Key。 第一节里说过 fcsandbox 不在可视化编辑器里、要用脚本编辑手写——所以真正的现象往往是「沙箱跑得好好的，一到配额接口就 401」，因为两条链路上的凭证压根不是同一套。

用阿里云 POP Go SDK 的骨架：

config := &openapiutil.Config{
 AccessKeyId: tea.String(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")),
 AccessKeySecret: tea.String(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")),
 SecurityToken: tea.String(os.Getenv("ALIBABA_CLOUD_SECURITY_TOKEN")),
 Endpoint: tea.String("fcsandbox.cn-beijing.aliyuncs.com"),
}

client, err := fcsandbox.NewClient(config)

resp, err := client.UpdateQuota(&fcsandbox.UpdateQuotaRequest{
 Body: &fcsandbox.Quota{
 TagValue: tea.String(teamID),
 CpuCores: tea.Int32(32),
 MemoryGB: tea.Int32(32),
 },
})

错误码表（也可以当排错用）：

HTTP	Code	说明
400	`InvalidParameter`	参数校验失败，缺少必填字段或格式不合法
401	`Unauthorized`	凭证无效或未提供
403	`Forbidden`	无权操作
404	`ResourceQuotaNotFound`	查询的配额不存在
429	`LimitExceeded`	超出配额限制
500	`InternalError`	服务内部错误

删除配额后再查会返回 404，但可能有短暂的最终一致性延迟，文档建议用有上限的轮询确认——「有上限」三个字是重点。

使用建议里我最认同两条：「不要让测试任务和生产任务共用同一个高配额 Team」，以及 「配额只解决资源上限问题，不能替代业务侧限流、任务队列、超时控制和资源释放」。后者是在提醒你：配额是天花板，不是限流器；撞到天花板的失败模式和排队等待完全不一样。

日志采集要确认的三件事

前面坑四里说过，E2B 的 Logs 接口返回空数组是已知行为。正路是走监控与日志。那一页有一句我觉得该抄进设计文档的话：

应用侧可以记录 sandboxId、任务 ID 和命令结果，便于在云上监控或日志页面中定位问题。

它还把常见观测对象列成了清单，可以直接当埋点需求单用：

Sandbox 生命周期：创建、连接、暂停、恢复、终止。
命令执行结果：退出码、stdout、stderr、耗时。
资源使用：CPU、内存、磁盘和网络。
关联字段：sandboxId、任务 ID、用户或租户标识、模板名称。
结构化日志：event、taskId、sandboxId、exitCode、stdout / stderr 摘要。

注意这里列了「资源使用：CPU、内存、磁盘和网络」——但指标接口的磁盘字段是占位值，所以真实数据得从控制台或云监控拿。这两处放在一起看，能看出「观测对象」和「可获取的数据源」是两件事。

八、迁不动的那部分怎么办

几个决策，我按「原来怎么做 → 现在怎么做」列一下（E2B 兼容与迁移）：

原来（E2B 原生）	现在（云沙箱）
Volume 做持久化	换 NAS / OSS；跨 Sandbox 的数据本来就不该放本地文件系统
SDK 管理 API Key	函数计算控制台创建、查看、编辑、重置、禁用、删除
Team 管理	函数计算控制台（创建 Team 见创建 Team，订阅计划见 Team 与订阅计划）
Snapshot 做状态分叉	可以，但要白名单 + 第二代运行时，且注意命名与超时规则与官方不同
文件自定义元数据	不支持；改用控制面 `metadata`，或把标签写进业务库 / JSON 清单
依赖 E2B 的 Logs 接口	换成函数计算日志采集 + 业务侧结构化日志
依赖 E2B 的网络配置更新接口	换到云沙箱控制面
想要固定域名和自有证书	用 FC Extensions 的自定义域名
沙箱要访问内网 RDS / Redis / NAS	用 FC Extensions 的 VPC 网络配置
E2B 托管 MCP Gateway / BYOC	不在兼容路径里，需要单独设计

API Key 的隔离策略值得单独说一句：按应用、环境、团队或租户拆分 Key，不要多人多系统共用一个长期 Key；生产用自定义过期时间并定期轮换；重置或删除前先确认业务侧已经切到新 Key——这条写在文档里，但我猜真出事的时候是「先重置，再发现有三个服务挂了」。

还有一条和 E2B 一样的老常识，仍然要重复一遍：Sandbox 的本地文件系统只适合当前任务内的临时文件。 Sandbox 终止之后，这些文件不应该被当成持久数据依赖。临时输入、生成代码和中间结果建议写 /tmp 或业务自定义工作目录。

以及从沙箱选型那篇就一直在强调的点：处理用户上传路径时，要限制文件大小、文件类型和可写路径，别把未校验的路径直接传给 Filesystem API 或命令行。这一点和用哪家沙箱无关——沙箱防的是代码逃逸，不防你的业务逻辑被 prompt injection 牵着走。浏览器模板那一页把这条说得更直接：网页内容和下载文件都可能携带 prompt injection。

九、上生产前必须确认的边界

这一节是使用约束的整理。官方把话说得很直接：快速入门只演示最小接入路径，实际业务接入前应先确认本文约束。

配额：六类不能假设无限

单账号或单地域并发 Sandbox 数
单个 Sandbox 可用的 CPU、内存和本地磁盘空间
单个 Sandbox 可打开的进程数、端口数、文件数
单次任务的输入、输出文件大小
模板构建的并发数、构建资源和构建时长
端口访问

超出默认配额时，Sandbox 创建、模板构建或任务执行都可能失败。需要更高配额要走控制台或阿里云支持渠道申请。这条对做 To C 产品的人尤其重要——你的并发上限不是你代码写的并发数，是账号配额。

生命周期

Sandbox 创建后会持续占用资源，直到被主动终止、超时回收，或进入支持的暂停状态。任务完成后 kill()。

三个和生命周期相关的数字放在一起记：上限 24 小时（86400 秒）、空闲超时下限 60 秒、命令超时默认 60 秒。 超时参数单位差异再说一遍：Python 通常用秒，TypeScript 用毫秒。

文件与存储

本地文件系统只服务当前 Sandbox 生命周期。
跨 Sandbox 保留、共享或长期保存的数据写 NAS / OSS。
处理用户上传时限制文件大小、类型和可写路径。

十、一份可执行的迁移顺序

如果你手上有现成的 E2B 应用，我会建议按这个顺序推，每一步都有明确的验收点：

开通、建 Team、建 Key。 确认目标地域支持云沙箱、账号已开通云沙箱功能，按「项目 × 环境」建 Team，再在 Team 下创建 API Key，描述写清楚用途。这一步会同时决定你要不要那段 fcsandbox 策略——只用 SDK 就不需要，要在 OpenAPI 侧管资源才要。
定地域、配环境变量、钉版本。 选出地域，配好三个环境变量，把 SDK 版本写进 requirements / package.json，别用 latest。
跑最小验证，只验证四件事：创建 Sandbox、执行命令、读写文件、释放资源。文档原话是「不要一开始就迁移复杂模板、网络和存储逻辑」——这个顺序是对的，因为它把变量控制在最少。
想清楚用哪个模板，别让默认值替你做决定。 要 run_code 就必须装 e2b-code-interpreter / @e2b/code-interpreter；用通用 e2b SDK 时必须显式传 template，不传会落到 base。
再迁自定义模板。 用官方镜像先跑通构建流程，再换自己的 ACR EE 镜像；构建前对着镜像要求表逐条核一遍，并确认镜像仓库、VPC 和沙箱同地域。
需要浏览器能力的话，这里才开始。browser / All-In-One 都要先构建模板，再注意 /health 轮询、X-Access-Token、窗口尺寸烤镜像这几件事。
迁移时同步做「能力减法」：把 Volume、Access Token、Team 管理、文件自定义元数据、E2B Logs 接口这些从代码里挑出来，换成 NAS / OSS、控制台、控制面 metadata 和日志采集。
最后才是网络和可观测。 VPC、OSS 挂载、自定义域名、日志采集、Team 配额，都属于 FC Extensions，走 metadata 或控制面配置，不占用迁移改造的窗口。
上线前补三样东西：显式的 kill() 释放路径（try/finally、defer 或 AutoCloseable 都行）、业务侧的 taskId ↔ sandboxId 映射、以及结构化日志。

十一、排错对照表

踩过一轮之后，我把「现象 → 先查什么」整理成了一张表，比按文档目录翻快：

现象	优先排查
认证失败 / 模板不可见	三个环境变量是否配全、Key 是否被禁用或重置、账号与地域是否一致
创建失败、连接失败、模板找不到	API URL、域名、模板、Sandbox 是否同地域
连接失败	目标 Sandbox 是否已终止、超时回收，或不属于当前账号 / 地域
Sandbox 创建成功但 `run_code` 失败	SDK 是否装错；通用 `e2b` SDK 不传模板会落到 `base`
内置模板正常、自定义模板 `run_code` 失败	自定义模板的 Code Interpreter 依赖、启动命令、监听端口、就绪条件
TypeScript 里上下文管理方法不可用	该能力当前仅 Python SDK 提供
写入报 `File metadata requires envd 0.6.2 or later`	用了文件自定义元数据，当前不支持；改用控制面 `metadata`
上传 / 下载 URL 403	创建 Sandbox 时是否显式设了 `secure=false`
服务起来 60 秒后被杀	命令超时默认 60 秒，后台进程要显式设 `timeout` / `timeoutMs`
PTY 输出解析不了	PTY 会改变输出格式；批处理应该用 `commands.run()`
浏览器端点 403	请求头缺 `X-Access-Token`（`sbx._envd_access_token` / `sbx.envdAccessToken`）
noVNC 连不上	浏览器 WebSocket API 不能带自定义 header；改用支持 header 的客户端，或直接截图
CDP 探测返回退出码 28	正常现象，看响应里有没有 `101 Switching Protocols`
改了浏览器窗口尺寸没生效	`envs` 不影响浏览器栈，要烤进镜像（`RESOLUTION` 等）
browser / All-In-One 创建模板失败	跨地域镜像构建会失败，镜像地址里的地域要换成沙箱地域
建了带 VPC 的沙箱但内网连不通	安全组出方向、目标资源白名单里的 vSwitch 网段、服务监听状态
挂载 OSS 后没有权限	是否同时配了 `fc.sandbox.auth.role`（RAM Role ARN）
自定义域名证书校验失败	证书要覆盖数据链路泛域名（`*.example.com`），且私钥是未加密 RSA PEM
改了网络策略没生效	Network Config Update 是受限能力，要去控制面改
抓不到沙箱日志	E2B Logs 接口返回空数组是已知行为，走函数计算日志采集
容量 / 费用看着不对	别用 Metrics 的磁盘字段（占位值），以控制台 / 云监控 / 日志服务为准
创建 Snapshot 超时	`request_timeout` 是否 ≥ 300；先查是否已建成，不要无条件重试
沙箱列表里找不到失败的快照	`snapshot_failed` 状态默认不显示，要按状态过滤
刚建的 Snapshot 列表里看不到	索引延迟；直接用创建返回的 `snapshotId`
Team 配额调用报 401 / 403	配额用 AK/SK + `fcsandbox` RAM 授权，不用沙箱 API Key
RAM 控制台搜不到 `fcsandbox`	该服务不在可视化编辑器的服务列表里，改用脚本编辑手写 action
建策略后仍建不了模板 / API Key	Team 级策略要同时给 `teams/<id>` 和 `teams/<id>/*`，只给前者会「看得见动不了」
沙箱能跑，但 OpenAPI 管不了 Team / API Key	两套鉴权别混：SDK / CLI 用 API Key，控制台 / OpenAPI 用 RAM 策略 + AK/SK
模板构建失败	先查镜像仓库、网络、账号权限，再查 SDK 参数
SDK 可用但 CLI 不可用	CLI 版本、`E2B_API_KEY`、`E2B_API_URL`、`E2B_DOMAIN`
CLI 行为与文档不一致	先 `e2b --version` 和 `<cmd> --help`

十二、文档地图

上面所有结论都来自官方文档。我把 38 页按分组列在这里，并标了每页在本文的对应位置——标「—」的是我提了一句但没展开的，需要细节请直接点链接。

入门与接入

页面	内容	本文位置
产品简介	定位、五类场景、八个核心对象、基本使用路径	第一节
创建 API Key	控制台创建步骤、过期时间、编辑/重置/删除、安全建议	第一节
通过 SDK 使用云沙箱	Python / TypeScript 快速入门、版本要求	第一节
通过 CLI 使用云沙箱	CLI 安装、八步操作流程、各命令示例	第三节
E2B SDK 接入参数说明	三个环境变量与 SDK 参数逐个对应、snake/camel 差异、不作为接入参数的能力	第一、二节

兼容与迁移

页面	内容	本文位置
E2B 兼容说明	四档兼容状态、各模块完整方法清单、受限与暂不兼容能力	第三节
E2B SDK 兼容 API 清单	按对象罗列的兼容方法、使用建议	第三节
E2B 兼容与迁移	迁移四件事、地域一致性、常见问题	第一、八节
E2B SDK（Java 与 Go）	两个 SDK 的安装与快速入门、Maven / replace 注意事项	第二节
使用约束	地域、版本、鉴权、六类配额、生命周期、模板构建、文件存储	第九节

Sandbox 功能

页面	内容	本文位置
创建沙箱	`Sandbox.create` 参数（`timeoutMs` / `envs` / `metadata`）、Python 与 TS 传参差异	第三节
生命周期	创建、连接、查询、终止、设置超时	第三节
超时	创建时配置、创建后调整、单位差异	第三节
暂停与恢复	白名单、`pause()`、连接时自动恢复、使用建议	第五节
环境变量	沙箱级与命令级 `envs`、覆盖规则	第六节
元数据	控制面 `metadata` 写法、与环境变量的区别	第四节
快照（邀测）	API 表、名称规则、保留 7 天、请求超时 300 秒、十种失败条件、参数覆盖清单	第五节

Commands 与 Filesystem

页面	内容	本文位置
运行命令	`commands.*` 方法清单、与 PTY 的分工	第三节
后台命令	`background=True`、`getHost`、进程连接与终止、命令超时默认 60 秒	第三节
PTY	`pty.create` / `send_stdin` / `wait` / `resize` / `connect`、何时该用 PTY	第三节
读写文件	方法清单、批量写入、二进制与流、目录监听	第三节
上传和下载文件	`uploadUrl` / `downloadUrl`、`secure=false` 要求、选型建议	第四节
自定义元数据	不支持文件自定义元数据、失败行为、三条替代方案	第四节

Code Interpreter

页面	内容	本文位置
Code Interpreter 概览	Code Interpreter 能力总览	第三节
使用 Code Interpreter Sandbox	四步推荐流程、固定脚本入口优于 `run_code`、六条上线建议	第六节

模板

页面	内容	本文位置
内置模板	三个内置模板清单、哪些需要自行构建、如何查看	第六节
base 模板	功能特性、默认配置（2 vCPU / 2048 MB）、不传 template 时的默认值	第六节
code-interpreter-v1 模板	默认端口 5000、24 小时上限、空闲超时下限、`run_code` 参数与默认超时、上下文管理仅 Python	第三、六节
browser 模板	镜像与规格、CDP / VNC 端点、`X-Access-Token`、窗口尺寸烤镜像、构建与验证	第六节
All-In-One 模板	与 browser 的差异、3000 + 5000 双端口、跨地域构建会失败	第六节
使用 Browser Use Sandbox	八步推荐流程、Puppeteer 示例、BrowserUse 接入、六条上线建议	第六节
使用 AIO Sandbox	浏览器 + 代码执行协同流程、固定任务目录、接入建议	第六节
快速开始（模板）	`Template.build` 用法、从模板创建沙箱	第六节
模板名称与版本	命名建议、标签 `assignTags` / `getTags` / `removeTags`、`default` 不可删	第六节
构建自定义镜像模板	ACR EE 前置条件、镜像要求表、官方镜像地址、构建脚本	第六节
其他模板（Desktop / Claude Code / OpenClaw 等）	需从对应官方镜像自行构建	第六节（未展开）

FC Extensions

页面	内容	本文位置
FC Extensions 概览	七项扩展、五步使用方式、注意事项	第七节
VPC 网络配置	`fc.sandbox.network.vpc` metadata 格式、前置条件、连通性验证、常见问题	第七节
动态挂载 OSS	`fc.sandbox.storage.oss` + `fc.sandbox.auth.role`、挂载字段、RAM Policy 建议	第七节
自定义域名	控制链路 / 数据链路域名、证书与私钥要求、DNS 配置、五步验证	第七节
监控与日志	配置入口与生效范围、结构化日志、常见观测对象	第四、七节
Team 配额管理	POP SDK + AK/SK 鉴权、配额模型、四个接口、RAM 授权、错误码	第七节
配置 RAM 用户权限	两套鉴权方式的边界、`fcsandbox` action 与 ARN 格式、三种授权粒度、常见误区	第一节
创建 Team	创建 Team、获取 Team ID、资源组与订阅计划	第一节
Team 与订阅计划	Team 与订阅计划的关系	—
创建 OSS Volume	为 OSS Bucket 或子目录创建可复用挂载配置	—
创建 AgenticFS Volume	为 AgenticFS Access Point 创建可复用挂载配置	—

总结

几点收获：

1. 「协议兼容」比「接口兼容」值钱得多。 三个环境变量就能跑通，是因为它兼容的是数据面协议，而不是照着表抄了一遍方法名——这也是 Java / Go SDK 能被第三方写出来的前提。代价是你得把 SDK 版本钉住，因为协议对齐是跟着版本走的，而且 Python 与 TypeScript 的参数名和单位还不一样。

2. 兼容清单要当成契约读，重点看「受限」和「暂不兼容」那两档。 「能调用」不等于「有效果」。Logs 返回空数组、Network Config Update 返回成功但不生效，这两个如果只看方法名不看文档，最后会以「线上偶发空白」和「改了没反应」的形式还给你。

3. 默认值是这个系统里最需要审计的东西。 通用 SDK 不传模板落到 base（没有 Code Interpreter）、命令超时默认 60 秒、Snapshot 请求超时默认 60 秒但它要跑好几分钟、Snapshot 默认保留 7 天、secure 默认要求带 token——这五个默认值凑在一起，就是一个「Demo 能跑、生产出事」的配置集合。 文档里专门写了「不要无条件重试」，这种提醒通常意味着它真的发生过。

4. 静默失败比报错更贵。 这次真正花时间的坑，基本都不抛异常。metadata 那个算厚道的——至少在发请求前把你拦下来了；secure 和 Network Config Update 连拦都不拦。判断一个兼容层成熟不成熟，可以看它有多少能力是「返回成功但什么都没做」。

5. 跨语言抄示例是新的高频错误源。 timeout 秒 vs timeoutMs 毫秒、api_key vs apiKey、make_dir vs makeDir、get_tags 要传模板 ID 而 TS 传模板名、TS 里模板是第一个位置参数但没模板时 options 又跑到第一位——同一个功能两套写法，而 SDK 不会因为你传错字段名报错，只会用默认值继续跑。这类错误的共同特征是不报错，所以只能靠纪律防。

6. 「兼容」两个字的颗粒度，比你想的细。 同一个 Code Interpreter，run_code 在两种语言里都通，但上下文管理只有 Python 有；同一个 Snapshot，创建和恢复能用，命名和删除路径又和官方不同。迁移检查表要按「方法 × 语言 × 平台」三维核对，不能按模块粗过。

7. 白名单能力不要写进架构。 pause、Snapshot、Team 配额都要加白。能开不代表一直在，当成设计前提就是把可用性挂在别人的后台配置上。

8. 云沙箱的差异化在 E2B SDK 之外。 真正的增量是 FC Extensions——VPC、OSS、自定义域名、日志、配额。如果你的场景需要这些，那这套东西的价值远不止「国内能连上的 E2B」；如果不需要，它就成了架构里一块只属于这朵云的代码。

9. 同一朵云里并存两套鉴权，是新的认知负担。 API Key 管数据面，RAM 权限策略管控制台和 OpenAPI，管配额还要再叠一层 AK/SK。它们报的错长得几乎一样（401 / 403），但该修的地方完全不同。排查任何「没权限」之前，先确认自己走的是哪条链路——我这次的弯路，就是从「以为只有一套凭证」开始的。还有一个附带结论：fcsandbox 这种新服务不在 RAM 可视化编辑器里，是正常现象，不是你的账号有问题。

10. 顺手再提醒一次地域。 E2B_API_URL、E2B_DOMAIN、模板、Sandbox 必须同地域；镜像仓库、VPC、自定义域名也都要同地域。这条排在最前面，也最容易在第一次接入时踩到，因为它和「Key 填错了」的现象几乎一样——都是认证或创建失败，而人的第一反应通常是去查 Key。

Agent 沙箱选型指南：隔离边界、产品对比与判断标准

Wed, 02 Sep 2026 18:00:00 +0800

事情是这样的。

这两天我在给自己的通用 Agent Runtime 加代码执行能力。

前面都挺顺，模型接上了，文件能传了，多轮对话也存进 SQLite 了。然后我顺手看了一眼 Deep Agents 里面的 LocalShellBackend，发现只要换掉一行代码，Agent 就能直接运行 Shell。

那一瞬间确实有点爽。

前一秒它还只是个会聊天、会读文件的脑子，后一秒它就能写 Python、跑测试、装依赖、改项目。像是给一个飘在空气里的灵魂，突然塞进去一双手。

然后我又顺手看了一眼它的底层实现。

subprocess.run(
 command,
 shell=True,
 cwd=str(self.cwd),
)

我当时就冷静了。

这哪是什么沙箱。

这分明是把我 Mac 的终端密码写在纸条上，然后递给了一个会自己做决定的 AI 牛马。。。

它当然能干活。但它也能读我的 .env，能翻 SSH Key，能删文件，能装软件，能访问网络。只要一次 Prompt Injection，一份被投毒的 README，或者模型单纯抽了一下风，事情就可能从「帮我跑个测试」变成「哥们你项目怎么没了」。

所以我开始认真研究 Agent 沙箱。

研究完以后，我发现这个领域最容易让人误解的地方，不是产品太少，而是大家把四五种完全不同的东西，全叫成了 Sandbox。

有的只是限制 Python 能调用哪些函数。

有的是共享宿主机内核的容器。

有的是一秒钟启动一台微型虚拟机。

还有的干脆给 Agent 准备了一台可以暂停、快照、分叉的云电脑。

名字都一样，安全边界差得十万八千里。

这篇文章，我就想把这件事彻底聊清楚。

不一定全对，我自己也还在给 Runtime 做选型。但至少下次再看到「安全执行任意代码」这几个字，我们可以先别急着信，先问一句。

你这个安全，到底安全在哪？

先把一个最大的误会拆掉。

工作目录，不等于沙箱。

很多 Agent 框架会让你配置一个 workspace，然后告诉模型，所有文件都在这个目录里操作。听起来像是给它圈了一块地，但如果底层只是普通的 subprocess，这个目录通常只决定命令从哪里开始运行。

Agent 依然可以执行 cd ..，可以读取绝对路径，也可以访问整个网络。

chroot 不是完整沙箱，Python 虚拟环境不是沙箱，Conda 不是沙箱，给 Agent 单独建个文件夹更不是沙箱。

甚至 virtual_mode=True 这种路径限制，也只能约束框架提供的 read_file 和 write_file。一旦 Agent 拿到了 Shell，它直接执行 cat ~/.ssh/id_ed25519，前面的路径规则就跟门口贴的「闲人免进」差不多。

LocalShellBackend 也一样。

它很适合你在完全可信的个人开发环境里快速试验，因为简单，快，而且没有云端延迟。但 Deep Agents 自己在源码里写得很直白，它没有进程隔离，没有资源限制，命令直接以当前用户权限在宿主机运行。

所以它是执行器，不是沙箱。

这句话可以记一下。

能执行代码，和能安全执行代码，中间隔着一整套基础设施。

那一套基础设施至少要回答5个问题。

Agent 能看到哪些文件，能不能碰宿主机，能不能访问网络，能拿到哪些密钥，CPU、内存、进程数和执行时间有没有上限。

少回答一个，那个洞以后都可能变成事故入口。

最轻的一层，是语言级沙箱。

典型代表是 WebAssembly、Wasmtime、Deno 权限系统，还有一些基于 QuickJS、Pyodide 的代码解释器。

这类方案不是给 Agent 一台完整电脑，而是给它一个能力受限的语言运行时。

以 Wasmtime 为例，WebAssembly 代码默认拿不到宿主机文件、网络和系统调用。它想读某个目录，宿主程序必须通过 WASI 明确把这个能力交给它。官方把这套模型称为 capability-based security，也就是你不给钥匙，它连门在哪里都不知道。Wasmtime Security

Deno 也有类似的味道。默认情况下，程序不能随便读文件、访问网络、读取环境变量或者启动子进程，必须显式添加 --allow-read、--allow-net、--allow-env 这类权限。Deno Permissions

这类沙箱最大的优点就是轻。

启动快，资源开销小，很适合让 Agent 做公式计算、数据转换、运行一小段 JavaScript 或 Python 子集。你有10万个用户，每个人偶尔让 AI 算个表格，没必要给每个人启动一台 Linux 虚拟机。

但限制也非常明显。

真实的软件工程世界，根本不是一个纯函数。

Agent 可能要运行 git，装 npm 包，调用 ffmpeg，编译 Rust，起一个 PostgreSQL，再用 Playwright 打开浏览器。到了这一步，语言级沙箱很快就会开始劝退你。

不是它不安全，而是它太安全了。

安全到很多活干不了。

所以我的判断很简单。如果你的 Agent 只运行短小、单语言、输入输出明确的代码，Wasm 或受限解释器非常香。如果你想做 Claude Code、Codex 这类真正的软件工程 Agent，就别硬拗了，直接往完整 Linux 环境走。

再往上一层，是容器。

也就是大家最熟悉的 Docker。

Docker 通过 Linux Namespace 隔离进程、网络和挂载点，再用 cgroups 限制 CPU、内存和 I/O。相比在宿主机直接跑 subprocess，已经安全了太多。Docker 官方的安全文档也把 Namespace、cgroups、Capabilities、seccomp 和 AppArmor 这些能力列为主要防线。Docker Engine Security

而且它真的太方便了。

一个 Dockerfile 就能把 Python、Node.js、浏览器和项目依赖钉死。镜像可以缓存，容器可以秒级创建，出了问题直接删掉重来。对本地开发、CI 和内部可信 Agent 来说，性价比高得离谱。

但普通 Linux 容器有一个绕不开的问题。

它和宿主机共享内核。

这就像酒店里每个房间都有自己的门锁，但大家共用同一套地基和管道。大多数时候完全够用，可一旦攻击者找到内核漏洞或容器配置错误，边界就可能被打穿。

如果你想保留容器的使用方式，又不想让应用直接面对宿主机内核，中间还有 gVisor 这条路。它用一个由 Go 编写的用户态应用内核拦截系统调用，Docker 和 Kubernetes 仍然可以通过 OCI Runtime runsc 来运行容器。代价也很直接，系统调用多的程序会慢一点，部分 Linux 能力不完全兼容。What is gVisor

所以 gVisor 很像夹在普通容器和虚拟机之间的一层。比共享内核的原生容器多一道墙，又没有完整虚拟机那么重。

更危险的往往还不是内核漏洞，而是我们自己手欠。

为了让 Agent 能构建镜像，顺手把 /var/run/docker.sock 挂进容器。

为了方便改代码，直接把整个项目甚至用户目录读写挂载进去。

为了少处理几个权限问题，加一个 --privileged。

好家伙。

三板斧下去，沙箱基本只剩图标了。

Docker 官方也明确提醒，能控制 Docker daemon 的用户，本身就拥有接近宿主机 root 的能力。因为它完全可以创建一个容器，再把宿主机根目录挂进去。Docker daemon attack surface

如果你只是做个人开发，Docker 容器依然是一个很现实的起点。但至少要做到非 root 用户、只挂载必要目录、禁止 privileged、不挂 Docker Socket、默认断网、限制 CPU 和内存、设置超时、执行后销毁。

一开始可能会有点烦。

尤其依赖缓存、文件同步、Git 权限这些东西，搞起来很容易让人想直接 chmod 777 然后躺平。但你相信我，沙箱配置里每一次为了省事而开的口子，最后都会变成 Agent 最自由发挥的地方。

比较骚的事来了。

就在很多人还把 Docker 容器当成 Agent 沙箱的时候，Docker 自己已经推出了一个就叫 Docker Sandboxes 的产品。

它不是普通容器套壳，而是给每个编码 Agent 启动独立的 microVM。每个沙箱有自己的内核、文件系统、网络和 Docker Engine，Agent 可以在里面 sudo、装包、跑 Compose，但碰不到宿主机的 Docker daemon。Docker Sandboxes

而且它已经直接支持 Claude Code、Codex、Copilot、Cursor、Gemini、OpenCode 等一堆 Agent。Supported agents

对本地开发者来说，这个方向我是真的觉得很对。

以前你要安全运行 Codex，大概有两个选择。要么自己折腾 Docker 和一堆安全参数，要么把代码扔给远程沙箱。现在变成一句命令。

sbx run codex

微虚拟机里甚至还有一套独立 Docker Engine。Agent 要构建镜像、起数据库、跑 Docker Compose，都在那台 VM 里面折腾。炸了也是炸自己的小房间，不会把宿主机 Docker 一锅端。

但这里有一颗非常值得提醒的雷。

Docker Sandboxes 默认会把当前工作区直接读写挂进 VM。Agent 在里面删除代码，你宿主机上的代码也会同步消失。官方提供 --clone 模式，让 Agent 在 VM 内的私有副本工作，原仓库只读挂载，但这不是默认值。Docker Sandboxes Security

所以真要用，我会优先开 clone 模式。

另外它默认禁止未授权的出站 TCP，凭证通过宿主机代理注入，请求发到被允许的域名时才补上真实密钥。这个设计非常关键，因为密钥压根不以明文进入沙箱。Docker Sandbox Credentials

这也是我研究这圈产品以后越来越在意的一条标准。

一个沙箱如果把 API Key 塞进环境变量，然后告诉我「放心，环境是隔离的」，我会打一个问号。

因为 Prompt Injection 不需要逃逸沙箱。Agent 自己就能执行 env，然后把 Key 发出去。

真正更稳的做法，是让密钥永远留在沙箱外面，由受控代理在指定域名的请求出口临时注入。

墙是一层。

不把金库钥匙放进墙里，是另一层。

如果要把这种微虚拟机能力做成云 API，最知名的玩家之一就是 E2B。

E2B 用 Firecracker microVM 运行沙箱。它的架构文档里讲得很细，每个 Sandbox 是一个有独立内核的 Linux 微虚拟机，模板会提前启动并做内存、磁盘和 VM 状态快照。创建沙箱时不是从零开机，而是恢复快照，文件系统再用 Copy-on-Write，只拉取真正访问到的数据。E2B Architecture

所以它能同时拿到两个以前看起来有点冲突的东西。

虚拟机级隔离，和接近容器的启动速度。

E2B 的产品心智也特别清晰，就是给 Agent 一台临时 Linux 电脑。你可以运行 Shell，可以读写文件，可以自定义模板。如果只是做数据分析，还有单独的 Code Interpreter SDK，直接运行 Python 或 JavaScript，并返回图表和执行结果。项目本身开源，也支持自托管。E2B GitHub

如果你正在做一个模型无关的代码解释器、数据分析 Agent，或者需要大量短生命周期环境，E2B 很顺手。

它的问题也很现实。

这是远程环境，文件要上传，结果要下载，每次工具调用都有网络延迟。自托管虽然开源，但底下是 Firecracker、网络、快照、调度、对象存储和一整套控制面，绝不是周五下午 docker compose up 一下就能收工的东西。

我自己看完它的架构，只剩一个感受。

可以自己部署，和适合自己部署，完全是两回事。。。

Daytona 和 E2B 看起来很像，但气质不太一样。

E2B 更像给 AI 应用提供一个通用的安全执行层。Daytona 更像是给 Agent 准备完整、可组合、可长期工作的开发机。

Daytona 官方把 Sandbox 描述为拥有独立内核、文件系统、网络栈和 vCPU、内存、磁盘配额的计算环境，支持 Python、JavaScript、TypeScript、Shell、持久化会话和快照。Daytona Documentation

它比较打动我的一个设计，是 Secret 不一定要真的进入 Sandbox。

Daytona 可以在沙箱里只放一个占位 Token，出站 HTTPS 请求经过代理时，只有目标域名命中允许列表，代理才把占位符替换成真实密钥。沙箱里的代码看不到明文，日志里也不该出现明文。Daytona Secrets

这个能力对企业内部 Agent 特别重要。

因为很多 Agent 不是只跑一段 Python，它要拉私有仓库、访问内部 API、查数据库。你不可能永远断网，但你也绝对不想把一个万能 Token 塞给它。域名绑定的代理注入，至少把「能使用凭证」和「能偷走凭证」分开了一点。

Daytona 还支持有状态解释器、后台 Session、PTY 和长进程，比较适合 Coding Agent、数据流水线，以及需要多轮保留环境的任务。Daytona Process Execution

如果你的 Agent 工作方式像一个工程师，要在同一台机器上连续干几十分钟甚至几小时，我会重点看 Daytona。

再往工程师工作站这个方向走，就是 Runloop。

它把沙箱叫 Devbox。

这个名字其实很诚实，因为它提供的已经不只是安全执行一段代码，而是一台面向 Agent 的云开发机。可以拉仓库、编译代码、跑浏览器、保留状态、暂停恢复，还能使用自定义 Blueprint 和 Snapshot。Runloop Devbox

Runloop 最有意思的场景，是分叉。

假设 Agent 面前有3种修 Bug 的方案。你可以先给当前磁盘做一个快照，再从同一个快照启动3台 Devbox，让3个 Agent 各走一条路，最后跑测试选最好的那一个。Runloop Snapshots

这一下就不只是安全问题了。

沙箱开始变成 Agent 的时间机器。

可以回滚，可以复制，可以并行探索。以前工程师在 Git 分支上做的事，现在整个操作系统状态都能分支。

当然，能力越完整，成本和生命周期治理就越重要。快照如果不清理，会一直占存储。长生命周期 Devbox 如果忘了暂停，账单也会用自己的方式提醒你什么叫长期记忆。

所以 Runloop 更适合复杂 Coding Agent、自动修复、代码评测和并行实验，不是拿来算 1+1 的。

Modal 又是另一种气质。

它本来就是 Serverless AI 基础设施，Sandbox 只是其中一个能力。所以它特别适合需要弹性并发、定制镜像，甚至 GPU 的 Agent 任务。

Modal Sandbox 可以动态创建容器，执行任意命令，保留同一沙箱里的状态，设置超时，也可以挂载 Volume。官方甚至专门给了 Claude Code 和 LangGraph Coding Agent 的完整例子。Modal Sandboxes

比较夸张的是，你可以直接给 Agent 的沙箱挂一张 T4，让它在里面跑模型或处理视频。Modal LangGraph Agent

如果你的 Agent 要做的是普通代码解释，Modal 可能有点像开跑车送外卖。

但如果任务是视频生成、模型推理、GPU 数据处理，或者突然并发出几千个沙箱，Modal 的基础设施属性就出来了。它不是最纯粹的 Agent Sandbox 产品，但它是一个很强的通用计算平台。

这块选型其实看任务，不看名气。

要一台会长期工作的开发机，看 Daytona、Runloop。

要大量短时解释器，看 E2B、Deno Sandbox。

要 GPU 和 Serverless 弹性，看 Modal。

Deno Sandbox 是最近让我有点惊喜的一个新选手。

它不是前面讲的 Deno 语言权限系统，而是真正的 Linux microVM。官方文档显示，每个沙箱都在 Hypervisor 层隔离，毫秒级启动，可以执行命令、使用持久卷，并且默认是临时环境。Deno Sandbox

它在安全设计上也比较激进。

出站网络可以做严格策略，Secret 不进入环境变量，只在访问批准域名时由平台替换，而且会做结果脱敏。Deno Sandbox Security

目前它更像一个快速发展的新产品，默认资源和会话时长有明确限制，区域也不像成熟云厂商那么广。但对于 TypeScript、Deno 生态和边缘应用来说，它非常值得关注。

顺便说一句，这里特别容易混淆。

deno run 的权限沙箱，是语言级能力控制。

Deno Sandbox，是云端 Linux microVM。

一个名字，两层边界。

买东西之前真的得看说明书，不然很容易拿到一把儿童安全剪刀，然后以为自己租了一间银行金库。

如果公司已经深度在 AWS 里，Amazon Bedrock AgentCore Code Interpreter 会更顺。

它提供托管的 Python 执行环境，能做计算、数据分析、可视化和结果校验。网络可以选择 Sandbox、Public 或 VPC 模式，访问 AWS 资源则由 IAM Role 控制。AgentCore Code Interpreter

它的优势不是「最适合所有 Agent」，而是 AWS 那套治理能力。

IAM、VPC、Security Group、CloudTrail、企业账户、合规控制，这些东西一旦进了大公司，比单纯启动快几十毫秒重要得多。Agent 要访问 S3、EFS、内部数据库，也有一条相对原生的路。

但 AWS 的代价大家也懂。

概念多，配置多，权限策略写着写着，人会逐渐进入一种我是谁我在哪的哲学状态。

LangSmith Sandbox 也属于生态型选择。它和 LangGraph、Deep Agents 的衔接自然，支持命令、文件、端口隧道和工作区权限。但截至我写这篇文章时，官方文档仍标记为 Private Preview，所以更适合已经重度使用 LangSmith、愿意跟着产品一起迭代的团队。LangSmith Sandbox Permissions

聊了这么多，我做了一张尽量不骗人的表。

方案	隔离边界	最适合什么	最明显的短板
LocalShellBackend	没有隔离	可信个人实验	直接执行宿主机命令
Wasm、受限解释器	语言运行时	短代码、计算、转换	系统工具和依赖受限
普通 Docker	共享内核容器	本地开发、CI、可信内部任务	配置不当容易穿透边界
Docker Sandboxes	本地 microVM	Codex、Claude Code 等编码 Agent	默认直挂工作区仍有风险
E2B	云端 Firecracker microVM	Code Interpreter、短时 Agent 任务	远程延迟，自托管复杂
Daytona	云端隔离开发环境	有状态 Coding Agent、企业内部 Agent	引入外部平台与费用
Runloop	云端虚拟 Devbox	长任务、快照分叉、并行修复	生命周期和存储治理更重
Modal	Serverless 隔离容器	高并发、GPU、定制计算	对简单解释器可能偏重
Deno Sandbox	云端 Linux microVM	快速临时环境、Deno 与 TS 生态	产品较新，资源与区域有限
AgentCore	AWS 托管解释器	AWS 企业环境、VPC 与 IAM 集成	云绑定和配置复杂度高
LangSmith Sandbox	LangChain 托管沙箱	LangGraph、Deep Agents 团队	当前仍处预览阶段

如果屏幕前的你，现在就在做自己的 Agent，我自己的不成熟建议是这样。

个人在 Mac 上玩 Coding Agent，先看 Docker Sandboxes，尽量用 --clone，别让 Agent 直接改宿主机工作区。只是偶尔跑一点可信代码，硬化后的 Docker 也够用。

做一个面向用户的 Code Interpreter，优先试 E2B、Deno Sandbox，或者 Daytona。先把文件上传、命令执行、超时、结果下载这条链跑通，再考虑自建。

做企业内部 Coding Agent，看 Daytona、Runloop，或者你所在云厂商的托管方案。重点不是 Demo 跑得多快，而是身份、审计、网络、密钥和数据驻留能不能交代清楚。

需要 GPU、高并发和复杂镜像，看 Modal。

已经全家桶 AWS，就认真评估 AgentCore，别为了技术洁癖硬造一套 IAM 和 VPC。

至于自己用 Docker 或 Firecracker 搭一套，我不是说不行。

但你得诚实评估一下，你到底是在做 Agent 产品，还是准备顺便创业做一家云计算公司。

最后再说几个我觉得比产品名字更重要的判断标准。

沙箱是不是每个用户、每个 Thread 独立。不同用户共用一个长生命周期环境，文件和进程串了，那就不是记忆，是串门。

网络是不是默认拒绝。只要默认全网可达，Prompt Injection 就有了天然的数据出口。

密钥是不是明文进环境变量。最好由外部代理按域名注入，而且日志、错误信息和响应都要脱敏。

宿主机目录是不是直接读写挂载。尤其 .git/hooks、CI 配置、IDE Task、.claude、.codex 这些文件，有些改动甚至不会出现在普通 git diff 里。

有没有 CPU、内存、磁盘、PID、输出大小和墙钟时间限制。超时只杀父进程不杀进程组，也可能留下一窝后台孤儿。

有没有快照和销毁策略。沙箱太短，装一次依赖等半天。沙箱太长，污染、成本和跨任务泄漏一起上来。

有没有完整审计。谁在什么时间，以哪个 Agent 身份，执行了哪条命令，读写了哪些文件，访问了哪个域名，最后退出码是什么。

还有一个经常被忘掉的点。

沙箱防得住代码逃到宿主机，但防不住 Agent 在沙箱里做坏事。

如果网络是开放的，Agent 仍然可以把用户上传的文件发走。如果你把数据库密钥放进去，它仍然可以把库删掉。如果它能调用宿主机上的高权限 MCP，那个 MCP 就是墙上新开的一扇门。

所以沙箱从来不是一句「安全了」。

它只是把事故半径，从整台电脑，缩小到一个可控房间。

我写到这里，突然想起计算机安全里一个特别老的原则，最小权限。

这个词听起来一点都不性感，甚至有点像公司安全培训里最容易被跳过的那页 PPT。

但 Agent 时代，它突然变得非常具体。

以前的软件权限是开发者写死的。一个图片处理程序，正常情况下不会突然决定去翻你的 SSH Key。

Agent 不一样。

它的能力边界是动态的，它会读新的内容，会形成新的计划，会把几个看起来无害的工具串起来。模型越聪明，越能自己找到完成目标的路，也越需要我们提前决定，哪些路从物理上就不应该存在。

这有点像养一只特别聪明的哈士奇。

你不能把家门钥匙、银行卡和电锯全扔给它，然后靠 System Prompt 写一句「你是一只可靠、简洁、不会拆家的狗」。

它今天不拆，不代表这套系统是安全的。

真正的安全，是它就算想拆，也只能拆自己的玩具屋。

回到我最开始那行 subprocess.run。

代码还是那几行，Agent 也还是那个 Agent。但当它从宿主机 Shell 被放进一个有独立文件系统、受控网络、外置密钥和资源上限的沙箱以后，它才真正从一个危险的 Demo，开始有了一点产品的样子。

手，是给了。

笼子，也得跟上。

大时代啊，朋友们。

以上，既然看到这里了，如果觉得不错，随手点个赞、在看、转发三连吧，如果想第一时间收到推送，也可以给我个星标⭐～

谢谢你看我的文章，我们，下次再见。

Agent 用户记忆与 Skill 沉淀：开源项目参考与架构设计

Mon, 31 Aug 2026 18:00:00 +0800

当 Agent 可以替换、模型持续升级时，真正应该长期留在平台中的，不是某个 Agent 的私有会话状态，而是用户拥有的资料、记忆和可复用 Skill。

目前还没有一个开源项目同时做好跨 Agent 用户记忆、来源追溯、权限、删除、Skill 版本、评测和发布治理。比较现实的路线是组合借鉴：用成熟项目解决提取、检索和加载问题，由平台自己负责资产归属与治理。

本文回答三个问题：

用户记忆可以参考哪些项目？
Skill 应该如何沉淀、加载和演进？
如何把这些机制组合成一个面向生产环境的 Agent Harness？

1. 先区分 Memory、Experience 和 Skill

长期数据不应全部塞进一个向量库。更清晰的分类是：

类型	回答的问题	推荐资产
Semantic Memory	用户是谁、偏好什么、有哪些稳定事实？	`MemoryItem`
Episodic Memory	过去发生了什么、结果如何？	`Run / Event / Outcome / Experience`
Procedural Memory	怎样做某件事更可靠？	`SkillCandidate / SkillVersion`

LangGraph 的长期记忆概念也采用 semantic、episodic、procedural 分类，并区分交互热路径写入与后台写入。参考：LangGraph Memory Overview。

这个边界很重要：用户偏好不是 Skill，一次成功运行也不是 Skill。只有经过抽象、验证、去除个案数据并且能够复用的过程，才适合晋升为 Skill。

2. 用户记忆项目对比

项目	擅长什么	值得借鉴	不宜直接照搬
Mem0 / OpenMemory	结构化提取、检索和 Memory CRUD	scope、变更历史、过滤删除、混合检索	Agent 可直接修改正式记忆，治理层较弱
Letta / MemGPT	分层记忆和后台整理	Memory Block、共享记忆、sleep-time consolidation	记忆通常围绕 Agent 组织
Zep / Graphiti	时间变化的事实和关系	Episode、Entity、Relation、valid time	第一阶段直接引入图数据库成本较高
LangGraph / LangMem	记忆分类和写入时机	semantic/episodic/procedural、hot/background write	是组件工具箱，不是完整治理系统

2.1 Mem0：参考第一版 API 和检索流水线

Mem0 的典型流程是：

Conversation
 → 提取事实或偏好
 → 判断 ADD / UPDATE / DELETE / NOOP
 → 按 user / agent / run 等 scope 保存
 → 向量或图检索

它已经提供更新、删除、历史和反馈等实际能力。更新操作可以纠正旧事实；删除支持按用户、Agent、Run 和 metadata 过滤，并对无过滤条件的全量删除增加保护。参考：Mem0 Update Memory、Mem0 Delete Memory。

适合借鉴的部分包括：

标准化的 add/search/update/delete/history 能力；
用户、应用、Agent 和 Run 等检索 namespace；
提取、冲突判断与索引更新分离；
显式批量删除和防误删设计；
用 feedback 修正后续记忆。

生产平台应在 Mem0 之上增加治理层。模型不能直接执行正式的 ADD/UPDATE/DELETE，而应先提交候选：

MemoryCandidate
 → policy / user review
 → MemoryRevision
 → active MemoryItem projection

2.2 Zep / Graphiti：参考会变化的事实

Graphiti 使用时间知识图谱保存动态上下文，主要对象包括：

Episode：原始会话、文档或业务事件；
Entity：用户、组织、项目、地点等实体；
Relation/Fact：实体之间的关系与事实；
时间信息：事实何时观察到、何时有效、何时失效。

Graphiti 支持增量更新，不要求每次重新批处理全部历史。参考：Graphiti 官方介绍、Zep Graph 数据模型。

例如，下面两条偏好不应该简单覆盖：

2026-01：用户优先海运
2026-06：用户现在优先空运

更合理的表达是：

Preference("shipping_mode", "sea")
valid_from = 2026-01
valid_to = 2026-06

Preference("shipping_mode", "air")
valid_from = 2026-06
valid_to = null

第一版不一定需要图数据库，但数据模型应预留：

observed_at
valid_from / valid_to
supersedes_memory_id
contradicts_memory_id
source_refs
status=active/superseded/disputed/retracted

否则长期记忆很容易退化成不断被覆盖、无法审计的用户画像 JSON。

2.3 Letta：参考分层上下文和后台整理

Letta 将一部分长期状态组织成持续出现在上下文中的 Memory Block，并允许多个 Agent 共享 Block。参考：Letta Memory Blocks。

它提出的 sleep-time compute 也很有价值：主 Agent 完成交互后，由后台 Agent 整理、压缩和重构记忆，把高延迟的 consolidation 移出用户交互路径。参考：Letta Sleep-time Compute。

可以映射成下面的后台流水线：

Run completed
 → Candidate extraction
 → contradiction detection
 → clustering / deduplication
 → sensitivity classification
 → user or policy review
 → index refresh

需要注意的是：Canonical Memory 应属于用户或组织，而不是某个 Agent。Agent 只能通过当前 Run 的授权 ContextPack 获得只读快照。

3. Skill 沉淀项目对比

3.1 Agent Skills：作为可携带交换格式

Agent Skills 使用一个简单目录表达可复用能力：

my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

它采用 Progressive Disclosure：

启动时只暴露名称和描述；
任务匹配时加载完整 SKILL.md；
执行时才按需读取脚本、参考资料和资源。

这样可以让大量 Skill 共存，而不必把所有指令一次性塞入上下文。参考：Agent Skills 规范、Anthropic Agent Skills。

推荐把 Agent Skills 当成导入、导出和适配器交付格式，而不是平台事实源：

SkillVersion（平台事实源）
 ↓ build / export
Agent Skills bundle（可携带交换格式）
 ↓ adapter
Codex / Claude / OpenHands / 自有 Agent

平台内部继续维护不可变 SkillVersion，每个版本可以构建成标准 Skill Bundle，并带有 checksum、依赖、权限和兼容性信息。

3.2 OpenHands：参考多级作用域和加载优先级

OpenHands 支持项目级、用户级、组织级和全局 Skill，并区分 always-on instructions 与按需加载 Skill。参考：OpenHands Skills。

平台可以采用类似作用域：

platform baseline
 < organization Skill
 < workspace or project Skill
 < user Skill
 < Run explicitly selected Skill

但不能只用“同名文件覆盖”处理冲突。每次 Run 应记录：

实际选择的 SkillVersion；
选择原因：用户指定、规则匹配或 Agent 请求；
匹配分数与被排除原因；
依赖解析结果；
实际注入的文件和 token 成本；
执行过的脚本、工具和权限。

这些信息应成为 ContextPack 和 Run Evidence 的一部分。

3.3 Voyager：参考从成功轨迹生成 Skill

Voyager 在任务执行成功并通过验证后，将可复用实现抽象进 Skill Library；新任务再根据描述检索、组合已有 Skill。Skill Library 是它实现跨任务泛化的重要部分。参考：Voyager 论文。

值得借鉴的机制包括：

只从经过验证的成功轨迹中蒸馏；
Skill 具有明确描述、前置条件和适用场景；
新 Skill 与已有 Skill 做相似性和能力重叠检查；
Skill 可以组合，但依赖必须显式；
失败用于修复候选，不直接污染正式 Skill 库。

4. 推荐的双流水线设计

Memory 和 Skill 可以共享来源追踪、Review 和 Eval 基础设施，但生命周期不能混在一起。

4.1 Memory Pipeline

Run / Event / Artifact
 → MemoryCandidate
 → Review or low-risk policy
 → MemoryRevision
 → MemoryItem projection
 → Retrieval evaluation

MemoryItem 不应原地覆盖，推荐使用“不可变 Revision + 当前投影”：

MemoryItem
- id
- owner_scope
- memory_kind
- active_revision_id
- status

MemoryRevision
- id
- memory_id
- content
- structured_claim
- source_refs
- confidence
- sensitivity
- observed_at
- valid_from / valid_to
- created_by
- decision
- supersedes_revision_id

纠正时创建新 Revision，旧版本保留审计但不再进入新的 ContextPack。删除还应区分：

Logical retraction：禁止召回，但保留必要审计记录；
Physical purge：清除正文、embedding、缓存、图索引和派生副本；
Tombstone：只保留不能反推出原文的删除证明。

4.2 Skill Pipeline

Successful Run + Outcome + Ground Truth
 → SkillCandidate
 → Draft SkillVersion
 → Sandbox Eval
 → Review
 → Published SkillVersion
 → Canary / rollback

一个可运行的 SkillVersion 至少需要：

SkillVersion
- instructions
- description / trigger hints
- references
- scripts / assets checksums
- tool and runtime dependencies
- required capabilities
- requested permissions
- compatibility constraints
- source run / outcome refs
- eval suite and version
- publish status
- rollback target

其中 description 不只是展示信息，它参与 Skill 召回，因此也必须版本化并接受评测。

5. ContextPack 必须说明“为什么选中”

只记录“本次用了哪条记忆和哪个 Skill”还不够。为了调试召回错误、权限问题和效果退化，建议记录检索证据：

ContextPackEntry
- asset_id / version_id
- asset_type
- selection_reason
- scope_match
- relevance_score
- recency_score
- trust / confidence
- token_cost
- policy_decision_id
- redaction_applied

这样才能回答：

为什么选中了这条记忆？
为什么另一条没有进入上下文？
是召回、重排、权限过滤还是 token budget 导致遗漏？
更换 Agent 或模型后，ContextPack 是否仍然一致？

ContextPack 应是每个 Run 的不可变授权快照，而不是 Agent 对用户资产仓库的一次开放查询权限。

6. Skill 的安全晋升路径

不要从一次成功运行直接自动发布正式 Skill。更安全的顺序是：

Observed pattern
 → Suggested procedure
 → SkillCandidate
 → Draft
 → Sandbox verified
 → Human approved
 → Published
 → Canary
 → Stable

只有同时满足以下条件，才适合创建 SkillCandidate：

至少有一次带明确 Ground Truth 的成功；
能从业务输入中移除用户个案和敏感数据；
相对已有 Skill 有新增价值；
没有扩大工具或数据权限；
有可重复执行的测试 fixture；
能明确描述适用条件和失败边界。

自动提炼可以提高效率，但发布必须由 Eval、权限检查和明确门禁控制。

7. 推荐的组合方案

没有必要选择一个框架承包全部能力。更实际的组合是：

设计领域	推荐参考
Memory API 与基础检索流水线	Mem0
时间、冲突和事实失效模型	Graphiti / Zep
后台整理与 consolidation	Letta
记忆类型和写入时机	LangGraph / LangMem
Skill Bundle 与渐进加载	Agent Skills / SKILL.md
用户、组织、项目作用域	OpenHands
从成功经验蒸馏 Skill	Voyager
发布、验证与回滚	平台自己的 Eval、Ground Truth 与 Verifier

整体架构可以概括为：

UserResource / Run / Event / Artifact
 │
 ├──→ Memory Candidate ──→ Review ──→ Memory Revision
 │ │
 │ ↓
 │ ContextPack Retrieval
 │ │
 └──→ Skill Candidate ───→ Eval ────┤
 ↓
 Authorized Agent Run

Mem0 和 Graphiti 主要解决“怎样记住和找到”，Agent Skills 解决“怎样包装和按需加载”。生产级 Agent Harness 还需要回答：

这是谁的资产、来源是什么、为什么可信、谁批准、哪个 Agent 可以使用、运行时用了哪个版本、效果是否真的改善，以及如何纠正、撤回和删除。

这些治理能力，才是用户记忆和 Skill 能够跨 Agent 长期沉淀的关键。

主流 Agent 框架对比与多框架统一接口设计

Mon, 31 Aug 2026 16:00:00 +0800

Agent 框架没有一个绝对的“最优解”。文件研究 Agent、强类型业务 Agent、确定性审批流和云厂商原生 Agent，面对的是不同问题。真正稳定的架构不是押注一个框架，而是把业务协议与框架运行时分开。

本文回答三个问题：

主流 Agent 框架分别擅长什么？
它们的输入与返回结构是否兼容？
如何让不同任务使用不同框架，同时保持统一 API？

1. 先理解 Agent 框架的层次

不同产品都被称为“Agent 框架”，但抽象层次并不相同：

业务 API / Web / App
 ↓
业务 Agent：客服、研究、抽取、编码
 ↓
Agent Harness：Prompt、Tools、Skills、Memory、Subagents
 ↓
Workflow Runtime：状态图、Checkpoint、Interrupt、恢复
 ↓
模型与工具 Provider

例如：

LangGraph 更接近可持久化的 Workflow Runtime。
LangChain create_agent 是轻量 Agent Harness。
Deep Agents 是建立在 LangChain 与 LangGraph 上的“电池齐全”Harness。
OpenAI Agents SDK 同时封装 Agent Loop、Handoff、Guardrail、Session 与 Tracing。
PydanticAI 更强调 Python 类型、依赖注入和结构化结果。

如果不区分层次，很容易拿“工作流引擎”和“开箱即用的研究 Agent”直接比较。

2. 主流框架速查

框架	核心优势	更适合	主要代价
Deep Agents	文件上下文、Skills、Subagents、沙箱、压缩	研究、编码、文档处理、长任务	默认能力多，升级时要关注 Harness 行为变化
LangGraph	状态图、Checkpoint、Interrupt、可恢复执行	确定性流程、审批、长事务	需要自己设计节点、状态和路由
LangChain `create_agent`	轻量、模型与工具生态广	普通工具调用 Agent	文件工作区和复杂编排需要自行补充
OpenAI Agents SDK	`Agent + Runner`、Handoff、Guardrail、Tracing	OpenAI 技术栈、客服、业务协作	与 OpenAI Responses 生态结合更紧
PydanticAI	强类型、依赖注入、结构化输出	FastAPI 后端、抽取、业务自动化	文件型 Harness 和复杂工作区能力较少
Google ADK	Sequential/Parallel/Loop、多 Agent、Vertex 集成	Gemini、GCP、A2A 场景	跨云项目的迁移价值要单独评估
Microsoft Agent Framework	Workflow、Memory、Middleware、Azure 托管	Azure、C#、微软企业生态	对非微软栈未必是最低成本选择

2.1 Deep Agents：长上下文任务 Harness

Deep Agents 的价值不只是“能调用子 Agent”，而是一组协同工作的默认能力：

通过虚拟文件系统保存和卸载大块上下文；
通过 Summarization 控制长对话；
用 Subagents 隔离搜索、代码执行等中间过程；
用 Skills 按需加载工作流，避免把所有规则塞进 System Prompt；
用 Backend 对接本地目录、状态存储、持久 Store 或沙箱；
继承 LangGraph 的流式执行、Checkpoint 和 Human-in-the-loop。

适合：代码 Agent、深度研究、长文档分析、需要沙箱和文件产物的任务。

不适合：只调用两三个业务 API 的简单客服。此时完整 Harness 可能比业务本身还复杂。

从 0.7.0 开始，Deep Agents 默认 Prompt 更精简，TodoListMiddleware 改为显式启用，文件 Backend 默认使用更安全的虚拟路径模式。升级旧项目时还要检查 write_file 覆盖语义和新增的递归 delete 能力。

参考：Deep Agents 官方概览、Deep Agents Changelog。

2.2 LangGraph：确定性主流程

当业务流程本身清晰时，不要把全部控制权交给模型：

输入校验 → 分类 → 检索 → 人工审批 → 执行 → 验证 → 结束

这种流程适合直接实现为 LangGraph。模型只负责需要语义判断的节点，路由、重试、上限和失败处理仍由代码决定。

推荐组合：

确定性主流程：LangGraph
开放式复杂节点：Deep Agent 或其他 Agent

2.3 LangChain `create_agent`：轻量通用 Agent

如果需求只是“模型根据问题选择工具，拿到结果后回答”，create_agent 通常已经足够。它保留 LangChain 的模型、工具和 Middleware 生态，又不强制引入完整文件工作区与子 Agent。

2.4 OpenAI Agents SDK：OpenAI 原生体验

OpenAI Agents SDK 使用 Agent + Runner 管理工具、轮次、Handoff、Guardrail 和 Session，并提供内置 Tracing。它适合：

项目主要使用 OpenAI 模型和 Responses API；
需要不同专业 Agent 之间 Handoff；
希望快速加入输入、输出和工具 Guardrail；
不想自己维护 Agent Loop。

如果需要完全跨模型、虚拟文件系统或复杂状态图，Deep Agents/LangGraph 通常更自然。

参考：OpenAI Agents SDK、Guardrails。

2.5 PydanticAI：强类型业务 Agent

PydanticAI 很适合已有 Pydantic/FastAPI 技术栈的团队：

输入依赖和运行上下文容易注入；
输出可以直接是 Pydantic 模型；
类型检查和测试体验清晰；
可结合 Temporal、DBOS、Prefect、Restate 实现 Durable Execution。

典型任务包括票据抽取、合同分类、字段补全和调用内部业务 API。它们更像“带工具的类型化服务”，不一定需要一个文件型 Agent OS。

参考：PydanticAI Durable Execution。

2.6 Google ADK：GCP 与多 Agent Workflow

Google ADK 提供 Sequential、Parallel、Loop 以及动态工作流，可以混合确定性执行节点与 LLM Agent。对于 Gemini、Vertex AI、A2A 和 GCP 托管场景，它具有明显的平台整合优势。

参考：Google ADK Workflows。

2.7 Microsoft Agent Framework：微软企业栈

Microsoft Agent Framework 覆盖 Agent、Workflow、Memory、Middleware、Checkpoint、Human-in-the-loop 和 Azure 托管，并提供 AutoGen、Semantic Kernel 的迁移路线。Azure、C# 和微软企业集成是它最自然的使用环境。

参考：Microsoft Agent Framework。

3. 它们的返回接口一样吗？

不一样。

框架	常见调用	最终结果入口
Deep Agents / LangGraph	`agent.ainvoke(...)`	`state["messages"][-1]` / `state["structured_response"]`
OpenAI Agents SDK	`Runner.run(...)`	`result.final_output`
PydanticAI	`agent.run(...)`	`result.output`
Google ADK	Runner/Event API	从事件或最终响应中提取
Microsoft Agent Framework	Agent/Workflow API	Response、Message 或 Event

差异不仅是字段名。各框架的内部对象还承载不同语义：

LangChain 有 HumanMessage、AIMessage、ToolMessage；
OpenAI Agents SDK 有 Run Item、Handoff 与原始 Response Item；
PydanticAI 有自己的 Model Message；
ADK 和 Microsoft Framework 以各自的 Event/Message 表达执行过程。

因此，不应把框架原始对象直接作为 HTTP 响应。否则前端会被某个框架绑定，切换框架时 API、流式协议和会话结构都要一起重写。

4. 统一业务协议，而不是统一框架内部

建议只统一四样东西：

请求 AgentRequest
最终响应 AgentResponse
流式事件 AgentEvent
业务会话 ID 到框架会话 ID 的映射

不要强行统一：

框架内部 Message；
LangGraph Checkpoint；
OpenAI Session/Conversation；
Provider 原始 Response；
框架专属的恢复状态。

4.1 统一请求与响应

from typing import Any, Literal, Protocol

from pydantic import BaseModel, Field


class AgentRequest(BaseModel):
 """统一的 Agent 请求。"""

 task_id: str
 message: str
 thread_id: str | None = None
 user_id: str | None = None
 context: dict[str, Any] = Field(default_factory=dict)


class Usage(BaseModel):
 """统一的模型用量。"""

 input_tokens: int | None = None
 output_tokens: int | None = None
 total_tokens: int | None = None


class AgentResponse(BaseModel):
 """与框架无关的最终响应。"""

 task_id: str
 framework: Literal[
 "deepagents",
 "langgraph",
 "openai-agents",
 "pydantic-ai",
 "google-adk",
 "microsoft-agent-framework",
 ]
 output: str
 data: dict[str, Any] | None = None
 usage: Usage | None = None
 trace_id: str | None = None
 metadata: dict[str, Any] = Field(default_factory=dict)


class AgentAdapter(Protocol):
 """所有 Agent Adapter 必须实现的业务接口。"""

 async def run(self, request: AgentRequest) -> AgentResponse:
 """运行 Agent 并返回标准结果。"""
 ...

output 用于展示给人，data 用于程序消费。结构化数据不要从自然语言中二次解析，应优先使用框架的 Structured Output 能力。

4.2 Deep Agents Adapter

from typing import Any


class DeepAgentsAdapter:
 """将 Deep Agents 状态转换成业务响应。"""

 def __init__(self, agent: Any) -> None:
 self.agent = agent

 async def run(self, request: AgentRequest) -> AgentResponse:
 config: dict[str, Any] = {}
 if request.thread_id:
 config["configurable"] = {"thread_id": request.thread_id}

 result = await self.agent.ainvoke(
 {"messages": [{"role": "user", "content": request.message}]},
 config=config,
 )
 output = result.get("structured_response")
 data = output.model_dump() if hasattr(output, "model_dump") else output

 return AgentResponse(
 task_id=request.task_id,
 framework="deepagents",
 output=str(result["messages"][-1].content),
 data=data if isinstance(data, dict) else None,
 )

4.3 PydanticAI Adapter

from typing import Any


class PydanticAIAdapter:
 """将 PydanticAI 结果转换成业务响应。"""

 def __init__(self, agent: Any) -> None:
 self.agent = agent

 async def run(self, request: AgentRequest) -> AgentResponse:
 result = await self.agent.run(request.message)
 output = result.output
 data = output.model_dump() if hasattr(output, "model_dump") else None

 return AgentResponse(
 task_id=request.task_id,
 framework="pydantic-ai",
 output=str(output),
 data=data,
 )

4.4 OpenAI Agents SDK Adapter

from typing import Any

from agents import Runner


class OpenAIAgentsAdapter:
 """将 OpenAI Agents SDK 结果转换成业务响应。"""

 def __init__(self, agent: Any) -> None:
 self.agent = agent

 async def run(self, request: AgentRequest) -> AgentResponse:
 result = await Runner.run(self.agent, request.message)
 output = result.final_output
 data = output.model_dump() if hasattr(output, "model_dump") else None

 return AgentResponse(
 task_id=request.task_id,
 framework="openai-agents",
 output=str(output),
 data=data,
 metadata={"last_agent": result.last_agent.name},
 )

5. 流式接口才是多框架适配的难点

最终结果容易统一，流式事件更难。不同框架可能输出 Token、Message、Node Update、Tool Event、Handoff、Approval 或 Artifact。

建议定义最小公共事件集：

class AgentEvent(BaseModel):
 """面向前端的统一流式事件。"""

 task_id: str
 sequence: int
 type: Literal[
 "run.started",
 "text.delta",
 "tool.started",
 "tool.completed",
 "handoff.started",
 "approval.required",
 "artifact.created",
 "run.completed",
 "run.failed",
 ]
 agent: str | None = None
 content: str | None = None
 tool_call_id: str | None = None
 tool: str | None = None
 data: dict[str, Any] = Field(default_factory=dict)

Adapter 负责映射：

LangGraph model token → text.delta
LangGraph tool node → tool.started / tool.completed
OpenAI response event → text.delta
OpenAI handoff item → handoff.started
PydanticAI text delta → text.delta
ADK function event → tool.started / tool.completed

建议使用 SSE 或 WebSocket 对外发送这些业务事件，同时将框架原始事件保存在可观测系统中，而不是全部暴露给前端。

6. 会话和恢复如何处理

不同框架的持久化机制不能直接互换：

Deep Agents/LangGraph 使用 thread_id + checkpointer；
OpenAI Agents SDK 可以使用 Session、Conversation 或 Previous Response；
PydanticAI 可以传入历史消息，长任务可接 Durable Execution；
ADK 和 Microsoft Framework 有各自的 Session/Event/Checkpoint。

业务数据库只保存映射：

class AgentSession(BaseModel):
 """业务会话与框架会话的映射。"""

 session_id: str
 framework: str
 external_session_id: str | None = None
 checkpoint_id: str | None = None
 metadata: dict[str, Any] = Field(default_factory=dict)

不要尝试把 LangGraph Checkpoint 转换成 OpenAI Session。需要迁移框架时，使用业务层保存的用户消息、结构化结果和必要摘要重新构造上下文。

7. 推荐的多框架架构

HTTP / SSE / WebSocket
 ↓
AgentRequest / AgentEvent / AgentResponse
 ↓
任务路由器
 ├── 文件与深度研究 → DeepAgentsAdapter
 ├── 确定性长流程 → LangGraphAdapter
 ├── 结构化业务任务 → PydanticAIAdapter
 ├── OpenAI 客服 → OpenAIAgentsAdapter
 └── 云厂商原生任务 → ADK / Microsoft Adapter
 ↓
框架自己的 State、Session、Tracing 和 Runtime

任务路由器不应该根据用户的一句话临时“猜框架”，而应该基于明确的任务类型、能力需求和部署策略选择：

class AgentRouter:
 """根据任务类型选择 Agent Adapter。"""

 def __init__(self, adapters: dict[str, AgentAdapter]) -> None:
 self.adapters = adapters

 async def run(
 self,
 task: str,
 request: AgentRequest,
 ) -> AgentResponse:
 adapter = self.adapters.get(task)
 if adapter is None:
 msg = f"不支持的任务类型：{task}"
 raise ValueError(msg)
 return await adapter.run(request)

8. 实际选型建议

选择 Deep Agents，如果

工具会产生大量文本或文件；
需要独立子 Agent 隔离上下文；
需要沙箱执行代码；
任务持续时间长且步骤开放；
Skills、Memory、Filesystem 是核心能力。

选择 PydanticAI，如果

输出必须严格符合业务 Schema；
Agent 是 FastAPI 服务的一部分；
依赖注入和 Python 类型体验优先；
工作流主要是调用业务 API，而不是操作文件工作区。

选择 OpenAI Agents SDK，如果

主要使用 OpenAI Responses API；
Handoff、Guardrail、Session 和 Tracing 是核心需求；
接受较强的 OpenAI 生态结合。

选择 LangGraph，如果

流程有明确状态机；
必须可靠暂停、恢复和重试；
人工审批是正式流程节点；
需要精确控制每一步，而不是让模型自由规划。

选择 ADK 或 Microsoft Agent Framework，如果

部署平台、身份、监控和企业集成本身就在对应云生态；
平台整合收益高于跨框架可移植性。

9. 最后的工程原则

框架是实现细节，业务协议才是长期资产。
统一请求、响应与前端事件，不统一内部消息和 Checkpoint。
确定性流程交给代码，开放式任务交给 Agent。
结构化输出由 Schema 保证，不要解析自然语言。
安全边界放在工具、权限和沙箱，不要只依赖 Prompt。
每种框架独立做回归评测，再决定路由策略。

一个健康的多框架系统最终应该做到：替换某个 Agent 实现时，前端 API、业务数据库和其他 Agent 都无需跟着重写。

Gliding Horse Agent OS 介绍：Rust 构建的工业级 AI Agent 操作系统

Mon, 29 Jun 2026 10:00:00 +0800

项目概览

Gliding Horse Agent OS 是由 doiito 在 GitHub 上开源的 Rust 编写的工业级 AI Agent 操作系统。项目名称源自三国时期诸葛亮发明的"木牛流马"——一种能在险峻山路上自主运输粮草的机械装置,象征"以基础设施驾驭集体智能":不仅构建 Agent,更构建让多个 Agent 协同调度、自主演化、可审计的底层系统。

仓库:doiito/gliding_horse
许可:MIT
当前版本:v0.1.2.preview(2026-06 发布)
语言占比:Rust ≈ 80.9%
定位:面向企业级 AI Agent 系统的多智能体编排框架,提供完整的中文文档

“We don’t just build agents; we build the infrastructure that harnesses their collective intelligence.”

设计哲学

借鉴"木牛流马"的范式:古代机械并不是替换人力,而是把人从机械性劳动中解放出来。Gliding Horse 同样不追求把 Agent 框死在某种刚性流程里,而是提供一套自适应任务复杂度的编排基础设施——从一次性的即时查询,到多周的长流程项目,同一套引擎都能覆盖。

核心理念可以概括为一句话:

“灵活编排适应任务复杂度,而非刚性框架强迫任务就范”(The wise adapt their methods to circumstances, just as water shapes its course according to the ground over which it flows.)

整体架构

仓库分为多个 Workspace,核心层次按职能拆分:

层级	目录	技术栈	职责
核心调度	`crates/` · `src/`	Rust 2021 · PDCA · 5W2H · EventBus	Agent 编排与生命周期
应用层	`apps/software_engineering_team/`	Center (Go+Temporal) + Edge (Rust+axum) + VS Code Plugin	完整 SDLC 联邦
终端助手	`crates/gliding_code/`	Rust (musl 静态二进制)	零依赖命令行 AI 助手
技能定义	`skills/`	RDF / YAML	可插拔的 Skill 描述
数据契约	`proto/` · `workflow.jsonld`	gRPC Proto · JSON-LD 1.1	跨进程/跨语言接口
文档	`docs/`	Markdown (中英双语)	设计文档与设计哲学

核心机制详解

1. 广义 PDCA —— 7 级自适应执行

PDCA(Plan-Do-Check-Act)是经典的戴明环。Gliding Horse 将其广义化为 7 级复杂度,通过任务的 5W2H 元数据动态选择:

级别	含义	触发场景
L0	即时响应	简单问答、不需要工具
L1	单步工具调用	单次搜索、单次代码执行
L2	多步推理	多轮 ReAct,需要思考
L3	子任务分解	任务拆解后并行执行
L4	长链 Pipeline	多阶段流水线
L5	递归 PDCA	任务作为其他任务的子节点
L6	应急模式	异常升级、人工接管

一个引擎覆盖从 L0 的即时查询到 L6 的应急处置——这是 Gliding Horse 区别于其他编排框架的关键:不要求开发者为不同复杂度写不同框架。

2. 5W2H 本体级审计 —— 告别黑盒 PASS/FAIL

传统 Agent 评测只给一个"通过/不通过"的二值信号。Gliding Horse 对每一次执行结果按 5W2H 七个维度独立审计:

维度	失败时动作
What(产物对不对)	重新生成
Why(决策理由是否充分)	重新分析
How(方法是否合理)	重新规划
Where(执行环境/上下文是否合适)	重新规划
When(时序/截止日期)	有条件放行
HowMuch(资源消耗是否在预算内)	有条件放行
(附加)Who/Which	角色/工具匹配

这让精确回滚成为可能——你可以精准定位"哪一维度出问题",而不是把整个流程推倒重做。

3. CPU 缓存启发的 4 层记忆 + MESI 一致性

Gliding Horse 最具创新性的设计之一是把 CPU 缓存架构搬到多 Agent 记忆系统中:

层	类比	技术实现	性能指标
L0	寄存器/缓存	`Sled` KV + `Qdrant` 向量库	读取 ~1ms · 1000 ops/sec
L1	L1 缓存	上下文窗口 / 最近对话	由 LLM 决定
L2	L2 缓存	`Oxigraph` RDF 三元组存储	写入 ~2ms · 500 ops/sec
L3	L3 缓存 / 内存	`SPARQL 1.1` 投影视图	查询 ~15ms · 66 ops/sec

更关键的是引入了 CPU 的 MESI 缓存一致性协议(Modified / Exclusive / Shared / Invalid)的记忆改造版,解决多 Agent 共享记忆时的不一致问题。配合扩散激活式预取(Spreading Activation),常用记忆提前加载,感知延迟下降约 90%。

4. JSON-LD 1.1 通用数据总线

Agent 之间共享数据时,字段命名冲突是隐形大坑。Gliding Horse 用 JSON-LD 1.1 作为跨子系统、跨语言的通用数据契约:

@context —— 鸭子类型,消除字段命名冲突
@id —— 零成本跨 Agent 实体合并(同一个对象在不同子系统里指向同一 @id 即视为同一对象)
@graph (Named Graphs) —— 命名图机制,允许不同子系统并行写入而不冲突

配套的 workflow.jsonld 把"工作流描述"也建模为带 @id 的实体,可以直接写入 RDF 图并被 SPARQL 查询。

5. 统一知识图谱 —— Oxigraph RDF

所有子系统(技能、记忆、任务、代码知识)共享同一个 Oxigraph RDF 存储,通过命名图隔离,通过 @id 互联:

代码 AST 由 tree-sitter 自动解析为 RDF 三元组入图
跨子系统的 SPARQL JOIN 让"代码模块 ↔ 任务 ↔ 记忆"可以一次性查询
单一 @id 保证实体在所有上下文中的身份一致

这一设计的核心收益是消除信息孤岛:跨子系统的关联不再需要额外的 ETL 管道,直接在图上做关联查询即可。

6. 自演化 Skill Graph

Skill 不是一个静态的 YAML 列表,而是一张自演化的认知网络:

约 7,500+ LOC 的动态 RDF 网络
6 种语义链接:Prerequisite(前置)、Composition(组合)、Related(相关)、Conflict(冲突)、Refine(精炼)、Deprecate(废弃)
任务后学习:/learn 机制根据执行结果创建新知识片段与新链接
去重压缩:/reduce 机制定期合并冗余节点

简单说,系统跑得越多,这张"能力地图"自动生长得越完备。

7. 主动感知引擎

不是等任务失败再处理,Gliding Horse 内置主动监控:

10 类执行触发器:截止日期、Token 预算超 80%、角色失配、环境冲突、循环检测……
60 秒异常去重窗:避免同一异常反复打扰
自动升级人工:超出 Agent 能力的异常自动升级到人介入

8. 微工具系统(Micro-Tool)

当 Agent 输出超过 8 KB 的结果时,Gliding Horse 自动把它包装为一组对话式微工具(例如 search_in_results、summarize_section)。原本 50 KB+ 难以一次性塞进上下文的结果,变成可在上下文里交互式查询的对象——极大降低 LLM 上下文压力。

9. MCP 协议接入

原生支持 Model Context Protocol,一个协议接入 GitHub、Slack、Jira 等所有 MCP 兼容服务,运行时动态发现工具,告别"每接一个外部服务就写一套对接代码"。

10. 检查点与恢复

长任务最怕崩溃丢失进度。Gliding Horse 在关键节点对会话状态打快照:

崩溃后完整恢复到最近检查点,无需重头开始
支持事后回放调试(post-mortem replay)
支撑小时级甚至天级的 Agent 长任务

Center + Edge 联邦架构

这是一个独立于以上机制之上的部署拓扑,值得单独说。

VS Code Plugin (TypeScript)
 │ WebSocket / REST
 ▼
 Edge Daemon (Rust · axum)
 ├─ API Server (ws / chat / health)
 ├─ Agent Core (SupervisorAgent · DoAgent · LLM Client)
 ├─ Docker Sandbox (安全执行: 编译 / 测试)
 └─ Graph Layer (本地 Sled + Delta Sync)
 │ gRPC + REST
 ▼
 Center (Go · Gin)
 ├─ HTTP API (/api/v1/* · /ws)
 ├─ Temporal Workflow (编排引擎)
 ├─ Agent Manager (注册 · 心跳 · 派发)
 ├─ Executors (req → design → coding → review → test → cicd → deploy)
 └─ Store (SQLite · gRPC Client · Graph Sync)

角色	语言 / 框架	核心职责
Center	Go + Gin + Temporal	全局工作流编排、项目生命周期、Agent 注册中心、图谱同步
Edge	Rust + axum	本地 LLM 执行、Docker 沙箱、VS Code WebSocket 桥
VS Code Plugin	TypeScript	Chat Panel + Graph View + Task Panel,实时呈现 Agent 协作

设计哲学:Center 负责编排,Edge 负责执行,VS Code 负责感知——三者解耦,任一节点宕机不影响其他局部。

两个旗舰应用

1. Software Engineering Team

最完整的多 Agent 协作软件工程团队:

需求 → 设计 → 编码 → 评审 → 测试 → CI/CD → 部署

提供完整 Dashboard(项目总览、Agent 状态、Pipeline 进度)以及 VS Code 插件(Chat Panel / Graph View / Task Panel),让开发者可以实时看到多个 Agent 在背后协作。

这种"联邦式"设计的好处是:Center/Edge 可以独立扩展,VS Code 插件可以独立演进,核心调度引擎不必关心 UI 细节。

2. Gliding Code

零依赖终端 AI 编码助手——Gliding Horse 知识图谱与编排能力的"轻量入口":

平台	包大小	说明
Linux (x86_64, musl)	13.9 MB	完全静态链接
Linux (aarch64, musl)	12.9 MB	-
macOS (Apple Silicon)	12.1 MB	-
Windows (x86_64)	11.6 MB	-

# 下载即用,无需安装任何依赖
tar xzf glidingcode-*.tar.gz

# 设置 API Key(支持 DeepSeek 或任意 OpenAI 兼容端点)
export DEEPSEEK_API_KEY="sk-..."

# 交互式会话
./glidingcode

# 或一次性任务
./glidingcode "Explain how Rust's borrow checker works"

它的特点是把整套"知识图谱 + Agent 编排"塞进一个 13 MB 的二进制——这是 musl 全静态链接的功劳。对于想体验 Gliding Horse 但又不想搭建完整 Center/Edge 的开发者,Gliding Code 是最佳入口。

性能基线

操作	延迟	吞吐
L2 节点写入 (Oxigraph)	~2 ms	500 ops/sec
L3 SPARQL 投影	~15 ms	66 ops/sec
L0 Sled KV 读取	~1 ms	1000 ops/sec
Agent ReAct 一轮	1–5 s	0.2–1 turns/sec
空闲内存	~200 MB	随任务规模线性增长

注意:吞吐数据为仓库 README 公布的基线,实际表现取决于 LLM 调用频次与上下文长度。

上手指南

快速体验:Gliding Code(零依赖)

git clone https://github.com/doiito/gliding_horse.git
cd gliding_horse
# 在 releases 页面下载对应平台的预编译包
./glidingcode --help

完整搭建:Software Engineering Team

前置依赖:

Rust ≥ 1.94
Go ≥ 1.24
Docker
Temporal Server(本地或远端)
一个 OpenAI 兼容的 LLM API Key(DeepSeek、OpenAI、本地 vLLM 均可)

启动步骤:

# 1) 启动 Center
cd apps/software_engineering_team/center
cp center/config.yaml center/config.local.yaml
# 编辑 config.local.yaml,填入 LLM Key、Temporal 地址
go run ./cmd/server/... # API server on :8080
go run ./cmd/worker/... # Temporal worker

# 2) 启动 Edge Daemon
cd ../edge/daemon
cargo run -- daemon start # Agent daemon on :7890

# 3) 安装 VS Code 插件
code --install-extension apps/software_engineering_team/edge/vscode/

也可以直接调用 API:

curl http://localhost:8080/api/v1/projects \
 -X POST -H "Content-Type: application/json" \
 -d '{"name":"My Project","description":"Build a microservice"}'

路线图

核心 OS(持续推进):

扩展 MCP 工具生态与动态发现
多模型路由优化(成本感知调度)
知识图谱查询性能与规模优化
带版本化 Prompt 继承的模板引擎
细粒度订阅过滤的事件系统

应用层(未来):

时间	内容
Q3 2026	原生 Web 仪表板 · Python/TypeScript SDK
Q4 2026	Kubernetes Operator · 多轮对话记忆压缩 · Skill Marketplace 原型
2027	跨 Edge 节点的分布式 Agent Mesh · 多模态 Agent(视觉/音频) · 社区插件注册中心

一些深度观察

作为一份完整的概览,以下是我认为 Gliding Horse 与同类项目相比的几个显著差异点:

PDCA 7 级自适应让它对"什么算 Agent 框架"的定义更宽泛——同一套引擎既可做即时问答,又可跑周级项目,这种"弹性"是 LangChain / AutoGen 目前都没做到的。
CPU 缓存架构 + MESI 一致性是从硬件架构借来的概念,工程上不是新东西,但移植到多 Agent 记忆是很新鲜的一手;若实现得当,能极大缓解"Agent 之间互相覆盖记忆"的常见 bug。
JSON-LD 作为跨子系统数据总线使得"技能/记忆/任务/代码"得以在 RDF 图层统一——这一点与 GraphRAG 全景思路一脉相承,但走得更远。
OpenAI 兼容 API + MCP 双协议意味着开发者不强制绑定任何单一模型生态,DeepSeek、Qwen、本地 vLLM 都可以无缝接入,适合国内闭源/开源混合场景。

目前的不确定性:

项目仍处 v0.1.2.preview,生产环境稳定性未充分验证
官方 Issue 中已有用户反馈"流程太繁琐、跑半天没结果、重问又从头开始"(Issue #3),会话连续性与状态恢复仍是体验痛点
实时统计(stargazer_count / watcher_count)GitHub API 返回 null,需访问仓库页确认当前社区热度

适合谁:正在搭建多 Agent 协作平台 / 企业级 Agent 工作流 / 知识密集型 Agent 系统的团队。不适合谁:只要做一次性 prompt 调用或单 Agent RAG 的项目(用 LangChain / LlamaIndex 更轻)。

系列文章

注:Hugo 的相对路径解析对含空格目录使用 URL 编码(%20);若仍出现 broken 链接,请以博客最终渲染为准。

AI Agent Loop 工程：原理、模式与实现

Fri, 26 Jun 2026 15:40:07 +0800

一句话概括 Agent 工程的核心:把 LLM 放进一个可控的循环里,让它在"思考—行动—观察—反思"之间反复迭代,直到任务收敛。 这个"循环"——也就是 Agent Loop——就是本文的主角。

0. 为什么是 “Loop”?

如果你把 LLM 当成"一个函数 f(prompt) -> response",那你写出的就是 prompt 工程;但如果你把 LLM 当成"一个可以被调用的决策者",你就会发现:几乎所有复杂的 Agent 行为,本质上都是一个循环。

场景	单次调用能做到吗?	为什么需要 Loop?
让模型查今天北京天气	✅	一次生成即可
让模型读完 50 页 PDF 后回答	❌	需要循环:分块 → 读取 → 累计 → 汇总
让模型调用 5 个 API 完成订单	❌	需要循环:规划 → 调 API → 处理异常 → 重试
让模型写出能跑通的代码	❌	需要循环:写代码 → 执行 → 报错 → 修正
让模型通过多轮对话解决开放问题	❌	需要循环:追问 → 反思 → 补充 → 收敛

Loop 是 Agent 与"普通 LLM 应用"的分水岭。没有循环的 LLM 只是个文本生成器;有了循环,它才有机会成为"会思考、会试错、会自我修正"的智能体。

1. Agent Loop 的解剖

无论你用 ReAct、Reflection 还是 LangGraph,一个标准的 Agent Loop 都由 5 个固定角色组成:

角色	作用	工程实现
State(状态)	当前任务的所有上下文:目标、历史、记忆、工具结果	一个 `TypedDict` / Pydantic 模型
Policy(策略)	决定下一步该做什么	通常是一次 LLM 调用 + 结构化输出
Action(动作)	执行策略选定的动作	工具调用 / 子 Agent 调用 / 写文件
Observer(观察)	把动作结果回填到状态	`tool_result` 追加到 messages
Terminator(终止器)	判断循环是否该结束	显式 finish / 步数上限 / 置信度阈值

把这 5 个角色串起来,就是最经典的循环骨架:

state = init_state(user_goal)
for step in range(max_steps):
 decision = policy(state) # LLM 决定下一步
 if terminator(decision): # 是否结束?
 return final_answer(decision)
 observation = action(decision) # 调工具 / 子 Agent
 state = update(state, observation) # 更新状态
return forced_finish(state) # 兜底:步数耗尽

后续所有"花式"Loop(ReAct、Reflection、Reflexion、Plan-and-Execute)都只是对这 5 个角色的不同实现与重组。

2. 经典 Loop 模式

2.1 ReAct:Reason + Act(推理与行动交替)

ReAct(Yao et al., 2022)是最广为人知的 Agent Loop 范式,它强制让 LLM 在每一步都按 “Thought → Action → Observation” 的格式输出:

Thought 1: 我需要先查一下用户的订单状态
Action 1: get_order(order_id="12345")
Observation 1: {"status": "shipped", "tracking": "SF123..."}

Thought 2: 订单已发货,接下来需要根据物流信息估算送达时间
Action 2: get_eta(tracking="SF123...")
Observation 2: {"eta": "2026-06-28"}

Thought 3: 信息齐全,可以回答用户了
Action 3: finish(answer="您的订单预计 6 月 28 日送达")

Loop 视角的关键点:ReAct 的循环不是"调 LLM 一次",而是**“调 LLM → 解析动作 → 执行 → 把结果塞回 prompt → 再调 LLM”**。LLM 本身是无状态的,Loop 才是它"持续思考"的载体。

最小可运行的 ReAct Loop:

import json, re
from openai import OpenAI

client = OpenAI()
TOOLS = {
 "get_weather": lambda city: f"{city} 今天晴, 25°C",
 "get_time": lambda _: "现在是 2026-06-26 15:00",
}

SYSTEM = """你是一个 Agent。每轮必须严格输出:
Thought: <你的推理>
Action: <JSON,形如 {"name": "工具名", "args": {...}} 或 {"name": "finish", "args": {"answer": "..."}}>
"""

def react_loop(user_goal, max_steps=8):
 messages = [
 {"role": "system", "content": SYSTEM},
 {"role": "user", "content": user_goal},
 ]
 for step in range(max_steps):
 resp = client.chat.completions.create(
 model="gpt-4o-mini", messages=messages
 )
 text = resp.choices[0].message.content
 messages.append({"role": "assistant", "content": text})

 # 解析 Action
 m = re.search(r"Action:\s*(\{.*\})", text, re.S)
 if not m:
 raise ValueError(f"step {step}: 模型未输出 Action")
 action = json.loads(m.group(1))

 if action["name"] == "finish":
 return action["args"]["answer"], messages

 # 执行工具 → Observation
 obs = TOOLS[action["name"]](**action["args"])
 messages.append({"role": "user", "content": f"Observation: {obs}"})

 raise TimeoutError("超过最大步数,未收敛")

2.2 Reflection:让模型对自己的输出打分并改写

Reflection(Shinn et al., 2023)把 Loop 从"短反馈"升级成"长反馈":

[生成阶段] LLM 生成初稿 answer_0
[反思阶段] LLM(可以是同一个,也可以是更强的 critic)输出:
 - score: 0~10
 - critique: 具体问题清单
 - improved_answer: 改进版
[循环 N 次] 或 直至 score >= threshold

Loop 的关键差异:ReAct 的循环驱动来自"环境反馈"(工具返回),Reflection 的循环驱动来自"自我反馈"(LLM 评价自己)。

def reflection_loop(draft_prompt, max_rounds=3, threshold=8):
 draft = llm(draft_prompt)
 history = []
 for r in range(max_rounds):
 critique = critic_llm(f"""
 请评估以下回答,输出 JSON:
 {{"score": 0-10, "issues": [...], "improved": "..."}}
 原题: {draft_prompt}
 当前回答: {draft}
 """)
 score, improved = parse(critique)["score"], parse(critique)["improved"]
 history.append({"round": r, "score": score})
 if score >= threshold:
 return improved, history
 draft = improved
 return draft, history # 兜底:返回最后一轮

2.3 Reflexion:把反思结果"沉淀"到长期记忆

Reflexion 是 Reflection 的进化:它不只是"当场改",还会把反思结果写入长期记忆,让下次遇到类似问题时少走弯路:

Trajectory → Reflector → Self-Critique
 ↓
 Memory Store (vector db)
 ↓
 下次同类任务 ← 检索相关反思 ←┘

工程上常见的实现:用一个独立的 MemoryStore 对象,每次反射后写入 {situation, lesson, score_delta},在新任务的 system prompt 里通过 RAG 检索 top-k 相关反思塞进去。

2.4 Plan-and-Execute:先想清楚,再动手

Plan-and-Execute 把 Loop 拆成两个嵌套循环:

外层 Planner Loop: 任务 → 计划(步骤列表)
内层 Executor Loop: 对计划中每个 step 反复 ReAct,直至完成
外层 Replanner: 若某个 step 失败,回到 Planner 重新规划

适合长流程、阶段性强的任务(比如"调研 → 写作 → 校对 → 发布"),能让 Plan 阶段用更强的模型(慢但准),Execute 阶段用更便宜的模型(快且糙)。

2.5 CAMEL:多智能体角色扮演循环

CAMEL(Communicative Agents for “Mind” Exploration of LLMs)用两个 Agent(User Proxy + Assistant)在 Loop 中互相对话,中间插入"Inception Prompt"防止角色漂移:

User Proxy ──► Assistant ──► User Proxy ──► Assistant ...
 ↑ │
 └──────────── Critic/Inception Prompt ←──────────────┘

适合对话式博弈、谈判模拟、教学场景等"两个角色反复讨论"的场景。

3. Loop 的 4 大工程问题

把 Loop 从论文搬到生产,真正难的是下面 4 个问题。

3.1 状态管理:Loop 的"内存"

State 是 Loop 工程的命门。常见的 State 设计:

from typing import TypedDict, Annotated, List
from langgraph.graph.message import add_messages

class AgentState(TypedDict):
 # 对话历史(自带 reducer,自动追加)
 messages: Annotated[List[dict], add_messages]
 # 当前计划(Plan-and-Execute 用)
 plan: List[str]
 # 已执行的步骤与结果
 past_steps: List[tuple[str, str]]
 # 反思/记忆
 reflections: List[str]
 # 控制字段
 step_count: int
 is_finished: bool

设计原则:

State 必须可序列化:能 pickle / 写 Redis,这是断点续跑、调试回放的前提。
State 必须有 schema:用 TypedDict 或 Pydantic,避免字段拼写错误。
State 的写入要走 reducer:特别是 messages,不能简单覆盖,而要 append,否则 Loop 会"失忆"。

3.2 终止条件:Loop 不能"停不下来"

没有终止条件的 Loop 就是个无底洞。生产中至少要有 3 重保险:

def should_continue(state) -> Literal["continue", "end"]:
 # 1. 显式 finish(由 LLM 主动调用 finish 工具)
 if state["is_finished"]:
 return "end"
 # 2. 步数硬上限(防止 token 爆炸)
 if state["step_count"] >= 20:
 return "end"
 # 3. 步数软上限 + 强制收敛(兜底,走 LLM 总结)
 if state["step_count"] >= 15:
 return "force_summarize"
 # 4. 重复检测(防止模型在两个动作间反复横跳)
 if state["messages"][-1].content == state["messages"][-3].content:
 return "end"
 return "continue"

真实生产事故经常源于:忘了设上限,或者上限设了但没接 billing 报警,一夜烧掉几千美元 Token。

3.3 记忆机制:Loop 跨轮次"活下来"

Loop 内部的 state 是短期记忆,跨会话需要长期记忆:

类型	存储	写入时机	检索时机
短期(Scratchpad)	In-memory state	每一步	每一步
程序性(Procedural)	系统 prompt	启动时	启动时
语义性(Semantic)	Vector DB	反思后/总结后	新任务开始
情节性(Episodic)	时序 DB	任务结束时	反思阶段

class LongTermMemory:
 def __init__(self, vector_store, embedder):
 self.vs, self.emb = vector_store, embedder

 def write(self, situation: str, lesson: str):
 self.vs.add(
 text=f"情境: {situation}\n教训: {lesson}",
 embedding=self.emb.embed(situation),
 )

 def recall(self, current_situation: str, k=3):
 q = self.emb.embed(current_situation)
 return self.vs.search(q, top_k=k)

3.4 工具调用:Loop 与现实世界的接口

Loop 里 80% 的 Action 都是"调工具"。工具设计要点:

工具描述即 Prompt——LLM 选错工具,90% 是工具描述写得烂。
工具要返回结构化数据(JSON)而非自然语言,便于程序解析。
工具有超时和重试,避免一个慢工具把整个 Loop 拖死。
危险操作(写库、发邮件、删文件)走二次确认分支,而不是直接执行。

@tool
def send_email(to: str, subject: str, body: str) -> str:
 """发送邮件(危险操作,需要 confirm=true 才真正发送)。"""
 if not confirm:
 return f"[DRY-RUN] 将发送邮件给 {to},主题: {subject}"
 return _smtp_send(to, subject, body)

4. 用 LangGraph 把 Loop 工程化

手写 ReAct Loop 在 demo 阶段可以,但生产中你需要:可视化、断点续跑、人介入、可观测——这些 LangGraph 已经帮你做好。

4.1 最小的 LangGraph Agent Loop

from typing import Literal, Annotated, List
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
from langgraph.prebuilt import ToolNode

@tool
def search(query: str) -> str:
 """模拟搜索工具。"""
 return f"关于 '{query}' 的搜索结果: ..."

tools = [search]
llm = ChatOpenAI(model="gpt-4o-mini").bind_tools(tools)

class State(TypedDict):
 messages: Annotated[List, add_messages]
 step_count: int

def agent(state: State):
 return {
 "messages": [llm.invoke(state["messages"])],
 "step_count": state.get("step_count", 0) + 1,
 }

def should_continue(state: State) -> Literal["tools", END]:
 last = state["messages"][-1]
 if last.tool_calls:
 return "tools"
 return END

graph = (
 StateGraph(State)
 .add_node("agent", agent)
 .add_node("tools", ToolNode(tools))
 .add_edge(START, "agent")
 .add_conditional_edges("agent", should_continue)
 .add_edge("tools", "agent")
 .compile()
)

for chunk in graph.stream({"messages": [("user", "查一下 LangGraph 最新版本")]}):
 print(chunk)

4.2 加 Reflection 节点

在上面的图里多加一个 reflect 节点和一条边:

def reflect(state: State):
 last_answer = state["messages"][-1].content
 critique = llm.invoke([
 {"role": "system", "content": "你是质检员,打分 0-10,并指出问题。"},
 {"role": "user", "content": f"评价: {last_answer}"},
 ])
 score = parse_score(critique.content)
 if score >= 8 or state["step_count"] >= 10:
 return END
 return "agent" # 不满意,把 critique 塞回 messages 让 agent 重写

完整图就是:agent → tools → agent → … → reflect → (END | agent)。

4.3 加人介入(Human-in-the-Loop)

生产中,任何高风险分支都该有"暂停等人确认"的节点:

graph.add_node("human_review", lambda s: s) # 实际是中断点
graph.add_edge("agent", "human_review",
 condition=lambda s: "send_email" in str(s["messages"][-1]))

部署时打开 interrupt_before=["human_review"],LangGraph 会在该节点暂停,把当前 state 持久化,等人通过 API 决策后再 resume。

4.4 测试:比"人介入"更重要的一环

人介入(Human-in-the-Loop)常被当作安全兜底,但它不是目的,而是过渡手段。真正能让 Agent Loop 规模化运转的,是把"人测"变成"自动测"。

如果测试做得好,Loop 在每一轮迭代后都能自动验证中间产物(代码是否编译、单测是否通过、API 返回是否符合 schema、生成内容是否满足评分标准),那么大量原本需要人工复核的环节就会被自动化覆盖,人工介入才会被压缩到真正的"异常"和"边界"上。反之,如果测试缺位,Loop 跑完后人还是要从头到尾做验收,Agent 带来的效率提升会被人工测试抵消大半。

所以 Agent Loop 工程里真正值得重点设计的,其实是两个节点:

需求提出:人把目标、验收标准、约束说清楚——这是 Loop 的输入。
测试介入:用可执行、可自动化的测试把输出验回来——这是 Loop 的收敛判据。

这个思路其实来源于芯片设计的理念:芯片一旦流片,发现问题就是天价损失;但如果前期验证(仿真、形式验证、原型测试)做得充分,就能把风险挡在量产之前。AI 时代的 Agent 部署也类似——Loop 里多跑几轮测试,多消耗一些 token,边际成本几乎为零;可一旦把有缺陷的产出发布上线,修复成本和业务影响会大得多。

因此,不要把测试看成"额外的开销",而要把它当成用廉价 token 换取上线确定性的投资。其余环节(规划、执行、反思)都应该朝着"让需求端到测试端之间的循环尽量少依赖人工"去优化。

5. Loop 的可观测性

Loop 跑起来后,你必须能回答这三个问题:

它在每一步想了什么、做了什么? → 记录完整的 messages / tool_calls / observations。
它为什么没收敛? → 终止时把"最后 3 步状态"dump 出来。
它花了多少钱/多少时间? → 每个 step 单独计费。

LangGraph 与 LangSmith 集成最省事:

import os
os.environ["LANGSMITH_TRACING"] = "true"
os.environ["LANGSMITH_API_KEY"] = "..."

# 之后每次 graph.invoke() 都会自动 trace 到 LangSmith

自建可观测栈的话,关键埋点:

with tracer.start_as_current_span("agent_loop") as span:
 span.set_attribute("goal", user_goal)
 for step in range(max_steps):
 with tracer.start_as_current_span(f"step_{step}") as s:
 s.set_attribute("messages_count", len(state["messages"]))
 s.set_attribute("tokens_in", usage.prompt_tokens)
 s.set_attribute("tokens_out", usage.completion_tokens)
 ...

6. Loop 的反模式

写了几年 Agent Loop 后,我总结出最常踩的几个坑:

6.1 无限循环 / 上限过高

# 反例
for step in itertools.count(): # 真的无限
 ...

一定要设硬上限,而且上限要和 budget 系统联动。

6.2 把所有上下文都塞进 Prompt

Loop 跑 20 步,prompt 里堆 20 轮对话 + 10 个工具结果,Token 直接爆炸。要么用摘要压缩,要么用外部状态机把历史写到外部存储,prompt 里只保留"最近 K 步 + 关键事件"。

6.3 没有 fallback 工具调用失败

工具超时 / 5xx / 返回错误 JSON 都太常见。Action 层必须包一层 retry + fallback,而不是直接把异常抛给 LLM 让它自己"看着办"。

6.4 终止条件依赖 LLM 自报

# 反例
done = llm("请判断任务是否完成,只回答 yes/no") == "yes"

LLM 自报"完成"非常不可靠,用结构化 finish 工具 + 外部校验双保险。

6.5 跨任务共享同一个 LongTerm Memory 不做清理

记忆库会越积越杂,质量会越来越差。定期做记忆蒸馏:把多条相似记忆合并成一条;对引用次数为 0 的记忆做 GC。

7. 一个生产级 Agent Loop 的参考骨架

综合前文,生产里我推荐的 Agent Loop 骨架长这样:

┌─────────────────────────────────────────────────┐
│ 主循环 (Agent Loop) │
│ │
│ ┌────────┐ ┌────────┐ ┌─────────────┐ │
│ │ Planner│───►│Executor│───►│ Reflector │ │
│ └────────┘ └────┬───┘ └──────┬──────┘ │
│ ▲ │ │ │
│ │ ▼ ▼ │
│ │ ┌────────┐ ┌─────────────┐ │
│ └────────│Replanner│ │Memory Writer│ │
│ └────────┘ └─────────────┘ │
│ │
│ 三重保险:Step 上限 / Token 上限 / 重复检测 │
│ 三层记忆:State / Vector DB / External Store │
└─────────────────────────────────────────────────┘

对应到 LangGraph,就是带分支的图 + 多个子节点 + 持久化 checkpointer。所有"花式"Agent 框架的差异,本质上都是这个骨架的不同拓扑。

8. 总结

Agent Loop = 状态 + 策略 + 动作 + 观察 + 终止器 的循环。
经典模式:ReAct(环境反馈)、Reflection(自我反馈)、Reflexion(反馈入长期记忆)、Plan-and-Execute(嵌套循环)、CAMEL(双角色循环)。
工程化的 4 大难题:状态管理、终止条件、记忆机制、工具设计。
落地推荐 LangGraph:它把 Loop 的节点、边、终止、持久化、人介入都做成了原生能力。
可观测性和硬上限是 Loop 工程的生死线——没有它们,Agent 就是个会烧钱、会失控的黑盒。

掌握了 Agent Loop,你就不再是"在调 LLM",而是在设计一个由 LLM 驱动的分布式系统——这正是"智能体编排设计工程师"的核心能力。

参考资料

Yao et al., ReAct: Synergizing Reasoning and Acting in Language Models, 2022.
Shinn et al., Reflexion: Language Agents with Verbal Reinforcement Learning, 2023.
Wei et al., Chain-of-Thought Prompting Elicits Reasoning in Large Language Models, 2022.
LangGraph Documentation, https://langchain-ai.github.io/langgraph/
《智能体编排设计工程师学习指南》(本系列前篇)

Agent 记忆模块深度技术文档

Tue, 17 Jun 2025 11:00:00 +0800

Agent 记忆模块深度技术文档

一、记忆模块概述

1.1 为什么 Agent 需要记忆？

在传统软件开发中，系统状态存储在数据库、缓存或文件系统中。但当系统从"规则驱动"转向"AI 驱动"时，记忆成为Agent 的核心能力之一：

维度	传统系统	Agent 系统
状态存储	结构化数据库	非结构化向量存储 + Context Window
知识获取	硬编码规则	从对话、文档中学习
上下文理解	Session 管理	记忆检索 + LLM 推理
个性化能力	用户配置表	长期记忆 + 用户画像

核心价值：

连续性：跨对话保持上下文，记住用户偏好
学习能力：从历史交互中积累知识
个性化：针对不同用户提供定制化服务
效率优化：避免重复询问相同信息

1.2 记忆的分类维度

从不同维度理解记忆系统：

┌─────────────────────────────────────────────────────────┐
│ 记忆系统分类矩阵 │
├─────────────────────────────────────────────────────────┤
│ │
│ 时效维度 存储维度 │
│ ├─ 短期记忆 ├─ 内存存储 │
│ ├─ 长期记忆 ├─ 向量数据库 │
│ └─ 工作记忆 └─ 关系数据库 │
│ │
│ 内容维度 访问维度 │
│ ├─ 对话历史 ├─ 精确匹配 │
│ ├─ 知识事实 ├─ 语义检索 │
│ ├─ 用户画像 └─ 混合检索 │
│ └─ 任务状态 │
│ │
└─────────────────────────────────────────────────────────┘

二、短期记忆（Short-term Memory）

2.1 核心概念

短期记忆存储在 LLM 的 Context Window（上下文窗口）中，随对话结束而消失。

关键参数：

Context Window 大小：不同模型的支持能力
- GPT-4 Turbo：128K tokens
- GPT-4：8K tokens
- Claude 3 Opus：200K tokens
- Claude 3.5 Sonnet：200K tokens

核心挑战：

Token 限制：长对话会超出限制导致截断
成本问题：每次请求都要传递完整历史
注意力稀释：上下文过长影响模型推理质量

2.2 实现方案对比

方案一：完整对话历史（ConversationBufferMemory）

原理：保留所有历史对话

from langchain.memory import ConversationBufferMemory
from langchain.chains import ConversationChain

# 初始化记忆
memory = ConversationBufferMemory()

# 对话过程
memory.save_context({"input": "你好"}, {"output": "你好！我是AI助手"})
memory.save_context({"input": "我叫张三"}, {"output": "你好张三！很高兴认识你"})

# 查看记忆内容
print(memory.load_memory_variables({}))
# 输出：{'history': 'Human: 你好\nAI: 你好！我是AI助手\nHuman: 我叫张三\nAI: 你好张三！很高兴认识你'}

优点：

实现简单
不丢失任何信息

缺点：

Token 消耗线性增长
长对话会超出 Context Window

适用场景：

短对话（< 20 轮）
需要完整上下文的场景

方案二：滑动窗口（ConversationBufferWindowMemory）

原理：只保留最近 K 轮对话

from langchain.memory import ConversationBufferWindowMemory

# 只保留最近 5 轮对话
memory = ConversationBufferWindowMemory(k=5)

# 模拟 10 轮对话
for i in range(10):
 memory.save_context(
 {"input": f"问题 {i+1}"},
 {"output": f"回答 {i+1}"}
 )

# 查看记忆（只保留最后 5 轮）
print(memory.load_memory_variables({}))
# 输出：最近 5 轮的对话内容

优点：

Token 消耗可控
实现简单

缺点：

会丢失早期对话
无法回溯远期信息

适用场景：

中等长度对话
更关注最近上下文的场景

Token 计算：

def estimate_tokens_window(k: int, avg_tokens_per_turn: int = 50) -> int:
 """
 估算滑动窗口的 Token 消耗

 Args:
 k: 保留的对话轮数
 avg_tokens_per_turn: 平均每轮对话的 Token 数

 Returns:
 总 Token 数
 """
 return k * avg_tokens_per_turn

# 示例：5 轮对话，平均每轮 50 tokens
print(f"预估 Token: {estimate_tokens_window(5)}") # 250 tokens

方案三：Token 限制截断（ConversationTokenBufferMemory）

原理：根据 Token 数量动态截断

from langchain.memory import ConversationTokenBufferMemory
from langchain_openai import OpenAI

llm = OpenAI()

# 限制最大 2000 tokens
memory = ConversationTokenBufferMemory(
 llm=llm,
 max_token_limit=2000
)

# 添加对话
memory.save_context({"input": "长文本..." * 100}, {"output": "回答..."})

# 自动截断超出部分
print(memory.load_memory_variables({}))

优点：

精确控制 Token 消耗
最大化利用 Context Window

缺点：

截断位置可能不自然
需要额外的 Token 计算

实现细节：

from langchain_core.messages import BaseMessage, get_buffer_string

class CustomTokenBufferMemory:
 """自定义 Token 限制记忆"""

 def __init__(self, llm, max_token_limit: int = 4000):
 self.llm = llm
 self.max_token_limit = max_token_limit
 self.buffer: list[BaseMessage] = []

 def save_context(self, inputs: dict, outputs: dict):
 """保存对话上下文"""
 from langchain_core.messages import HumanMessage, AIMessage

 self.buffer.append(HumanMessage(content=inputs["input"]))
 self.buffer.append(AIMessage(content=outputs["output"]))

 # 检查并截断
 self._trim_buffer()

 def _trim_buffer(self):
 """截断超出 Token 限制的部分"""
 current_tokens = self._count_tokens()

 while current_tokens > self.max_token_limit and len(self.buffer) > 0:
 # 从最旧的对话开始删除
 removed = self.buffer.pop(0)
 current_tokens -= self._count_message_tokens(removed)

 def _count_tokens(self) -> int:
 """计算当前 Buffer 的 Token 数"""
 buffer_str = get_buffer_string(self.buffer)
 return len(self.llm.get_num_tokens(buffer_str))

 def _count_message_tokens(self, message: BaseMessage) -> int:
 """计算单条消息的 Token 数"""
 return len(self.llm.get_num_tokens(message.content))

方案四：摘要记忆（ConversationSummaryMemory）

原理：定期对历史对话生成摘要，用摘要替代原始对话

from langchain.memory import ConversationSummaryMemory
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4")

memory = ConversationSummaryMemory(llm=llm)

# 添加对话
memory.save_context(
 {"input": "我最近在学习 Python，有什么建议吗？"},
 {"output": "建议从基础语法开始，然后学习数据结构和算法..."}
)

memory.save_context(
 {"input": "有没有推荐的书籍？"},
 {"output": "推荐《Python编程：从入门到实践》和《流畅的Python》..."}
)

# 查看摘要
print(memory.load_memory_variables({}))
# 输出：{'history': '用户正在学习Python，我推荐了从基础语法开始学习，并建议了两本书籍...'}

优点：

大幅压缩 Token 消耗
保留关键信息

缺点：

摘要过程需要额外的 LLM 调用（成本）
可能丢失细节信息
摘要质量依赖模型能力

成本分析：

def calculate_summary_cost(
 conversation_turns: int,
 avg_tokens_per_turn: int = 50,
 summary_interval: int = 10,
 compression_ratio: float = 0.2
) -> dict:
 """
 计算摘要记忆的成本

 Args:
 conversation_turns: 总对话轮数
 avg_tokens_per_turn: 平均每轮对话的 Token 数
 summary_interval: 每隔多少轮生成一次摘要
 compression_ratio: 摘要压缩比

 Returns:
 成本分析字典
 """
 # 原始对话的 Token 数
 original_tokens = conversation_turns * avg_tokens_per_turn

 # 摘要次数
 summary_count = conversation_turns // summary_interval

 # 摘要生成成本（输入 tokens + 输出 tokens）
 summary_generation_cost = summary_count * summary_interval * avg_tokens_per_turn

 # 最终保留的摘要 Token 数
 final_summary_tokens = original_tokens * compression_ratio

 # 最近未摘要的对话
 recent_unsummarized = (conversation_turns % summary_interval) * avg_tokens_per_turn

 # 总 Token 消耗（包括摘要生成 + 最终传递）
 total_tokens = summary_generation_cost + final_summary_tokens + recent_unsummarized

 return {
 "original_tokens": original_tokens,
 "total_tokens_consumed": total_tokens,
 "compression_rate": (1 - (final_summary_tokens + recent_unsummarized) / original_tokens),
 "summary_count": summary_count
 }

# 示例：100 轮对话
cost = calculate_summary_cost(
 conversation_turns=100,
 avg_tokens_per_turn=50,
 summary_interval=10,
 compression_ratio=0.2
)
print(f"压缩率: {cost['compression_rate']:.1%}") # 压缩率: 72.0%

方案五：混合记忆（ConversationSummaryBufferMemory）

原理：结合摘要和完整对话，保留最近 K 轮 + 历史摘要

from langchain.memory import ConversationSummaryBufferMemory
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4")

# 保留最近 5 轮 + 历史摘要
memory = ConversationSummaryBufferMemory(
 llm=llm,
 max_token_limit=2000
)

# 添加 20 轮对话
for i in range(20):
 memory.save_context(
 {"input": f"问题 {i+1}"},
 {"output": f"回答 {i+1}"}
 )

# 查看记忆：早期对话会被摘要，最近几轮保持完整
print(memory.load_memory_variables({}))

优点：

平衡信息完整性和 Token 效率
保留最近关键上下文

缺点：

实现复杂
需要调优参数

架构图：

┌─────────────────────────────────────────────────────────┐
│ 混合记忆结构 │
├─────────────────────────────────────────────────────────┤
│ │
│ [对话历史] │
│ ├─ 第 1-10 轮 ──→ 摘要生成 ──→ 摘要 A (200 tokens) │
│ ├─ 第 11-15 轮 ──→ 摘要生成 ──→ 摘要 B (200 tokens) │
│ └─ 第 16-20 轮 ──→ 完整保留 ──→ 5 轮对话 (500 tokens)│
│ │
│ [最终传递给 LLM] │
│ └─ 摘要 A + 摘要 B + 最近 5 轮 = 900 tokens │
│ │
└─────────────────────────────────────────────────────────┘

2.3 短期记忆最佳实践

实践一：动态调整窗口大小

根据任务复杂度动态调整保留的对话轮数：

class DynamicWindowMemory:
 """动态调整窗口大小的记忆"""

 def __init__(self, initial_k: int = 5, max_k: int = 20):
 self.k = initial_k
 self.max_k = max_k
 self.buffer = []
 self.complexity_scores = []

 def save_context(self, inputs: dict, outputs: dict):
 """保存上下文并评估复杂度"""
 self.buffer.append((inputs, outputs))

 # 评估对话复杂度
 complexity = self._estimate_complexity(inputs["input"])
 self.complexity_scores.append(complexity)

 # 动态调整窗口
 self._adjust_window()

 def _estimate_complexity(self, text: str) -> float:
 """估算对话复杂度"""
 # 简单启发式：基于文本长度和关键词
 score = 0.0

 # 长度因素
 if len(text) > 200:
 score += 0.3

 # 关键词因素
 complex_keywords = ["详细", "解释", "为什么", "如何", "分析"]
 if any(kw in text for kw in complex_keywords):
 score += 0.3

 # 多问题因素
 if text.count("?") > 1 or text.count("？") > 1:
 score += 0.4

 return min(score, 1.0)

 def _adjust_window(self):
 """根据复杂度调整窗口大小"""
 if len(self.complexity_scores) < 5:
 return

 # 计算最近 5 轮的平均复杂度
 avg_complexity = sum(self.complexity_scores[-5:]) / 5

 # 动态调整 k
 if avg_complexity > 0.6:
 self.k = min(self.k + 2, self.max_k) # 增加窗口
 elif avg_complexity < 0.3:
 self.k = max(self.k - 1, 3) # 减小窗口

实践二：重要信息提取与保留

识别并优先保留重要信息：

from langchain_core.messages import HumanMessage, AIMessage
import re

class ImportanceAwareMemory:
 """重要信息感知的记忆"""

 def __init__(self, max_tokens: int = 4000):
 self.max_tokens = max_tokens
 self.buffer = []
 self.important_facts = []

 def save_context(self, inputs: dict, outputs: dict):
 """保存上下文并提取重要信息"""
 # 提取重要信息
 important_info = self._extract_important_info(inputs["input"], outputs["output"])

 if important_info:
 self.important_facts.extend(important_info)

 # 保存完整对话
 self.buffer.append((inputs, outputs))

 # 检查并压缩
 self._compress_if_needed()

 def _extract_important_info(self, user_input: str, ai_output: str) -> list:
 """提取重要信息"""
 important = []

 # 模式 1：用户偏好
 preference_patterns = [
 r"我喜欢(.+)",
 r"我偏好(.+)",
 r"我希望(.+)",
 r"我叫(.+)",
 r"我的(.+)是"
 ]

 for pattern in preference_patterns:
 matches = re.findall(pattern, user_input)
 important.extend(matches)

 # 模式 2：关键决策
 decision_keywords = ["决定", "确认", "选择", "同意"]
 if any(kw in user_input for kw in decision_keywords):
 important.append(f"决策: {user_input}")

 return important

 def _compress_if_needed(self):
 """如果超出限制则压缩"""
 current_tokens = self._count_tokens()

 if current_tokens > self.max_tokens:
 # 保留重要信息 + 最近对话
 recent_conversations = self.buffer[-5:]

 # 构建压缩后的记忆
 compressed = {
 "important_facts": self.important_facts,
 "recent_conversations": recent_conversations
 }

 # 替换 buffer
 self.buffer = compressed

 def load_memory(self) -> str:
 """加载记忆"""
 if isinstance(self.buffer, list):
 # 正常模式
 return self._format_conversations(self.buffer)
 else:
 # 压缩模式
 facts_str = "\n".join([f"- {fact}" for fact in self.buffer["important_facts"]])
 recent_str = self._format_conversations(self.buffer["recent_conversations"])
 return f"【重要信息】\n{facts_str}\n\n【最近对话】\n{recent_str}"

实践三：多级记忆架构

构建多级记忆系统，平衡效率和完整性：

class MultiLevelMemory:
 """多级记忆架构"""

 def __init__(self):
 # Level 1: 工作记忆（当前对话）
 self.working_memory = []

 # Level 2: 短期记忆（滑动窗口）
 self.short_term_memory = []
 self.short_term_limit = 10

 # Level 3: 摘要记忆
 self.summary_memory = ""

 # Level 4: 重要信息
 self.key_facts = []

 def add_message(self, role: str, content: str):
 """添加消息"""
 # 添加到工作记忆
 self.working_memory.append({"role": role, "content": content})

 # 如果工作记忆达到阈值，推送到短期记忆
 if len(self.working_memory) >= 2:
 self._push_to_short_term()

 # 如果短期记忆达到阈值，生成摘要
 if len(self.short_term_memory) >= self.short_term_limit:
 self._summarize_short_term()

 def _push_to_short_term(self):
 """推送到短期记忆"""
 # 提取重要信息
 self._extract_key_facts()

 # 移动到短期记忆
 self.short_term_memory.extend(self.working_memory)
 self.working_memory = []

 def _extract_key_facts(self):
 """提取关键事实"""
 # 简化版：实际应该用 LLM 提取
 for msg in self.working_memory:
 if "我叫" in msg["content"] or "我喜欢" in msg["content"]:
 self.key_facts.append(msg["content"])

 def _summarize_short_term(self):
 """摘要短期记忆"""
 # 生成摘要（实际应该调用 LLM）
 summary = f"过去 {len(self.short_term_memory)} 条消息的摘要..."

 # 更新摘要记忆
 if self.summary_memory:
 self.summary_memory += "\n" + summary
 else:
 self.summary_memory = summary

 # 清空短期记忆
 self.short_term_memory = []

 def get_context_for_llm(self, max_tokens: int = 4000) -> str:
 """获取传递给 LLM 的上下文"""
 context_parts = []

 # 1. 关键事实（优先级最高）
 if self.key_facts:
 context_parts.append("【用户信息】\n" + "\n".join(self.key_facts))

 # 2. 历史摘要
 if self.summary_memory:
 context_parts.append("【历史摘要】\n" + self.summary_memory)

 # 3. 短期记忆
 if self.short_term_memory:
 short_term_str = self._format_messages(self.short_term_memory)
 context_parts.append("【近期对话】\n" + short_term_str)

 # 4. 工作记忆（当前对话）
 if self.working_memory:
 working_str = self._format_messages(self.working_memory)
 context_parts.append("【当前对话】\n" + working_str)

 return "\n\n".join(context_parts)

 def _format_messages(self, messages: list) -> str:
 """格式化消息"""
 return "\n".join([
 f"{msg['role']}: {msg['content']}"
 for msg in messages
 ])

三、长期记忆（Long-term Memory）

3.1 核心概念

长期记忆用于存储跨对话的信息，需要外部存储系统支持。

关键特性：

持久化：数据永久存储
跨会话：不同对话可以访问相同记忆
可扩展：理论上无限容量

核心技术：

向量数据库（Vector Database）
嵌入模型（Embedding Model）
检索算法（Retrieval Algorithm）

3.2 向量数据库选型

主流向量数据库对比

数据库	类型	特点	适用场景	性能
Pinecone	云服务	托管式，零运维	生产环境，快速上手	⭐⭐⭐⭐⭐
Milvus	开源	高性能，可扩展	大规模生产环境	⭐⭐⭐⭐⭐
Weaviate	开源	语义搜索强	知识图谱场景	⭐⭐⭐⭐
ChromaDB	开源	轻量级，易用	开发测试，小规模应用	⭐⭐⭐
Qdrant	开源	Rust 实现，高性能	性能敏感场景	⭐⭐⭐⭐⭐
FAISS	库	Meta 开源，纯算法	本地嵌入，极致性能	⭐⭐⭐⭐⭐

选型决策树

需要长期记忆？
├─ 是
│ ├─ 团队有运维能力？
│ │ ├─ 是
│ │ │ ├─ 数据规模 > 1000万向量？
│ │ │ │ ├─ 是 → Milvus
│ │ │ │ └─ 否 → Qdrant
│ │ │ └─ 需要 RAG + 知识图谱？
│ │ │ ├─ 是 → Weaviate
│ │ │ └─ 否 → Qdrant
│ │ └─ 否（无运维能力）
│ │ └─ Pinecone（托管服务）
│ └─ 开发测试阶段？
│ └─ ChromaDB（最简单）
└─ 否（仅需短期记忆）
 └─ 使用内存存储

3.3 嵌入模型选型

主流嵌入模型对比

模型	提供商	维度	性能	成本
text-embedding-3-small	OpenAI	1536	⭐⭐⭐⭐	$0.02/1M tokens
text-embedding-3-large	OpenAI	3072	⭐⭐⭐⭐⭐	$0.13/1M tokens
text-embedding-ada-002	OpenAI	1536	⭐⭐⭐	$0.10/1M tokens
bge-large-zh-v1.5	BGE	1024	⭐⭐⭐⭐	免费（本地）
bge-m3	BGE	1024	⭐⭐⭐⭐⭐	免费（本地）
Cohere embed-v3	Cohere	1024	⭐⭐⭐⭐⭐	$0.10/1M tokens

选择建议

# 场景 1：追求最佳性能
from langchain_openai import OpenAIEmbeddings
embeddings = OpenAIEmbeddings(model="text-embedding-3-large")

# 场景 2：成本敏感
from langchain_openai import OpenAIEmbeddings
embeddings = OpenAIEmbeddings(model="text-embedding-3-small")

# 场景 3：中文场景，本地部署
from langchain_community.embeddings import HuggingFaceBgeEmbeddings
embeddings = HuggingFaceBgeEmbeddings(
 model_name="BAAI/bge-large-zh-v1.5",
 model_kwargs={'device': 'cuda'},
 encode_kwargs={'normalize_embeddings': True}
)

# 场景 4：多语言混合
from langchain_cohere import CohereEmbeddings
embeddings = CohereEmbeddings(model="embed-multilingual-v3.0")

3.4 实现方案详解

方案一：基于向量检索的记忆

架构图：

┌─────────────────────────────────────────────────────────┐
│ 向量检索记忆架构 │
├─────────────────────────────────────────────────────────┤
│ │
│ 用户输入 │
│ ↓ │
│ Embedding 模型 │
│ ↓ │
│ 查询向量 │
│ ↓ │
│ 向量数据库 ──→ 相似度检索 ──→ Top-K 记忆 │
│ ↓ │
│ 相关记忆 + 用户输入 ──→ LLM ──→ 回复 │
│ ↓ │
│ 回复 + 输入 ──→ Embedding ──→ 存入向量数据库 │
│ │
└─────────────────────────────────────────────────────────┘

实现代码：

from langchain.memory import VectorStoreRetrieverMemory
from langchain_community.vectorstores import Chroma
from langchain_openai import OpenAIEmbeddings
from langchain.chains import ConversationChain
from langchain_openai import ChatOpenAI

# 1. 初始化向量数据库
embeddings = OpenAIEmbeddings()
vectorstore = Chroma(
 embedding_function=embeddings,
 persist_directory="./chroma_memory_db"
)

# 2. 创建检索器
retriever = vectorstore.as_retriever(
 search_kwargs={"k": 5} # 检索最相关的 5 条记忆
)

# 3. 创建记忆
memory = VectorStoreRetrieverMemory(retriever=retriever)

# 4. 使用记忆
# 保存对话
memory.save_context(
 {"input": "我喜欢吃苹果"},
 {"output": "好的，我会记住你喜欢吃苹果"}
)

memory.save_context(
 {"input": "我叫张三"},
 {"output": "你好张三！很高兴认识你"}
)

# 5. 检索相关记忆
relevant_memories = memory.load_memory_variables({"prompt": "我的名字是什么？"})
print(relevant_memories)
# 输出：最相关的记忆，包含"我叫张三"的对话

高级实现：带元数据的记忆：

from datetime import datetime
from typing import Optional
from langchain_core.documents import Document

class AdvancedVectorMemory:
 """高级向量记忆系统"""

 def __init__(self, vectorstore, embeddings, user_id: str):
 self.vectorstore = vectorstore
 self.embeddings = embeddings
 self.user_id = user_id

 def save_memory(
 self,
 user_input: str,
 ai_output: str,
 importance: str = "normal", # high, normal, low
 category: Optional[str] = None
 ):
 """保存记忆"""

 # 构建文档
 document = Document(
 page_content=f"User: {user_input}\nAI: {ai_output}",
 metadata={
 "user_id": self.user_id,
 "timestamp": datetime.now().isoformat(),
 "importance": importance,
 "category": category or "general",
 "type": "conversation"
 }
 )

 # 添加到向量数据库
 self.vectorstore.add_documents([document])

 def save_fact(self, fact: str, category: str = "fact"):
 """保存事实性知识"""
 document = Document(
 page_content=fact,
 metadata={
 "user_id": self.user_id,
 "timestamp": datetime.now().isoformat(),
 "type": "fact",
 "category": category
 }
 )
 self.vectorstore.add_documents([document])

 def retrieve_relevant(
 self,
 query: str,
 k: int = 5,
 filters: Optional[dict] = None
 ) -> list:
 """检索相关记忆"""

 # 基础过滤条件
 base_filter = {"user_id": self.user_id}

 # 合并额外过滤条件
 if filters:
 base_filter.update(filters)

 # 检索
 results = self.vectorstore.similarity_search(
 query,
 k=k,
 filter=base_filter
 )

 return results

 def retrieve_by_time_range(
 self,
 start_time: datetime,
 end_time: datetime,
 k: int = 10
 ) -> list:
 """按时间范围检索"""
 # 注意：不同向量数据库的过滤语法不同
 # 这里以 Chroma 为例
 results = self.vectorstore.similarity_search(
 "", # 空查询
 k=k,
 filter={
 "user_id": self.user_id,
 "timestamp": {
 "$gte": start_time.isoformat(),
 "$lte": end_time.isoformat()
 }
 }
 )
 return results

 def get_user_preferences(self) -> list:
 """获取用户偏好"""
 return self.retrieve_relevant(
 query="用户偏好",
 k=10,
 filters={"category": "preference"}
 )

 def get_important_memories(self) -> list:
 """获取重要记忆"""
 return self.retrieve_relevant(
 query="",
 k=10,
 filters={"importance": "high"}
 )

方案二：混合检索记忆

结合向量检索和关键词检索，提高召回率：

from langchain.retrievers import EnsembleRetriever
from langchain_community.retrievers import BM25Retriever
from langchain_community.vectorstores import Chroma

class HybridMemory:
 """混合检索记忆"""

 def __init__(self, vectorstore, documents):
 # 向量检索器
 self.vector_retriever = vectorstore.as_retriever(
 search_kwargs={"k": 5}
 )

 # 关键词检索器（BM25）
 self.keyword_retriever = BM25Retriever.from_documents(documents)
 self.keyword_retriever.k = 5

 # 混合检索器
 self.ensemble_retriever = EnsembleRetriever(
 retrievers=[self.vector_retriever, self.keyword_retriever],
 weights=[0.6, 0.4] # 向量检索权重更高
 )

 def retrieve(self, query: str) -> list:
 """混合检索"""
 return self.ensemble_retriever.invoke(query)

混合检索的优势：

查询："Python 异常处理"

┌─────────────────────────────────────────────────────────┐
│ 向量检索结果 │
├─────────────────────────────────────────────────────────┤
│ 1. 如何捕获 Python 异常？ │
│ 2. try-except 语句的使用 │
│ 3. Python 错误处理最佳实践 │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│ 关键词检索结果 │
├─────────────────────────────────────────────────────────┤
│ 1. Python 异常类型列表 │
│ 2. 异常处理的代码示例 │
│ 3. raise 语句的用法 │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│ 混合检索结果 │
├─────────────────────────────────────────────────────────┤
│ 去重 + 加权排序 → 更全面的记忆召回 │
└─────────────────────────────────────────────────────────┘

方案三：知识图谱增强记忆

将记忆组织成知识图谱，支持复杂推理：

from langchain.graphs import Neo4jGraph
from langchain.chains import GraphQAChain

class KnowledgeGraphMemory:
 """知识图谱记忆"""

 def __init__(self, neo4j_url: str, neo4j_user: str, neo4j_password: str):
 self.graph = Neo4jGraph(
 url=neo4j_url,
 username=neo4j_user,
 password=neo4j_password
 )

 def save_entity(self, entity_type: str, entity_name: str, properties: dict):
 """保存实体"""
 props_str = ", ".join([f"{k}: {v}" for k, v in properties.items()])

 query = f"""
 MERGE (e:{entity_type} {{name: $name}})
 SET e += {{{props_str}}}
 """

 self.graph.query(query, params={"name": entity_name})

 def save_relation(self, from_entity: str, relation: str, to_entity: str):
 """保存关系"""
 query = f"""
 MATCH (a {{name: $from_name}})
 MATCH (b {{name: $to_name}})
 MERGE (a)-[r:{relation}]->(b)
 """

 self.graph.query(query, params={
 "from_name": from_entity,
 "to_name": to_entity
 })

 def save_conversation_memory(
 self,
 user_id: str,
 entities: list,
 relations: list,
 conversation_id: str
 ):
 """保存对话记忆到知识图谱"""

 # 保存实体
 for entity in entities:
 self.save_entity(
 entity_type=entity["type"],
 entity_name=entity["name"],
 properties=entity.get("properties", {})
 )

 # 保存关系
 for relation in relations:
 self.save_relation(
 from_entity=relation["from"],
 relation=relation["type"],
 to_entity=relation["to"]
 )

 # 关联到对话
 query = """
 MATCH (u:User {id: $user_id})
 MATCH (c:Conversation {id: $conv_id})
 MERGE (u)-[:HAD]->(c)
 """
 self.graph.query(query, params={
 "user_id": user_id,
 "conv_id": conversation_id
 })

 def query_related_knowledge(self, entity_name: str, depth: int = 2) -> list:
 """查询相关知识"""
 query = f"""
 MATCH path = (e {{name: $name}})-[*1..{depth}]-(related)
 RETURN path
 """

 return self.graph.query(query, params={"name": entity_name})

知识图谱记忆示例：

用户说："我和李四在讨论 Python 项目"

知识图谱存储：
┌─────────────────────────────────────────────────────────┐
│ │
│ (User:张三) ──[:DISCUSSED_WITH]──→ (User:李四) │
│ │ │
│ └──[:DISCUSSED_ABOUT]──→ (Topic:Python) │
│ │ │
│ └──[:RELATED_TO] │
│ ↓ │
│ (Project:XXX) │
│ │
└─────────────────────────────────────────────────────────┘

下次用户问："上次我和谁讨论 Python？"
→ 查询图谱 → 返回"李四"

方案四：层级化长期记忆

模拟人类记忆的层级结构：

class HierarchicalLongTermMemory:
 """层级化长期记忆"""

 def __init__(self):
 # Level 1: 工作记忆（当前会话）
 self.working_memory = []

 # Level 2: 情景记忆（Episodic Memory）
 # 存储具体事件和经历
 self.episodic_store = {} # {session_id: [events]}

 # Level 3: 语义记忆（Semantic Memory）
 # 存储事实和知识
 self.semantic_store = {} # {concept: facts}

 # Level 4: 程序记忆（Procedural Memory）
 # 存储技能和规则
 self.procedural_store = {} # {skill: rules}

 def add_to_working_memory(self, event: dict):
 """添加到工作记忆"""
 self.working_memory.append(event)

 def consolidate_to_episodic(self, session_id: str):
 """将工作记忆巩固到情景记忆"""
 if session_id not in self.episodic_store:
 self.episodic_store[session_id] = []

 self.episodic_store[session_id].extend(self.working_memory)
 self.working_memory = []

 def extract_to_semantic(self, concept: str, facts: list):
 """提取事实到语义记忆"""
 if concept not in self.semantic_store:
 self.semantic_store[concept] = []

 self.semantic_store[concept].extend(facts)

 def learn_procedure(self, skill: str, rules: list):
 """学习程序性知识"""
 self.procedural_store[skill] = rules

 def retrieve(self, query: str, context: dict) -> dict:
 """检索记忆"""
 results = {
 "episodic": self._search_episodic(query),
 "semantic": self._search_semantic(query),
 "procedural": self._search_procedural(context)
 }
 return results

 def _search_episodic(self, query: str) -> list:
 """搜索情景记忆"""
 # 实际应该用向量检索
 results = []
 for session_id, events in self.episodic_store.items():
 for event in events:
 if query.lower() in str(event).lower():
 results.append(event)
 return results

 def _search_semantic(self, query: str) -> list:
 """搜索语义记忆"""
 results = []
 for concept, facts in self.semantic_store.items():
 if query.lower() in concept.lower():
 results.extend(facts)
 return results

 def _search_procedural(self, context: dict) -> list:
 """搜索程序记忆"""
 # 根据上下文匹配相关技能
 results = []
 for skill, rules in self.procedural_store.items():
 if self._is_skill_relevant(skill, context):
 results.extend(rules)
 return results

 def _is_skill_relevant(self, skill: str, context: dict) -> bool:
 """判断技能是否相关"""
 # 简化实现
 return skill in str(context)

记忆层级示意：

┌─────────────────────────────────────────────────────────┐
│ 记忆层级结构 │
├─────────────────────────────────────────────────────────┤
│ │
│ Level 1: 工作记忆（秒级） │
│ └─ 当前对话中的最近几轮 │
│ │
│ Level 2: 情景记忆（小时-天） │
│ └─ 具体事件："昨天讨论了 Python 项目" │
│ │
│ Level 3: 语义记忆（永久） │
│ └─ 事实知识："用户喜欢 Python"、"用户叫张三" │
│ │
│ Level 4: 程序记忆（永久） │
│ └─ 技能规则："遇到代码问题 → 先检查语法错误" │
│ │
└─────────────────────────────────────────────────────────┘

3.5 长期记忆的最佳实践

实践一：记忆去重与更新

class DeduplicatedMemory:
 """去重记忆系统"""

 def __init__(self, vectorstore, similarity_threshold: float = 0.95):
 self.vectorstore = vectorstore
 self.similarity_threshold = similarity_threshold

 def save_memory(self, content: str, metadata: dict):
 """保存记忆（带去重）"""

 # 检查是否已存在相似记忆
 similar_docs = self.vectorstore.similarity_search_with_score(
 content,
 k=1
 )

 if similar_docs:
 doc, score = similar_docs[0]
 # 相似度高于阈值，认为是重复
 if score > self.similarity_threshold:
 # 更新元数据（如时间戳）
 self._update_metadata(doc.id, metadata)
 return False # 未添加新记忆

 # 添加新记忆
 self.vectorstore.add_texts([content], metadatas=[metadata])
 return True # 添加成功

 def _update_metadata(self, doc_id: str, new_metadata: dict):
 """更新元数据"""
 # 实现取决于具体的向量数据库
 pass

实践二：记忆遗忘机制

模拟人类遗忘，避免存储过多无用信息：

from datetime import datetime, timedelta
import numpy as np

class ForgettingMemory:
 """带遗忘机制的记忆"""

 def __init__(self, vectorstore, half_life_days: int = 30):
 self.vectorstore = vectorstore
 self.half_life_days = half_life_days

 def calculate_retention_score(
 self,
 timestamp: datetime,
 access_count: int = 1,
 importance: float = 1.0
 ) -> float:
 """
 计算记忆保留分数

 艾宾浩斯遗忘曲线变体：
 R = importance * access_count * e^(-t/τ)
 """
 # 时间衰减
 days_passed = (datetime.now() - timestamp).days
 time_decay = np.exp(-days_passed / self.half_life_days)

 # 访问增强
 access_boost = np.log1p(access_count)

 # 最终分数
 score = importance * access_boost * time_decay

 return score

 def should_forget(self, memory_metadata: dict) -> bool:
 """判断是否应该遗忘"""
 score = self.calculate_retention_score(
 timestamp=datetime.fromisoformat(memory_metadata["timestamp"]),
 access_count=memory_metadata.get("access_count", 1),
 importance=memory_metadata.get("importance", 1.0)
 )

 return score < 0.1 # 阈值

 def cleanup_memories(self, user_id: str):
 """清理低价值记忆"""
 # 检索用户所有记忆
 all_memories = self.vectorstore.similarity_search(
 "",
 k=1000,
 filter={"user_id": user_id}
 )

 # 识别需要遗忘的记忆
 to_forget = []
 for memory in all_memories:
 if self.should_forget(memory.metadata):
 to_forget.append(memory.id)

 # 删除
 if to_forget:
 self.vectorstore.delete(to_forget)
 print(f"已清理 {len(to_forget)} 条记忆")

实践三：记忆重要性评估

class ImportanceScorer:
 """记忆重要性评分"""

 def __init__(self):
 self.importance_keywords = {
 "high": [
 "重要", "紧急", "必须", "关键", "决定",
 "偏好", "喜欢", "讨厌", "习惯"
 ],
 "medium": [
 "需要", "想要", "希望", "建议", "想法"
 ],
 "low": [
 "随便", "无所谓", "可能", "或许"
 ]
 }

 def score_importance(self, user_input: str, ai_output: str) -> float:
 """评估记忆重要性"""
 score = 0.0

 # 1. 关键词匹配
 score += self._keyword_score(user_input)

 # 2. 情感强度
 score += self._sentiment_score(user_input)

 # 3. 信息熵（信息量）
 score += self._information_entropy_score(user_input)

 # 4. 交互深度（追问、确认等）
 score += self._interaction_depth_score(user_input)

 return min(max(score, 0.0), 1.0) # 归一化到 [0, 1]

 def _keyword_score(self, text: str) -> float:
 """关键词评分"""
 for level, keywords in self.importance_keywords.items():
 if any(kw in text for kw in keywords):
 if level == "high":
 return 0.4
 elif level == "medium":
 return 0.2
 else:
 return 0.1
 return 0.05

 def _sentiment_score(self, text: str) -> float:
 """情感强度评分"""
 # 简化实现，实际可用情感分析模型
 strong_emotions = ["非常", "特别", "极其", "超级"]
 return 0.2 if any(e in text for e in strong_emotions) else 0.0

 def _information_entropy_score(self, text: str) -> float:
 """信息熵评分"""
 # 基于文本长度和信息密度
 word_count = len(text.split())

 if word_count < 5:
 return 0.05
 elif word_count < 20:
 return 0.1
 else:
 return 0.2

 def _interaction_depth_score(self, text: str) -> float:
 """交互深度评分"""
 # 多问题、追问等表示重要
 question_marks = text.count("?") + text.count("？")
 return min(question_marks * 0.1, 0.2)

四、记忆系统集成实践

4.1 完整记忆系统架构

from typing import Optional, List, Dict
from datetime import datetime
from dataclasses import dataclass
from enum import Enum

class MemoryType(Enum):
 """记忆类型"""
 WORKING = "working" # 工作记忆
 SHORT_TERM = "short_term" # 短期记忆
 LONG_TERM = "long_term" # 长期记忆
 EPISODIC = "episodic" # 情景记忆
 SEMANTIC = "semantic" # 语义记忆

@dataclass
class MemoryEntry:
 """记忆条目"""
 id: str
 content: str
 memory_type: MemoryType
 timestamp: datetime
 importance: float
 access_count: int
 metadata: dict

class UnifiedMemorySystem:
 """统一记忆系统"""

 def __init__(
 self,
 vectorstore,
 embeddings,
 llm,
 user_id: str,
 config: Optional[dict] = None
 ):
 self.vectorstore = vectorstore
 self.embeddings = embeddings
 self.llm = llm
 self.user_id = user_id

 # 配置
 self.config = config or {
 "working_memory_limit": 10,
 "short_term_limit": 20,
 "long_term_retrieval_k": 5,
 "importance_threshold": 0.7,
 "consolidation_interval": 10
 }

 # 记忆存储
 self.working_memory: List[MemoryEntry] = []
 self.importance_scorer = ImportanceScorer()
 self.forgetting_system = ForgettingMemory(vectorstore)

 def add_memory(
 self,
 user_input: str,
 ai_output: str,
 force_long_term: bool = False
 ):
 """添加记忆"""

 # 评估重要性
 importance = self.importance_scorer.score_importance(
 user_input, ai_output
 )

 # 创建记忆条目
 entry = MemoryEntry(
 id=self._generate_id(),
 content=f"User: {user_input}\nAI: {ai_output}",
 memory_type=MemoryType.WORKING,
 timestamp=datetime.now(),
 importance=importance,
 access_count=1,
 metadata={
 "user_id": self.user_id,
 "user_input": user_input,
 "ai_output": ai_output
 }
 )

 # 添加到工作记忆
 self.working_memory.append(entry)

 # 检查是否需要巩固到长期记忆
 if (len(self.working_memory) >= self.config["working_memory_limit"] or
 importance > self.config["importance_threshold"] or
 force_long_term):
 self._consolidate_memories()

 def retrieve_memories(
 self,
 query: str,
 memory_types: Optional[List[MemoryType]] = None
 ) -> List[MemoryEntry]:
 """检索记忆"""

 memory_types = memory_types or [
 MemoryType.WORKING,
 MemoryType.SHORT_TERM,
 MemoryType.LONG_TERM
 ]

 results = []

 # 1. 从工作记忆检索
 if MemoryType.WORKING in memory_types:
 results.extend(self.working_memory)

 # 2. 从长期记忆检索
 if MemoryType.LONG_TERM in memory_types:
 long_term_results = self._retrieve_long_term(query)
 results.extend(long_term_results)

 # 3. 排序（按重要性和时间）
 results.sort(key=lambda x: (x.importance, x.timestamp), reverse=True)

 # 4. 更新访问计数
 for entry in results:
 entry.access_count += 1

 return results[:self.config["long_term_retrieval_k"]]

 def _consolidate_memories(self):
 """巩固记忆"""

 if not self.working_memory:
 return

 # 批量存储到向量数据库
 contents = [entry.content for entry in self.working_memory]
 metadatas = [
 {
 **entry.metadata,
 "timestamp": entry.timestamp.isoformat(),
 "importance": entry.importance,
 "memory_type": entry.memory_type.value
 }
 for entry in self.working_memory
 ]

 self.vectorstore.add_texts(contents, metadatas=metadatas)

 # 清空工作记忆
 self.working_memory = []

 def _retrieve_long_term(self, query: str) -> List[MemoryEntry]:
 """从长期记忆检索"""

 docs = self.vectorstore.similarity_search(
 query,
 k=self.config["long_term_retrieval_k"],
 filter={"user_id": self.user_id}
 )

 entries = []
 for doc in docs:
 entry = MemoryEntry(
 id=doc.metadata.get("id", ""),
 content=doc.page_content,
 memory_type=MemoryType.LONG_TERM,
 timestamp=datetime.fromisoformat(doc.metadata["timestamp"]),
 importance=doc.metadata.get("importance", 0.5),
 access_count=doc.metadata.get("access_count", 1),
 metadata=doc.metadata
 )
 entries.append(entry)

 return entries

 def get_context_for_llm(
 self,
 query: str,
 max_tokens: int = 4000
 ) -> str:
 """获取传递给 LLM 的上下文"""

 # 检索相关记忆
 memories = self.retrieve_memories(query)

 # 构建上下文
 context_parts = []

 # 1. 重要事实
 important_memories = [
 m for m in memories if m.importance > 0.7
 ]
 if important_memories:
 facts_str = "\n".join([
 f"- {m.metadata['user_input']}"
 for m in important_memories
 ])
 context_parts.append(f"【重要信息】\n{facts_str}")

 # 2. 相关对话
 relevant_str = "\n\n".join([
 m.content for m in memories[:5]
 ])
 context_parts.append(f"【相关历史】\n{relevant_str}")

 context = "\n\n".join(context_parts)

 # Token 检查
 token_count = self._count_tokens(context)
 if token_count > max_tokens:
 context = self._truncate_context(context, max_tokens)

 return context

 def _generate_id(self) -> str:
 """生成唯一 ID"""
 import uuid
 return str(uuid.uuid4())

 def _count_tokens(self, text: str) -> int:
 """计算 Token 数"""
 # 简化实现
 return len(text.split()) * 1.5

 def _truncate_context(self, context: str, max_tokens: int) -> str:
 """截断上下文"""
 # 简化实现
 words = context.split()
 return " ".join(words[:int(max_tokens / 1.5)])

 def cleanup(self):
 """清理低价值记忆"""
 self.forgetting_system.cleanup_memories(self.user_id)

4.2 与 LangChain 集成

from langchain.chains import ConversationChain
from langchain_openai import ChatOpenAI
from langchain.prompts import PromptTemplate

# 初始化记忆系统
memory_system = UnifiedMemorySystem(
 vectorstore=Chroma(
 embedding_function=OpenAIEmbeddings(),
 persist_directory="./memory_db"
 ),
 embeddings=OpenAIEmbeddings(),
 llm=ChatOpenAI(model="gpt-4"),
 user_id="user_123"
)

# 自定义 Prompt 模板
template = """
你是一个智能助手，拥有对用户的长期记忆。

{memory_context}

当前对话：
{input}

请基于记忆和当前输入回复：
"""

prompt = PromptTemplate(
 input_variables=["memory_context", "input"],
 template=template
)

# 对话函数
def chat_with_memory(user_input: str) -> str:
 """带记忆的对话"""

 # 1. 检索相关记忆
 memory_context = memory_system.get_context_for_llm(user_input)

 # 2. 生成回复
 llm = ChatOpenAI(model="gpt-4")
 prompt_text = prompt.format(
 memory_context=memory_context,
 input=user_input
 )
 ai_output = llm.invoke(prompt_text).content

 # 3. 保存记忆
 memory_system.add_memory(user_input, ai_output)

 return ai_output

# 使用示例
response1 = chat_with_memory("我叫张三，我喜欢 Python")
print(response1)
# 输出：你好张三！很高兴认识你。Python 是一门很棒的语言...

# ... 开启新对话

response2 = chat_with_memory("你还记得我的名字吗？")
print(response2)
# 输出：当然记得！你叫张三。而且我知道你喜欢 Python...

4.3 记忆系统评估

class MemoryEvaluator:
 """记忆系统评估器"""

 def __init__(self, memory_system: UnifiedMemorySystem):
 self.memory_system = memory_system

 def evaluate_retrieval_quality(
 self,
 test_cases: List[dict]
 ) -> dict:
 """评估检索质量"""

 results = {
 "precision": [],
 "recall": [],
 "mrr": [] # Mean Reciprocal Rank
 }

 for case in test_cases:
 query = case["query"]
 expected_ids = set(case["relevant_memory_ids"])

 # 检索
 retrieved = self.memory_system.retrieve_memories(query)
 retrieved_ids = set([m.id for m in retrieved])

 # 计算指标
 if retrieved_ids:
 precision = len(retrieved_ids & expected_ids) / len(retrieved_ids)
 results["precision"].append(precision)

 if expected_ids:
 recall = len(retrieved_ids & expected_ids) / len(expected_ids)
 results["recall"].append(recall)

 # MRR
 for i, memory in enumerate(retrieved):
 if memory.id in expected_ids:
 results["mrr"].append(1.0 / (i + 1))
 break
 else:
 results["mrr"].append(0.0)

 # 平均值
 return {
 "avg_precision": np.mean(results["precision"]),
 "avg_recall": np.mean(results["recall"]),
 "avg_mrr": np.mean(results["mrr"])
 }

 def evaluate_memory_usage(self) -> dict:
 """评估记忆使用情况"""

 # 统计各类记忆数量
 all_memories = self.memory_system.vectorstore.similarity_search(
 "",
 k=10000,
 filter={"user_id": self.memory_system.user_id}
 )

 # 按重要性分布
 importance_dist = {
 "high": 0,
 "medium": 0,
 "low": 0
 }

 for memory in all_memories:
 importance = memory.metadata.get("importance", 0.5)
 if importance > 0.7:
 importance_dist["high"] += 1
 elif importance > 0.3:
 importance_dist["medium"] += 1
 else:
 importance_dist["low"] += 1

 # Token 消耗估算
 total_tokens = sum([
 len(m.page_content.split()) * 1.5
 for m in all_memories
 ])

 return {
 "total_memories": len(all_memories),
 "importance_distribution": importance_dist,
 "estimated_tokens": total_tokens,
 "working_memory_size": len(self.memory_system.working_memory)
 }

 def benchmark_retrieval_speed(
 self,
 queries: List[str],
 k: int = 5
 ) -> dict:
 """基准测试检索速度"""

 import time

 latencies = []

 for query in queries:
 start_time = time.time()
 _ = self.memory_system.retrieve_memories(query)
 latency = time.time() - start_time
 latencies.append(latency)

 return {
 "avg_latency_ms": np.mean(latencies) * 1000,
 "p50_latency_ms": np.percentile(latencies, 50) * 1000,
 "p95_latency_ms": np.percentile(latencies, 95) * 1000,
 "p99_latency_ms": np.percentile(latencies, 99) * 1000
 }

五、高级主题

5.1 多用户记忆隔离

class MultiUserMemorySystem:
 """多用户记忆系统"""

 def __init__(self, vectorstore, embeddings, llm):
 self.vectorstore = vectorstore
 self.embeddings = embeddings
 self.llm = llm

 # 用户记忆系统缓存
 self.user_memories: Dict[str, UnifiedMemorySystem] = {}

 def get_user_memory(self, user_id: str) -> UnifiedMemorySystem:
 """获取用户的记忆系统"""

 if user_id not in self.user_memories:
 self.user_memories[user_id] = UnifiedMemorySystem(
 vectorstore=self.vectorstore,
 embeddings=self.embeddings,
 llm=self.llm,
 user_id=user_id
 )

 return self.user_memories[user_id]

 def chat(self, user_id: str, user_input: str) -> str:
 """用户对话"""
 memory = self.get_user_memory(user_id)

 # 获取上下文
 context = memory.get_context_for_llm(user_input)

 # 生成回复
 prompt = f"{context}\n\n用户：{user_input}\n\n助手："
 response = self.llm.invoke(prompt).content

 # 保存记忆
 memory.add_memory(user_input, response)

 return response

 def share_memory_between_users(
 self,
 from_user: str,
 to_user: str,
 memory_ids: List[str]
 ):
 """在用户间共享记忆"""

 # 检索源用户的记忆
 from_memory = self.get_user_memory(from_user)

 # 复制到目标用户
 to_memory = self.get_user_memory(to_user)

 for memory_id in memory_ids:
 # 从向量数据库检索
 # 然后添加到目标用户
 pass

5.2 跨模态记忆

class MultiModalMemory:
 """多模态记忆"""

 def __init__(self, vectorstore, text_embeddings, image_embeddings):
 self.vectorstore = vectorstore
 self.text_embeddings = text_embeddings
 self.image_embeddings = image_embeddings

 def save_text_memory(self, text: str, metadata: dict):
 """保存文本记忆"""
 embedding = self.text_embeddings.embed_query(text)

 self.vectorstore.add_embeddings(
 [(text, embedding)],
 metadatas=[{**metadata, "modality": "text"}]
 )

 def save_image_memory(self, image_path: str, description: str, metadata: dict):
 """保存图像记忆"""
 # 提取图像特征
 embedding = self.image_embeddings.embed_image(image_path)

 self.vectorstore.add_embeddings(
 [(description, embedding)],
 metadatas=[{
 **metadata,
 "modality": "image",
 "image_path": image_path
 }]
 )

 def retrieve_multimodal(
 self,
 query: str,
 modalities: List[str] = ["text", "image"]
 ) -> List[dict]:
 """多模态检索"""

 # 文本查询嵌入
 query_embedding = self.text_embeddings.embed_query(query)

 # 检索
 results = self.vectorstore.similarity_search_by_vector(
 query_embedding,
 k=10,
 filter={"modality": {"$in": modalities}}
 )

 return results

5.3 记忆压缩与总结

class MemoryCompressor:
 """记忆压缩器"""

 def __init__(self, llm):
 self.llm = llm

 def compress_memories(
 self,
 memories: List[MemoryEntry],
 strategy: str = "summary"
 ) -> str:
 """压缩记忆"""

 if strategy == "summary":
 return self._summarize(memories)
 elif strategy == "extract":
 return self._extract_key_points(memories)
 else:
 raise ValueError(f"Unknown strategy: {strategy}")

 def _summarize(self, memories: List[MemoryEntry]) -> str:
 """生成摘要"""

 # 合并记忆内容
 combined_text = "\n\n".join([
 m.content for m in memories
 ])

 # 使用 LLM 生成摘要
 prompt = f"""
请将以下对话历史压缩成简洁的摘要，保留关键信息：

{combined_text}

摘要：
"""

 summary = self.llm.invoke(prompt).content
 return summary

 def _extract_key_points(self, memories: List[MemoryEntry]) -> str:
 """提取关键点"""

 combined_text = "\n\n".join([
 m.content for m in memories
 ])

 prompt = f"""
从以下对话中提取关键事实和信息点：

{combined_text}

关键信息：
-
"""

 key_points = self.llm.invoke(prompt).content
 return key_points

六、性能优化

6.1 检索优化

class OptimizedMemoryRetriever:
 """优化的记忆检索器"""

 def __init__(
 self,
 vectorstore,
 embeddings,
 cache_size: int = 1000
 ):
 self.vectorstore = vectorstore
 self.embeddings = embeddings

 # 查询缓存
 self.query_cache = {}
 self.cache_size = cache_size

 def retrieve_with_cache(
 self,
 query: str,
 k: int = 5,
 use_cache: bool = True
 ) -> List:
 """带缓存的检索"""

 # 检查缓存
 cache_key = self._get_cache_key(query, k)

 if use_cache and cache_key in self.query_cache:
 return self.query_cache[cache_key]

 # 执行检索
 results = self.vectorstore.similarity_search(query, k=k)

 # 更新缓存
 if use_cache:
 self._update_cache(cache_key, results)

 return results

 def _get_cache_key(self, query: str, k: int) -> str:
 """生成缓存键"""
 import hashlib
 return hashlib.md5(f"{query}_{k}".encode()).hexdigest()

 def _update_cache(self, key: str, value: List):
 """更新缓存"""
 # LRU 淘汰
 if len(self.query_cache) >= self.cache_size:
 # 删除最旧的
 oldest_key = next(iter(self.query_cache))
 del self.query_cache[oldest_key]

 self.query_cache[key] = value

 def batch_retrieve(
 self,
 queries: List[str],
 k: int = 5
 ) -> List[List]:
 """批量检索"""

 # 批量嵌入
 query_embeddings = self.embeddings.embed_documents(queries)

 # 批量检索
 results = []
 for embedding in query_embeddings:
 docs = self.vectorstore.similarity_search_by_vector(
 embedding,
 k=k
 )
 results.append(docs)

 return results

6.2 存储优化

class OptimizedMemoryStorage:
 """优化的记忆存储"""

 def __init__(self, vectorstore, compression_threshold: int = 1000):
 self.vectorstore = vectorstore
 self.compression_threshold = compression_threshold

 def save_with_compression(
 self,
 contents: List[str],
 metadatas: List[dict]
 ):
 """带压缩的存储"""

 # 如果内容过长，先压缩
 compressed_contents = []
 for content in contents:
 if len(content) > self.compression_threshold:
 content = self._compress_content(content)
 compressed_contents.append(content)

 # 存储
 self.vectorstore.add_texts(compressed_contents, metadatas=metadatas)

 def _compress_content(self, content: str) -> str:
 """压缩内容"""
 # 移除多余空白
 import re
 content = re.sub(r'\s+', ' ', content)

 # 截断
 if len(content) > self.compression_threshold:
 content = content[:self.compression_threshold] + "..."

 return content

 def optimize_storage(self):
 """优化存储"""
 # 1. 合并相似记忆
 # 2. 删除过期记忆
 # 3. 更新索引
 pass

七、实战案例

案例：个性化学习助手记忆系统

class PersonalizedLearningAssistant:
 """个性化学习助手"""

 def __init__(self, user_id: str):
 # 初始化记忆系统
 self.memory_system = UnifiedMemorySystem(
 vectorstore=Chroma(
 embedding_function=OpenAIEmbeddings(),
 persist_directory=f"./learning_assistant/{user_id}"
 ),
 embeddings=OpenAIEmbeddings(),
 llm=ChatOpenAI(model="gpt-4"),
 user_id=user_id
 )

 # 学习档案
 self.learning_profile = {
 "knowledge_level": {}, # 各知识点的掌握程度
 "learning_style": None, # 学习风格
 "goals": [], # 学习目标
 "weaknesses": [] # 薄弱环节
 }

 def learn(self, topic: str, content: str):
 """学习过程"""

 # 1. 检索相关记忆
 context = self.memory_system.get_context_for_llm(
 f"关于 {topic} 的知识"
 )

 # 2. 生成学习内容
 prompt = f"""
用户正在学习 {topic}。

历史学习记录：
{context}

当前学习内容：
{content}

请：
1. 讲解这个知识点
2. 关联之前的学习内容
3. 提供练习题
"""

 response = self.memory_system.llm.invoke(prompt).content

 # 3. 保存记忆
 self.memory_system.add_memory(
 f"学习 {topic}: {content}",
 response,
 force_long_term=True
 )

 # 4. 更新学习档案
 self._update_profile(topic, content, response)

 return response

 def review(self, topic: str) -> str:
 """复习过程"""

 # 检索该主题的所有相关记忆
 memories = self.memory_system.retrieve_memories(
 f"{topic} 知识点",
 memory_types=[MemoryType.LONG_TERM]
 )

 # 生成复习内容
 context = "\n\n".join([m.content for m in memories])

 prompt = f"""
用户要复习 {topic}。

学习历史：
{context}

请生成一份复习总结，包括：
1. 核心概念回顾
2. 重点难点梳理
3. 常见错误提醒
4. 巩固练习
"""

 return self.memory_system.llm.invoke(prompt).content

 def _update_profile(self, topic: str, content: str, response: str):
 """更新学习档案"""

 # 使用 LLM 提取知识点和掌握程度
 extraction_prompt = f"""
分析以下学习内容，提取：
1. 知识点
2. 用户掌握程度（1-5）
3. 学习难点

学习内容：
{content}

AI 回复：
{response}

以 JSON 格式返回。
"""

 import json
 extraction = self.memory_system.llm.invoke(extraction_prompt).content

 try:
 data = json.loads(extraction)

 # 更新知识点掌握程度
 for kp in data.get("knowledge_points", []):
 self.learning_profile["knowledge_level"][kp["name"]] = {
 "level": kp["level"],
 "last_review": datetime.now().isoformat()
 }

 # 更新薄弱环节
 difficulties = data.get("difficulties", [])
 self.learning_profile["weaknesses"].extend(difficulties)
 self.learning_profile["weaknesses"] = list(set(
 self.learning_profile["weaknesses"]
 ))

 except Exception as e:
 print(f"更新档案失败: {e}")

 def get_personalized_recommendation(self) -> str:
 """获取个性化学习推荐"""

 # 基于记忆和学习档案生成推荐
 prompt = f"""
基于用户的学习档案：

{json.dumps(self.learning_profile, indent=2)}

请推荐：
1. 下一步应该学习什么
2. 需要复习哪些内容
3. 如何改进学习方法
"""

 return self.memory_system.llm.invoke(prompt).content

# 使用示例
assistant = PersonalizedLearningAssistant(user_id="learner_123")

# 学习
response1 = assistant.learn(
 "Python 基础",
 "变量和数据类型"
)
print(response1)

# 继续学习
response2 = assistant.learn(
 "Python 基础",
 "条件和循环"
)
print(response2)

# 复习
review = assistant.review("Python 基础")
print(review)

# 获取推荐
recommendation = assistant.get_personalized_recommendation()
print(recommendation)

八、总结与最佳实践清单

记忆系统设计原则

分层原则：工作记忆 → 短期记忆 → 长期记忆
重要性优先：重要信息优先存储和检索
遗忘机制：定期清理低价值记忆
上下文相关：检索与当前上下文相关的记忆
用户隔离：多用户场景下的记忆隔离

最佳实践清单

短期记忆

✅ 根据场景选择合适的记忆类型（滑动窗口 vs 摘要）
✅ 监控 Token 消耗，避免超出 Context Window
✅ 提取并优先保留重要信息
✅ 考虑混合记忆策略（摘要 + 完整对话）

长期记忆

✅ 选择合适的向量数据库（考虑规模、性能、成本）
✅ 选择合适的嵌入模型（考虑语言、性能、成本）
✅ 实现记忆去重机制
✅ 实现遗忘机制，定期清理
✅ 为记忆添加丰富的元数据
✅ 考虑混合检索（向量 + 关键词）

性能优化

✅ 实现查询缓存
✅ 批量操作优化
✅ 内容压缩
✅ 异步处理

评估与监控

✅ 建立检索质量评估体系
✅ 监控记忆使用情况
✅ 基准测试检索速度
✅ 收集用户反馈

常见问题与解决方案

问题	解决方案
Token 超限	滑动窗口 + 摘要记忆
检索不准确	混合检索 + 元数据过滤
记忆重复	去重机制 + 相似度阈值
检索慢	缓存 + 索引优化
存储爆炸	遗忘机制 + 压缩
跨用户泄露	用户 ID 过滤 + 权限控制

参考资料

论文

开源项目

向量数据库

教程

智能体编排设计工程师学习指南

Tue, 17 Jun 2025 11:00:00 +0800

什么是智能体编排设计工程师？

智能体编排设计工程师是一个随着大模型（LLM）技术落地而新兴的热门岗位。它介于算法工程师、全栈开发工程师和产品经理之间，核心目标是让多个 AI 智能体协同工作，解决复杂问题。

可以把它看作是 AI 时代的"系统架构师"。

为什么这个岗位会出现？

传统软件开发中，系统架构师负责设计模块划分、接口定义、通信协议。当系统从"人写代码"变成"AI 写代码 + AI 执行任务"时，架构师的角色自然演化为：

不再设计模块间调用，而是设计 Agent 间协作
不再定义 API 接口，而是设计 Prompt 接口
不再关注性能瓶颈，而是关注 Token 成本和推理延迟

2023 年以前，做 AI 应用的人主要是"调 API"——把用户输入发给模型，拿到输出返回。但随着任务复杂度提升，单个模型无法完成长流程任务，多 Agent 编排成为刚需。

Agent 的内部结构

理解编排之前，先要理解单个 Agent 的内部结构。一个标准 Agent 包含四个核心模块：

1. 记忆（Memory）

记忆是 Agent 最核心的模块之一，决定了 Agent 能否"记住"用户、保持上下文连续性、从历史中学习。记忆系统分为两大类：

类型	说明	实现方式
短期记忆	当前对话上下文，存储在 LLM 的 Context Window 中	滑动窗口、摘要压缩、Token 限制截断
长期记忆	跨对话的知识存储，需要外部数据库	向量数据库（Milvus、Pinecone、ChromaDB）或关系数据库

短期记忆的核心挑战：LLM 有 Token 限制（GPT-4 约 128K），长对话会超出限制。LangChain 提供了多种短期记忆策略：

# 策略 1：滑动窗口 — 只保留最近 K 轮
from langchain.memory import ConversationBufferWindowMemory
memory = ConversationBufferWindowMemory(k=5)

# 策略 2：Token 限制截断 — 精确控制 Token 消耗
from langchain.memory import ConversationTokenBufferMemory
memory = ConversationTokenBufferMemory(llm=llm, max_token_limit=2000)

# 策略 3：摘要压缩 — 用摘要替代原始对话
from langchain.memory import ConversationSummaryMemory
memory = ConversationSummaryMemory(llm=llm)

# 策略 4：混合策略 — 摘要 + 最近完整对话
from langchain.memory import ConversationSummaryBufferMemory
memory = ConversationSummaryBufferMemory(llm=llm, max_token_limit=2000)

长期记忆的实现：

# 向量数据库存储对话历史
from langchain.memory import VectorStoreRetrieverMemory
from langchain.vectorstores import ChromaDB

vectorstore = ChromaDB(embedding_function=embeddings)
memory = VectorStoreRetrieverMemory(retriever=vectorstore.as_retriever())

📖 记忆模块的完整技术文档（包括多级记忆架构、向量数据库选型、嵌入模型对比、遗忘机制、知识图谱增强记忆、性能优化等）请参考：记忆模块技术文档

2. 规划（Planning）

规划是 Agent 的"大脑"，决定下一步做什么。主流方法：

方法	原理	适用场景
CoT（思维链）	让模型逐步推理，输出中间步骤	数学、逻辑推理
ToT（思维树）	多路径探索，选择最优分支	复杂决策问题
ReAct	Reasoning + Acting，推理与行动交替	需要调用工具的任务
Plan-and-Execute	先生成完整计划，再逐步执行	长流程任务

ReAct 模式示例：

用户：北京今天天气怎么样？

Agent 内部过程：
Thought: 用户想知道北京的天气，我需要调用天气 API
Action: call_weather_api(city="北京")
Observation: 北京今天晴，气温 25°C，湿度 40%
Thought: 已经获取天气信息，可以回答用户了
Answer: 北京今天晴天，气温 25 度，湿度较低，适合外出活动。

3. 工具（Tools）

工具是 Agent 的"手"，让它能执行实际操作。常见工具类型：

工具类型	示例	用途
搜索类	Google Search、Wikipedia API	获取外部信息
计算类	Python REPL、Calculator	数学计算
数据类	SQL Database、Vector Store	查询数据
操作类	HTTP API、文件操作	执行动作

Function Calling 实现：

from langchain.tools import Tool

# 定义工具
search_tool = Tool(
 name="web_search",
 description="搜索互联网获取信息，输入搜索关键词",
 func=search_function
)

# Agent 使用工具
from langchain.agents import AgentExecutor

agent = AgentExecutor.from_agent_and_tools(
 agent=llm_agent,
 tools=[search_tool, calculator_tool, weather_tool]
)

4. 行动（Action）

行动是 Agent 的最终输出。两种模式：

响应式：回答用户问题，不改变外部状态
执行式：调用 API、写入数据库、发送邮件等，改变外部状态

多智能体编排模式

单个 Agent 能力有限，复杂任务需要多个 Agent 协作。主流编排模式：

模式一：链式编排（Chain）

任务按顺序传递，每个 Agent 处理一个步骤。

适用场景：流水线任务，如"搜索 → 总结 → 翻译"

LangGraph 实现：

from langgraph.graph import StateGraph

# 定义状态
class ChainState(TypedDict):
 input: str
 search_result: str
 summary: str
 translation: str

# 构建 DAG
graph = StateGraph(ChainState)
graph.add_node("search", search_agent)
graph.add_node("summarize", summarize_agent)
graph.add_node("translate", translate_agent)

graph.add_edge("search", "summarize")
graph.add_edge("summarize", "translate")
graph.set_finish_point("translate")

缺点：无法并行，延迟累加。

模式二：层级编排（Hierarchical）

一个"管理者 Agent"拆解任务，分配给"工作者 Agent"，汇总结果。

适用场景：复杂项目，如"写代码 + 测试 + 部署"全流程

AutoGen 实现：

from autogen import AssistantAgent, UserProxyAgent

# 管理者
manager = AssistantAgent(
 name="Manager",
 system_message="你是项目经理，负责拆解任务并分配给合适的工程师"
)

# 工作者
coder = AssistantAgent(name="Coder", system_message="你负责写代码")
tester = AssistantAgent(name="Tester", system_message="你负责测试")
deployer = AssistantAgent(name="Deployer", system_message="你负责部署")

# 组建团队
groupchat = GroupChat(
 agents=[manager, coder, tester, deployer],
 messages=[]
)

优点：并行执行，效率高；职责清晰，便于调试。

模式三：网状编排（Mesh）

所有 Agent 地位平等，可以自由通信。适合创意性、探索性任务。

适用场景： brainstorming、创意写作、复杂问题讨论

缺点：通信复杂，难以预测结果，调试困难。

三种模式对比

模式	结构	并行能力	可控性	适用场景
链式	线性	❌ 无	⭐⭐⭐ 高	流水线任务
层级	树形	✅ 有	⭐⭐ 中	项目管理
网状	图形	✅ 有	⭐ 低	创意探索

企业级落地案例

案例 1：智能客服系统

需求：处理用户咨询，复杂问题转人工

Agent 设计：

关键技术点：

Router Agent：分类模型（GPT-4 或微调小模型）
FAQ Agent：RAG 检索知识库
Order Agent：调用订单系统 API
Tech Agent：RAG + 工具调用（日志查询、配置修改）
Human Agent：判断是否需要转人工，生成工单

成本优化：

模型选择	适用 Agent	原因
GPT-4o	Router Agent	分类准确性最重要
GPT-3.5	FAQ Agent	简单问答，成本低
Claude	Tech Agent	长上下文，技术文档理解强

案例 2：自动化报表生成

需求：每周自动生成销售报表，包含数据查询、图表生成、文字总结

Agent 设计：

# 链式编排
workflow = [
 ("sql_agent", "查询数据库获取销售数据"),
 ("analysis_agent", "分析数据趋势"),
 ("chart_agent", "生成可视化图表"),
 ("writer_agent", "撰写报表文字说明")
]

实际代码：

from langgraph.graph import StateGraph

class ReportState(TypedDict):
 raw_data: list # SQL 查询结果
 analysis: dict # 分析结论
 charts: list # 图表文件路径
 report: str # 最终报表文本

graph = StateGraph(ReportState)

# SQL Agent
def sql_agent(state):
 query = "SELECT date, revenue FROM sales WHERE date >= '2024-01-01'"
 data = db.execute(query)
 return {"raw_data": data}

# Analysis Agent
def analysis_agent(state):
 data = state["raw_data"]
 # 计算增长率、异常点等
 analysis = analyze_sales_data(data)
 return {"analysis": analysis}

# Chart Agent
def chart_agent(state):
 charts = generate_charts(state["raw_data"])
 return {"charts": charts}

# Writer Agent
def writer_agent(state):
 report = write_report(state["analysis"], state["charts"])
 return {"report": report}

# 构建流程
graph.add_node("sql", sql_agent)
graph.add_node("analysis", analysis_agent)
graph.add_node("chart", chart_agent)
graph.add_node("writer", writer_agent)

graph.add_edge("sql", "analysis")
graph.add_edge("analysis", "chart")
graph.add_edge("chart", "writer")

案例 3：代码开发助手

需求：从需求描述到代码提交的完整流程

层级编排设计：

实际效果对比：

任务	传统开发	Agent 辅助	提升
写 CRUD API	2 小时	15 分钟	8x
写单元测试	1 小时	5 分钟	12x
写 API 文档	30 分钟	3 分钟	10x
Code Review	20 分钟	10 分钟	2x

核心技术栈详解

LangChain：最全生态的 LLM 框架

核心模块：

LangChain
├── langchain-core # 核心抽象（Chain、Agent、Tool）
├── langchain-community # 社区集成（各种 API、数据库）
├── langchain-openai # OpenAI 专用集成
├── langchain-anthropic # Anthropic 专用集成
└── langgraph # 状态机编排（独立包）

必学概念：

概念	说明	学习优先级
Chain	顺序执行的调用链	⭐⭐⭐
Agent	自主决策的执行单元	⭐⭐⭐
Tool	Agent 可调用的工具	⭐⭐⭐
Memory	对话历史管理	⭐⭐
Retriever	RAG 检索器	⭐⭐⭐
Callback	执行过程监听	⭐

学习资源：

官方文档：https://python.langchain.com/
LangChain v0.3 API 文档（本项目已收录）：langchain_v0.3_API
LangSmith 使用教程：LangSmith使用教程

LangGraph：状态机编排

LangGraph 是 LangChain 团队推出的循环图编排框架，核心概念：

from langgraph.graph import StateGraph, END

# 定义状态（在节点间传递的数据）
class AgentState(TypedDict):
 messages: list
 next_action: str

# 定义节点（Agent 或函数）
def agent_node(state):
 response = llm.invoke(state["messages"])
 return {"messages": state["messages"] + [response]}

def tool_node(state):
 tool_result = execute_tool(state["messages"][-1])
 return {"messages": state["messages"] + [tool_result]}

# 构建图
graph = StateGraph(AgentState)
graph.add_node("agent", agent_node)
graph.add_node("tool", tool_node)

# 定义边（条件分支）
def should_continue(state):
 if state["messages"][-1].tool_calls:
 return "tool"
 return END

graph.add_conditional_edges("agent", should_continue)
graph.add_edge("tool", "agent")

# 运行
app = graph.compile()
result = app.invoke({"messages": ["帮我查北京天气"]})

与 LangChain Chain 的区别：

特性	Chain	LangGraph
结构	线性	循环图
状态管理	无	有（TypedDict）
条件分支	❌	✅
持久化	❌	✅（可中断恢复）
适用场景	简单流程	复杂流程、对话循环

学习资源：

官方文档：https://langchain-ai.github.io/langgraph/
LangGraph 使用教程（本项目已收录）：Langgraph使用教程

AutoGen：微软多智能体框架

核心特点：

Agent 之间通过对话协作
支持人类介入（Human-in-the-loop）
内置代码执行沙箱

快速示例：

import autogen

# 配置 LLM
config_list = [{"model": "gpt-4", "api_key": "your-key"}]

# 创建 Agent
assistant = autogen.AssistantAgent(
 name="Assistant",
 llm_config={"config_list": config_list}
)

user_proxy = autogen.UserProxyAgent(
 name="User",
 human_input_mode="TERMINATE", # 人类只在结束时介入
 code_execution_config={"work_dir": "coding"}
)

# 开始对话
user_proxy.initiate_chat(
 assistant,
 message="写一个 Python 函数计算斐波那契数列"
)

与 LangGraph 对比：

特性	AutoGen	LangGraph
编排方式	对话驱动	状态机驱动
控制流	隐式（Agent 自主决定）	显式（开发者定义图）
可控性	⭐ 低	⭐⭐⭐ 高
灵活性	⭐⭐⭐ 高	⭐⭐ 中
适用场景	创意、探索性任务	流程化、工程化任务

提示词工程核心技巧

提示词是 Agent 的"编程语言"，掌握核心技巧至关重要。

1. CoT（思维链）

让模型逐步推理，输出中间步骤。

普通提示词：

问：小明有 5 个苹果，给了小红 2 个，又买了 3 个，现在有多少个？
答：6 个

CoT 提示词：

问：小明有 5 个苹果，给了小红 2 个，又买了 3 个，现在有多少个？
请逐步思考：
1. 初始有多少？
2. 给出去多少？
3. 又买了多少？
4. 最终有多少？

答：
1. 初始有 5 个苹果
2. 给小红 2 个，剩下 5-2=3 个
3. 又买了 3 个，现在有 3+3=6 个
4. 最终有 6 个苹果

效果：复杂问题上准确率提升 30-50%。

2. Few-shot Prompting

给模型几个示例，让它学习模式。

prompt = """
任务：将句子翻译成 SQL

示例：
句子：查询所有年龄大于 20 的用户
SQL：SELECT * FROM users WHERE age > 20

句子：查询订单金额超过 1000 的订单
SQL：SELECT * FROM orders WHERE amount > 1000

现在请翻译：
句子：查询最近一周登录过的用户
SQL：
"""

3. Structured Output

让模型输出结构化数据（JSON），便于程序解析。

from langchain.output_parsers import PydanticOutputParser
from pydantic import BaseModel

class AnalysisResult(BaseModel):
 sentiment: str # positive/negative/neutral
 topics: list[str] # 主题列表
 summary: str # 总结

parser = PydanticOutputParser(pydantic_object=AnalysisResult)

prompt = f"""
分析以下文本的情感和主题：
{text}

{parser.get_format_instructions()}
"""

4. ReAct 模板

结合推理和行动的标准模板：

react_prompt = """
你是一个智能助手，可以使用工具完成任务。

可用工具：
- search: 搜索互联网
- calculator: 数学计算
- weather: 查询天气

思考过程格式：
Thought: 思考下一步做什么
Action: 调用什么工具（tool_name）
Action Input: 工具输入参数
Observation: 工具返回结果
...（重复直到完成任务）
Answer: 最终答案

开始！
用户问题：{question}
"""

评估与优化

评估指标

指标	说明	计算方式
任务完成率	Agent 是否成功完成任务	人工标注或规则判断
响应准确率	输出内容是否正确	人工评估或 LLM-as-Judge
Token 成本	每次调用的 Token 消耗	直接从 API 返回获取
延迟	从输入到输出的时间	计时统计
工具调用成功率	Agent 调用工具是否正确	检查工具返回

LangSmith：调试与监控平台

LangSmith 是 LangChain 官方的调试平台：

import os
os.environ["LANGCHAIN_API_KEY"] = "your-key"
os.environ["LANGCHAIN_TRACING_V2"] = "true"

# 所有 LangChain 调用都会记录到 LangSmith
from langchain.agents import AgentExecutor

agent = AgentExecutor.from_agent_and_tools(...)
result = agent.invoke({"input": "hello"})
# 在 LangSmith 网站查看完整调用链、Token 消耗、耗时等

成本优化策略

策略	说明	效果
分层模型	分类用小模型，复杂任务用大模型	成本降低 60-80%
Prompt 精简	去除冗余描述，压缩 Token	成本降低 20-30%
缓存	相似问题复用答案	成本降低 40-50%
并行调用	多 Agent 同时执行	延迟降低 50-70%

学习路径详细规划

第一阶段：基础（1-2 周）

目标：理解 LLM 基础，掌握 API 调用

内容	学习资源	验收标准
Python 异步编程	官方文档、asyncio 教程	能写异步 API 服务
LLM API 调用	OpenAI 文档、Claude 文档	能调用并处理返回
Prompt 基础	Learn Prompting 网站	能写 CoT、Few-shot

练习项目：

写一个聊天机器人（调用 OpenAI API）
实现简单的 CoT 推理（数学问题）

第二阶段：框架（2-4 周）

目标：掌握 LangChain 核心用法

内容	学习资源	验收标准
LangChain Chain	官方文档 + 本项目教程	能构建顺序调用链
LangChain Agent	官方文档 + 本项目教程	能让 Agent 使用工具
LlamaIndex RAG	官方文档 + 本项目 RAG 系列	能构建文档问答系统
Function Calling	OpenAI 文档	能定义和使用工具

练习项目：

构建一个文档问答系统（RAG）
构建一个能搜索互联网的 Agent

第三阶段：编排（4-8 周）

目标：掌握多 Agent 编排

内容	学习资源	验收标准
LangGraph 状态机	官方文档 + 本项目教程	能构建循环流程
多 Agent 协作模式	AutoGen/CrewAI 文档	能设计协作架构
AutoGen 实践	微软官方教程	能构建对话式多 Agent

练习项目：

构建一个自动化报表生成系统（链式编排）
构建一个代码开发助手（层级编排）

第四阶段：工程化（持续）

目标：生产环境落地能力

内容	学习资源	验收标准
Agent 系统架构	架构设计书籍 + 实战经验	能设计高可用系统
评估体系搭建	LangSmith + 自建评估	能监控 Agent 性能
成本优化	实战经验积累	能降低 50%+ 成本
部署与运维	Docker/K8s + CI/CD	能部署到生产环境

发展趋势与前景

从"对话"走向"行动"

2023 年的 Agent 主要做"问答"。2024-2025 年的 Agent 开始执行操作：

能力	2023 年	2025 年
回答问题	✅	✅
搜索信息	✅	✅
写代码	⭐ 需人工复制	✅ 自动执行
调用 API	❌	✅
修改文件	❌	✅
发送邮件	❌	✅

典型案例：

Devin：AI 软件工程师，能独立完成开发任务
Claude Code：能直接在终端执行开发任务
GPT-4o + Actions：能直接调用外部服务

低代码化趋势

编排工具正在从"写代码"向"画流程图"转变：

工具	编排方式	技能要求
LangGraph	写 Python 代码	⭐⭐⭐ 高
Flowise	拖拽可视化	⭐ 低
Dify	拖拽 + 配置	⭐ 低
LangFlow	拖拽可视化	⭐ 低

对工程师的影响：

简单编排将被低代码平台取代
高阶工程师需深入：算法优化、模型微调、复杂架构设计

企业级落地爆发

2024-2025 年是 Agent 落地元年。行业需求：

行业	Agent 应用	人才需求
金融	自动化投研、风控分析	⭐⭐⭐ 高
医疗	病历分析、诊断辅助	⭐⭐⭐ 高
法律	合同审查、案例分析	⭐⭐ 中
客服	智能客服、工单处理	⭐⭐⭐ 高
制造	生产调度、质量控制	⭐⭐ 中

薪资水平（2024 年中国市场参考）：

级别	经验	薪资范围
初级	0-2 年	15-25k/月
中级	2-4 年	25-40k/月
高级	4-6 年	40-60k/月
专家	6+ 年	60-100k/月

多模态编排

未来 Agent 需要处理多种模态：

示例场景：

营销 Agent：写文案 → 生成海报图 → 合成配音视频
教育 Agent：分析学生作业图片 → 语音讲解 → 生成练习题

核心竞争力总结

不在于你会调某个 API，而在于你能否设计出一套机制，让不完美的模型通过工具和协作，输出稳定、可靠的结果。

核心能力拆解：

能力	说明	如何培养
架构设计	设计 Agent 结构和协作模式	实战项目 + 参考优秀案例
Prompt 工程	精准控制模型行为	大量练习 + 持续迭代
成本优化	在效果和成本间找到平衡	实战数据 + 对比实验
评估能力	判断 Agent 是否达到目标	建立评估体系 + 数据驱动
业务理解	把业务问题转化为 Agent 流程	深入业务 + 持续沟通

适合人群

有后端开发背景，对 AI 算法感兴趣的工程师
善于逻辑拆解，懂技术的产品型工程师
希望从传统开发转型 AI 应用落地的开发者
有数据/算法背景，想往工程化方向发展的人

常见问题

Q1：需要学机器学习/深度学习吗？

不需要深入。这个岗位侧重应用落地，不是模型研发。但需要理解：

LLM 的基本原理（Token、Context Window、Temperature）
模型的能力边界（幻觉、遗忘、推理能力）
如何评估模型效果

Q2：Python 不熟怎么办？

必须补。LangChain、LangGraph、AutoGen 都是 Python 框架。建议：

先学基础语法（1 周）
重点学异步编程、API 开发（FastAPI）
边做项目边学，不要光学不练

Q3：如何选择 LangGraph vs AutoGen？

你的情况	推荐
需要可控流程、工程化项目	LangGraph
需要灵活对话、创意任务	AutoGen
初学者	LangGraph（文档更清晰）

Q4：Agent 和传统自动化有什么区别？

特性	传统自动化	Agent
规则	人工硬编码	模型自主决策
灵活性	❌ 低	✅ 高
错误处理	需人工编码	模型可自主处理
适用场景	固定流程	不确定任务

Agent Orchestration on 扎塔-Zata

E2B 迁到阿里云云沙箱：能跑通，但别急着上生产

一、先把它跑起来

核心对象先认一遍

先分清：Team、API Key 和 RAM 权限是三件事

前置：先把 API Key 建出来

三个环境变量

最小验证：Python

最小验证：TypeScript

版本会被钉住

二、这套兼容比我想的更深

三、一页清单：什么能用，什么别用

Sandbox：覆盖了完整生命周期

Commands：批处理走 run，交互走 pty，长任务走后台

Filesystem：够用，但不要当存储

Code Interpreter：核心能力齐全，但减法不止一个

Template 与 CLI

四、五个会静默骗你的坑

坑一：files.write() 的 metadata 参数

坑二：run_code 用错了 SDK

坑三：上传下载 URL 需要 secure=false

坑四：Logs 和 Network Config Update

坑五：Metrics 的磁盘字段

五、Snapshot 和 pause：白名单能力，别写进架构

Snapshot 比「兼容」两个字复杂得多

pause：只为短期保留上下文

六、模板：三个档位，和一个必须自己构建的

内置模板清单

三者的默认配置对比

Code Interpreter 的硬限制

Code Interpreter Sandbox 的生产形态

browser 模板：不是开通即用，CDP 之外还要过鉴权

All-In-One：浏览器 + 代码执行，同一沙箱

BrowserUse 这类框架怎么接

自定义模板：从自己的镜像构建

一次真的跑通：从跨地域失败到新加坡模板可用

第一步永远用官方镜像建立基线

地域不一致不是“慢一点”，而是构建器根本不存在

“账号一致”可以从错误信息里反推

镜像要同时满足构建器和登录 Shell

推送时关闭附加 manifest

最后的验收必须发生在云端 Sandbox

模板的版本管理：名称 + 标签

沙箱内的环境变量

七、FC Extensions：云沙箱不是 E2B 的镜像

VPC 配置：一个保留 metadata 字段

OSS 挂载：两个 metadata 字段

自定义域名：证书要求比想象中严格

Team 配额管理：注意鉴权通道不一样

日志采集要确认的三件事

八、迁不动的那部分怎么办

九、上生产前必须确认的边界

配额：六类不能假设无限

生命周期

文件与存储

十、一份可执行的迁移顺序

十一、排错对照表

十二、文档地图

总结

Agent 沙箱选型指南：隔离边界、产品对比与判断标准

Agent 用户记忆与 Skill 沉淀：开源项目参考与架构设计

1. 先区分 Memory、Experience 和 Skill

2. 用户记忆项目对比

2.1 Mem0：参考第一版 API 和检索流水线

2.2 Zep / Graphiti：参考会变化的事实

2.3 Letta：参考分层上下文和后台整理

3. Skill 沉淀项目对比

3.1 Agent Skills：作为可携带交换格式

3.2 OpenHands：参考多级作用域和加载优先级

3.3 Voyager：参考从成功轨迹生成 Skill

4. 推荐的双流水线设计

4.1 Memory Pipeline

4.2 Skill Pipeline

5. ContextPack 必须说明“为什么选中”

6. Skill 的安全晋升路径

7. 推荐的组合方案

主流 Agent 框架对比与多框架统一接口设计

1. 先理解 Agent 框架的层次

2. 主流框架速查

2.1 Deep Agents：长上下文任务 Harness

坑一：`files.write()` 的 `metadata` 参数

坑二：`run_code` 用错了 SDK

坑三：上传下载 URL 需要 `secure=false`

2.3 LangChain `create_agent`：轻量通用 Agent