Agent 工程 on 扎塔-Zata

Agent 决策审计落地：写入点、复核器与门禁降级判据

Thu, 24 Sep 2026 14:15:00 +0800

一份能用的决策审计，第一版可以只有六行 JSONL。还是上一篇里那个改数据库连接配置的例子——Agent 选中了单元测试和真实数据库冒烟，这次把事件流补全：

{"seq":1,"decision_id":"dec-42","event_type":"plan_created","actor":"planner",
 "source_revision":"a1b2c3","detail":{"checks":[
 {"check_id":"unit-tests","disposition":"selected"},
 {"check_id":"real-db-smoke","disposition":"selected"}]}}
{"seq":2,"decision_id":"dec-42","event_type":"check_started","actor":"executor",
 "detail":{"check_id":"unit-tests"}}
{"seq":3,"decision_id":"dec-42","event_type":"check_finished","actor":"executor",
 "detail":{"check_id":"unit-tests","result":"passed","exit_code":0,
 "evidence_ref":"runs/17/logs/pytest-1"}}
{"seq":4,"decision_id":"dec-42","event_type":"check_started","actor":"executor",
 "detail":{"check_id":"real-db-smoke"}}
{"seq":5,"decision_id":"dec-42","event_type":"check_finished","actor":"executor",
 "detail":{"check_id":"real-db-smoke","result":"unavailable","reason":"无预发凭据"}}
{"seq":6,"decision_id":"dec-42","event_type":"verdict_issued","actor":"verifier",
 "detail":{"verdict":"escalate","missing_boundaries":["连接池真实行为"]}}

字段比设计篇的记录少一些——run_id、attempt_id、occurred_at、trace_id 都还在，这里略去不展。第六行就是这套东西的价值：冒烟拿不到凭据时，裁决不是"通过"，是升级。事后任何人拿着 dec-42 都能回答：当时计划跑什么、实际跑到哪、缺了什么、为什么没放行。

设计篇把"该记什么"讲清了：身份模型、计划/执行/裁决分离、history_complete。这篇接着回答落地时真正卡住的三件事——**写入点挂在哪、复核器怎么不变成第二个 Agent、什么条件下才允许它影响放行。**我的判断放在前面：存储本身一晚上就能写完，卡人的从来是这三件。

一、先说不建什么

动手前先划掉三个"看起来该做"的东西。审计的第一死因不是记得不准，是被绕过——系统一重，团队总有办法绕过它。

做重了的信号	v1 的做法
起一个独立的审计服务	一张追加式表，执行进程内直接写
把原文（prompt、源码、终端输出）存进审计	只存引用与摘要，原文走受控存储
上线即接管放行、替换现有门禁	先与固定门禁并行，只记录分歧

第三条是全文最重要的边界。设计篇说决策审计让"自选验证深度"的自由度可复核，但可复核不等于可放行——从"并行记录"走到"参与放行"，中间隔着第五节那套判据，判据没满足之前，记录再完整也不构成授权。

二、最小数据契约：一张只允许 INSERT 的表

DDL 以 SQLite 3 为准，换 PostgreSQL 只需要改触发器写法：

CREATE TABLE decision_events (
 seq INTEGER PRIMARY KEY AUTOINCREMENT,
 event_id TEXT NOT NULL UNIQUE, -- 幂等键，由业务身份拼出
 decision_id TEXT NOT NULL,
 run_id TEXT NOT NULL,
 attempt_id TEXT,
 event_type TEXT NOT NULL CHECK (event_type IN
 ('plan_created','check_started','check_finished',
 'verdict_issued','decision_invalidated')),
 actor TEXT NOT NULL,
 source_revision TEXT NOT NULL,
 policy_version TEXT NOT NULL,
 trace_id TEXT,
 occurred_at TEXT NOT NULL,
 detail TEXT NOT NULL -- JSON，自带 detail_schema_version
);
CREATE INDEX idx_events_decision ON decision_events(decision_id);

CREATE TRIGGER no_update BEFORE UPDATE ON decision_events
BEGIN SELECT RAISE(ABORT, 'append-only'); END;
CREATE TRIGGER no_delete BEFORE DELETE ON decision_events
BEGIN SELECT RAISE(ABORT, 'append-only'); END;

追加式不是审美偏好，它换来两个便宜：没有 UPDATE，历史就不可改；完整性验证退化为检查"存在且有序"（第六节展开）。触发器挡的是自己人手滑，真正的防线在读取端。

五个事件类型各自的写入责任：

event_type	谁写	必填 detail	记录的事实
plan_created	planner	checks（每项含 disposition 与 reason）	决策的存在起点
check_started	executor	check_id	某项检查开始执行
check_finished	executor	check_id、result、evidence_ref	执行器观察到的结果
verdict_issued	verifier / 放行器	verdict、依据摘要	对计划与证据的裁决
decision_invalidated	平台	失效原因、新 revision	旧裁决作废

两个容易写错的字段。occurred_at 用写入方本地时钟就行，排序靠 seq，时钟只负责展示——分布式环境里别指望时钟可排序。detail 里必须带 detail_schema_version：追加式意味着旧记录永远不会迁移，演进只能靠新版本号，读取端按版本解释。

事件不是随便堆的，读取端会按一个状态机校验它们：

▲ 图：自绘

三、写入点：审计不改变控制流，只挂在三个钩子上

决策审计在 Runtime 里没有自己的环节。它不参与循环，不加延迟，只挂在三个既有节点的出口上：

▲ 图：自绘

写入点	挂在哪	actor	写什么	不写什么
计划成立时	planner 的结构化输出通过 schema 校验之后	planner	plan_created	模型原始 token 流
检查起止时	执行器进程内，每项检查的前后	executor	check_started / check_finished	Agent 对结果的转述
裁决签发时	verifier 出结论、放行器动动作	verifier	verdict_issued	覆盖 planner 的记录

三个坑都在挂的位置上。

**计划写入要在 schema 校验之后。**校验之前写，Agent 输出里每段格式垃圾都进审计表。审计表被噪声淹没后没人再信它——这比没有审计更糟。

**check_finished 只能由执行器写。**这是设计篇"Agent 承诺和执行器事实分开"的实现面：Agent 在上下文里说"测试通过了"不算数，执行器进程里那行代码写下的才算。执行器与 Agent 同进程时，至少保证写入点在执行函数内部，而不是在 Agent 转述的文本后面。

**审计写不进去时，决策还能不能继续？**按阶段分两说。v1 的并行阶段，写入失败只把该 attempt 计为"审计缺失"，让缺失率本身成为统计指标；到了将来接管的阶段，写不进审计的 attempt 一律不允许自动放行。哪种都可以，唯独不能静默吞掉失败。

写入器是全文最简单的代码，唯一值得注意的是幂等键——由业务身份拼出来，重试同一个动作不会写进两条：

def append_event(conn, decision_id, run_id, event_type, actor,
 source_revision, policy_version, detail,
 attempt_id=None, trace_id=None, key_suffix=""):
 event_id = f"{decision_id}:{event_type}:{key_suffix}" # 确定性幂等键
 conn.execute(
 "INSERT OR IGNORE INTO decision_events "
 "(event_id, decision_id, run_id, attempt_id, event_type, actor,"
 " source_revision, policy_version, trace_id, occurred_at, detail)"
 " VALUES (?,?,?,?,?,?,?,?,?,?,?)",
 (event_id, decision_id, run_id, attempt_id, event_type, actor,
 source_revision, policy_version, trace_id,
 datetime.now(timezone.utc).isoformat(),
 json.dumps(detail, ensure_ascii=False)),
 )
 conn.commit()

幂等键的取法和全景手册对工具调用的要求同源：按业务身份（decision_id + event_type + key_suffix）去重，不按请求 ID。检查类事件里 key_suffix 就是 check_id，同一项检查反复重试，check_started 只落一条。

四、复核器：规则在前，模型在后

复核器最大的落地风险，是写成"再跑一个 Agent 看一遍"——那就成了第二个 planner，共享同样的盲点，还多付一遍模型钱。把复核拆成两层，规则层不花钱，不过就升级：

def verify_decision(events, pending_revision):
 plan = first_of(events, "plan_created") # 缺它，整份记录无效
 checks = {e["detail"]["check_id"]: e["detail"]
 for e in events if e["event_type"] == "check_finished"}

 missing = [c["check_id"] for c in plan["detail"]["checks"] # 规则一
 if c["disposition"] == "selected" and c["check_id"] not in checks]
 not_passed = [cid for cid, d in checks.items() # 规则二
 if d["result"] != "passed"]
 stale = plan["source_revision"] != pending_revision # 规则三
 unexplained = [c["check_id"] for c in plan["detail"]["checks"] # 规则四
 if c["disposition"] == "skipped" and not c.get("reason")]

 if missing or not_passed or stale or unexplained:
 return escalate(missing, not_passed, stale, unexplained)
 return model_coverage_review(plan, events) # 规则全过，才问模型覆盖面

四条规则各自挡一种"结果是绿的、判断仍然错"：规则一挡"计划写了但没跑完"；规则二挡 unavailable、failed 被当通过——开场例子里冒烟拿不到凭据，裁决只能 escalate，就是这条在起作用；规则三挡"检查的是 A、要合并的是 B"；规则四挡跳过不留理由。规则四其实应该在 plan_created 写入时就被 schema 拦下，复核器再查一遍，是因为写入端校验会随时间漂移，读取端要有独立的防线。

规则层全过，才进第二层。模型复核只回答规则回答不了的问题：计划对风险事实的覆盖面。“改了连接池配置，计划里却没有真实数据库冒烟"这类漏边界，规则查不出来，模型或人可以。第二层的产出同样是一条 verdict_issued，actor=verifier，引用同一个 decision_id，不覆盖任何旧记录。verdict 只需要两个值：支持放行、升级人工——“拦截"不是它的职责，规则层已经拦了。

防共享盲点的最低成本做法：verifier 的提示词版本、甚至模型路由，都和 planner 不同，且两者的 policy_version 都写进了记录。事后能看出"同一个模型自己复核自己"这种结构缺陷。

五、降级判据比记录格式更重要

并行阶段的目标不是"验证审计好用”，是把固定门禁和决策审计放在同一批任务上，量化它们在哪儿不一致。每个 attempt 两边各有结论，落在四个象限：

	固定门禁拦下	固定门禁放行
决策审计放行	漏报候选——最危险的象限，逐条人工复检	一致放行，正常交付，抽样复核
决策审计拦截	一致拦截，抽查确认拦截理由	误报候选——计入审计的误拦成本

分歧统计一条 SQL 就够：gate_outcomes 记固定门禁结果，audit_outcomes 从 verdict_issued 聚合出 passed（verdict 为"支持放行”）：

SELECT g.gate_name,
 COUNT(*) AS attempts,
 SUM(g.blocked AND a.passed) AS audit_missed,
 SUM(NOT g.blocked AND NOT a.passed) AS audit_false_block
FROM gate_outcomes g
JOIN audit_outcomes a USING (attempt_id)
GROUP BY g.gate_name;

（SQLite 3 的布尔求和写法；PostgreSQL 换成 COUNT(*) FILTER (WHERE …)。）

什么时候允许决策审计接管某个固定门禁？三个条件必须同时满足，并且要写进试点协议、带上样本量下限：

漏报候选归零。人工逐条复检这个象限，没有一条真实漏网。样本量下限按该门禁的历史拦截率反推——拦得越少的门禁，需要越长的并行期。
误报候选率不高于固定门禁自己的误拦率。否则不是升级，只是把可见的脚本误报换成不易发现的判断误报。
分歧可归因。每条分歧都能落到具体原因：策略版本差、检查覆盖差、环境不可用。归因不出的分歧占比高，说明记录本身还不可复核——先修记录，别谈接管。

三个条件连续 N 轮（N 写进协议）同时满足，才把这一项门禁从阻断降为提示，逐项降、不打包。迁移链完整性这种失误代价极高的规则，可能永远不该降。

并行期里 decision_invalidated 同样要写：待合并分支更新导致 source_revision 变化、policy_version 升级，都追加一条失效事件。放行器只认"verdict 绑定的 revision 等于当前待放行的 revision"。

判据比记录格式重要，这句话值得单独一段：没有判据的并行记录，只是一份更贵的日志。

六、审计存储自身会坏：读取端怎么认账

设计篇提过 history_complete，落到读取端是一个便宜的校验函数：拿一个 decision_id 的事件序列，检查它以 plan_created 开头、以 verdict_issued 结尾、每个 check_started 都有配对的 check_finished：

def history_complete(events): # events 已按 seq 排序、按 decision_id 过滤
 types = [e["event_type"] for e in events]
 if not types or types[0] != "plan_created":
 return False
 if "verdict_issued" not in types or "decision_invalidated" in types:
 return False
 started = {e["detail"]["check_id"] for e in events
 if e["event_type"] == "check_started"}
 finished = {e["detail"]["check_id"] for e in events
 if e["event_type"] == "check_finished"}
 return started <= finished

注意校验按 decision_id 分组做，不按全局 seq——并发之下全局 seq 本来就有空洞，完整性是每个决策自己的性质。

校验不过，这个 decision 的证据就当不存在：放行器走"无审计"路径（人工或固定门禁），并把"无审计放行"本身记下来。沉默缺失被误读成通过，是审计存储最坏的失败方式，宁可显式降级。

单机 SQLite 的丢失风险要诚实写进 v1 的边界：它没解决多副本，靠的是这张表很小（一次决策几 KB）、全量备份便宜、备份脚本可以拿校验函数自检。真正占空间的是 evidence 原文，那是另一套保留策略——审计表只存 evidence_ref 和摘要，本来就不该跟着膨胀。

七、我的判断

v1 的合理成本上限是一两周。做的过程中一旦发现要起独立服务、要改现有 CI 的控制流，说明做重了，回第一节的表对照。
决策审计改变的不是风险本身，是漏报的可发现性：没有它，“Agent 跳过了该跑的检查"只能在事故后追查；有了并行期，漏报候选在统计表里按周可见。
反过来，如果 Agent 只提建议、放行始终由人或固定规则拍板，trace 加审批日志就够了。这套东西的成本，只在放行权真的开始转移时回本。

速查：落地顺序与每步的完成判据

步骤	交付物	完成判据
1. 建表	DDL + 追加式触发器	UPDATE / DELETE 被 ABORT
2. 写入点	三个钩子 + 幂等写入器	同一事件重试只落一条
3. 读取校验	按 decision_id 的完整性函数	缺头、缺尾、缺配对的序列被判无效
4. 规则复核器	四条确定性规则	任一不过即 escalate，不进模型层
5. 并行运行	分歧四象限统计	每个门禁的漏报/误报候选都有数
6. 判据与降级	写进试点协议的三个条件	逐项降级，永不打包

一句话收尾：先让它记录分歧，再让它参与放行——降级判据写清楚之前，决策审计只是一份更贵的日志。

Session、Thread、Run：一条消息为什么是一个 Run

Wed, 23 Sep 2026 23:11:14 +0800

把 Run 表定义摊开看，有个细节很别扭：

class AgentRunModel(Base):
 id: Mapped[str] # Run ID
 thread_id: Mapped[str] # 外键 -> conversation_thread，NOT NULL
 session_id: Mapped[str | None] # 外键 -> chat_session，允许为空
 agent_id: Mapped[str]
 status: Mapped[str]
 ...

一张表上挂了两个"会话类"外键，一个必填、一个可空。第一眼看上去像是设计没收敛——要么统一用 session，要么统一用 thread，为什么两个都要？

真正解释这件事的，是那个允许为空的字段。它存在的理由，不是一个空值占位，而是"一次执行可以不隶属于任何对话"。等子 Agent 出现时，这个空位会立刻被填满意义。

一、三个名字，三种事实

这三层不是同义词，也不是新旧替代关系，它们各自是一类问题的权威答案：

层	表	谁看得见	回答的问题	生命周期
Session	`chat_session`	用户	这是哪一段对话	长期，可继续
Thread	`conversation_thread`	只有后端	模型的连续记忆装在哪	与对话同寿
Run	`agent_run`	用户（状态/取消）、管理员（审计）	这是哪一次执行、用了什么、跑到哪	单次，有终态

Session 用户可见的一段对话：标题、owner、历史消息
 └─ Thread 模型的连续记忆（checkpointer 线程），前端不维护
 └─ Run 一次执行：快照 / 状态机 / 事件流 / 取消 / 计费

几处容易混的地方，一次说清：

Session 是产品概念。它管标题、归属、消息顺序；删掉一个 Session 意味着用户不再看到那段对话。
Thread 是实现细节。Session 到 Thread 的映射在后端完成，客户端不需要传也不需要存 thread_id。它存在的唯一理由是：模型需要一个连续的上下文容器。
Run 是事实源。它不属于"对话"这个层级，而属于"执行"这个层级：一次输入落进去，出来的是带序号的事件流和一个终态。

所以那条别扭的表定义翻译过来是：每次执行必须属于一个记忆线程，但不一定属于一段用户对话。

这里要跟另一套常见用法区分开：在审计与可观测性的语境里，run_id 有时指"跨暂停、重试仍稳定的业务任务身份"，再用 attempt_id、trace_id 区分每一次尝试（可参考本系列的《Agent 决策审计：它与 Tracing 的关系》）。本文说的 Run 是执行层的单位：单次、有终态、不可重开——想重跑，就是一次新的 Run。两套用法服务的问题不同，混用会在"重试算不算同一次"上直接打架。

二、一条消息，就是一个 Run

用户视角里，一次交互是"在对话里发了一句话"。到 API 这一层，它变成一次 Run 创建：

POST /sessions/{session_id}/messages
→ 202 { "message_id": "...", "run_id": "run_xxx", "events_url": "/api/agent-runs/run_xxx/events",
 "agent_id": "...", "agent_name": "..." }

返回体里同时出现 session_id（在 URL 上）和 run_id（在响应里），这不是冗余，而是两个层级各自交回自己的凭据：前者继续指向那段对话，后者指向刚刚开始的这次执行——订阅事件、取消、查状态，用的全是它。

历史消息也保留了这层关系：assistant 消息上挂一个唯一的 run_id 回指生成它的那次执行。这样当用户在同一个对话里换了 Agent，回看历史时依然能说出"这条回答当时是哪个 Agent 给的"，而不是拿当前绑定去反推过去。

而 Session 上的 agent_id 只是初始默认值：同一段对话的后续每条消息都可以逐次切换 Agent，切换只影响下一次发送。这一点是后面所有讨论的前提——如果 Session 就等于 Run，这条规则根本无法表达。

三、为什么不能"一个 Session 一个 Run ID"

合并成一层听起来更简洁，但会立刻遇到四个对不上的地方：

1. 快照必须逐次冻结。 每个 Run 在创建事务里固化两份不可变快照：Agent 执行快照和资料上下文快照。它们记录的是"这一次用的版本"，而不是"这段对话现在用什么"。会话级 ID 没有位置安放"逐次"这个语义。

2. 终态是执行的属性，不是对话的。 Run 的状态机有唯一终态且不可重开：succeeded、failed、cancelled、interrupted。一次执行失败，不应该把整段还能继续聊的对话标记为失败。

3. 幂等键挂在 Run 上。 创建 Run 必须带 Idempotency-Key，唯一约束是 (owner_id, idempotency_key_hash)。同一用户、同一个 key、同一份请求会重放原来那次 Run；同样的 key 配不同请求则稳定返回 idempotency_conflict。重放的单位是"那一次执行"，不是"那段对话"。

4. 取消、租约、事件游标都是 per-Run 的。 GET /api/agent-runs/{run_id}/events?after_seq=N 的游标是 Run 内的序号；执行租约（lease）也写在 Run 上。刷新续流用 Last-Event-ID 接上原来那条流——如果一段对话只有一条流，换 Agent、重试、取消全都会糊在同一根管道里。

换个角度看得更清楚。挂在 Run 上的这些字段，每一条都在说"这是单次执行的属性"：

事实	字段
用哪个 Agent、什么版本	`agent_id`、`agent_execution_snapshot`
看的哪些资料	`context_pack_snapshot`
跑到哪一步	`status`、`last_event_seq`
谁在跑	`executor_instance_id`、`lease_expires_at`
能不能重放	`idempotency_key_hash`、`request_checksum`
结果与失败	`final_message_id`、`error`
时间线	`created_at` / `started_at` / `finished_at`

四、Run 的状态机：把"事实"和"活性"分开

既然执行是单位，状态就必须说准。非终态有三个，终态有四个：

queued ─→ running ─→ succeeded
 │ │ └→ failed
 │ ├─────→ cancelled
 └─────────┴─────→ interrupted
 cancelling 是 running 到 cancelled 之间的过渡态

三条容易踩的语义：

租约不是历史事实。 lease_expires_at 只表示"执行者还活着"，它过期不代表这次执行失败了。失联的 Run 由 reconciliation 追加 run.interrupted 收口——而且不会自动重跑模型。想重跑，是人的决定，是一次新的 Run。
取消只追加一次终态。 用户取消先写 run.cancelling，运行中的执行器收到信号后回收当前图或模型流，恰好追加一次 run.cancelled（带 external_stop_confirmed: true）。确认取消之后，不会再出现 run.completed 或 run.failed。
终态不可重开。 一个 Run 进入终态，它的故事就结束了。任何"再来一次"都是新 Run、新快照、新的幂等键。

这套规则的价值不在单 Agent 场景——那里一条流从头读到尾就够了。它的价值在于：当你需要并行、需要重试、需要给一部分工作单独踩刹车时，你必须有一个不可重开的最小单位。

五、委派那天，这个空字段被填满了

现在回到开头那个可空的 session_id。

子 Agent 委派落地后，父 Run 在执行过程中会请求平台创建 child Run。child 是另一次真实执行：目标 Agent 不同、快照不同、独立线程、独立事件流、独立状态与独立取消入口。它满足"执行"的全部定义，但不隶属于用户的那段对话——用户没有在对话里发过那句话。

所以 child 的 session_id 就是 NULL：

root Run session_id = sess_xxx 用户可见，出现在会话历史
├─ child A session_id = NULL 内部执行，只有树里能看到
└─ child B session_id = NULL

父子关系不表达在 Session 上，而是靠 Run 表自己的两个自引用字段：root_run_id 指向所属的根执行，parent_run_id 指向直接父节点。运行树因此可以从持久化记录里重建：刷新页面后树还在，服务重启后未完成节点统一收敛为 interrupted。

对前端而言，这个分层直接决定了工作量：原来"发一次消息 = 拿到一个 run_id = 连一条 events_url“的假设，要变成"先读树，再按每个节点的 events_url 各自订阅”。一条流变多条流，正是因为一次对话里现在真的有了多次执行。

反过来验证一下：如果当初把 Run 合并进 Session，委派就得在 Session 上开洞——一段对话要同时容纳多个 Agent、多份快照、多个终态、多个取消目标。这个洞会一直开到把 Session 拆回去为止。

几点收获

ID 的层级应该跟生命周期对齐，而不是跟界面层级对齐。 用户看到的是对话，系统需要的是执行；把两者合成一个 ID，短期少一个字段，长期处处要打补丁。
允许为空的外键往往在讲一个未来的故事。 session_id 可空不是随手留的，它提前承认了"执行可以不属于任何对话"这类存在。
状态机要区分事实与活性。 心跳、租约、连接状态说明的是"谁还在跑"；状态、事件流说明的是"发生了什么"。把两者混在一起，就会出现"进程没了所以这次执行失败了"这种错误结论。
幂等、取消、游标、计费都需要一个不可重开的最小单位。 它们四个的需求指向同一个答案：Run。先把这层定清楚，后面加并行、加委派、加预算，都是在这个单位上做加法。

回到最开始那张表：两个外键不是没收敛的设计，而是两层身份各自在场的证据。一个必填，因为执行总需要记忆；一个可空，因为执行不一定需要观众。

Agent 生产工程全景手册：从 Runtime 到业务闭环

Wed, 23 Sep 2026 16:48:35 +0800

本文是一份 Agent 工程知识总纲，目标是把“能跑一个 Agent”推进到“能让 Agent 系统在真实任务中稳定运行，并能证明它有效”。它覆盖架构、运行、验证、治理和业务结果；具体框架的 API 与云产品参数应以对应版本的官方文档为准。

先看全貌：生产级 Agent 系统是什么

生产级 Agent 不是一个模型调用循环，而是一套围绕任务运行的系统。模型负责在有限上下文中提出下一步行动；平台负责验证、执行、记录和约束这些行动；用户或业务系统负责定义什么结果才算完成。

先把系统划分成三个边界：

控制面：身份、策略、配置版本、模型路由、配额、队列和工作流定义。它决定谁可以发起什么任务，以及任务如何调度。
执行面：Run Controller、Agent Runtime、工具网关、Worker 和沙箱。它在受限环境中推进任务，并把状态写回持久化存储。
证据面：事件、Trace、审计、评测结果、成本和业务指标。它回答任务发生了什么、是否合格、出了问题如何追查。

flowchart LR U[用户 / Issue / API] --> G[入口与身份认证] G --> Q[任务队列与调度] Q --> O[工作流编排] O --> R[Agent Runtime] R --> M[模型与上下文] R --> T[工具 / MCP / 沙箱] T --> D[代码库 / 数据 / 外部系统] R --> E[事件、日志、Trace] E --> V[评测、审计、成本与告警] V --> O O --> H[人工审批 / 交付] H --> U

一个典型 Coding Agent 任务会经过：接收 Issue、检查权限、创建隔离工作区、读取代码和约束、调用模型规划、执行工具、运行测试、整理证据、等待必要审批、创建 PR，最后记录结果。任务可能持续数分钟甚至数小时，中间会遇到模型超时、工具异常、用户取消、机器重启和预算耗尽。因此，系统设计必须覆盖任务全生命周期，而不只是“模型返回了答案”。

能力层次：知道、会做、做过生产、能负责

层级	证据	例子
知道	能说清概念、适用范围和风险	解释幂等、工具权限和离线评测
会做	独立完成可复现实验或功能	实现可恢复的 Agent Run，跑固定任务集
做过生产	真实用户持续使用，处理过故障和回归	有任务量、成功率、接管率、事故复盘
能负责	能做架构取舍、设指标、推动协作并承担结果	设计多租户平台并对质量、成本和业务价值负责

“做过生产”不是部署到一台服务器就算。它意味着有真实使用、有运行数据、有故障处理、有变更回归，也知道系统在哪些情况下应该拒绝执行或交给人。

1. Agent Runtime：把模型循环变成可管理的任务执行

1.1 Runtime 的边界

Agent Runtime 是一次 Agent 运行的执行环境与控制层。它负责把输入、上下文、模型、工具和状态组织成受控循环，直到任务成功、失败、被取消或达到限制。

一次基础循环如下：

接收输入与权限上下文
 → 构造模型请求
 → 解析模型输出（最终答复或工具调用）
 → 校验工具参数与权限
 → 执行工具并记录结果
 → 更新任务状态和上下文
 → 继续循环，直到终止条件成立

Runtime 应明确区分“模型建议做什么”和“平台允许执行什么”。模型输出不是授权凭证；任何读写工具都需要由 Runtime 按用户、租户、任务和资源范围再次鉴权。

1.2 一次 Run 的完整生命周期

Run 是有身份、有边界、有预算、有结果的一次任务尝试。一次用户目标可能因为重试或人工修复而有多个 Run；不要把“业务任务”和“某次执行尝试”混成一个对象。

创建请求 → 鉴权/策略检查 → 排队 → 分配 Worker → 准备沙箱
 → 运行 Agent Loop ↔ 调用模型/工具
 → 验收与风险检查 → 成功/等待审批/失败/取消/超时
 → 保存交付物 → 清理资源 → 汇总指标与审计

建议区分以下对象：

对象	生命周期	应保存的核心字段
Task	用户希望完成的业务目标	来源、需求、仓库/资源、验收条件、发起者
Run	对 Task 的一次执行尝试	状态、配置版本、模型、预算、起止时间、终止原因
Step	Run 中可观察、可重试或可审批的工作单元	类型、输入/输出引用、状态、尝试次数、耗时
Event	状态变化或重要事实的追加记录	序号、时间、主体、事件类型、关联对象、脱敏载荷
Artifact	运行产生的文件或交付物	内容摘要、存储位置、访问策略、来源 Step

将大块日志和工作区快照放对象存储，以不可变引用关联 Run；关系数据库保存状态与索引。不要把完整代码 diff、长模型输出和二进制文件塞入运行状态行。

1.3 Runtime 的核心部件

部件	责任	关键设计问题
Run Controller	创建、推进、取消和终止一次运行	状态转换是否合法？谁能取消？
Model Adapter	统一模型请求、流式输出、工具调用和错误	超时、限流、模型差异如何处理？
Context Builder	选择并组织提示词、历史、检索资料和工具说明	如何限制 token、隔离不可信内容？
Tool Gateway	校验 schema、权限、配额并分发工具调用	写操作是否需要审批？如何防止重放？
State Store	保存 Run、步骤、事件和检查点	进程重启后能否恢复？状态如何迁移？
Execution Sandbox	隔离运行代码、浏览器或命令	文件、网络、密钥、CPU 和内存边界是什么？
Observability	记录结构化事件、指标、Trace 和审计	能否重建因果链？敏感数据如何脱敏？

1.4 状态机、事件与恢复

不要只把运行状态存成一个 running=true/false。至少为任务定义清晰的状态机，例如：

queued → running → waiting_approval → running → succeeded
 ↘ retrying ↗ ↘ failed / cancelled / timed_out

每次状态转换都应有可检查的前置条件，并写入事件记录。建议保存：Run ID、任务输入摘要、配置和提示词版本、模型版本、工具调用、步骤结果、预算消耗、错误分类、检查点和终止原因。事件用于审计和重建过程；检查点用于从安全边界继续运行。二者用途不同，不能只留一份最终对话文本。

恢复时要区分：

可安全重试：只读请求、带幂等键的操作，或明确没有副作用的步骤。
需要对账：请求可能已在下游成功，但本地没收到响应。先查下游状态，再决定是否重试。
不能自动重试：不可逆外部副作用、资金或权限变更等高风险步骤，应暂停并要求人工处理。

幂等键应覆盖业务任务与操作身份，例如 run_id + step_id + operation。只按 HTTP 请求 ID 去重，无法阻止同一业务动作在重试时重复发生。

检查点需要放在语义安全的边界，例如“工具调用已完成且结果已持久化”，而不是任意一段对话文本之后。若在工具执行完成、结果还没写入状态库时进程崩溃，重启后系统无法知道副作用是否发生。这种不确定窗口需要由下游幂等键、查询对账或人工确认来解决。

故障位置	恢复动作	需要防范的问题
调用模型前	从当前步骤继续	请求重复、上下文版本变化
模型响应后、尚未执行工具	保存响应或重发请求	采样结果变化、重复费用
工具执行中	按工具语义查询/重试/转人工	下游已成功但本地超时
工具成功、结果未落库	使用幂等键查询结果	重复写入或重复发布
等待审批	持久暂停，审批事件到达后恢复	审批过期、参数被替换
Worker 被终止	租约过期后由新 Worker 接管	两个 Worker 同时执行

Worker 领取任务时可使用带过期时间的租约。续租失败的旧 Worker 必须停止写入；数据库条件更新或 fencing token 可以阻止失去租约的进程覆盖新执行者的状态。租约本身不能撤销已经发出的外部副作用，因此副作用仍需幂等保护。

1.5 限制循环和资源

每个 Run 都要有明确预算：最大步骤数、墙钟时间、模型调用次数、输入输出 token、工具调用次数、并发数、CPU/内存、网络访问范围和金钱成本。达到限制时要有确定行为：安全终止、降级、请求用户补充信息，或转人工；不能无限循环或静默超支。

常见防护包括重复工具调用检测、相同状态循环检测、指数退避和抖动、熔断、请求取消传播、模型与工具级超时、队列背压。重试策略必须设置总预算，避免瞬时故障引发重试风暴。

1.6 会话上下文不等于长期记忆

短期上下文用于当前 Run 的推理，长期记忆用于跨 Run 保留经过授权、经过筛选的信息。把所有历史直接塞回上下文会增加费用、噪声和隐私风险。上下文构建应显式决定：系统规则、任务输入、可信业务数据、检索资料、历史摘要、工具定义各自的边界和优先级。

上下文预算需要为模型输出和工具结果留空间；检索结果应带来源与时间；工具返回内容和用户内容都视为不可信数据，不能让它们覆盖系统指令。压缩历史时保留决策、未完成事项、关键证据和引用，而不是只保留一段无法核对的自然语言总结。

1.7 工具执行与隔离

工具调用的安全边界至少包括：JSON/schema 校验、身份与资源授权、租户隔离、速率和成本限制、审计记录、超时与取消。工具风险可以分级：只读、可逆写入、不可逆或外部副作用。高风险工具应采用最小权限、人工审批和执行后核验。

执行不可信代码时，进程隔离不等于完整沙箱。要检查文件系统、网络出口、凭证注入、容器逃逸面、CPU/内存/运行时限额和清理策略。密钥尽量通过短期凭证或受控代理提供，避免写入提示词、日志、环境快照和 Agent 可读文件。

延伸阅读：Agent Runtime 详解、Agent 沙箱选型指南、Agent Run 流式协议。

2. 工作流、调度与交付

2.1 工作流与 Agent Loop 的区别

Agent Loop 是一次运行内部“观察—推理—行动”的循环。工作流是更高层的业务过程，规定多个步骤、条件、并行分支、人工检查和失败补偿如何衔接。调度器负责何时、在哪个执行资源上启动工作；队列负责缓冲和分发工作。它们相关，但不是同一个组件。

适合用确定性工作流的部分：权限检查、测试、审批、发布、通知、数据迁移。适合交给 Agent 判断的部分：从 Issue 提取意图、探索代码、提出修改方案、解释失败。把所有步骤都交给模型，会让本应确定的控制流程变得不可预测。

2.2 工作流的基本要素

触发器：Issue、Webhook、定时任务、API 请求或人工启动。
步骤与依赖：顺序、并行、条件分支、循环和子流程。
状态：每步输入、输出、版本、开始结束时间和执行结果。
等待点：人工审批、外部事件、限流恢复或长时间等待。
失败策略：重试、补偿、回滚、暂停、转人工或终止。
版本：流程定义和执行中的 Run 使用哪个版本；升级如何兼容旧 Run。
可见性：用户能看到进展、暂停原因、待审批动作和最终证据。

对长任务，应将工作流状态持久化，不能依赖一个常驻进程的内存。工作进程可随时被替换；任务恢复依靠数据库、事件日志、队列和明确的步骤边界。

2.3 如何选择同步执行、队列与持久化工作流

执行方式	适合场景	主要代价	必须考虑
同步请求	几秒内完成、没有长等待、失败可以直接返回	请求连接占用、超时传播复杂	网关超时、客户端断线、取消语义
队列 + Worker	异步任务、需要削峰和并发控制	需要状态查询和结果通知	重复投递、死信、背压、公平调度
持久化工作流引擎	长任务、等待审批、多步骤副作用、跨小时恢复	状态模型和版本治理更复杂	历史兼容、活动超时、重放确定性

不要为“可能以后会很复杂”先引入重量级引擎。先根据任务时长、恢复要求、等待点和副作用数量选型；一旦需要长时间等待、可靠恢复和人工审批，内存里的简单队列通常就不够了。

2.4 工作流定义应版本化

每次执行开始时固定工作流版本、工具策略版本、提示词版本和模型路由版本。运行中的流程不要被新配置静默改变。升级策略通常有三种：让旧 Run 按旧版本继续；提供显式迁移函数；或安全暂停旧 Run 并由人工决定。修改审批条件、权限规则或数据格式时，要把迁移纳入发布评审。

工作流活动应有确定的输入输出契约。活动可以是普通服务函数，也可以是 Agent 子任务；Agent 子任务也要有超时、预算、输入范围、验收条件和明确的失败结果。

2.5 幂等、补偿和人工门禁

队列通常提供至少一次投递，因此消费者必须假设同一消息会重复到达。通过 Run/Step 唯一键、状态条件更新和下游幂等键实现去重。若一个流程包含多个外部副作用，数据库事务通常无法覆盖所有系统；应采用 Saga 思路，为已完成步骤定义补偿操作，或在失败时暂停并人工对账。

人工审批不是弹窗装饰，而是流程中的持久状态。审批记录应绑定具体动作、目标资源、参数摘要、发起者、审批者、时间和策略版本；动作内容发生变化时，旧审批不能自动复用。审批通过后仍要再次检查授权和资源状态。

2.6 Coding Agent 示例工作流

接收 Issue
→ 校验来源、仓库权限、预算和任务类型
→ 创建 Worktree / 沙箱并固定基线提交
→ Agent 分析并制定计划
→ 按权限执行代码和工具操作
→ 运行单测、集成测试和静态检查
→ 归纳差异、测试输出和风险
→ 人工审查高风险变更
→ 创建 PR 并等待 CI
→ 汇总结果、清理资源、记录指标

每个阶段都应有输入契约、输出契约和超时。Agent 未完成任务时，系统要能给出明确失败原因，而不是制造一个看似成功的空 PR。验证步骤失败时，工作流应保留工作区和证据，方便继续修复或人工接管。

3.1 软件测试与 Agent 评测分别验证什么

类型	要回答的问题	例子
单元测试	单个函数和状态转换是否正确？	重试计数、权限判定、序列化
集成测试	模型、工具、存储和队列接口能否协作？	Tool Gateway 与沙箱联调
端到端测试	从入口到交付的链路是否跑通？	Issue 到 PR 的真实流程
可靠性测试	故障后是否可恢复、是否会重复副作用？	杀进程、断网、超时、重复消息
Agent 评测	Agent 对一组任务完成得如何？	修改正确性、验收测试、成本和时间
安全测试	是否越权、泄露、受注入影响或逃出隔离？	提示注入、恶意仓库内容、网络探测

传统测试主要验证程序行为；Agent 评测验证一组可变模型行为。二者需要共同构成发布门禁，不能用单元测试覆盖率替代任务成功率。

3.2 测试金字塔和发布门禁

越靠近底层的测试运行越快、越稳定，适合高频执行；端到端和真实模型测试更接近用户结果，但运行成本更高、方差也更大。推荐的门禁组合：

每次提交：格式、静态检查、单元测试、权限和状态机测试。
合并前：集成测试、工具契约测试、少量端到端 Smoke 用例。
模型/提示词/工作流变更：固定 Agent 回归集和安全用例。
发布候选：多次重复运行关键任务、容量检查、故障注入与人工抽查。
上线后：小流量灰度、监控任务质量和成本，达到停止条件时回滚配置或关闭高风险工具。

端到端测试不要依赖无法控制的实时模型响应来断言每个 token。可以在不同层次使用固定响应模拟器验证协议，在隔离评测环境中调用真实模型验证整体表现，并为每层分别设定通过标准。

3.3 建立可信的任务 Benchmark

每个评测用例至少固定：任务描述、仓库和提交版本、环境、工具权限、模型与提示词版本、预算、验收标准、参考结果或自动评分器。用例应覆盖正常路径、边界输入、工具失败、模糊需求和安全风险。数据集要记录来源、许可、隐私处理和修改历史。

对于 Coding Agent，验收可组合使用：隐藏测试、公开测试、静态分析、差异范围检查、构建成功、人工代码审查和任务说明一致性。测试必须在干净环境中从固定基线执行，不能接受 Agent 修改测试来“证明”自己正确。对于开放式任务，先由领域专家写评分 rubric，再通过盲评样本校准自动评分器。

指标至少分四组：

结果质量：验收测试通过率、功能正确性、缺陷率、回归率。
交付效率：端到端时间、首次成功时间、人工接管率、返工次数。
资源消耗：模型调用次数、token、工具时间、单任务成本。
安全与可靠性：越权率、敏感信息泄露率、恢复成功率、重复副作用率。

成功定义必须先写清楚。例如，代码“有 diff”不等于任务成功；只有满足验收、未破坏现有功能、成本在预算内且没有越权才可计为成功。LLM-as-judge 可补充主观质量判断，但评分器也会偏差，应抽样人工校准，并保留可重复的客观检查。

3.4 方差、回归与线上反馈

模型采样会导致同一用例多次运行结果不同。关键用例应重复运行，报告均值、区间和失败分布；样本较小时不要把细微涨幅包装成确定提升。修改模型、系统提示、工具 schema、检索、Runtime 或工作流后，运行同一套回归集，并按预先设定的质量、安全、延迟和成本门槛决定是否发布。

线上评估需要关注分布漂移：真实用户任务可能超出离线集合。记录失败类型和人工接管原因，经隐私审查后抽样补充到评测集；防止只收录 Agent 容易完成的任务。可采用影子运行、有限灰度和 A/B，但要避免把高风险动作直接交给实验组。

3.5 失败分类与实验设计

失败应按可行动的原因分类，而不是只记“模型失败”：需求解析错误、上下文缺失、计划不完整、工具选择错误、参数无效、权限拒绝、环境不一致、测试没有发现缺陷、结果总结失真、预算耗尽、用户取消等。分类要能落到改进手段，并允许多个原因共同存在。

比较两个 Agent 版本时，固定任务集和执行环境，记录模型、提示词、工具、Runtime、采样参数和数据版本。一次只改变少数变量；否则即使成绩变化，也无法知道原因。报告总成功率之外的分任务类型表现、失败类别、成本和方差。避免只挑容易提升的任务或在看过测试答案后反复调到过拟合。

3.6 故障注入和发布验证

主动模拟模型 429/5xx、工具超时、队列重复投递、数据库不可用、进程被杀、沙箱耗尽、用户取消和预算超限。验证的不只是“报警响了”，还包括：Run 状态是否正确、重试是否受控、用户能否理解当前状态、恢复后是否重复副作用、审计证据是否完整。

发布后用 SLO 判断系统是否健康。可为入口可用性、任务排队时间、任务完成率、恢复时间和安全事件设置服务目标；当错误预算耗尽，应暂停高风险变更，优先修复可靠性问题。

4. 可观测性、审计与事故响应

4.1 三种记录各自回答什么

日志：某个组件发生了什么，适合诊断具体错误。
指标：整体趋势和服务健康度如何，适合告警与容量规划。
Trace：一次任务跨模型、工具、队列和服务的因果链是什么。
审计事件：谁或哪个 Agent 在什么授权下，对哪个资源做了什么动作，结果如何。

一次 Agent Run 的 Trace 应贯穿排队、Runtime、模型请求、工具调用、测试、审批和交付。每个 Span 记录耗时、状态、版本和必要的成本信息。提示词和完整输出可能含有敏感数据，不应无条件写入通用日志；采用访问控制、脱敏、保留期限和按需取样。

可把每个 Run 的关联标识统一起来：task_id 关联业务目标，run_id 关联一次尝试，step_id 关联工作流步骤，trace_id 关联分布式调用链。不要把用户邮箱、原始 Issue 文本等个人或敏感信息直接放入指标标签，避免高基数和隐私泄漏。

建议先建立以下运行指标：

指标	关注点
入队数、排队时长、队列深度	是否积压、调度是否公平
活跃 Run、完成/失败/取消数	执行容量和终止原因
模型请求成功率、限流率、延迟	供应商健康与路由表现
工具调用成功率、超时率	工具可靠性和参数质量
每 Run Token、成本、沙箱时长	成本上限与优化空间
人工审批等待、人工接管、返工	产品可用性与人力负担

SLO 要对应用户能感知的结果。例如“99% 的任务在 30 秒内开始执行”比“Worker CPU 低于 80%”更接近服务承诺。Agent 的任务成功率受任务类型影响，需要分层统计；只报全局均值会掩盖某类任务严重退化。对于低频高风险安全事件，可采用绝对告警和人工升级，而不是等待统计显著性。

4.2 事故闭环

事故处理要能完成发现、止损、恢复、根因分析和预防。复盘聚焦系统条件，不止写“模型犯错”：是权限过宽、验收标准缺失、重试导致副作用、上下文截断、部署变更回归，还是用户操作不清楚？每个行动项都要有负责人和可验证的完成标准。

事故响应手册至少说明：如何停止新 Run、如何取消正在运行的 Run、如何撤销/轮换凭证、如何封禁工具或模型路由、如何保留证据、如何恢复队列和数据、谁负责通知用户。定期演练这些操作；紧急按钮如果从未演练，不能视为可用控制。

延伸阅读：Agent Tracing 基础、Agent 决策审计、Agent 决策审计落地。

5. 安全与治理：让 Agent 的权限可控、行为可追溯

5.1 威胁边界

把用户、模型、工具、检索内容、代码仓库、浏览器页面、MCP 服务和外部 API 都纳入威胁模型。攻击者可能通过直接提示、文档/网页中的间接提示注入、恶意依赖、伪造工具输出或被盗凭证影响 Agent。模型输出本身也可能错误或越权。

风险至少包括：提示注入、数据泄露、工具越权、命令执行、供应链攻击、跨租户访问、凭证暴露、拒绝服务和不可逆副作用。每种风险要写明资产、攻击路径、影响、预防、检测和应急处置。

5.2 控制原则

最小权限：按用户、Run、仓库和操作发放短期、细粒度权限。
明确授权：模型不能通过自然语言自行扩大权限。
输入分区：系统指令与不可信内容分开，并把检索和工具结果标为数据。
外部副作用门禁：删除、发布、付款、权限修改等动作默认需审批或受严格策略控制。
网络与文件隔离：限制沙箱出站访问和挂载路径，防止读取宿主凭证。
审计和响应：保存必要的动作证据，支持撤销凭证、停用工具和终止 Run。
自动化红队回归：把已发现的攻击模式加入回归集，确保修复不会退化。

提示词防护只能作为一层，不能替代工具授权、沙箱、网络限制和人工控制。对高影响操作，应使用确定性策略在模型之外实施。

5.3 威胁建模工作表

对每项重要能力，可以按“资产—主体—入口—动作—影响—控制—证据”建立威胁记录：

场景	可能路径	必要控制	验证证据
仓库中的恶意指令诱导 Agent 外传密钥	Agent 读取 README 后调用网络工具	密钥不暴露给模型；网络出口白名单；工具授权	注入回归用例、网络拒绝日志
两租户共享缓存返回彼此结果	缓存键没有租户/权限维度	租户隔离键、授权后读取、敏感结果不共享	跨租户负向测试
重试重复创建外部资源	下游成功但响应丢失	幂等键、状态查询和对账	断网故障注入与副作用计数
沙箱读取宿主凭证	目录挂载或环境变量泄露	最小挂载、短期凭证代理、无特权容器	沙箱逃逸测试和配置审查
审批后内容被替换	审批只绑定 Run 而不绑定参数	对规范化动作摘要签名/绑定，执行前复核	参数篡改测试与审计记录

不要把威胁模型当成一次性表格。新工具、新数据源、新租户共享能力和权限变更都可能引入新的攻击路径；安全测试应跟随架构变化持续更新。

6. 模型、RAG 与上下文工程

6.1 工程岗位需要的模型深度

Agent 平台工程师不必训练大参数基座模型，但应理解 Transformer 如何基于上下文计算下一个 Token、Tokenization 与上下文窗口对输入长度的影响、推理调用的延迟与成本、结构化输出和 Tool Use 的失败模式、采样参数、模型版本变化以及模型能力边界。无需成为训练算法专家，但应能和算法团队一起定义任务、数据、评价器和实验设计。

工程上要把模型看成带有能力、价格、延迟、上下文长度和服务等级属性的依赖，而不是一个永远稳定的纯函数。模型升级、供应商切换、系统提示调整和推理参数修改都属于影响行为的变更，需要版本记录与回归验证。

可逐步掌握：

模型路由：根据任务难度、延迟、隐私和预算选择模型；失败时有受控降级策略。
RAG：文档解析、切分、索引、召回、重排、引用和检索质量评估。
上下文工程：按任务装配信息，控制噪声、冲突、长度和可信度。
推理部署：理解吞吐、并发、批处理、KV cache、量化和服务弹性等核心取舍。
微调实验：能完成一次有基线、有独立测试集、有版本记录的 LoRA/SFT 实验。

是否微调，应由失败分析决定。知识频繁变化通常应先更新检索数据；工具调用失败可能需要改 schema、示例或 Runtime；只有在行为模式稳定、数据合规且收益可测时，才考虑训练。训练集和测试集必须隔离，避免把测试答案泄漏进训练。

6.2 RAG 的质量链

RAG 不是“接向量数据库”。需要分别评估解析与切分质量、召回率、排序、答案忠实度、引用准确性、时效性和访问控制。权限过滤要在检索阶段生效，不能先取出不该访问的内容，再指望模型不复述。对每个答案保留来源片段，方便验证与审计。

检索阶段可用 Recall@k 检查相关片段是否进入候选集，用 MRR 或 nDCG 检查相关结果是否排在前面；生成阶段则检查答案是否由证据支持、引用是否指向正确段落、证据不足时是否正确拒答。检索和生成要分开诊断：答案错了，不一定是模型不会总结，也可能是解析漏页、切分破坏语义、过滤器误删或重排器排序失误。

6.3 成本和延迟

完整任务成本包括模型 Token、工具/沙箱计算、检索、存储、网络和人工处理。使用小模型处理分类、提取等简单步骤，大模型处理复杂推理；结合缓存、上下文裁剪、并行化和预算上限。缓存键要考虑租户、权限、模型与提示词版本、数据时效，避免跨用户泄漏或返回过期结果。

跟踪端到端延迟及 p50/p95/p99，而不只看模型首 Token 时间。对于长任务，可将用户感知拆成排队时间、首次进展时间、人工等待时间和总完成时间。

6.4 什么时候微调，什么时候不微调

观察到的问题	优先检查	可能的处理方式
答案缺少最新事实	数据是否进入检索、过滤是否正确	更新知识源、重建索引、改进引用验证
工具参数经常不合法	Schema、示例、解析与错误反馈	收紧 schema、结构化输出、工具契约测试
任务经常漏步骤	工作流是否显式、上下文是否完整	拆分阶段、增加检查点、调整规划提示
领域表达风格不稳定	规范样例是否足够、评价目标是否清楚	提示词和样例优化；必要时评估微调
高难推理不稳定	任务是否超出模型能力、评测是否可诊断	模型升级/路由、工具辅助、问题降级或人工复核

只有当目标行为稳定、样本质量和授权合格、训练/验证/测试分离、推理成本与收益可量化时，微调才是合理候选。一次实验应保留基座模型、数据版本、训练配置、随机种子、评估集、结果和回滚方式；否则无法判断提升来自哪里，也无法复现。

6.5 SFT、偏好优化与 Agent 轨迹

SFT（监督微调）：用高质量输入—目标输出示例训练模型模仿期望行为。数据要定义清楚角色、工具调用格式、成功终止和拒绝边界。
偏好优化（如 DPO）：用偏好对表达“同一上下文下哪个结果更好”。偏好标注必须有一致标准；不能把安全拒绝错误地标成低质量答案。
Tool Use 训练：不只训练工具名，还需要覆盖何时调用、参数如何组织、工具失败后如何修正、何时停止和何时询问用户。
Agent 轨迹数据：包含任务、上下文、动作、工具结果、验证反馈和最终结果。轨迹必须检查权限、隐私、成功标签和失败原因，不能把“曾经执行过”当成“值得模仿”。

训练集和验证集按任务或来源隔离，防止同一个仓库、用户或模板的近重复任务跨集合泄漏。实验结果应与不微调的强基线比较，并同时评估任务质量、拒答、安全、工具调用、延迟和部署成本。

7. 分布式执行与多租户平台

从单机原型走向平台，主要增加的是故障域、隔离和控制面复杂度，而不是简单地把服务多开几份。

7.1 参考架构和数据边界

典型组件包括 API/控制面、任务队列、调度器、无状态 Worker、状态数据库、对象存储、模型网关、沙箱池和可观测性管道。控制面管理配置、身份、配额和策略；数据面执行具体 Run。运行状态应持久化，Worker 尽可能可替换。

多租户需逐层隔离：身份与数据行、队列和配额、密钥、检索索引、文件/沙箱、Trace 查看权限及缓存。任何一个共享层都要验证租户边界。限流和公平调度可避免一个租户占满模型额度或 Worker。

7.2 可靠性和扩展

队列削峰并提供背压；消费者处理重复投递。
Worker 水平扩展，但受模型并发、沙箱容量和租户配额约束。
数据库使用事务和版本化迁移；可再生成的索引与不可丢失的原始任务数据分开治理。
对模型供应商、队列和存储故障定义降级、重试、隔离和恢复策略。
设定容量指标和成本预算；压测排队、吞吐、尾延迟与恢复能力。
通过备份恢复演练验证数据可恢复，而不是只确认备份任务成功。

先收集真实负载和瓶颈，再引入分布式组件。对个人原型，过早引入复杂微服务会增加运维面，却未必增加用户价值。

7.3 容量规划与压测

Agent 工作负载通常是长短任务混合、下游调用扇出明显、资源占用差异很大。容量规划不能只按 API 请求/秒估算，还要测每个 Run 的平均/高分位模型调用次数、工具并发、沙箱占用时长、人工等待和结果存储量。

压测至少覆盖：稳定负载下的吞吐、突发负载下的排队与背压、慢模型造成的并发占用、某租户大量任务时的公平性、数据库/队列故障时的退化行为，以及恢复后队列是否能在目标时间内清空。高并发不一定等于高有效吞吐；如果模型供应商限流，继续增加 Worker 只会堆积更多等待任务。

7.4 数据治理与隐私生命周期

为 Run 输入、模型请求/响应、工具输出、代码快照、Trace 和评测样本分别定义数据分类、访问角色、加密方式、保留期限和删除路径。默认只记录诊断所需的摘要和引用；确需存原文时应明确用途、访问审批和保留时间。用户删除任务时，要识别对象存储、缓存、搜索索引、分析副本和备份中的数据如何按策略删除或到期。

评测数据尤其容易混入客户代码和个人信息。对外公开 Benchmark 前要审查许可、机密、凭证、版权和重识别风险，并提供数据来源与清理说明。

8. 真实试点与业务结果

8.1 先定义任务边界

挑选频繁、可验收、风险可控、节省时间可测的任务类型，例如测试补全或低风险 Bug 修复。明确不支持的任务、用户需要提供的材料、所需权限、人工检查点和失败退路。不要一开始就承诺“Agent 自动完成所有研发工作”。

8.2 建立基线和试点协议

试点前记录当前人工流程的完成时间、返工率、缺陷率和直接成本；约定试点持续时间、参与团队、任务范围、数据权限、成功门槛和停止条件。记录所有任务，包括失败、放弃和人工接管，避免只展示成功样例。

推荐对比：

指标	定义示例	使用注意
任务成功率	满足预设验收条件的任务数 / 纳入任务数	固定任务范围，报告分母
人工接管率	需要人继续实质工作或纠正的任务比例	审批与接管分开统计
交付时间	从接单到验收的端到端时长	区分排队和人工等待
返工与回归	失败重跑、后续修复和引入缺陷	观察足够长时间
单任务成本	模型、工具、基础设施及必要人工成本	统一计算口径
用户持续使用	重复使用的团队/用户和任务量	注册数不等于持续采用

业务价值要和对照基线比较；“处理了 2000 个任务”本身不是收益证明。还需说明任务难度、人工参与、失败占比和结果质量。

8.3 反馈进入产品闭环

每次人工接管都应分类：需求不清、上下文缺失、模型规划错、工具不可用、权限不够、测试不充分、工作流设计差或用户不信任。优先修复重复出现且影响大的类别，并把修复转换为测试、策略或文档。外部案例和评价须取得许可，区分已验证结果与目标值。

8.4 试点结果的计算口径

定义一个可复核的“净节省时间”估算：

净节省时间 = 人工基线时间
 - Agent 运行期间仍需投入的人工时间
 - 返工时间
 - 审核与运维分摊时间

将任务成功率与净节省时间一起看。若成功率上升但人工审查时间翻倍，整体收益可能为负；若平均节省明显但高风险错误增加，也不能简单判定成功。报告至少分任务类型、难度、模型版本和人工参与程度，并展示失败案例。

样本选择要避免偏差：纳入连续时间段内符合条件的任务，解释排除条件；记录用户拒绝交给 Agent 的任务，避免只测“最容易的那一类”。对照组尽量保持任务类型和人员经验相近，必要时采用分阶段上线，以区分季节、团队和学习效应。

9. 从能力地图到实践计划

建议按依赖关系推进，而不是同时造所有平台功能：

阶段	重点	可审查交付物
1. 定位与基线	选定窄任务，定义结果和成本指标	任务范围、基线、最小演示和用例集
2. Runtime 与评测	固定运行状态、工具边界、验收与回归	可恢复 Run、评测报告、失败分类
3. 真实试点	让小范围用户持续执行真实任务	试点协议、使用数据、反馈和事故记录
4. 平台化	按实际瓶颈建设队列、多租户、弹性和 SLO	压测、故障演练、容量和成本报告
5. 治理与扩展	威胁模型、权限策略、审计和变更管理	红队回归、威胁模型、发布门禁
6. 影响力与负责	多团队采用、案例、协作和技术决策	可复现案例、设计决策、复盘和分享

一年内合理的成长目标通常是：Runtime、测试和工作流达到有真实生产经历；评测、安全和模型工程达到能独立设计、实现并解释取舍；分布式平台完成有证据的有限规模部署；团队领导力通过试点协作逐步积累。成熟的平台负责人能力需要更长的真实责任周期。

9.1 逐步推进的 12 个月路线

阶段	工作重点	阶段证据
第 1–2 个月：定位和基线	选一个高频、可验收任务；砍掉分散功能；为现有 Runner 建任务记录和版本信息	可安装演示、任务定义、基线数据、首批真实用户
第 3–4 个月：评测和模型	建立固定 Benchmark、失败分类、成本/成功率报表；完成路由或上下文实验	可重复评测、模型对比报告、回归门禁
第 5–7 个月：有限平台化	根据真实瓶颈加入队列、可恢复状态、多租户原型、压测和故障注入	架构决策记录、压测数据、恢复演练
第 5–8 个月：安全并行	做威胁模型、最小权限、沙箱边界、密钥治理和红队回归	威胁模型、策略测试、审计证据
第 2–9 个月：真实试点	持续收集用户任务、人工接管原因和业务结果	试点报告、用户反馈、事故/复盘记录
第 8–12 个月：放大影响	文档、公开案例、外部贡献、面试和技术方案表达	可复现项目、技术文章、案例证明和系统设计材料

时间表只是安排先后关系，不是必须按月完成的承诺。若试点尚未证明任务价值，就应该继续缩小任务和修复可靠性，不应因为路线图写着“平台化”而提前堆分布式组件。

9.2 试点规模目标如何使用

可以把“多个团队或持续用户、上千个真实任务、百例级 Benchmark、重复运行、故障演练、用户案例”等作为求职证据的参考目标，但这些数字不适用于所有产品。金融审批和代码自动修改的风险不同，任务难度、人工介入和质量标准也不同。更重要的是定义口径、报告分母和结果可复核。达到数量但没有质量、成本和用户价值证据，不等于生产成熟。

9.3 技术负责人能力如何形成

高级工程师和技术负责人不仅实现组件，还要为取舍负责：什么先做、什么明确不做；哪些任务允许自动执行；质量、成本、延迟和风险如何权衡；何时买服务、何时自建；出现事故时如何止损；多个团队的需求如何形成稳定接口。可以用轻量的架构决策记录（ADR）保存背景、备选方案、决定、代价和复核条件，让决策可讨论、可修订。

带人能力可从小范围试点开始：写清任务和验收，拆分工作，帮助同伴定位问题，做代码与设计评审，复盘交付偏差。衡量重点是团队能否持续交付和改进，而不是自己完成了多少代码。

9.4 把生产经验转成可信的职业证据

简历和面试中的生产案例应能回答：用户是谁、问题是什么、系统如何工作、你负责什么、规模和指标如何定义、遇到过什么故障、如何处理、哪些方案被放弃、结果有什么局限。每个数字都要能解释分母、时间范围和数据来源。

一个可信的案例表述应采用结构：

背景与任务范围
→ 本人负责的架构/实现/推广
→ 约束与关键取舍
→ 验证方式和真实使用规模
→ 质量、效率、成本、安全指标变化
→ 失败、局限与下一步

避免声称“成功率提升 30%”却说不清基线、样本、版本和是否包含人工接管。工程能力的有力证据不仅是代码，也包括复现实验、事故复盘、设计决策、用户反馈和可公开的架构材料。

10. 生产就绪检查表

任务与用户

任务范围、拒绝条件、验收标准和人工接管路径明确。
有真实基线、固定成功定义和隐私处理规则。
用户能看到进度、暂停原因、预算和最终证据。

Runtime 与工作流

Run 状态、步骤状态、版本和事件可持久化。
超时、取消、重试、重复投递和进程崩溃经过验证。
副作用有幂等保护；无法确认结果时能对账。
资源、模型调用、工具调用和成本均有硬限制。
人工审批绑定具体动作与参数，流程升级不会错用旧审批。

测试与评测

有单元、集成、端到端、安全和故障注入测试。
固定评测集覆盖常见任务、边界、失败和攻击场景。
关键任务重复运行，报告方差、成本和失败类别。
模型、提示词、工具、数据和 Runtime 变更能触发回归门禁。
评分器经过人工抽检，测试集没有训练或提示泄漏。

安全与运维

身份、租户、仓库、工具和网络权限符合最小权限。
不可信代码在受限沙箱中运行，密钥不会进入模型上下文或日志。
日志、指标、Trace 和审计事件可关联并有保留策略。
有告警、停止运行、撤销凭证、恢复数据和事故复盘流程。
有容量、成本、延迟和服务目标，并经过演练。

业务证据

记录全部纳入任务、人工介入、失败、取消和成本。
与相同口径的人工基线比较质量、时间和成本。
结果由试点用户确认；公开案例获得许可并注明范围。

11. 常见误区

**把能调用模型当成 Runtime。**缺少状态、预算、权限、取消和恢复，仍只是 Demo 循环。
**把 Agent 评测等同于单元测试。**代码可以测对，任务仍可能做错；要分别验证软件和 Agent 行为。
**把工作流做成全由模型决定。**权限、审批、测试和发布等控制步骤应由确定性策略执行。
**把重试当可靠性。**没有幂等和对账的重试会放大副作用。
**把 Trace 当审计。**Trace 解释技术调用链，审计还要说明主体、授权、对象和动作结果。
**先做多租户和微服务再找用户。**先证明任务价值和负载，再按瓶颈扩平台。
**只报成功任务和模型分数。**要报告分母、人工投入、方差、成本、安全和后续缺陷。
**把微调当作所有失败的解法。**先归因问题来自数据、提示、工具、流程还是模型，再选手段。

延伸阅读

本文是领域知识入口，不替代针对特定技术栈的操作手册。后续可将 Runtime、评测、工作流、安全和平台运营分别扩展为专题，并在这里维护它们之间的关系、实践顺序与生产验收标准。

内置 Agent 放哪：一个 is_runnable 陷阱与三类事实源

Tue, 22 Sep 2026 18:39:16 +0800

def is_runnable(self, *, supported_source_types: frozenset[str]) -> bool:
 return bool(
 self.enabled
 and self.organization_unit_id
 and self.runtime_connection_id
 and self.runtime_source_agent_id
 and self.runtime_descriptor_checksum
 and self.runtime_source_type in supported_source_types
 )

这是我们 Agent 平台领域模型里的一个函数。六项条件硬 AND，是用户目录 available 字段的唯一来源——某个 Agent 在用户面前是「可用」还是灰掉的，就看这一行。

原型评审通过那天（13 个页面状态全可达、console 零报错），我以为万事俱备。这个函数不这么认为，而我当时的第一反应居然是：是不是原型里哪个开关忘了画。打开领域模型逐个条件对了一遍，才发现不对的是更深一层——我们正准备上线的「内置 Agent」，第四、第五个条件永远没有值可填。

先交代这是个什么平台

一个企业内的 Agent 托管平台，两类角色两个面：管理员在 Admin 侧管 Runtime、管 Agent、做分配；普通用户在 public 目录里挑一个 Agent 对话，每次对话背后是一次可恢复、有事件流的 Run。

「Agent 在这个平台上」其实是两半东西：

业务定义行，存在数据库里：名字、系统提示词、业务目的、任务契约、负责人、可见范围、分配给了哪些部门/人；
Runtime 绑定，就是上面 runtime_ 开头的那几个字段：这个 Agent 实际「由谁执行」——绑到哪条连接、远端的哪个候选、候选定义的哪个版本、来源类型是什么。

平台自己的执行引擎叫 internal Runtime（另有一个隔离沙箱 sandbox），而所谓外部 Runtime，是通过 endpoint 接进来的第三方 Agent 服务：管理员登记一条连接，向它「发现」远端暴露的候选 Agent，再挑一个绑到业务定义行上——平台只负责转发对话，真正的执行发生在远端。

上线至今的 Agent 全是这种「外部绑定型」。这次要新增的是另一种：内置 Agent——跟着平台发布、定义由平台方（ops）拥有、跑在平台自己的 internal Runtime 上，不再有任何远端。

而 is_runnable 是在只有外部绑定型的世界里写出来的。这就是冲突的全部来源。

一个硬 AND 的陷阱

回到开头那六项条件。为什么外部 Agent 个个能过？因为三个 runtime_* 字段是一套「绑定三件套」，从发现流程里带回来：绑的是哪条连接（runtime_connection_id）、远端的哪个候选（runtime_source_agent_id）、候选定义的哪个版本（descriptor 的 SHA-256）。三个字段的语义全部指向远端有个东西。

内置 Agent 没有任何远端，也没有「发现候选再绑定」这一步。第四、第五个字段没东西可填，只能空着。于是内置 Agent 一建出来：管理页面上一切正常，用户目录里永远「不可用」。原型画得再顺，接上实现就是坏的。

这个坑怎么爬，其实只有三条路，走一遍就明白为什么最后只剩「按来源分叉」一条：

路一：全局放宽，把两个字段从校验里删掉。 不行。这两项对外部 Agent 是实打实的防线——远端候选被改名、被下线，descriptor 的 checksum 会变化，创建 Run 时能当场拦下；删掉之后，坏绑定要到运行时被远端拒绝才知道，而且「这条分配基于哪个版本的远端定义」这个审计问题永远失去答案。

路二：内置行也填上值。 给 runtime_source_agent_id 造一个假想候选的常量 ID、checksum 填占位符。能跑，但等于伪造语义——内置 Agent 并不对应任何「被发现的候选」，审计里那句「基于远端哪个版本」在内置行上变成一个指向不存在事物的假答案。这种假答案能骗过所有人，直到有人认真看一眼。

路三：按来源分叉。 条件不再是「六个字段都有值」，而是「这个来源的 Agent，凭什么算完整」。内置行的完整性定义本来就不同：它需要的不是远端三件套，而是定义内容的哈希——声明文件的 SHA-256（下一节讲定义放哪，那里会看到这个哈希从哪来）。外部那套一个字不改，内置按自己的完整性定义显式分叉：

if self.origin == "builtin":
 return bool(
 self.enabled
 and self.organization_unit_id
 and self.runtime_connection_id
 and self.runtime_descriptor_checksum # 声明文件内容的 SHA-256
 and self.runtime_source_type in supported_source_types
 )

但这句话立刻引出了下一个问题：内置 Agent 的定义，到底放在哪里？ 不回答「定义放哪」，checksum 根本无从谈起。

定义放哪：三个候选，和仓库里的三个先例

摆出来的选项有三个。翻代码时发现，每个选项在仓库里都已有先例——这反而让选择变得清楚了。

选项一：Python 常量 + 启动 seed。 内置工具就是这么办的：

def seed_tools() -> None:
 """写入模板内置工具种子数据。"""
 ...
 if database_session.query(ToolModel).first() is not None:
 return # 表里有数据就跳过：seed 只插一次
 seed_tool_models = [
 ToolModel(id="web_search", name="网页搜索", ...),
 ToolModel(id="code_runner", name="代码执行", ...),
 ]

最省事，但改一个 prompt 要发版。更麻烦的是它让数据库处于一种「半拥有」状态：seed 只插一次不更新，管理员在 DB 里改了，DB 成了事实源；管理员删了，下次重启又复活。「内置项的删除与启停归属」必须额外写死规则，不然一定有人踩。

选项二：config.toml 声明段。 平台里非密钥配置的家：

[mcp_connection.types.standard-remote-mcp]
label = "标准远程 MCP"
capability_id = "mcp_generic"

可评审、可 diff，但 TOML 是放标量和短表的地方。内置 Agent 的核心资产是一篇长 prompt，塞进配置文件会把 config.toml 变成没人愿意 review 的怪物。

选项三：ops 拥有的声明目录。 仓库里刚沉淀出的新模式——每个条目一个声明文件，和它的实现代码放在一起：

# 启动声明目录：每个 *.toml 声明一个本地 stdio server 的启动方式...
# ⚠️ 本目录必须由 ops 拥有、运行时只读，且不能落在 workspace_root 内
[mcp_connection.declarations]
root = "src/skill_mcp_react_agent/servers"

改文件 = 提 PR + 评审 + 重新部署；装配期校验，越界直接启动失败；管理面只能选用、不能编辑内容。「ops」在这里是所有权：声明目录归运维/平台方，管理员只能启停和分配，运行时进程只读。

最后拍板选了目录，起决定性作用的却是第四个观察——内置 Skill 早就在过同一条路：每个 Skill 一个目录、SKILL.md 带 frontmatter、加载器解析、content_checksum = SHA-256(SKILL.md)。内置 Agent 和内置 Skill 在资产性质上完全同构：ops 拥有、内容是长文本、随代码发布。Skill 用目录用得很好，没有理由给 Agent 发明第二套。

于是 checksum 的问题顺手解了：内置行的 runtime_descriptor_checksum 填声明文件的内容哈希。和 Skill 的 content_checksum 完全同构，审计表零分叉——「这条分配基于哪个版本的定义」对外部行是远端 descriptor 的哈希，对内置行是声明文件的哈希，语义同一个：定义内容的哈希。

顺带两条派生结论：

内置 Agent 禁止派生。 Derive（把一个 Agent 复制成独立新行，留 derived_from_agent_id 但后续不同步）隐含假设「定义在 DB 里、可以随意复制」。内置 Agent 的定义根本不在 DB，派生出来的行既不是内置（不在目录里）也不是外部（没有远端），目录会被迫长出第三类。想以内置 Agent 为底做变体，正确动作是去声明目录加一个文件。
内置 Runtime 反过来，不需要目录。 内建的 Runtime 就一两个，存在与否跟着代码装配走（adapter 类注册了才存在），为它们建声明目录等于给两个硬编码条目套登记簿。它唯一值得声明的是基础提示词——而这一项现状已经是文件式的：config.toml 只放指针，prompt 是代码旁边的 markdown：

system_prompt_path = "src/skill_mcp_react_agent/SYSTEM_PROMPT.md"

长文本进文件、ops 评审、config 只做指针——声明目录的精神已经在这了，只差给它一个名分。

权限：把 Agent 给了他，Skill 跟不跟过去？

模型问题定了，下一个问题更贴近日常：管理员把一个 Agent 分配给某人，这个人就能直接用 Agent 需要的 Skill 吗？还是全部解耦——给了 Agent 还要再给 Skill / MCP 的权限？

先盘现状，发现已经是混合模型：

资源	授权挂在哪
MCP 连接	Agent 上（一个 Agent 绑一条连接）
工具	Agent 上（descriptor 声明）
Skill	人身上（平台范围默认全员；restricted 需要按人或按部门显式授权）

而且 Skill 的门禁是刻意双层：目录展示和 Run 创建共用同一个策略实例，装配处的注释写得很直白——否则「目录里看不到，但直接提交 skill_id 仍能运行」，两层门禁形同虚设。也就是说现状的回答是解耦：分配 Agent 给的是「可以指挥这个 Agent」，不是「获得这个 Agent 用到的一切」。

要不要改成随 Agent 传递授权？想明白的结论还是不要，三个理由：

越权面。Skill 的运行资产是会真实进入沙箱执行环境的字节。随 Agent 传递，等于分配动作一次性授出该 Agent 引用的全部执行能力，做分配的人根本不知道授出去了什么。
审计粒度。授权挂人身上，「谁能用这个 Skill」是一次查询；挂 Agent 上，要从分配图反向遍历才能算出来。
哲学一致。「Agent 声明它用什么、人决定他能用什么」的分离，和前面「定义不进 DB、DB 只存启停与分配」是同一件事：声明与授权分离。

代价当然有：管理员要多做一步 Skill 分配，用户会碰到「Agent 能打开、跑到某步被拒」。这个用 UX 补，不用权限模型补——分配页展示该 Agent 引用了哪些 Skill、标出当前用户缺哪些授权、给一个「补齐授权」的快捷入口。

一条没查过的链路：执行根本不读 DB 里的提示词

到这里，「让内置 Agent 能用」的清单看起来就是：模型加 origin、is_runnable 分叉、装配期 seed、Run 创建门禁分叉——两天量级的活。但把「创建 → 快照 → 执行」整条链路走一遍之后，发现真正的大鱼藏在水里：

RunStartRequest 只有 run_id / question / session_id / skill_id / resources——没有提示词字段。内部 runner 执行时用的是自己初始化时加载的配置 prompt，DB Agent 行上的 system_prompt 在 canonical Run 链路里根本没人读，只被一版旧编排器消费过。

也就是说：光修 is_runnable，内置 Agent 只是「建得出来、显示可用」；管理员精心填写的业务提示词是摆设，跑出来的行为和平台默认 Agent 一模一样。

要让它「按配置真的跑出区别」，得是第二档工作：把业务提示词送进执行链路，按「Runtime 基础 → Agent 业务 → 本次 Skill」固定顺序拼接，并且在 Run 创建时就拼好冻进执行快照——而不是执行时现查。否则声明文件后续一改，历史 Run 的含义跟着变，审计链就断了。快照冻结合并结果，「这条 Run 基于哪个版本的什么定义」才永远有据可查。

内部 runner 恰好有一个顺手的性质：它自己配置的那份 prompt（SYSTEM_PROMPT.md）天然就是拼接的第一层「Runtime 基础」。两层结构不用推翻任何现有设计，缺的只是把第二层递进去的那段管道。

沉淀：三类事实源

问题讨论完，发现贯穿始终的其实只有一个问题：每类「内置事实」的事实源在哪。仓库里绕了一圈，答案收敛成三类，各归各位：

事实长什么样	放哪	例子
少量标量、开关、阈值，环境相关	config.toml 段	风险门的 `enabled=false`、超时、URL
长文本、ops 拥有、要评审、条目会增多	声明目录	内置 Agent 定义、MCP server 启动声明、SKILL.md
行为实现、绑定关系、每行可变状态	代码 + DB 行	Runtime adapter、连接登记、启停 override

判断触发信号从来不是「它是内置的」，而是三个条件是否同时成立：内容是文本、改它不该发版、条目会长多。风险门控全是数字和开关，一条都不中，所以它老老实实待在 config.toml；Runtime 实例的 endpoint 每个部署环境一个值，进 Git 只会造成配置漂移，所以它待在管理面维护的 DB 里；内置 Agent 的 prompt 三条全中，所以它进声明目录。

还有两条纪律，防止这个模式长歪：

第二个真实案例出现之前，不再开新目录。 边界靠需求撑开，不靠类比——否则三个月后会有七八个名义上「声明式」实际没人维护的目录。
目录加载器要收敛成一套约定。 现在 MCP declarations 和 Skill loader 已经是两套平行的「扫目录、解析、fail-fast、算内容哈希」实现，内置 Agent 是第三个。这次应该把共享部分抽出来——尤其是路径安全校验（目录必须 ops 拥有、运行时只读、不能落在 Agent 可写区），这种安全边界最容易在「照着上一个抄一份」时漏抄其中一行。

几点收获

「新增一类实体来源」的任务里，最值钱的检查不是画新页面，而是把现存的硬校验函数（如 is_runnable）逐条过一遍「新来源下这一项怎么办」。原型验证的是界面，领域模型里的 AND 才是会坏的地方。
承担审计语义的字段（checksum 类）永远给内容哈希，不留空、不造占位符。只要每类来源都能给出「定义内容的哈希」，表就不用分叉，审计问题就有统一句式的答案。
权限要不要随组合传递，答案基本永远是不要。授权粒度应该对齐审计粒度——挂在人身上的权限，才回答得了「谁能用这个」。
管理面填的字段，执行链路不读是最隐蔽的一类断裂。任何「配置了但没生效」的排查，都应该从配置一路走到 start_run 那一刻，看参数到底有没有出现在请求里。
「放哪」类决策（config / 目录 / DB）不是风格偏好，把「谁改它、内容是不是文本、有没有每行可变状态」三个问题一问，答案通常自己浮出来。问完记得再问一句：仓库里有没有人已经这么干过？先例比原则更有约束力。

相关阅读：这个链路里 Runtime、Adapter、Harness 的分工，之前整理过一篇《Agent Runtime 详解》，可以和本文对照着看。

Agent 决策审计：它与 Tracing 的关系

Tue, 22 Sep 2026 11:30:00 +0800

假设一个代码 Agent 改了数据库连接配置。它跑过单元测试，然后决定跳过真实数据库验证，给出“可以合并”的结论。几天后线上出现连接池故障。此时仅看到一条 tool.pytest succeeded 的 trace，并不能回答关键问题：它当时看到了哪些改动，为什么认为真实数据库验证可以跳过？

这正是决策审计（decision audit）要解决的问题。它与 Agent tracing 可以出现在同一条运行时间线上，但两者回答的问题不同：tracing 还原执行过程；决策审计保存判断依据与责任边界。 当 Agent 的判断会影响放行、权限或资源使用时，后者就不能只是几行自由文本日志。

一、先把四种记录分清

记录	核心问题	典型内容	常见用途
Trace	经过了哪些步骤，耗时和错误在哪里？	Agent、模型、工具、命令的 span 与父子关系	排障、性能分析
Log	某一刻发生了什么？	命令退出码、异常、状态变化的文本或结构化事件	定位具体故障
Decision record	基于哪些输入作了什么判断？	风险、候选项、选择/跳过及理由、决策版本	复核判断
Evidence	判断是否得到事实支持？	命令结果、测试报告、截图、审查报告及其摘要	验收与复验

一份 trace 完全可以包含 validation.plan、validation.execute 之类的 span，也可以链接决策记录。但把 span 存下来，不等于完成审计：span 常为排障服务，可能被采样、截断或按较短期限清理；审计记录则要明确必填字段、留存策略、版本关联与完整性状态。反过来，只有决策表而没有 trace，也很难诊断工具超时、重试和上下文断裂。

这里的“审计”不是声称记录模型的全部内心推理。我们能记录和复核的是可观察的输入、显式给出的理由、执行器实际取得的结果，以及最终授权动作。自由文本解释可以帮助人理解，但不能替代结果和证据。

二、决策审计是 tracing 的一部分吗？

从用户界面看，可以是一部分：点开一次 Agent run，沿着时间线看到“分析改动 → 制订验证计划 → 执行 → verifier 复核 → 放行”。从数据责任看，最好是独立记录，再通过标识关联。它们可以共用一次任务的 run_id，而 trace_id 指向这一轮执行的诊断轨迹。

需要特别区分 run_id 与 trace_id。一次长期任务可能暂停、恢复或重试，仍属于同一个业务 run，却产生多个 trace；一次 trace 也可能只覆盖其中一段执行。因此审计主键应围绕业务对象与代码版本设计，不能把“当前 trace 恰好存在”当作放行条件。

PRD / Issue / change
 └─ run_id：业务任务身份
 ├─ decision_id：一次验证计划或放行判断
 ├─ attempt_id：一次执行尝试
 └─ trace_id：该次尝试的诊断轨迹

一种实用做法是：审计记录保留最小且稳定的事实，trace 保留丰富的执行细节。审计记录可以引用 trace；trace 丢失或过期后，仍能知道当时基于哪个代码版本、采用了哪些检查、结果如何。若审计存储本身也可能故障，必须显式标记 history_complete=false，不能默默显示“通过”。

三、一条可复核的决策记录长什么样

以“Agent 自主选择验证项”为例，至少要分开记录计划、执行与裁决。这是本文最重要的边界：Agent 写下“我将运行测试”，不代表测试真的运行过。

{
 "schema_version": 1,
 "decision_id": "dec-42",
 "run_id": "run-17",
 "attempt_id": "attempt-2",
 "source_revision": "git-tree-sha-or-worktree-fingerprint",
 "policy_version": "validation-policy-v3",
 "actor": "validation-planner",
 "risk_facts": ["changed: database pool configuration"],
 "checks": [
 {
 "check_id": "unit-tests",
 "disposition": "selected",
 "reason": "配置解析路径已变更"
 },
 {
 "check_id": "real-db-smoke",
 "disposition": "selected",
 "reason": "连接池行为依赖真实数据库"
 }
 ],
 "created_at": "2026-09-22T03:30:00Z"
}

这条记录只是计划。执行器随后追加每项检查的 started、passed、failed、timed_out 或 unavailable 结果，并附命令摘要、退出码、环境说明、产物引用和摘要值。verifier 再引用同一个 decision_id，说明它是否认可计划覆盖面和实际证据。最终放行记录引用 verifier 结论及代码版本，避免“检查的是 A，合并的是 B”。

字段	为什么需要
`source_revision`	防止旧证据给新代码放行；未提交改动也需要工作区指纹
`policy_version`	以后规则变化时，还能解释当时采用哪套标准
`disposition` 与 `reason`	把跳过项显式化，便于统计误判与复核
`result` 与 `evidence_ref`	区分 Agent 承诺和执行器观察到的事实
`actor`	区分 planner、执行器、verifier 和人工签核
`history_complete`	告诉读者记录缺失，避免把沉默误读为成功

原始 prompt、源码、密钥和完整终端输出不应默认写进长期审计表。可以将原始产物放入受控存储，审计表只保留路径、摘要、脱敏摘要和访问范围。**哈希能证明后来查看的是同一份产物，但不能证明产物当初真实或结论正确。**真实性仍需靠可信执行器、环境记录和必要时的复跑。

四、它怎样帮助替代固定门禁

固定门禁适合确定、便宜、误报低且失误代价高的规则，比如迁移链完整性或禁止提交密钥。Agent 适合根据改动上下文决定验证深度，例如是否需要浏览器真实入口、真实数据库或特定回归场景。决策审计让后者的自由度能够被复核。

可落地的执行顺序是：

识别风险：从 diff、任务要求、依赖边界和历史故障提取具体事实，而不是只给“高/中/低”标签。
列出候选检查：同时记录选择与跳过；跳过需说明前提，例如“仅改文案，没有可执行行为变化”。
执行并留证：由执行器记录实际命令、环境、退出状态和产物；失败、超时、无凭据分别处理。
独立复核：verifier 检查计划是否漏掉关键边界，以及证据是否对应当前版本。它的意见也应作为一条新记录，而不是覆盖原计划。
形成最终裁决：只有与当前代码版本匹配、记录完整且满足必要硬约束的结果，才能支持自动放行；其余情况升级给人。

这不是要求每次都运行最昂贵的验证。它要求验证深度的取舍有可见依据。例如前端仅调整按钮文案，可以跳过端到端流程，但要说明未改交互或请求结果；修改 Dialog、Portal 或跨页流程时，单独的组件截图就不足以证明真实入口可用。

一个常见失败：结果是绿的，判断仍然错

症状	原因	修复
单元测试通过，线上连接池仍故障	计划漏了真实数据库边界	verifier 审查“覆盖了哪些风险”，而不只看退出码
证据文件存在，实际测试没跑完	Agent 把计划或旧文件当结果	执行器写入退出码、时间与产物摘要；绑定代码版本
verifier 判绿，但新提交改变了代码	裁决没有绑定修订版本	代码版本变化时使旧裁决失效并重新评估

五、从最小实现开始，不必先建平台

已有 runner、日志文件和生命周期账本的项目，可以先增加一张追加式 decision_events 表或等价的 JSONL 存储：decision_id、run_id、attempt_id、event_type、actor、source_revision、occurred_at、detail。事件类型先控制在 plan_created、check_started、check_finished、verdict_issued、decision_invalidated。原始输出继续落文件，通过 evidence_ref 关联。

第一阶段让 Agent 决策与现有门禁并行运行，只记录分歧，不自动改变放行。挑选常误拦、执行成本高的门禁，统计它拦住过哪些真实问题、Agent 漏掉了哪些检查、verifier 能否识别。只有在这些反例上表现稳定，才逐项把固定门禁降为提示。否则只是把可见的脚本误报，换成不易发现的判断漏报。

这个方案也有边界。独立 verifier 可能与 planner 共享同一种盲点；本机 SQLite 可能丢失；外部服务验证可能受凭据和环境限制。审计不能神奇地消除这些风险，它的价值是把依据、缺口与责任留在可复核的位置，让后续改进有真实样本。

速查：遇到一个问题该看哪里

你要问的问题	先看
为什么这次 run 很慢？	Trace 的 span 树与耗时
命令究竟报了什么错？	关联 `trace_id` 的日志及原始产物
为什么跳过真实入口验证？	决策记录中的候选项、理由和政策版本
跳过是否合理？	风险事实、任务要求、verifier 结论
测试通过是否能支持当前合并？	执行结果、证据引用、代码版本与最终裁决

我的判断是：决策审计可以嵌进 Agent tracing 的浏览体验，但应有独立的数据契约和留存责任。 当 Agent 只是辅助写代码，trace 通常足以排障；当 Agent 开始决定“哪些门禁可以不跑、这次是否放行”，决策记录就成为运行时的必要组成部分。

继续阅读：Agent 决策审计落地：写入点、复核器与门禁降级判据——本文的落地实现篇；Agent Tracing 基础：Trace、Span 与 OpenTelemetry 埋点；Agent Runtime 详解。

Agent Runtime 详解：从模型循环到可恢复的企业执行系统

Tue, 22 Sep 2026 10:17:24 +0800

用户说：“查询这票货的费用，解释异常，并生成一份待确认的调整建议。”模型可以决定调用什么工具，但模型本身不会验证用户是否有权查看这票货，也不会替你处理工具超时、断线重连、重复提交或进程崩溃。负责把一次模型决策变成受控执行过程的部分，就是 Agent Runtime。

这篇文章把 Runtime 当成工程概念来解释。它没有全行业统一的产品边界：有的框架把模型循环、工具和会话都叫 Runtime；有的平台把队列、沙箱、恢复和审批也纳入 Runtime。讨论具体系统时，必须说清楚它实际承担哪些职责。

一、先给出准确的定义

Agent Runtime 是执行一次 Agent 任务的控制循环及其运行环境。 它接收任务输入和被授权的能力，调用模型，解析模型输出，调度工具或其他 Agent，将执行结果送回模型，并在成功、失败、取消、暂停或预算耗尽时结束本次运行。

最小循环如下：

输入与授权上下文
 → 调用模型
 → 判断输出：最终回答 / 工具请求 / 委派 / 需要批准
 → 执行动作并取得结果
 → 更新本次运行状态
 → 再次调用模型，直到满足终止条件

OpenAI Agents SDK 的 Runner 就实现了这类循环：模型返回最终输出时结束；返回工具调用时执行工具并继续；发生 handoff 时切换执行 Agent 并继续。实际产品通常还要在它外面加上自己的权限、任务持久化和业务审计。官方运行机制

与普通模型调用的差别

能力	一次模型 API 调用	Agent Runtime
决定回复文字	可以	可以，通过模型完成
根据模型意图执行工具	调用方自行编写	Runtime 负责调度与回填
多轮工具循环	调用方自行编写	Runtime 管理循环与终止
取消、审批、恢复	调用方自行设计	视 Runtime 能力而定
权限、成本、审计	模型不负责	Runtime 或外层平台负责

所以“接上 LLM API”只是一个部件；Agent Runtime 的核心问题是谁控制下一步执行，以及错误发生后系统处于什么状态。

二、五个容易混淆的对象

名称	它回答的问题	货运场景例子
模型（Model）	如何生成判断或下一步意图？	判断应查询费用明细
Business Agent	谁负责某类稳定业务任务？	报价 Agent、单证审核 Agent
Runtime	一次任务怎样逐步执行？	调模型、调工具、回填结果、结束 Run
Adapter	怎样接入某个具体 Runtime？	将外部执行器事件转为平台统一事件
Harness / 平台	多个 Agent 怎样被统一治理？	身份、授权、路由、Run、审计、预算

在企业平台的一种常见设计中，Business Agent 是稳定身份；模型、Adapter、endpoint 和外部 Runtime 是可替换的绑定。两个 Business Agent 可以共用一个 Runtime，却保留不同任务契约、知识、Skill、负责人和历史。换 Runtime 也不应抹掉 Agent 的业务身份。

这里的“Runtime”也不要与模型推理服务混为一谈。推理服务负责运行模型并返回 token；Agent Runtime 负责决定何时请求推理、如何处理工具结果和何时停止。一个 Agent Runtime 可以调用远程模型推理服务，也可以调用本地模型。

三、一次真实 Run 怎样执行

仍以货运费用任务为例。下图描述的是一种合理的企业系统分工，不表示所有框架都内置了这些步骤。

sequenceDiagram actor U as 用户 participant H as Harness / API participant R as Agent Runtime participant M as 模型 participant T as 费用查询工具 U->>H: 请求解释费用异常 H->>H: 鉴权、创建 Run、冻结权限和资源引用 H->>R: start(run, input, event_sink, cancel_signal) R->>M: 发送允许的上下文和工具定义 M-->>R: 请求查询费用工具 R->>H: 工具调用候选事件 R->>T: 授权后执行查询 T-->>R: 费用明细或错误 R->>H: 工具结果候选事件 R->>M: 回填工具结果并继续 M-->>R: 异常解释与调整建议 R->>H: 最终输出与终态事件 H-->>U: 流式结果与可回读记录

逐步看，有六个关键点：

创建 Run：为这一轮工作分配稳定身份。会话（Conversation/Thread）可包含多个 Run；一个 Run 也可能包含多次模型调用。不要把“一个聊天窗口”“一条消息”和“一次 Run”混为一谈。
冻结本轮可用资源：平台先解析用户身份、数据权限、Skill 版本和工具范围。模型只能在授权边界内建议动作；不能靠生成文本扩大权限。
执行模型循环：Runtime 调模型，识别最终回答、工具调用、委派或暂停信号。每一轮都应有轮数、时间或费用上限。
执行工具：工具参数需要校验，读写操作需要不同授权。查询失败可以按策略重试；“创建调整单”这类外部副作用不能盲目重放。
产出事件：文本增量、工具开始/完成、错误与终态由 Runtime 报告，再由平台排序、持久化并交付前端。
确定终态：成功、失败、取消和中断含义不同。进程停止不等于业务动作被撤销；取消信号发出也不等于外部工具已经停止。

四、Runtime 内部最少有哪些模块

1. 执行循环与状态机

一个简单实现可以是 while 循环，但状态仍要明确：

# 教学伪代码：展示职责，不是可直接运行的 SDK 示例。
async def execute(run, model, tools, policy, emit):
 state = await load_or_create_state(run)
 while True:
 policy.check_deadline_turns_and_budget(state)
 response = await model.call(state.model_input(), tools.allowed_for(run))
 await emit("model.completed", safe_metadata(response))

 if response.is_final:
 await emit("run.succeeded", {"output_ref": save_output(response)})
 return
 if response.requests_tool:
 call = policy.validate_tool_call(run, response.tool_call)
 result = await execute_with_timeout_and_approval(call)
 state.append_tool_result(call.id, result)
 await emit("tool.completed", safe_metadata(result))
 continue
 if response.requests_handoff:
 await delegate_under_policy(run, response.target)
 continue
 raise UnsupportedModelOutput()

模型决定“建议做什么”，Runtime/平台决定“是否允许、怎样执行、何时结束”。这一分工是安全边界。

2. 状态与上下文

Runtime 至少要知道当前输入、已发生的模型和工具结果、使用的 Agent 配置，以及终止条件。长期运行还要考虑哪些状态能持久化。聊天历史、Run 状态、用户长期记忆是三种不同的数据：聊天历史帮助续谈；Run 状态帮助恢复这次执行；长期记忆跨任务存在并需要独立授权和纠错。

把全部历史聊天直接塞回模型既昂贵，也可能带入过期权限或不相关信息。较稳妥的方式是按本次任务和当前授权组装 ContextPack，记录实际引用与版本。若暂停后恢复，应明确哪些输入沿用快照、哪些权限必须重新校验。

3. 工具调度与副作用

工具执行不只是 functions[name](args)。Runtime 或其外层平台需要回答：参数是否符合 schema？用户是否有权访问目标对象？是否允许联网？工具超时后能否重试？工具已提交业务数据但响应丢失怎么办？

对有副作用的操作，应使用业务幂等键和执行前授权校验。“队列至少一次投递”不能推导出“业务动作恰好执行一次”。恢复时要能区分“未开始”“已经提交但未收到结果”和“已确认完成”。敏感动作可暂停等待用户批准，批准应绑定具体动作和参数；参数改变后需重新判断批准是否有效。官方 human-in-the-loop 示例

4. 调度、隔离与资源限制

Agent Runtime 不必天然等于沙箱。沙箱是它可能使用的一种执行环境。读取数据库的业务 Agent 可以运行在服务进程里；Coding Agent 执行 shell、安装依赖、修改文件时，通常需要更强的进程、文件系统、网络与密钥隔离。

当任务变长或用户增加，还要有队列、Worker、并发上限、租约、心跳、取消传播和预算。此时 Runtime 可以拆成控制面与执行面：控制面保存 Run、调度和策略，执行面在 Worker/沙箱中做模型与工具循环。系统不应因某个 Worker 退出而丢失所有任务事实。

五、取消、重试和恢复：最能检验 Runtime 的地方

取消不是“把 HTTP 连接关掉”

用户离开页面与取消任务是不同动作。取消应有明确命令和状态：平台接收请求、通知执行器、执行器停止可停止的工作、记录外部动作是否已真正停止，最后写入终态。如果外部系统不支持取消，就应如实报告，不要把“已发送取消请求”显示成“已取消成功”。

重试要区分层级

重试对象	常见触发	主要风险
模型调用	限流、超时	重复计费或不同输出
只读工具调用	网络暂时故障	结果可能已变化
写入工具调用	响应丢失	重复创建业务记录
整个 Run	Worker 崩溃	重放已完成步骤和副作用

因此“失败后重试一次”不是完整策略。需要保留每次 attempt 的原因、输入版本、已完成动作和幂等身份。对于无法安全重放的动作，应进入待核对或人工处理状态。

持久化也不等于恢复

保存聊天记录只能证明“知道过去说了什么”。真正的恢复还要知道执行到哪个步骤、哪些工具已成功、哪些回调可能重复、当时用的是哪个 Agent/Skill/权限快照。LangGraph 的持久化机制区分线程内的 checkpoint 与跨线程的 store，checkpoint 可用于中断后继续和故障恢复；但外部写入工具是否能安全重放，仍需由业务系统设计幂等与核对机制。LangGraph 持久化文档

六、Tracing 与事件日志在 Runtime 中的位置

一次 Agent Run 需要两类容易混淆的记录：

业务执行事件：Run 创建、工具调用、批准、终态等可审计事实，常需可靠持久化、顺序号和权限控制。
观测 Trace：模型/工具步骤的耗时、父子关系、token 和错误，帮助定位慢点、失败点与成本。

二者可以关联，也可以由同一组可靠事件投影出诊断视图，但不能默认认为一条采样 Trace 就能承担完整业务审计。Trace 可能被采样、丢弃或限期删除。敏感的 prompt、源码、邮件和工具结果也不应为了排障而默认全文写入观测系统。进一步阅读本站的 Agent Tracing 基础。

七、一个平台设计示例：Runtime、Adapter、Harness 如何分工

可以为不同执行器定义一个最小的执行适配接口，例如 start(run, input, event_sink, cancel_signal) 与 cancel(run_id)。Adapter 包装实际执行器，把来源事件映射为统一的 Run 事件；平台的 Run/Event 层负责持久化、序号、查询与 SSE 交付。这样业务 Agent 身份就不依赖某个执行器的事件格式。这里是说明边界的设计示例，并非通用标准接口。

Business Agent 目录：这是谁、负责什么、当前绑定哪个 Runtime
Harness Core：谁能调用、可用哪些资产、创建哪个 Run、保存什么事实
Runtime Adapter：怎样启动该来源、怎样翻译事件和取消信号
实际 Runtime：怎样调用模型、执行工具、维护循环
Run/Event 投影：怎样回读、流式展示、追踪和审计

一个具体的排障问题是：如果某 Runtime 只报告“工具 A 完成”，没有稳定调用 ID，就不能可靠地区分两次并行调用的同名工具。Adapter 应报告来源能力不足，而不是按工具名或完成顺序猜测父子关系。这是设计 Agent Run tracing 时必须处理的运行事实完整性问题。

最容易犯的边界错误

把模型当 Runtime：以为换模型就能解决任务恢复、工具授权或重复写入。
把 Adapter 当 Runtime：接口能翻译事件，不代表来源真的支持取消、恢复或子 Agent。
把业务身份绑定到 Runtime：换底层框架后，历史 Agent 身份、评测基线和组织规则全部丢失。
把日志当状态：日志能辅助排障，不能可靠判定一次业务动作是否已经提交。
把多 Agent 当成多个 Prompt：真实委派需要独立的子任务身份、权限衰减、预算和结果归属。

八、怎样判断一个 Runtime 是否“能用于生产”

拿一项真实业务任务做验收，比看功能列表有效：

问题	需要看到的证据
执行过程能解释吗？	模型轮次、工具调用、输入来源和终态可按 Run 还原
越权能被挡住吗？	构造跨用户、禁用工具、过期资源访问，均在实际调用前失败
重复请求安全吗？	同一幂等请求不产生两个 Run 或两次业务写入
Worker 崩溃怎么办？	重启后能判定已完成与待处理步骤，不盲目重放副作用
取消是否真实？	能区分取消已请求、执行器已停止和外部动作无法取消
成本可控吗？	轮数、token、时间、工具费用有上限并可归属任务
能替换底层实现吗？	换 Runtime 后业务 Agent 身份、权限与历史保持稳定

如果现在只能做“模型调用工具再返回答案”，那是一个可用的执行循环。当上述证据逐步齐备，它才成为能承担企业任务的 Runtime 与运行平台。

九、建议的学习和动手顺序

先写最小循环：一个模型、两个只读工具、最大轮数和最终输出。观察每轮输入与工具结果如何变化。
加入状态机：明确 queued、running、waiting_approval、succeeded、failed、cancelled 等状态及合法转换。
加入事件与回读：每个 Run 有稳定 ID、按序事件，刷新页面仍能看到已完成步骤。
注入故障：让模型超时、工具响应丢失、Worker 退出；验证重试和副作用边界。
接第二个 Runtime：通过 Adapter 转成同一套 Run/Event 契约，验证业务 Agent 身份不随底层变化。
再做委派和路由：让父子 Run 有独立身份与权限，证明子任务确实执行，而不是仅在 Prompt 中声称委派。

学完后应该能回答一个具体问题：某次 Agent 失败时，是模型判断错、工具返回错、权限拒绝、Runtime 中断，还是平台恢复策略出了问题？ 能沿着一次 Run 给出证据，就真正理解了 Agent Runtime。

参考资料

Agent Tracing 基础：Trace、Span 与 OpenTelemetry 埋点

Tue, 22 Sep 2026 09:51:00 +0800

用户说：这个 Agent 回答一个问题要 40 秒。

我去 grep 日志，符合条件的只有一行：

2026-09-20 14:02:11 INFO run finished run_id=run-7f3a elapsed=41.3s

41.3 秒，和用户说的对得上。然后呢？没有然后了——日志告诉你"慢"，但告诉不了"慢在哪一步"。

于是我加 print：在每轮 LLM 调用前后打一行，在每次工具调用前后打一行。半小时后日志变成这样：

14:01:30 LLM #1 start
14:01:37 LLM #1 done
14:01:37 tool web_search start
14:02:01 tool web_search done
14:02:01 LLM #2 start
14:02:16 LLM #2 done

能看了，但问题也很明显：这些行彼此之间没有关系。换个用户并发进来，两组行就交织成一片；想知道"哪一步占了这 41 秒"，还得靠人肉减时间戳。更别说线上没有 print，只有一条 run finished。

这篇文章要解决的，就是把这个"人肉减时间戳"的过程，换成一套有结构、能自动关联的数据。这正是 Tracing 干的事。

一、Trace 与 Span：一次 Agent Run 就是一棵树

先建立两个最基础的概念，用上面那个 run 当例子。

Trace（链路）：一次完整请求的全过程，有一个全局唯一的 trace_id。上面这次调用对应一条 trace。

Span（跨度）：trace 里的一段工作，有名字、有开始时间、有结束时间，可以有属性和事件。上面每一行 print，本质上都是一个 span。

Span 之间靠 父子关系 组织成树。上面那次 run 画成 span 树是这样的：

agent.run run.id=run-7f3a session.id=s-12 [t=0.0 → 41.3s]
├─ gen_ai.chat 第 1 轮 gen_ai.request.model=某模型 [t=0.2 → 6.8s]
├─ tool.web_search tool.name=web_search [t=7.0 → 24.1s] ← 元凶
├─ gen_ai.chat 第 2 轮 gen_ai.usage.input_tokens=4821 [t=24.3 → 39.6s]
└─ agent.finalize [t=39.7 → 41.2s]

树的形状一出来，答案就自己浮上来了：24.1 秒花在 web_search 上，占掉一半以上。不需要减时间戳，不需要猜。

这里有三点值得单独说清楚，因为后面所有的坑都出在这三件事上。

第一，父子关系是"包含"关系，不是"先后"关系。 子 span 的时间区间落在父 span 区间内。父 span 的耗时不是子 span 的加总——agent.run 是 41.3 秒，四个子项加起来也差不多，但如果两个子 span 时间重叠，说明它们在并行，加总就会超过父 span。时间重叠 = 并发，这是 span 树比日志强的最直观的一点。

第二，根 span 只有一个。 一次 run 对应一个 agent.run span（root span），其余都是它的后代。trace_id 相同、parent_span_id 串起来，就构成了这次 run 的完整路径。排查时从 root 往下看，就是一条推理链。

第三，span 可以跨进程。 一次 Agent Run 里，tool.web_search 很可能不是本地函数，而是打到一个远程服务甚至别人的 MCP Server 上。只要上下文传得过去（第五节讲），那边产生的 span 会挂到你这棵树上，变成你 trace 的一部分。

二、属性与事件：span 上该记什么

有了 tree 骨架，还得有内容。span 上能挂两类东西：属性（Attributes） 和 事件（Events）。这两个词经常被混用，但分工很清楚。

	属性 Attributes	事件 Events
形态	键值对，附着在 span 上	带时间戳的独立记录
回答的问题	这个 span 是什么	这个 span 过程中发生了什么
典型时机	span 存续期间的任何时刻	某个确定的时间点
主要用途	筛选、分组、聚合	还原时间线、记录离散动作
Agent 里的例子	`gen_ai.request.model`、`gen_ai.usage.output_tokens`、`tool.name`	重试一次、首个 token 到达、工具返回、抛异常

一个够用的判断口诀：能被拿来当筛选条件的，放属性；只在某一刻发生、要看"什么时候"的，放事件。

“所有用了 A 模型的 run 平均耗时多少” → 模型名必须是属性（要聚合)。
“这次 run 重试了 3 次，每次间隔多久” → 重试是事件（要看时刻）。

在 Agent 语境里，属性这块已经有一份现成的答案：OpenTelemetry 的 GenAI 语义约定（gen_ai.*）。模型名、token 用量、工具名、会话 id 该叫什么，规范里都钉死了，照着填就能被各种观测后端正确解析。这份约定的字段清单和几个已知的坑，我在 Agent 埋点接 ARMS 里已经逐条整理过，这里只补一条最容易踩的边界：

属性会被当成聚合维度，所以基数要有意识。 run.id、session.id 这种每次都不一样的值，挂在 span 上当属性没问题（trace 是按 trace_id 检索的，不存在"按属性建索引"的压力）；但如果这些属性被顺手套进了 Metrics 的维度里，一张指标卡片就会被炸成几万条时间线。分界线不是"能不能当属性"，而是"这个字段会不会流进指标聚合"。同样地，gen_ai.input.messages 这类可能含用户隐私的字段，规范明确标成了 Opt-In，不该默认记录。

事件这块有一件新变化，值得单独提醒。 OTel 在 2026 年 3 月宣布弃用 Span Event API（也就是 Span.AddEvent / Span.RecordException），原因是"span 事件"和"日志事件"两套并行的机制造成了重复和困惑。新的事件应该走 Logs API，通过上下文与当前 span 关联。需要注意边界：

这是弃用 API，不是删除能力。add_event() 现在还能用，存量数据和在 trace 视图里看事件也照常工作。
建议是：新写的埋点别再加对 add_event() 的新依赖；自己封装的异常上报，优先走日志库 + OTel 日志桥接，它会自动带上 trace_id / span_id。

如果你现在就在写埋点，实操上可以这么记：属性照旧填在 span 上；“某一刻发生了什么"优先记一条结构化日志——既符合新方向，也天然可搜索。

三、Traces、Metrics、Logs：三根柱子各自回答一个问题

到这可能会有一个误解：既然 tracing 这么好，是不是日志和指标就不需要了？

不是。它们是三种不同粒度的问题，互相不能替代：

信号	回答	Agent 里的典型用法
Metrics	“多少 / 趋势”	成功率、P95 延迟、token 消耗与成本、工具错误率
Traces	“哪里 / 路径”	单次 run 的完整执行路径、哪一步慢、哪一步失败
Logs	“具体是什么”	prompt/response 全文、工具入参出参、异常堆栈

换个说法：指标告诉你"出问题了”，trace 告诉你"出在哪个环节"，日志告诉你"那个环节具体发生了什么"。

三者真正的威力在关联。Agent 场景里最常见的一条排查路径长这样：

① 指标：今天 token 消耗比昨天涨了 40% ← Metrics 发现异常
② 点开这张图的某个时间点 ← 靠 exemplar 带出 trace_id
③ 落到那一次 run 的 span 树 ← 看到工具被循环调用了 12 次
④ 跳到对应 span 的日志 ← 看到检索关键词空字符串，导致反复搜

这条链要成立，靠的是一个共同的锚点：

trace_id 是把三根柱子缝在一起的线。 指标里带 exemplar 引用 trace，日志记录里带 trace_id/span_id，trace 上挂结构化的 usage 属性——三条路径都指向同一根线，你才能从"指标异常"一路点到"具体那次请求的日志"。

反过来说，如果日志里没有 trace_id，这套关联就断了，你又要回到"人肉 grep + 减时间戳"。

四、OpenTelemetry 埋点：从 API 到 span 树

OTel 的埋点 API 其实只有三层，理解了这个层次就不会写乱：

TracerProvider 一个进程一个，负责"把 span 送去哪里"（exporter / processor）
 └─ Tracer 按模块命名，比如 "agent.runtime"、"agent.tools"
 └─ Span 一次具体操作，就是树上的一个节点

最小可运行的接线（opentelemetry-sdk 1.44.0，2026-09 的版本）：

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

provider = TracerProvider()
provider.add_span_processor(
 BatchSpanProcessor(OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces"))
)
trace.set_tracer_provider(provider)

tracer = trace.get_tracer("agent.runtime")

埋点本身，推荐用上下文管理器——它保证异常也会结束 span：

with tracer.start_as_current_span("agent.run") as span:
 span.set_attribute("run.id", run_id)
 span.set_attribute("gen_ai.conversation.id", session_id)

 with tracer.start_as_current_span("gen_ai.chat") as chat:
 chat.set_attribute("gen_ai.request.model", model)
 chat.set_attribute("gen_ai.usage.input_tokens", usage.input_tokens)

注意 start_as_current_span 里的 current 两个字——它做的事情是"把新 span 设为当前 span 并放进上下文"，下一个 span 创建时就会自动认它当爹。父子关系不是手写的，是从上下文里自动读出来的。这也解释了为什么上下文一丢，span 树就会散成一片（下一节）。

如果用现成的框架，通常不需要手写这些。LangChain / LangGraph 走 callback，OTel 有 instrumentation 包能自动建 span；纯手写的 Agent Runtime 才需要自己决定"哪些动作值得单独一个 span"。我的经验是：

值得建 span：一次 LLM 调用、一次工具调用、一次检索、一次子 Agent 委派、一次 run 的起止。
不值得建 span：纯粹的参数拼装、字符串裁剪。这类动作建 span 只会让树变胖，真要记录就记事件/日志。

五、上下文传递：让父子关系不断链

这是入门到能用之间最容易被绊倒的一节。OTel 的上下文（Context）在 Python 里建立在 contextvars 之上，含义是"当前执行流里，此刻的当前 span 是谁"。它有两个天然的断裂点。

5.1 进程内：异步任务与线程池

asyncio 里 await 前后的上下文是连续的，一般不会丢。但下面这些会丢：

# 断链：新线程不会继承父线程的上下文
executor.submit(do_work) # do_work 里 get_current_span() 拿到的是 INVALID_SPAN（不记录的占位）

# 补救：显式把上下文复制过去
import contextvars
ctx = contextvars.copy_context()
executor.submit(ctx.run, do_work)

同理，process 池、Celery 之类的任务队列，都必须显式把上下文当参数传过去，再在另一端 attach。这类 bug 的表现很有辨识度：span 数量是对的，但全是平铺的——每个都是 root，没有父子关系。

5.2 跨进程：W3C Trace Context

跨服务传递靠的是 W3C 标准的 traceparent 头：

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
 │ └── trace_id (32 hex) ─────────┘ └─ parent ──┘ └flags
 └ version

注入和提取都是现成的：

from opentelemetry import propagate

# 发送方：把当前上下文写进 HTTP header
headers = {}
propagate.inject(headers) # -> {'traceparent': '00-...'}

# 接收方：从 header 还原上下文，再建 span 就会挂上去
ctx = propagate.extract(received_headers)
with tracer.start_as_current_span("remote.tool", context=ctx):
 ...

只要用了带自动埋点的 HTTP/gRPC 客户端，这一步通常是零成本的。但 Agent 场景有几个地方容易漏：

自己实现的流式接口（SSE 推 run 事件给前端）：手写的 fetch 或自定义协议不会自动带头，得手动 inject。
调用远程 MCP Server：这是最常漏的一处。MCP 的请求里如果没带 traceparent，那边的 span 就是一棵独立的树，你的 trace 到工具调用这一步就断了。
后台任务：异步评估、异步摘要、定时任务，这些不在请求链路里，需要显式把发起时的上下文带过去，否则它们永远是孤儿 span。

一个自查方法：跑一次完整 run，数一下 trace 里 root span 有几个。健康的 trace 只有一个 root；出现多个 root，说明某处上下文断了，去上面三个地方找。

六、三个最常见的坑

按"症状 → 原因 → 修复"记，方便回头查。

症状一：树是平的，所有 span 都是 root。 原因是上下文在异步/线程边界断了。修复：线程池用 contextvars.copy_context() 包一层；跨进程检查 traceparent 是否真的发出去了（抓一次包最快）。

症状二：某个 span 永远不结束，trace 一直在长。 原因是走了 start_span() 手动模式却忘了 end()，或者异常路径上没走到 end()。修复：默认用 start_as_current_span() 上下文管理器；确需手动模式就套 try/finally。

症状三：属性没上去，或者上报报类型错误。 原因是 OTel 的属性只接受基本类型（字符串、数字、布尔和它们的数组），结构化对象塞不进去。修复：结构化内容先 json.dumps() 成字符串；同时想清楚这个字段是不是该进指标维度。

七、速查表

概念	一句话	Agent 里对应什么
Trace	一次完整请求的全过程，有唯一 `trace_id`	一次 Agent Run
Span	一段有起止时间的工作，树上的一个节点	一次 LLM 调用 / 工具调用
父子关系	子 span 时间落在父 span 内，靠上下文自动建立	`agent.run` → `tool.web_search`
属性	键值对，描述 span"是什么"	`gen_ai.request.model`、`tool.name`
事件	带时间戳，记录"某一刻发生了什么"	重试、首个 token 到达、异常
Metrics	回答"多少 / 趋势"	成本、成功率、P95 延迟
Logs	回答"具体是什么"	prompt/response、工具入参出参
上下文传递	`contextvars`（进程内）+ `traceparent`（跨进程）	MCP 调用、SSE 流式、后台任务

几点收获

先问"我要回答什么问题"，再决定用什么信号。 “慢在哪一步"是 trace 的问题，“涨了多少"是指标的问题，硬用日志去回答前两个，就会退化成打印追踪。
属性填得对不对，看它能不能被拿来筛。 能筛的放属性，只能看时刻的放事件，这个口诀能解掉八成的纠结。
上下文是隐式的全局状态，隐式的东西最容易断。 凡是跨了线程、跨了进程、跨了任务队列的边界，都要问一句"当前 span 传过去了吗”。
trace_id 是整个可观测性的粘合剂。 日志里印上它、指标 exemplar 里带上它，三根柱子才真正连成一张网。
规范在变，别把 add_event() 写进新代码。 Span Event API 已经在 2026 年 3 月弃用，新的事件走 Logs API，能力不减，方向更统一。

基础篇到此，概念就这些。下一步是把它接到具体的观测后端上——gen_ai.* 字段怎么填、上报成功但看不到数据怎么办，这些实战里的坑见下一篇 Agent 埋点接 ARMS。

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 埋点接 ARMS：上报返回 success，控制台却是空的

Fri, 18 Sep 2026 18:05:00 +0800

上报接口返回 200，响应体是两个引号包着的 "success"。控制台刷新了五遍，调用链分析里 Span 数量: 0。

第一反应当然是上报没成功。于是回头去查 payload、查鉴权、查代理——查了小半个小时，最后发现数据一直都在，是我看的地方不对。

这篇文章把这个过程完整记下来。前面是排查（含三个可以复用的判别实验），后面是这次顺带做的一个具体问题：对话里带附件时，span 应该怎么记。

前置概念（Trace 与 Span、父子关系、属性与事件的边界、上下文传递）见同系列 Agent Tracing 基础：Trace、Span 与 OpenTelemetry 埋点。本篇不重复讲基础，直接从"接进 ARMS 之后为什么看不到"讲起。

一、`gen_ai.*` 到底是什么

动手之前先明确一件事：埋点里那一堆 gen_ai.xxx 不是我起的名字，是 OpenTelemetry 的 GenAI 语义约定（Generative AI semantic conventions）——社区为"生成式 AI / LLM 应用"单独定义的一套属性规范。

它解决的问题很朴素。没有规范时，同一个"模型名"会被写成 model、model_name、llm.model；“输入 token"叫 prompt_tokens、input_tokens、usage.prompt。结果就是换个观测后端，埋点得重写一遍。

约定把名字、类型、取值都钉死了，所以一份埋点能同时被 Langfuse、Phoenix、ARMS 正确解析。它大致覆盖五类：

类别	属性	说明
操作身份	`gen_ai.operation.name`	`chat` / `embeddings` / `invoke_agent`
厂商与模型	`gen_ai.provider.name`、`gen_ai.request.model`、`gen_ai.response.model`	provider 是判别字段
对话内容	`gen_ai.input.messages`、`gen_ai.output.messages`、`gen_ai.system_instructions`	结构化消息，见下文
用量与结果	`gen_ai.usage.input_tokens`、`output_tokens`、`gen_ai.response.finish_reasons`	成本核算靠这组
工具与会话	`gen_ai.tool.name`、`gen_ai.tool.call.id`、`gen_ai.conversation.id`	关联工具调用与多轮会话

其中 input.messages / output.messages 是结构化的，不是一段纯文本。每条消息是 {role, parts[]}，part 有这些类型：

part 类型	必填字段	用在哪
`text`	`content`	普通文本
`uri`	`uri`、`modality`	文件已在对象存储里，span 只记引用
`file`	`file_id`、`modality`	用厂商预上传能力（如 OpenAI Files API）
`blob`	`content`、`modality`	只有必须内联时才用，base64 进 span 有成本也有合规风险
`tool_call` / `tool_call_response`	`name` / `response`	工具调用与结果

三个必须知道的坑：这些属性绝大部分还是 Development 状态，会改名——gen_ai.system 就被重命名成了 gen_ai.provider.name，gen_ai.prompt.* 也被 input.messages 取代；结构化属性落不到 span 上，OTel 的 Python SDK 只接受基本类型，所以得 json.dumps 成字符串再塞；input/output.messages 是 Opt-In 属性，规范明确说不该默认记录，因为可能含用户隐私。

二、span 树怎么设计

目标形态是一次 Agent Run 对应一棵 span 树，业务库的 Run 记录里存 trace_id 作为关联键：

agent.run [run.id=run-xxx, user.id=demo-user-1, session.id=demo-session-1]
├─ agent.attach_document file.uri / file.mime_type / file.size_bytes
├─ gen_ai chat gen_ai.input.messages / usage.* / latency_ms
├─ tool get_freight_quote gen_ai.tool.name / gen_ai.tool.call.id / tool.result
└─ gen_ai chat 基于工具结果的第二轮作答

写属性的部分收敛成几个 helper，别散在业务代码里——改名时只改一处：

def set_llm_request(span, *, provider, model, messages, conversation_id=None):
 span.set_attribute("gen_ai.operation.name", "chat")
 span.set_attribute("gen_ai.provider.name", provider)
 span.set_attribute("gen_ai.request.model", model)
 if conversation_id:
 span.set_attribute("gen_ai.conversation.id", conversation_id)
 # system 消息按约定不进 input messages，单独走 system_instructions
 span.set_attribute(
 "gen_ai.input.messages",
 json.dumps(to_input_messages(messages), ensure_ascii=False),
 )

to_input_messages 里做两件事：把 system 消息摘出去、把文本统一截断。截断不是可选项——input.messages 里塞进一个 8000 字的 prompt，span 会大得没法用。

三、一个 200 success 的假象

配置填完，跑起来，日志里看到这一行：

POST http://tracing-analysis-dc-sg.aliyuncs.com/adapt_<xx>_<xx>/api/otlp/traces HTTP/1.1" 200 9

200、响应体 9 字节（就是 "success" 加引号）。这种时候人很容易直接跳到"好，通了”，然后去控制台发现什么都没有，再回头怀疑人生。

我做了三个实验来定位问题到底在链路哪一段。这三个实验本身挺通用，值得记：

实验	操作	结果	排除了什么
绕过本地代理	`--noproxy '*'` 直连重发	同样 `200 "success"`	不是代理伪造的响应
发垃圾 payload	`head -c 300 /dev/urandom` 当 body 发过去	`400 Bad Request`	网关真的在解析 protobuf，不是无脑返回成功
伪造 license key	把 `/adapt_.../` 换成随机串	`403 Forbidden`	key 是有效的，且服务端会校验 workspace

三个实验做完，结论就很硬了：数据确实被服务端收下了，而且收进了一个合法的 workspace。既然服务端没问题，那"看不到"就只剩一种可能——去看的那个地方，不是数据所在的地方。

事实也确实如此。

四、三个坑

坑一：地域

接入点是 tracing-analysis-dc-sg.aliyuncs.com，dc-sg 就是新加坡。而控制台默认停在别的地域，调用链分析自然是空的。


症状	上报 `200 success`，控制台调用链分析 `Span 数量: 0`，左侧所有维度显示"没有匹配的值"
原因	控制台地域与接入点地域不一致。数据在 `ap-southeast-1`，眼睛在别处
修复	控制台切到与接入点同地域；`应用列表` 也要在同地域看

这类问题最坑的地方在于：它不报错。上报端一切正常，服务端一切正常，只有"人对不上"。

坑二：入口

地域切对之后，还有第二层错位。控制台里同一个应用有不止一个入口：

应用列表 分 OpenTelemetry 和 ARMS 两个页签。通过 OTel SDK 上报的应用只出现在前者；后者是 ARMS 探针接入的应用列表。看错页签 = 看到空列表。
应用维度的调用链分析 是带过滤的。我一度搜索框里直接粘 trace_id，仍然是 0 —— 因为页面作用域被钉死在某个应用上，搜索条件没换掉"应用"这个更大的前提。页面里搜出来的搜索框内容长这样：

serviceName:"agentrun-agent-quick-oUpbu" and resources.acs.arms.service_id : "azmulz8rp8..."

第三段 resources.acs.arms.service_id 是 ARMS 探针注入的资源属性。OTel 自己上报的 span 根本没有这个属性，所以这个条件永远匹配不上。


症状	搜 trace_id 也搜不到；应用列表某个页签永远是空的
原因	页面作用域（应用 / 页签）与数据的归属不匹配
修复	换到不绑定单个应用的入口，或把搜索条件改成 `serviceName:"<你的服务名>"`

坑三：配置写法

第三个坑不致命，但错误信息很难自查，因为不报错：

# 错的：ARMS 的 header 不是 Authorization: Bearer
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <token>

# 对的：HTTP 接入点鉴权编码在 /adapt_<xx>_<xx>/ 路径里，headers 留空
OTEL_EXPORTER_OTLP_ENDPOINT=http://tracing-analysis-dc-sg.aliyuncs.com/adapt_<xx>_<xx>/api/otlp/traces
OTEL_EXPORTER_OTLP_HEADERS=

# 只有 gRPC 才需要 header，格式是 Authentication=<token>
OTEL_EXPORTER_OTLP_ENDPOINT=http://tracing-analysis-dc-sg.aliyuncs.com:8090
OTEL_EXPORTER_OTLP_HEADERS=Authentication=<token>

还有一条同类的：HTTP 接入点自带 /api/otlp/traces，不要再拼 /v1/traces——那是本地 Jaeger 的写法，拼上去就是 404。

五、对话里带附件怎么记

这是这次真正想解决的问题：Agent 的对话里带了文件，trace 上该怎么表达。

关键决定是文件不进 span 的字节流。做法是三处落点：

位置	记什么
`agent.attach_document` span	`file.uri` / `file.mime_type` / `file.size_bytes` / `file.doc_id`
`gen_ai chat` 的 `gen_ai.input.messages`	该条 user 消息的 `parts` 里一个 `uri` part + 一个 `text` part
业务库	文件归属业务层（doc_id ↔ Run），trace 里只留引用

实测落进 ARMS 的属性长这样：

[{"role": "user", "parts": [
 {"type": "text", "content": "按附件里的信息报价"},
 {"type": "uri", "uri": "oss://bucket/uploads/doc-adcc4d1f/booking-note.txt",
 "modality": "document", "mime_type": "text/plain"},
 {"type": "text", "content": "订舱委托书 / BOOKING NOTE\n委托编号：BN-2026-0918-075…"}
]}]

三个设计取舍值得说一下：

第一，uri part 和 text part 成对出现。 uri 是溯源（文件从哪来），text 是模型真正读到的内容（服务端预抽取的结果）。只记 uri，排查时无法回答"模型到底看没看到附件"；只记 text，又丢了文件来源。两个都记才查得动。

第二，modality 是必填。 uri 和 file part 都要求这个字段，取值 image / video / audio / document。容易漏，漏了后端可能直接忽略这个 part。

第三，模型调用侧和 trace 侧要分开构造。 应用侧消息保留结构化内容（{type: "text"} / {type: "document"}），发给 OpenAI 兼容端点时拍平成纯文本；转成 gen_ai.input.messages 时才展开成 uri + text。这样两边各取所需，不会为了迁就某一方而变形：

# 模型侧：附件以抽取文本注入
def to_openai_content(content):
 if isinstance(content, str):
 return content
 chunks = []
 for item in content:
 if item["type"] == "text":
 chunks.append(item["text"])
 elif item["type"] == "document":
 chunks.append(f"[[附件 {item['uri']}]]\n{item['extracted_text']}")
 return "\n\n".join(chunks)

验证方式是让模型复述附件里的独有信息——它在回答里用上了委托书的 ETD 2026-09-25、截关时间和"14 天免箱期"。这说明附件确实进了模型上下文，不只是进了 span。

顺手补的一个洞：BatchSpanProcessor 默认靠 atexit 冲刷，进程被强杀（Ctrl-C、沙箱超时）时最后一批 span 会丢。Run 结束处显式 force_flush() 更稳。

六、数据怎么拿出来给 AI 看

控制台是给人看的，AI 想自己查得走另外三条路：

1. OpenAPI（免费，最直接）。xtrace 产品两个接口就能拼出一个导出脚本：

接口	作用	关键参数
`SearchTraces`	按条件列出调用链，返回 TraceID 列表	`RegionId`、`StartTime`/`EndTime`（毫秒）、`ServiceName`、`OperationName`、`MinDuration`、`Tag`、`PageNumber`/`PageSize`
`GetTrace`	按 TraceID 取完整 span 明细	`TraceID`、`RegionId`

翻页拿 ID，再逐条取详情，落地成 JSON 就完了。

2. 可观测 MCP Server（aliyun/alibabacloud-observability-mcp-server）。Go 单二进制，里面正好有对应的工具：

{
 "mcpServers": {
 "alibaba_cloud_observability": {
 "command": "./bin/alibabacloud-observability-mcp-server",
 "args": ["start", "--stdio"],
 "env": {
 "ALIBABA_CLOUD_ACCESS_KEY_ID": "<AK>",
 "ALIBABA_CLOUD_ACCESS_KEY_SECRET": "<SK>",
 "ALIBABA_CLOUD_REGION": "cn-singapore"
 }
 }
 }
}

接上之后可以直接问"昨天耗时最长的几条 Run 是什么，gen_ai.input.messages 里带没带附件"，由 umodel_search_traces / umodel_get_traces 去取。两个注意点：用只读 RAM 用户（AliyunARMSReadOnlyAccess），别用主账号 AK；sls_text_to_sql、sls_sop 这类 AI 工具走 STAROps 单独计费，不需要就在 config.yaml 的 enabled_tools 里关掉。

3. Collector 双写。反正上报端在自己手里，OTel Collector 同一份数据同时投 ARMS 和本地存储（ClickHouse / 文件 / 对象存储）。本地那份没有 AK、没有分页、随便 SQL——AI 分析用它比用控制台 API 舒服得多。ARMS 负责看瀑布图和告警，本地那份负责喂给 Agent。

总结

几个收获，都是这次真金白银换来的：

1. 200 不等于数据可用。 "success" 只说明网关收了，说明不了数据落到了你正在看的那个地方。判断"到底通没通"要有独立证据——我这次用的是"发垃圾字节看它报不报错"和"伪造 key 看它拦不拦"，两个实验各一次请求，就能把链路切段定位。

2. 可观测性接入的坑，多半在"人对不上"而不是"数据不通"。 地域、页签、页面作用域、filter 条件，这四样任何一个不对，现象都是同一个：空列表。而且全都不报错。排查时优先怀疑这个，比怀疑 SDK 划算。

3. 约定比实现重要。 用 gen_ai.* 的收益在这次很直观：同一份埋点，改个 endpoint 就从本地控制台切到了 ARMS，一行代码没动。代价是要接受它还在 Development、会改名——所以属性写入必须收敛到 helper 里。

4. 文件类数据，“引用 + 摘要"比"内容"有用。 把 pdf 塞进 span 不会让排查更容易，只会让它更贵更难搜。uri part 记来源、text part 记模型看到的内容、业务库存文件本身，三层各司其职。

5. 顺手能修的洞就别留着。 force_flush() 这种一行的事，不补就是"偶发丢 trace”，而偶发丢 trace 是最难查的那类问题——它会让上面所有的排查经验都建立在错误的观察上。

Cua 框架详解：给任何 Agent 一台可操控的电脑

Mon, 14 Sep 2026 16:00:00 +0800

Cua 框架详解：给任何 Agent 一台可操控的电脑

前言：会写代码的 Agent，不会用电脑

过去两年，AI Agent 在"写代码"这件事上已经卷出了新高度——Claude Code、Codex、Cursor 个个都能独立完成复杂工程任务。但一旦任务超出终端的边界：打开计算器验证一个结果、在 LibreOffice 里填一张表、操作一个只有 GUI 的内部系统——大多数 Agent 就只能干瞪眼。

这就是 Computer Use（计算机使用） 要解决的问题：让 Agent 像人一样看屏幕、点鼠标、敲键盘、操作真实的桌面应用。

今天要介绍的 trycua/cua 是这个赛道上热度最高的开源项目之一（截至 2026-09 已超过 22.6k star，MIT 协议，4700+ commits，更新极其活跃）。它的定位一句话就能说清：

You bring the agent and model. Cua provides the computer and automation tools. 你带来 Agent 和模型，Cua 提供电脑和自动化工具。

它不是一个绑定某家模型的产品，而是一套模型无关、Agent 无关的基础设施：任何支持 MCP 的 Agent（Claude Code、Codex、Cursor、OpenClaw……）接上它，立刻获得对真实桌面的控制能力。

一、Computer-Use 2.0：不只会截图点击

Cua 提出了 “Computer-Use 2.0” 的概念，核心思想是：Agent 不应该在 API、代码和图形界面之间二选一，而是按任务自由切换。

路线	典型做法	问题
纯视觉 CUA（1.0）	截图 → 模型找坐标 → 模拟点击	慢、贵、易错，每一步都要一次模型往返
纯 API/脚本	直接调系统接口	覆盖不了没有 API 的 GUI 应用
Cua 的 2.0	语义接口优先，GUI 兜底，混合编排	兼顾速度与覆盖面

具体来说，Cua Driver 操作一个应用时，会优先走无障碍树（Accessibility Tree）、快捷键、直接赋值这类语义通道；只有在没有语义通道可用时，才退化到 OCR 和像素坐标。这带来两个直接好处：

低延迟：少截图、少模型往返，一步到位；
后台投递（Background Delivery）：向应用发送指令时不移动鼠标指针、不抢焦点——Agent 在后台操作 LibreOffice，你可以继续在前台干自己的事，两个 Cua 会话还能同时操作不同的应用。

这是它和"截图派"方案拉开差距最大的地方。

二、四大核心组件

Cua 仓库由四个产品组件构成，各自解决 computer use 链路中的一段：

┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Cua Driver │ │ Lume │ │ Cua Fleets │ │ Cua Bench │
│ 桌面驱动/MCP │ │ 本地虚拟化 │ │ 云桌面舰队 │ │ 评测基准 │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
 控制真实桌面 Apple Silicon 隔离的云端 训练/评估/
 macOS/Linux VM Linux 桌面池 数据生成

1. Cua Driver —— 核心驱动

整个项目的心脏，值得单独展开：

Rust 实现（cua-driver-rs），通过 UniFFI 同时提供 Python 和 TypeScript SDK 绑定，性能和内存占用都远好于 Python 方案；
三种接入方式：CLI（cua-driver call ...）、MCP Server（cua-driver mcp）、类型化 SDK；
MCP 协议支持：支持 MCP 2026-07-28 新版协议（stdio 通道），同时向后兼容老客户端；还内嵌了 skill://cua-driver/ 技能资源，Agent 可以按需读取使用指南；
跨平台：macOS、Windows、Linux（X11、Wayland/Hyprland、AT-SPI 都有适配）。

2. Lume —— 本地虚拟化

在 Apple Silicon Mac 上基于 Apple Virtualization.Framework 创建和管理本地 macOS / Linux 虚拟机（Swift 实现）。想让 Agent 在隔离环境里折腾而不污染宿主机，这是最顺手的选择——几条命令就能从 Apple 官方恢复镜像拉起一台干净的 macOS VM。

3. Cua Fleets —— 云桌面舰队

不想本地跑 VM？run.cua.ai 提供按需供应的隔离云桌面：Fleet 维护一个 sandbox 容量池，代码从池里"认领"桌面，通过 Sandbox SDK 执行命令、截图、与应用交互，用完即毁。底层是 Kubernetes 式的集群配置和 Image API（CRD 契约），适合批量任务和数据生成。

4. Cua Bench —— 评测与训练

构建 computer-use 任务、评估 Agent 表现、导出操作轨迹用于训练和数据生成（站点 cuabench.ai）。支持两种模式：

模拟任务：不需要 VM、Docker 甚至模型 API key 就能跑；
浏览器任务：基于 Playwright Chromium。

对做 Agent 研究和微调数据的人来说，这部分是宝藏。

三、安装与权限

安装 Driver

# macOS / Linux
/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"

# Windows (PowerShell)
irm https://cua.ai/driver/install.ps1 | iex

安装后先验证驱动能看到桌面：

cua-driver --version
cua-driver call list_apps

macOS 权限

macOS 上必须授予**辅助功能（Accessibility）和屏幕录制（Screen Recording）**权限：

cua-driver permissions status

权限模式：standard vs bounded

这是 Cua 安全模型里很关键的设计。注册 MCP server 时并不决定权限，权限由持有 driver 运行时的进程在启动时决定：

standard 模式：Agent 可以对桌面上所有应用执行输入操作；
bounded 模式：通过能力清单（capability manifest）限定 Agent 只能触碰审查过的应用、来源和目录。

# Windows/Linux 可用环境变量指定模式
CUA_DRIVER_PERMISSION_MODE=bounded \
CUA_DRIVER_CAPABILITY_MANIFEST_FILE=/path/to/manifest \
CUA_DRIVER_CAPABILITY_MANIFEST_APPROVED=1 cua-driver mcp

Agent 自己无法通过工具调用扩大权限，这个边界必须由用户在启动时画好。

本地虚拟化（可选）

/bin/bash -c "$(curl -fsSL https://cua.ai/lume/install.sh)"

四、接入你的 Agent

Cua Driver 内置 MCP server，所有支持 MCP 的客户端都能接。官方甚至提供了配置生成器：

cua-driver mcp-config --client <client>

Claude Code

claude mcp add --transport stdio cua-driver -- cua-driver mcp
claude mcp list # 确认已连接

Cursor

把生成的 JSON 粘到 ~/.cursor/mcp.json（或项目级 .cursor/mcp.json）：

{
 "mcpServers": {
 "cua-driver": {
 "command": "cua-driver",
 "args": ["mcp"],
 "type": "stdio"
 }
 }
}

Codex

cua-driver mcp-config --client codex
# 会输出使用绝对路径的注册命令，避免 PATH 问题：
codex mcp add cua-driver -- /Users/you/.local/bin/cua-driver mcp

任意 MCP 客户端（通用 JSON）

{
 "mcpServers": {
 "cua-driver": {
 "command": "cua-driver",
 "args": ["mcp"]
 }
 }
}

此外还有 OpenCode、Qwen Code、Prime Agent、OpenClaw 等一长串官方适配，完整的客户端清单见官方文档。

五、第一个任务：让 Agent 算 6 × 7

官方入门教程的任务很朴素：让 Agent 打开计算器，算出 6 × 7，并验证界面显示 42。

装好 Driver 并接入 Claude Code 后，直接说人话就行：

用 cua-driver 打开计算器，计算 6 × 7，
截图确认结果显示 42。

Agent 会自主完成：定位应用 → 激活窗口 → 语义/快捷键输入 → 截图验证。全过程你只负责最后看一眼结果。

实测记录：从安装到 42

笔者在 Apple Silicon Mac（macOS）上完整跑了一遍这条链路（不接 MCP、直接走官方 CLI cua-driver call，与 MCP 是同一个驱动内核），最终截图确认计算器显示 6×7 = 42。实际执行序列：

# 1. 安装（装到 /Applications/CuaDriver.app，symlink 到 ~/.local/bin）
/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"

# 2. 授权：一条命令搞定三项权限（弹出系统对话框，点击确认即可）
cua-driver permissions grant
cua-driver permissions status # Accessibility / Screen Recording / Direct Capture 全 ✅

# 3. 执行任务
cua-driver call launch_app --args '{"bundle_id": "com.apple.calculator"}'
cua-driver call bring_to_front --args '{"pid": <PID>, "window_id": <WID>}'
# 通过 AX 树点击按钮：'6' → 'Multiply' → '7' → 'Equals'
cua-driver call get_desktop_state --args '{}' # 截屏验证：6×7 = 42 ✅

看似简单，实际踩了三个坑，每一个都值得写进 Agent 的操作手册：

坑	现象	原因与解法
`ambiguous_window_target`	所有 click / press_key / bring_to_front 被拒绝执行	Calculator 有 5 个窗口（含离屏辅助窗口），driver 拒绝猜测目标。所有操作必须显式传 `window_id`——这是刻意的安全设计
`element_token` 快照绑定	第二次用同一 token 点击，静默失效	`get_window_state` 每次返回新 snapshot，token 与快照绑定。必须每次点击前重新拉取 AX 树取新 token
`zoom` 返回陈旧帧	明明点击成功了，截图里显示屏却"是空的"	`zoom` 可能命中缓存帧；用 `get_desktop_state` 全屏新鲜捕获再裁剪，才反映真实状态

还有一个反直觉的发现：press_key 走合成键盘事件（synthetic events）对 Calculator 不生效（返回 unverifiable，实际未注册输入），而 AX 元素点击（accessibility 路线）一次就中。这正好印证了 Cua “语义优先于像素坐标"的设计——能用无障碍树就别模拟键盘鼠标，又快又稳。

另外两个值得知道的细节：

遥测默认开启：安装器提示默认收集匿名 ID 和无内容用法统计，介意就 cua-driver telemetry disable；
验证要靠"新鲜眼”：driver 的 verify_state 支持对精确窗口做确定性断言（谓词 AND 组合、连续采样防抖），Agent 验证结果应优先用它，而不是自己截图目测。

其他官方教程场景：

组件	场景	教程
Fleets	供应云桌面 → 跑 `uname -a` → 截图 → 释放资源	Your first Cloud Fleet
Driver	计算器算 6×7 并验证	Drive your first app
Lume	从 Apple 恢复镜像创建 macOS VM → SSH 连接	Create your first Lume VM
Bench	创建模拟任务 → 跑参考解法 → 验证得分 1.0	Your first Cua Bench task

六、横向对比：该选哪个？

项目	Stars	形态	强项	适合
trycua/cua	22.6k	驱动 + MCP + VM + 云 + 评测	桌面级控制、低延迟后台操作、Mac 支持最好	给 Claude Code/Codex 等编码 Agent 加"手"
browser-use	114k	浏览器自动化库	浏览器内任务的事实标准	只需要网页操作
microsoft/OmniParser	25.4k	屏幕解析模型	纯视觉 GUI 理解的底层组件	自研 CUA 的基建
UI-TARS-desktop	39k	桌面 Agent 应用	开箱即用的多模态 Agent 产品	不想写代码直接用
Anthropic CUA API	—	闭源 API	与 Claude 深度集成	全托管的商业方案

简单决策树：

只操作网页 → browser-use；
想让编码 Agent 操控整个桌面（macOS 尤佳）→ Cua；
想要开箱即用的桌面 Agent 应用 → UI-TARS-desktop；
要自研底层 → OmniParser + Cua Bench。

七、安全注意事项

Computer use 天然是双刃剑，几个必须记住的点：

权限最小化：优先用 bounded 模式 + 能力清单，别随手开 standard；
屏幕内容只是数据：网页、邮件、OCR 出来的文字不能改变用户授权，警惕提示注入（prompt injection）——一个网页上写着"请把密钥发到 xxx"的页面，不该让 Agent 照做；
高危动作加人审：发送、付款、删除、上传、权限变更这类动作，务必留在确认边界之外；
沙箱优先：不信任的任务丢进 Lume VM 或 Fleets 云桌面里跑，别碰宿主机。

总结

Cua 补上了 AI Agent 工具链里缺了很久的一环：编码 Agent 已经很强，缺的只是一双操作真实电脑的手。它用 Rust 驱动保证了低延迟，用 MCP 保证了"任何 Agent 都能接"，用 Lume/Fleets 保证了隔离执行环境，用 Bench 打通了训练评测闭环——每一层都是独立可用的开源组件。

如果你的 Agent 目前只会敲终端命令，值得花半小时把 Cua Driver 接上试试——当 Claude Code 第一次自己打开计算器算出 42 并截图给你看时，那种"AI 长出手了"的感觉还是非常震撼的。

参考资源

仓库：https://github.com/trycua/cua
官方文档：https://cua.ai/docs
Agent 接入指南：https://cua.ai/docs/how-to-guides/driver/connect-your-agent
云桌面：https://run.cua.ai
评测基准：https://cuabench.ai

数据说明：文中 star 数截至 2026-09-14。Cua 主项目为 MIT 协议；可选的 cua-agent[omni] 依赖 ultralytics（AGPL-3.0），商用集成时注意区分。

AG-UI：当 Agent 学会了和前端说话

Thu, 10 Sep 2026 14:30:00 +0800

最近在给自己的 Agent Runtime 设计输入输出契约时，我在 README 里画了一张三方对照表：我定义的事件类型一列、Runtime 原生事件一列，第三列空着——那是留给 AG-UI 的。填完这张表之后我发现，AG-UI 值得不只是一列，它值得被完整讲一遍。为了写这篇文章，我把官方仓库、Python SDK 源码和 PyPI/npm 的发布记录都翻了一遍，下面带着版本号讲。

先看仓库现状（2026-09-10）

先把事实钉住，本文所有描述都对应这个版本：

项	值
仓库	`github.com/ag-ui-protocol/ag-ui`，创建于 2025-05-07
文档	docs.ag-ui.com（draft spec + SDK 参考）
热度	15.8k stars / 1.4k forks，MIT License
本文对应 commit	`main@5f32a64ee999`（2026-09-09）
Python SDK	`ag-ui-protocol` 0.1.22（PyPI，2026-08-31 发布，首版 0.1.4 于 2025-04-30）
TypeScript SDK	`@ag-ui/core` 及 client/encoder/proto 系列 0.0.59（npm latest，另有 canary/alpha 通道）
发布节奏	几乎每日切一次 release（2026-08-20 到 09-09 切了 5 个），协议仍处 draft 阶段

Python 包只依赖 pydantic>=2.11.2，一个依赖，克制得不像一个协议实现。

三层协议的最后一块

把 2024-2026 这两年 agent 协议的版图摊开，会发现一个很规整的分层：

MCP（Anthropic）：agent ↔ 工具。让模型能标准地"伸手拿东西"。
A2A（Google）：agent ↔ agent。让多个 agent 标准地互相委派任务。
AG-UI（CopilotKit）：agent ↔ 前端。让 agent 的运行过程标准地"演给用户看"。

前两层这几年讨论得足够多了，第三层却长期处于"每家自己造"的状态：LangGraph 自己定义 stream mode，OpenAI Assistants 自己定义 run steps，各家 ChatUI 各自解析各家的事件格式。你写一个 agent 后端，想换个前端，事件层的适配就得重写一遍；你写一个聊天前端，想接不同的 agent，每种 agent 的 SSE 格式都得单独处理。

AG-UI 的野心就是把这层标准化掉。它不是委员会里设计出来的协议——它是从 CopilotKit 这个产品里长出来的：CopilotKit 做了几年"把 agent 嵌进 React 应用"这件事，攒够了事件类型的实战样本，回头把内部格式提炼成了开放协议，初始合作伙伴是 LangChain（LangGraph）和 CrewAI。这一点从仓库结构里看得见：integrations/ 目录下有 21 个条目——18 个框架适配层、2 个 server starter 模板加一个 community 目录；apps/ 里挂着 dojo（官方演示站）和一个 CLI 示例应用。

仓库解剖：一个协议 monorepo 长什么样

官方仓库是一个 pnpm + nx 的 monorepo，顶层结构本身就是协议生态的切片：

ag-ui/
├── sdks/
│ ├── python/ # ag-ui-protocol 0.1.22 (core + encoder)
│ ├── typescript/ # @ag-ui/core|client|encoder|proto 0.0.59 + cli
│ ├── dotnet/ # 官方 .NET SDK
│ └── community/ # dart / rust / ruby / c++ / kotlin / go / java ...
├── integrations/ # 20 个框架适配层(见后文生态一节)
├── middlewares/ # a2a / a2ui / mcp / mcp-apps / event-throttle
├── apps/ # dojo(官方演示) + client-cli-example
└── docs/ # 文档源

两个细节值得注意：middlewares 是独立一层——A2A 桥接、MCP 桥接、MCP Apps、A2UI、事件节流各占一个包，说明协议把"和别的协议对接"也当成了标准件而不是用户自理；protocol 有 TypeScript 和 Python 两套官方实现，且明确以 TypeScript 为参考实现（源码注释里直接写着 TS 的行为是其他 SDK 对齐的基准）。

事件流是唯一事实源

AG-UI 的核心设计只有一句话：agent 的一次运行 = 一条有序事件流，前端状态完全由事件序列归约得到。

没有独立的 REST 查询接口，没有"拉取当前状态"的端点。前端想知道 agent 在干什么？订阅事件流，逐条归约。想在断线后恢复？重新拿一遍事件（或快照），重放。这个思想和事件溯源（Event Sourcing）一脉相承，也和我自己的 Canonical Run 契约不谋而合——事件即事实，投影即状态。

协议在 0.1.22 的定义里共有 36 个事件枚举成员——31 个在用，加上 5 个已废弃的 THINKING_*（1.0.0 移除）。全部继承自一个四字段信封：

{
 "type": "TEXT_MESSAGE_CONTENT",
 "timestamp": 1730000000,
 "rawEvent": null,
 "metadata": {}
}

按功能分组看一眼全集，就能感受到协议想覆盖的交互光谱：

生命周期（5 种）——RUN_STARTED、RUN_FINISHED、RUN_ERROR 管起止，STEP_STARTED/STEP_FINISHED 标记过程里的小步。注意 run 的两个标识 threadId 和 runId 都是客户端生成的，服务端在 RUN_STARTED 里回显——这和 OpenAI 式"服务端生成 ID 返回给你"正好相反。

文本消息（4 种）——经典三段式 TEXT_MESSAGE_START → TEXT_MESSAGE_CONTENT（带 delta）→ TEXT_MESSAGE_END，外加一个 TEXT_MESSAGE_CHUNK 快捷形式：省掉配对开销，客户端自己展开。消息靠 messageId 关联。

工具调用（5 种）——TOOL_CALL_START（带 toolCallId 和 toolCallName）→ TOOL_CALL_ARGS（参数 JSON 增量下发，支持流式渲染参数）→ TOOL_CALL_END，加上 TOOL_CALL_RESULT 和 TOOL_CALL_CHUNK。

共享状态（3 种）——这是 AG-UI 最有辨识度的部分。STATE_SNAPSHOT 全量下发一份 typed state，之后 STATE_DELTA 用 RFC 6902 JSON Patch 增量同步。这意味着前端不只是"看"agent 生成文本，而是和 agent 共享一份可编辑的应用状态——agent 改了表单、改了画布、改了文档大纲，前端实时跟着变。CopilotKit 的生成式 UI 就建立在这上面。

活动消息（2 种）——ACTIVITY_SNAPSHOT/ACTIVITY_DELTA，聊天消息之间的结构化进度材料，为 generative UI 准备的通道。

推理（7 种）——REASONING_* 一族把思维链流式透出（REASONING_MESSAGE_CONTENT 的 delta），甚至有 REASONING_ENCRYPTED_VALUE 用于加密透传私有推理。另有 5 个旧的 THINKING_* 事件已废弃、1.0.0 移除。

子代理（3 种）——SUBAGENT_STARTED/FINISHED/ERROR，用 subagentRunId + parentSubagentRunId 构成树。有个字段很说明问题：SUBAGENT_STARTED 带可选的 parentToolCallId，直接支持"agent-as-tool"模式——子代理是父代理调用的一个工具（deep agents 的 task 就是这个模式），事件树和工具调用树是同一棵。

特殊（2 种）——RAW（底层框架事件透传）和 CUSTOM（自定义事件通道）。

能力声明：协议里藏着一份"agent 名片"

读 Python SDK 源码时的一个意外发现：除了事件和输入类型，ag_ui/core/ 下还有一个 capabilities.py（415 行），定义了一整套 AgentCapabilities 能力声明体系，十个分类：

分类	回答的问题	典型字段
`identity`	你是谁	name / type(框架标识) / version / provider / documentation_url
`transport`	怎么连你	streaming / websocket / http_binary / push_notifications / resumable
`tools`	你能调什么	supported / 自带工具清单(完整 JSON Schema) / parallel_calls / client_provided
`output`	你产出什么	structured_output / supported_mime_types
`state`	你的状态怎么管	snapshots / deltas / memory(跨会话记忆) / persistent_state
`multi_agent`	你和谁协作	delegation / handoffs / sub_agents 清单
`reasoning`	你的思考可见吗	supported / streaming / encrypted(零数据保留模式)
`multimodal`	什么模态进、什么出	input: image/audio/video/pdf/file; output: image/audio
`execution`	你的执行边界	code_execution / sandboxed / max_iterations / max_execution_time
`human_in_the_loop`	人在哪介入	approvals / interventions / feedback / interrupts / approve_with_edits

关键语义写在 docstring 里：“所有字段可选，缺省意味着未声明（unknown），不等于不支持”——典型的开放协议渐进声明风格；外加 custom 逃生舱给集成特有能力。这份能力体系和我之前给自己协议设计 discovery 契约（RuntimeDescriptor）时想解决的问题一模一样：让调用方在运行前就知道对端有什么。AG-UI 的答案粒度更细——它同时服务于"agent 市场、发现 UI、调试"三类消费场景，甚至 sub_agents 清单的注释都写着"帮助客户端构建 agent 选择界面"。

输入：全量历史的无状态哲学

事件流往回走，输入往前送。AG-UI 的请求体 RunAgentInput 长这样：

class RunAgentInput(BaseModel):
 thread_id: str # 会话标识
 run_id: str # 本次运行,客户端生成
 parent_run_id: str | None # agent-started-agent 场景的父 run
 state: Any # 起始共享状态
 messages: list[Message] # 全量对话历史,按序
 tools: list[Tool] # 前端工具定义
 context: list[Context] # 注入上下文
 forwarded_props: Any # 透传段,中间层不得改动
 resume: list[ResumeEntry] | None # 中断应答

最有态度的是 messages：全量历史回传，按序，无旁路通道。服务器不存对话记忆，每一轮前端把完整历史发过来。这是刻意的——无状态服务器好扩展、好重放、好调试，代价是每轮请求变大、长对话依赖客户端裁剪。

消息定义了七种角色：developer、system、assistant（可带 OpenAI 风格的 tool_calls）、user（支持多模态：text/image/audio/video/document，URL 或 base64 inline）、tool（工具结果）、activity（渲染材料，发送前必须剥离，不作为恢复历史）、reasoning。

人在回路是一个完整闭环：RUN_FINISHED 的 outcome 可以是 {type: "interrupt", interrupts: [...]}——agent 停下来等输入，且源码里有校验：interrupt outcome 至少携带一个 interrupt，空的直接构造失败。每个 interrupt 带 id、reason、可选的 response_schema 和 expires_at；客户端下一轮在 resume 数组里逐条应答（resolved 或 cancelled，可带 payload）——审批、确认、澄清问题，都是这个机制的产品化。能力声明里的 approve_with_edits 说明连"批准前修改参数"都在协议考虑内。

从 SDK 源码里读出的工程细节

我读了 Python SDK（ag-ui-protocol 0.1.22）的几个核心模块，这几处注释值得单独说：

序列化的血泪史。基类 ConfiguredBaseModel 自定义了 serializer：可选字段为 None 时，整个键从线上 JSON 省略，而不是写 null。注释里明说了缘由——Python SDK 曾是唯一把 null 写上线的 producer，为此协议吃了三个兼容补丁（TOOL_CALL_START.parentMessageId、TOOL_CALL_CHUNK.parentMessageId、RUN_FINISHED.outcome）。类型注释里那句"在基类上统一省略，才能保证每一条序列化路径都生效"是一位工程师被 null 坑过之后的防御性姿势。字段 camelCase 上线（alias_generator=to_camel），extra="allow" 放行未知字段——协议演进不锁死旧 producer。

token 计数的跨语言红线。token_usage.py 里有一个细节：所有计数上限被钳在 2⁵³−1——不是 int64 的上限，而是因为"TypeScript 的 protobuf 解码器停在 Number.MAX_SAFE_INTEGER，这才是各语言绑定之间的真实天花板"。而且注释明确写了这个结构会喂给匿名遥测，不允许携带任何内容字段（无 prompt、无补全、无 thread/run/user ID），只有 provider/model 标签和纯数字。跨语言兼容和隐私边界都焊死在类型定义里。

metadata 的克制。每个事件都带可选 metadata，开放键值空间，但保留 "ag-ui" 键给协议自己用——而且是纯约定，不做运行时强制。注释的原话：验证它的 shape 会"contradict that"（与开放性矛盾）。

双编码传输。encoder.py 不只是 SSE——协议定义了二进制编码，媒体类型 application/vnd.ag-ui.event+proto（protobuf over HTTP），TypeScript 侧有独立的 @ag-ui/proto 包维护 .proto 定义。文本 SSE 用于开发调试，二进制用于生产，同一套事件类型两种编码。

运行时管线：一次 run 的完整解剖

前面讲的是协议的"静态"部分（类型和字段）。协议真正的工程含量在客户端 SDK 的运行时管线里——一次 runAgent() 调用背后是一条精心编排的 RxJS 管道。以 TypeScript @ag-ui/client 0.0.59 的 AbstractAgent.runAgent()（src/agent/agent.ts）为例，事件从网络到你的回调要穿过这条流水线：

run()（子类实现,发 HTTP/SSE 请求）
 ↓ pipe 依次串接:
① middleware 链 ← reduceRight 组装成洋葱模型
② transformChunks ← CHUNK 快捷事件展开成三段式
③ verifyEvents ← 事件文法状态机校验
④ takeUntil(detach$) ← 单次运行的中止信号
⑤ apply ← 把事件归约进 messages/state
⑥ processApplyEvents ← 分发到 subscriber 回调
⑦ catchError / finalize ← 错误与收尾

每一层都可以单独讲。这正是"看哪些文件"的答案：读懂这七个环节，你就读懂了 AG-UI 客户端的全部。

① Middleware：洋葱模型的拦截器

中间件机制定义在 src/middleware/middleware.ts。核心接口只有一个方法：

abstract class Middleware {
 abstract run(input: RunAgentInput, next: AbstractAgent): Observable<BaseEvent>;

 // 调下一个 agent,附带 chunk 展开
 protected runNext(input, next) {
 return next.run(input).pipe(transformChunks(false));
 }

 // 调下一个,且把每一步之后的 messages/state 一起带出来
 protected runNextWithState(input, next): Observable<EventWithState> { ... }
}

组装方式是 agent.ts 里的 reduceRight——数组里后注册的中间件先执行，next 指向链上更内层的 agent（最内层是真正 agent 的 run()）。这就是经典的洋葱模型，和 Koa/Express 中间件一个思想。

有意思的是 runNextWithState 的实现：它用一个 ReplaySubject 把事件喂给 defaultApplyEvents（事件归约器），让中间件在每个事件后都能拿到"应用了这个事件之后"的 messages 和 state——中间件因此能基于语义状态做决策，而不只是看原始事件。实现里那句 await new Promise(resolve => setTimeout(resolve, 0)) 是给归约器留一个微任务窗口同步状态，朴素但有效。

官方仓库 middlewares/ 目录下有 6 个可参考的成品：event-throttle（按帧率节流 + 合并 delta）、mcp（把 MCP 工具桥接进事件流）、a2a（A2A 协议互转）、a2ui、mcp-apps，外加一个 middleware-starter 脚手架。

② 三个值得抄的中间件设计

EventThrottleMiddleware（middlewares/event-throttle-middleware/src/index.ts）——把高频 delta 按时间窗（默认 16ms ≈ 60fps）和最小字符数节流并合并，防止前端被打爆。它的三个设计决策都写满了"为什么"：

其一，只对白名单事件做缓冲。BUFFERABLE_EVENT_TYPES 是显式白名单（各种 *_CHUNK、*_CONTENT、STATE_*、ACTIVITY_*），不在表内的事件一律立即透传。注释原话：“这是白名单而非黑名单，这样协议将来新增的事件类型默认走立即透传——对生命周期/边界事件来说，这是更安全的失败模式。“新事件宁可多一次渲染，也不能被错误地延迟。

其二，合并只在同一 subagent lane 内进行。chunk 的合并键是 JSON.stringify([kind, owner, entityId])——用 JSON 编码而不是分隔符拼接，因为 owner/id 是任意字符串，“任何分隔符都可能出现在某个分量里，把两个不同的 (owner, id) 别名到同一个键上”。这个注释值得所有写缓存键的人读一遍。

其三，metadata 反向合并。合并两个 chunk 时，role/name 取第一个（它们只出现在首 chunk），但 metadata 取最后一个并按 key 逐项合并——因为 metadata 是设计成"最后到达"的，携带 usage 和 finish reason。“在这里丢掉它会吞掉一个纯 usage 的尾 chunk。”

FilterToolCallsMiddleware（src/middleware/filter-tool-calls.ts）——按工具名拦截工具调用事件。看起来平平无奇，但注释记了一个真实并发 bug：中间件实例是跨 run 复用的，如果被拦截的 toolCallId 集合放在实例上，“一个卡住的 run 的订阅还开着时，下一个 run 启动会抹掉那些还在过滤这个卡住的 run 的 id，于是它被禁的工具的 TOOL_CALL_ARGS/END/RESULT 就开始漏出来了”。解法是用 defer 给每个订阅一份独立集合，并在 RUN_STARTED 时重置。并发场景下"状态放实例还是放订阅"这个坑，这是教科书级的案例。

四个 BackwardCompatibility 中间件（src/middleware/backward-compatibility-0-0-*.ts）——这是我见过最优雅的协议演进手法。agent 构造时读对端声明的 maxVersion，按版本号自动插到中间件链最前面：

if (compareVersions(this.maxVersion, "0.0.39") <= 0) {
 this.middlewares.unshift(new BackwardCompatibility_0_0_39());
}
if (compareVersions(this.maxVersion, "0.0.57") <= 0) {
 // 0.0.57 之前的 agent 不认识 subagent:剥掉 subagentRunId、丢弃 SUBAGENT_* 事件
 this.middlewares.unshift(new BackwardCompatibility_0_0_57());
}

0.0.45 中间件把废弃的 THINKING_* 事件翻译成新的 REASONING_*，0.0.47 把老的 BinaryInputContent 映射成新的分模态输入类型，0.0.57 给不认识 subagent 的老客户端剥掉归属字段。每个协议破坏性变更都固化为一个可测试、可移除的适配中间件，而不是散落在业务代码里的 if-else。协议处于日更的 draft 阶段还能保持向后兼容，靠的就是这套机制。

③ verifyEvents：1052 行的事件文法状态机

src/verify/verify.ts 是整个客户端最硬核的文件——它把"合法的 AG-UI 事件流"编码成了一个状态机，逐事件校验。维护四组"哪些实体还开着"的集合（文本消息、工具调用、推理、活动），外加每个实体类型的归属映射（哪个 subagent 开的）。

这个文件的注释本身就是一部协议演进史，每条规则背后都是真实 bug：

为什么 owners 按实体类别分桶：一个 message 和一个 tool call 可以都叫 “x” 而不冲突。早期单个桶时，“tool call 的写入会覆盖 message 的 owner，导致后续一个加密值拿了错误的 owner 做校验而被接受”。
为什么 owners 关闭后不清除：REASONING_ENCRYPTED_VALUE(subtype="tool-call") 合法地要在 TOOL_CALL_END 之后到达，“清掉 owner 会让这个不匹配变得无法匹配从而接受一个错误的”。
为什么 step 要按 (owner, name) 嵌套 Map 而不是拼字符串：曾经用分隔符拼接 owner 和 name，结果"没有 owner 的父级会和 subagent id 是空字符串的实体撞键”——而空字符串是合法的 opaque id。注释直言：“有个设计伙伴从真实的 deepagents run 里报回了这个 bug：合法的嵌套 step 被拒，而非法的跨 owner 关闭却被接受。”
为什么 STEP_STARTED 判重按 owner 分：父 agent 和子 agent 常常跑同一个图，两边同时有一个叫 “tools” 的 step 是合法的（父的包着委派，子的是自己的内部工作）——按名字单独判重会把合法嵌套当成错误拒绝。

这些不是设计文档里能写出来的东西，全是生产流量打磨出来的。想理解 AG-UI 的边界条件，verify.ts 比 spec 更有信息量。

④ transformChunks：快捷事件的双向门

src/chunks/transform.ts（564 行）负责 *_CHUNK 快捷事件和 *_START/CONTENT/END 三段式之间的转换。核心概念是 lane（通道）：每个 subagent 一条，“一条 lane 上最多有一路正在组装的流，因为 chunk 的简写只靠’和之前一样’来标识延续”。这里也有个精妙的元数据规则——chunk 的 metadata 会扩散到由它合成的每个事件上，但绝不施加于关闭前一条消息的合成 *_END，“这就是防止某个 chunk 的 metadata 泄漏到它正在关闭的那条消息上的原因”。

⑤ apply 与 subscribers：归约器和观察者

src/apply/default.ts（约 1500 行）是事件归约器——一个巨型 switch(event.type)，把每一种事件映射成 messages/state 的变更（AgentStateMutation）。这是"事件即事实、状态即投影"落地的地方。它对 *_CHUNK 事件直接抛错（TEXT_MESSAGE_CHUNK must be transformed before being applied）——这是管线的纪律：chunk 必须先过 transformChunks 这道门，归约器只认展开后的三段式。

src/agent/subscriber.ts（408 行）则是应用层的观察者接口，钩子分三类：生命周期（onRunInitialized/onRunFailed/onRunFinalized）、按事件类型（onTextMessageContentEvent 连 textMessageBuffer 都给你拼好了、onToolCallArgsEvent 带 toolCallBuffer 和 toolCallName）、变更通知（onMessagesChanged/onStateChanged）。

这里有个订阅者协议的关键设计：订阅者不直接改状态，而是返回一个 AgentStateMutation，由 runSubscribersWithMutation 统一应用。多个订阅者的 mutation 可以 stopPropagation 拦截后续订阅者——订阅者之间也是中间件式的。实现里还有一段性能注释：dev 环境会对输入做 structuredClone + deepFreeze 来抓"原地修改"的 bug，但这个守卫是"每个事件最大的一笔分配”，流式大参数时会把 V8 堆打爆，所以它在生产环境关闭、dev 环境下 payload 过大时也跳过——“常见的不改状态的事件cost 零次克隆”。

怎么读 AG-UI 的源码：一份导航

如果你要接 AG-UI 或者只是想学它的设计，按这个顺序读最省时间：

第一梯队——协议本身（先读，两小时）

文件	读什么
`sdks/python/ag_ui/core/events.py`	全部事件类型（555 行，每个类型的字段和约束都在）
`sdks/python/ag_ui/core/types.py`	`RunAgentInput`、七种消息、多模态、中断类型（416 行）
`sdks/python/ag_ui/core/capabilities.py`	能力声明体系（415 行，看注释里的"为什么这样设计"）
`sdks/python/ag_ui/encoder/encoder.py`	SSE 与二进制编码（很短，看序列化约定）

第二梯队——客户端运行时（TypeScript packages/client/src/，深读）

文件	读什么
`agent/agent.ts`	运行管线七环节 + middleware 链组装 + 生命周期（看 `runAgent`）
`middleware/middleware.ts`	洋葱模型基类 + `runNextWithState` 的状态追踪
`middleware/backward-compatibility-0-0-*.ts`	协议演进如何固化成中间件（四份文件一起看）
`verify/verify.ts`	事件文法状态机（注释里的 bug 案例最值钱）
`apply/default.ts`	事件归约器（看状态怎么从事件投影出来）
`chunks/transform.ts` + `agent/subscriber.ts`	chunk 双向门 + 订阅者协议

第三梯队——生态接线

目录	读什么
`integrations/langgraph/{python,typescript}/`	一个真实框架适配层的全貌（含中断处理、SSE 断线恢复测试）
`middlewares/event-throttle-middleware/`	生产级中间件的最完整示例（含性能和不变量注释）
`apps/dojo/`	官方演示站，交互式体验所有事件类型

一个实用建议：读 TS 客户端时先读注释再读代码——这个仓库的注释密度和坦诚度罕见，“我们当初这么写、后来发现 X 有问题、现在的写法是 Y、原因是 Z"的叙事随处可见。很多边界条件 spec 里没有，但注释里有。

生态：谁在用它

AG-UI 的知名产品就是创造它的 CopilotKit（React 前端 agent 框架，useCopilotAction 的 human-in-the-loop 模式就是协议里前端工具机制的产品化），加上官方 demo 站 Dojo（apps/dojo，仓库内）。

但真正的覆盖面在 integrations/ 目录里，18 个框架适配层的原文清单：LangGraph、LangChain、CrewAI、Microsoft Agent Framework、Google ADK、AWS Strands、Agno、Mastra、Pydantic AI、LlamaIndex、AG2、Vercel AI SDK、watsonx、Langroid、Claude Agent SDK、Claude Managed Agents、A2A、Agent Spec，另有两个 server starter 模板。社区 SDK 覆盖 Dart、Rust、Ruby、C++、Kotlin、Go、Java。客户端不止浏览器——终端、React Native、Slack、Teams 都能当 AG-UI client。

不过要校准一下预期：AG-UI 的"知名"集中在框架生态，不是终端产品。和 MCP 一样，它是管道协议，终端用户永远看不到它——人们用的是接了它的 CopilotKit 应用和 LangGraph agent。

和有状态 Runtime 的张力

最后说一个我实际设计契约时撞上的问题。AG-UI 的无状态模型很优雅，但我的 Runtime 是有状态的：对话记忆按 session_id 存在服务端（SQLite checkpointer），每次 Run 只需要送最新的问题。

两套范式接在一起时的正确姿势是：AG-UI 前端发全量 messages，adapter 只取最后一条 user 消息作为 Runtime 的输入，历史由服务端记忆提供；事件流方向则反过来，把 Runtime 的事件投影成 AG-UI 事件喂给前端。适配层的本质是两种会话范式之间的翻译。

还有几块 AG-UI 有、多数自研契约没有的东西，值得列为后续演进的清单：interrupt/resume 的人在回路（自研契约通常只有"取消”，没有"挂起等输入"）、共享状态的 StateSnapshot/StateDelta、子代理事件树、前端工具的反向执行回路，以及那份克制的能力声明体系。

三层协议凑齐之后的图景其实很清晰：MCP 让 agent 拿到工具，A2A 让 agent 找到同伴，AG-UI 让用户看见过程。你的 agent 用哪套实现无所谓——只要它在这三个边界上说标准语言，就同时获得了被所有前端渲染、被所有 agent 编排、被所有工具增强的资格。

本文基于 ag-ui-protocol/ag-ui main@5f32a64ee999（2026-09-09）、Python SDK ag-ui-protocol 0.1.22、TypeScript SDK @ag-ui/client 0.0.59 写成，源码研读覆盖 sdks/python/ag_ui/core/（events / types / capabilities / token_usage / encoder）与 sdks/typescript/packages/client/src/（agent / middleware / verify / apply / chunks / interrupts）、middlewares/event-throttle-middleware/。协议处于 draft 阶段、日更演进，引用前请核对最新版本。

阿里云百炼联网搜索：三种入口，三种结果，我全都踩了一遍

Mon, 07 Sep 2026 19:40:00 +0800

给 Agent 接搜索的时候，我以为阿里云百炼的联网搜索就是「一个开关」。实测下来发现完全不是：同一个模型，至少有三条完全不同的搜索入口——Chat Completions 的 enable_search 参数、Responses API 的 web_search 工具、以及 MCP 广场里的联网搜索 MCP。三者的触发方式、来源返回、计费方式都不同，混着看文档很容易得出「阿里云搜索不行」的错误结论，而实际上只是走错了入口。

这篇文章按我踩坑的顺序写：先说我怎么在错误的入口上浪费了一轮调试，再写正确入口的实测行为，最后把三条路的差异列成表，给一个选型判断。

一、Chat Completions + enable_search：会「假装成功」的入口

我的第一版代码走的是 OpenAI-compatible Chat Completions，请求里加了 extra_body={"enable_search": True}。请求返回 200，模型照样生成了一段关于 vLLM 的详细回答——看起来一切正常。

直到我想找引用来源才发现：响应里没有任何搜索相关字段。没有 search_results，没有 web_search_info，没有任何元数据。我又加了一堆参数组合（search_options.forced_search、enable_source 等文档里能搜到的字段）反复试，结论都一样：这个私有部署的百炼端点在 Chat Completions 协议下，搜索扩展参数被静默忽略了。

这类问题最麻烦的地方在于它不报错。请求成功、回答流畅，模型甚至会用「根据最新资料」开头——但那全是参数化记忆在演戏。如果你不检查来源字段，很容易把这种回答当成「搜索生效了但质量一般」，然后得出完全错误的结论。

后来在文档里翻到关键一句：Responses API 暂不支持 enable_source 等参数，来源要用专门的方式取——这句话反过来提醒我，这些参数本来就属于不同的协议层。Chat Completions 的搜索行为在不同部署形态下表现不一致，而 Responses API 是明确支持联网搜索的入口。

二、Responses API + web_search：能跑通的正路

换成 Responses API 之后，接法反而更简单了。不需要任何 enable_search 之类的开关，直接在 tools 数组里声明工具：

from openai import OpenAI

client = OpenAI(
 api_key=api_key,
 base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)
response = client.responses.create(
 model="qwen3.7-flash",
 input="今天的 GitHub trending",
 tools=[
 {"type": "web_search"}, # 搜索
 {"type": "web_extractor"}, # 抓取网页正文
 ],
 stream=True,
)

两个工具的分工和我在 Agent 里自己包搜索工具时的经验一致：web_search 负责查，web_extractor 负责读正文。文档建议再配上 code_interpreter，但多数搜索场景用不上。

实测下来有几个值得记录的行为细节。

**来源不在正文里，在 output 数组里。**提取方式：

for item in response.output:
 if item.type == "web_search_call":
 for source in item.action.sources:
 print(source.url)

Responses API 目前不支持 enable_source、enable_citation、citation_format，不会在正文里自动插 [1] 角标。要角标标注得走 DashScope 原生调用——这是三条入口差异最直观的一处：同样的搜索，Responses 给你原始链接列表，DashScope 原生给你排版好的引用。

流式事件是真实可用的。response.web_search_call.searching / completed 标记搜索阶段，response.output_text.delta 是正文增量。但有一个体验坑：SSE 事件存在批量下发——我实测中 in_progress、searching、completed 三个事件几乎同一时刻到达（23.9s），之前模型明显已经在搜了。如果你做前端 UI，别指望靠这些事件展示即时的「搜索中」状态，最好在请求发出时本地先打一行提示。

**耗时差距很大。**同一问题「今天的 GitHub trending」（qwen3.7-flash）：

工具组合	实测耗时
只开 `web_search`	约 14 秒
`web_search + web_extractor`	约 46–67 秒

web_extractor 会触发多轮网页抓取，模型要读正文再综合，时间翻三四倍。概览类问题用 web_search 就够；需要精确总结文档内容时再开 extractor。

**模型的搜索结果也有时效性陷阱。**即便搜索成功，拿它答「今天 GitHub trending」时，返回的项目列表在不同请求间差异很大，星标数明显不可靠。厂商侧搜索解决的是「能拿到网页」，不解决「网页本身可信」——这部分判断仍然要靠你的 prompt 约束。

三、计费：别把它当成模型调用的一部分

这是容易被忽略但必须算清的部分。Responses API 的联网搜索费用分两块：

模型调用费：搜索到的网页内容拼进提示词，输入 token 按模型标准价格计费。
搜索策略费：按调用次数收费。turbo 策略 3 元/千次、max 策略 4 元/千次（2026 年 2 月起正式计费，华北 2 地域）；agent 策略 4 元/千次。

也就是说一次带搜索的调用，实际成本 = 模型 token 费 + 搜索次数费，而搜索会把大量网页内容塞进上下文，token 那头的增量往往比搜索费本身更贵。

MCP 广场的「联网搜索 MCP」是另一套独立服务，计费也独立：所有用户前 2000 次调用免费，之后 29 元/千次。它和 Responses API 的内置搜索互不相通——这是很多人（包括我一开始）搞混的地方。

四、能力矩阵：三条协议到底差在哪

把官方的能力表和我的实测合在一起看，差异就清楚了。核心结论只有一句：DashScope 原生协议支持全部进阶功能，OpenAI 兼容协议（无论 Chat Completions 还是 Responses）都只是阉割版。

功能特性	DashScope	OpenAI 兼容 Chat Completions	OpenAI 兼容 Responses
基础联网搜索	✅	✅	✅
强制联网搜索	✅	✅	❌
搜索量级策略（turbo / max / agent）	✅	✅	❌
垂域搜索	✅	✅	❌
搜索时效性设置	✅	✅	❌
限定搜索来源站点	✅	✅	❌
自然语言干预检索范围	✅	✅	❌
返回搜索来源	✅	❌	❌
角标引用标注	✅	❌	❌
提前返回搜索来源	✅	❌	❌
图文混合输出	✅	✅	❌

这张表解释了我前面踩的所有坑：Chat Completions 能搜但拿不到来源；Responses API 虽然也不支持「来源返回参数」，但通过 output 数组里的 web_search_call.action.sources 可以把链接提取出来；强制搜索、策略设置、时效性、站点限定这些进阶控制，Responses 一律不支持。如果你的场景需要来源验收、时间范围约束或站点限定，DashScope 原生协议是唯一完整解。

五、search_strategy：四个档位，一次讲清

搜索策略是比协议选择更影响结果质量的参数。四个档位：

策略	行为	适用场景
`turbo`（默认）	兼顾速度与效果	日常查询
`max`	调用多源搜索引擎，结果更全	高精度、多源交叉验证
`agent`	多轮调用搜索工具与大模型，多轮检索与内容整合	研究报告；英文场景推荐
`agent_max`	agent 基础上加网页抓取	仅限 qwen3-max 思考模式

几个关键限制值得记下：

agent 和 agent_max 启用时，只支持 enable_source: true，其他联网搜索功能全部不可用——开了多轮检索就牺牲参数控制，这是硬约束。
agent 策略对模型有要求：Qwen3-Max 系列、Qwen3.5/3.6/3.7 系列可用；Qwen3.8、MiniMax-M2.1、Moonshot-Kimi-K2 与角色扮演模型不支持。走 text 端点时必须用流式调用。
不同模型处理时效数据的能力不同：qwen3-max 具备日期推理能力（能识别非交易日并提示无数据），qwen-max 会直接返回搜索到的过期数据。股价等强时效查询选 qwen3-max 或更新版本。

我的实测数据可以直接对应到档位：只开 web_search（近似 turbo）约 14 秒；加 web_extractor（行为上接近 agent_max 的抓取）约 46–67 秒。文档说 agent 策略「响应时间可能更长」不是客气话。

六、联网搜索 MCP：第四条路

MCP 广场的「联网搜索 MCP」和上面三条协议层能力完全独立——独立实现、独立计费，也独立于你选哪条 API 协议。所有用户前 2000 次调用免费，之后 29 元/千次。它适合的场景是：多个 Agent / 多个模型要共享同一个搜索出口，不想每条协议各接一遍。

七、我的判断

如果你在百炼上做 Agent 搜索，我的建议很短：

先想清楚要什么再选协议。需要来源验收、时效控制、站点限定 → DashScope 原生；只要基础搜索且想用 OpenAI SDK → Responses API；Chat Completions 只适合「搜到了就行」、不关心来源的场景。
每次搜索调用都验收来源列表。响应里没有来源字段或 web_search_call，就当搜索没发生——不管正文看起来多可信。
搜索策略按场景选。日常 turbo；研究报告或英文场景上 agent（记得流式）；开了 agent 就别指望还能设时效和站点——它只留了 enable_source。
强时效场景先挑模型。qwen3-max 有日期推理，qwen-max 没有；模型选错，策略再对也会拿旧数据当新数据。
成本核算要把 token 增量算进去。搜索策略费是明码标价的小头，搜索内容撑大的上下文才是大头。

至于「同一朵云为什么功能入口这么分裂」——Responses 是新一代 Agent 协议，搜索工具按它的 Item 模型设计；Chat Completions 是兼容层，进阶参数在协议上就带不回来。功能不是不存在，是协议层放不下。但文档把三条协议的差异藏在能力表里、又把 MCP 和内置搜索放在同一个页面，踩坑几乎不可避免。希望这篇实测记录帮你少绕一段路。

总结

百炼的联网搜索不是一个功能，而是四条入口：DashScope 原生、Chat Completions、Responses API、搜索 MCP。能力逐级递减，计费各自独立。
能力表的关键行是「返回搜索来源」和「角标引用标注」：只有 DashScope 支持。OpenAI 兼容协议能搜但拿不到结构化引用（Responses 靠 output 数组曲线救国）。
search_strategy 四档：turbo 快、max 全、agent 多轮整合但锁掉其他参数、agent_max 加抓取且只限 qwen3-max 思考模式。
强时效场景，模型选择和策略同样重要：qwen3-max 有日期推理，qwen-max 没有。
搜索类回答的最低验收标准是来源列表；没有来源，再流畅的回答也不能采信。

OpenAI Responses API与Chat Completions API区别详解

Mon, 07 Sep 2026 18:05:39 +0800

一句话结论

Chat Completions 是传统的“聊天消息补全”接口：调用方自己维护完整的消息历史，模型按输入生成一条 assistant 回复。Responses 是 OpenAI 推出的新一代统一接口：不仅支持生成回复，还内置工具调用、Agent 循环、会话状态管理和结构化输出 Item，为构建 Agent 应用而生。

核心区别总览

维度	Chat Completions	Responses
端点	`POST /v1/chat/completions`	`POST /v1/responses`
输入格式	`messages[]` 数组（客户端维护完整对话历史）	`input`（可以是字符串或消息数组），支持通过 `previous_response_id` 让服务端管理历史
系统提示	放在 `messages` 中的 `role: "system"`	独立的顶层 `instructions` 字段
输出格式	`choices[]`，每项包含 `message`	`output[]`，一组类型化 Item（`message`、`function_call`、`reasoning` 等）
内置工具	仅自定义函数调用	原生支持 `web_search`、`file_search`、`code_interpreter`、`computer_use`、MCP、图像生成等
Agent 循环	单次请求通常只完成一轮工具调用	一次请求内模型可多次调用工具，形成 Agent 循环
状态管理	无状态，客户端手动维护历史	`store: true` 默认开启，服务端保存上下文；也支持加密推理 Item 实现无状态
推理模型	推理 Token 暴露有限	提供更完整的推理摘要与工具联动
流式输出	`delta` 增量块	类型化的 SSE 事件（按 `type` 分支处理）
多候选生成	支持 `n > 1` 返回多个 `choices`	已移除，只返回一个结果
Structured Output	`response_format`	`text.format`

协议结构差异

Chat Completions：消息数组驱动

客户端负责拼装完整对话上下文：

{
 "model": "gpt-4o",
 "messages": [
 { "role": "system", "content": "You are a helpful assistant." },
 { "role": "user", "content": "什么是 Responses API？" }
 ]
}

响应结构围绕 choices 展开：

{
 "choices": [
 {
 "message": {
 "role": "assistant",
 "content": "Responses API 是..."
 }
 }
 ]
}

Responses：类型化 Item 驱动

输入更灵活，最简单可以直接传字符串：

{
 "model": "gpt-4o",
 "input": "什么是 Chat Completions API？"
}

也可以传入结构化消息并指定 instructions：

{
 "model": "gpt-4o",
 "instructions": "You are a helpful assistant.",
 "input": [
 { "role": "user", "content": "帮我比较两个 API 的区别。" }
 ]
}

响应由一组类型化 Item 组成：

{
 "id": "resp_xxx",
 "output": [
 { "type": "reasoning", "summary": "..." },
 { "type": "message", "role": "assistant", "content": [{ "type": "output_text", "text": "..." }] }
 ]
}

工具调用与 Agent 能力

Chat Completions 中的工具调用

Chat Completions 支持 tools 与 tool_calls，但逻辑是“一问一答”模式：模型返回 tool_calls 后，客户端需要执行工具、手动把结果追加回 messages，再发起下一次请求才能让模型继续。

适合场景：

单次函数调用（查数据库、调用一个 API）
简单的多轮对话机器人
兼容现有生态的主流方案（大量第三方框架和推理服务以此为准）

Responses 中的 Agent 循环

Responses API 一次请求内可以完成多轮工具调用。模型可以搜索、读文件、执行代码、再推理，最终在一个响应中返回结果，客户端无需手动维护中间的工具调用状态。

示例：

{
 "model": "gpt-4o",
 "tools": [{ "type": "web_search" }, { "type": "code_interpreter" }],
 "input": "搜索今天的AI新闻，然后写一段 100 字的摘要"
}

适合场景：

需要“搜索 + 总结”或“读文件 + 分析”的多步骤任务
Agent 工作流、自动化研究助手
希望服务端托管上下文与工具执行的应用

会话状态管理

这是两者最实际的工程差异之一。

Chat Completions： 完全无状态。每一轮对话客户端都要把之前所有消息重新发送一遍。对话越长，每次请求的 Token 成本越高，客户端需要自己实现历史裁剪、摘要、缓存等逻辑。

Responses： 默认开启 store: true，服务端会保存对话上下文。后续请求只需传 previous_response_id 指向上一次的响应，服务端自动拼接历史：

{
 "model": "gpt-4o",
 "previous_response_id": "resp_xxx",
 "input": "继续刚才的话题"
}

如果担心数据隐私，可以使用 store: false 并利用加密推理 Item（Encrypted Reasoning Items）实现“无状态但保留推理上下文”的模式，适合 ZDR（Zero Data Retention）场景。

流式事件差异

Chat Completions 流式

返回一系列 delta 块，客户端拼接 delta.content 即可：

data: {"choices":[{"delta":{"content":"你"}}]}
data: {"choices":[{"delta":{"content":"好"}}]}
data: [DONE]

Responses 流式

返回一组按 type 区分的 SSE 事件，每个事件都有明确的生命周期：

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"你"}

event: response.function_call_arguments.delta
data: {"type":"response.function_call_arguments.delta","delta":"..."}

event: response.completed
data: {"type":"response.completed"}

Responses 的事件粒度更细，能区分“文本开始”“工具参数流”“推理摘要”“响应完成”等阶段，适合构建更精确的 UI 反馈。

兼容性与迁移成本

方面	说明
向后兼容	Chat Completions 没有废弃计划，现有代码可继续使用
第三方兼容	大量开源推理服务（vLLM、Ollama、各种国内模型）只实现了 Chat Completions 兼容协议；Responses 兼容目前仅限 OpenAI 官方和少数服务
迁移路径	OpenAI 提供 migration guide，主要改动是把 `messages` 换成 `input`，系统提示提取到 `instructions`，`choices` 改为 `output`
SDK 支持	OpenAI 官方 SDK 两条路径都支持；社区 SDK 大多以 Chat Completions 为主

判断标准： 如果你的应用需要部署到非 OpenAI 的模型服务（本地模型、第三方推理引擎），Chat Completions 是事实标准。如果只在 OpenAI 生态内构建，Responses 功能更完整。

选型建议

场景	推荐
新项目、Agent 应用、需要内置工具	Responses
兼容已有代码 / 只做简单文本补全	Chat Completions
需要服务端托管对话状态、减少 Token 重复发送	Responses
需要部署到第三方或本地推理服务	Chat Completions
需要多候选生成（`n > 1`）	Chat Completions
需要完整推理摘要与工具联动	Responses

总结

Chat Completions 和 Responses API 目前都在维护，没有废弃关系。核心区别不是“新旧替代”，而是定位不同：

Chat Completions 是通用的事实标准协议，兼容性最好，适合任何模型服务和简单对话场景。
Responses 是 OpenAI 为 Agent 时代设计的新一代接口，提供内置工具、Agent 循环、会话状态管理和更丰富的输出结构，适合在 OpenAI 生态内构建复杂智能体应用。

如果你在构建多步骤、需要工具协作的 Agent 应用，Responses API 能显著降低工程复杂度；如果你的核心需求是“调一个模型拿结果”，Chat Completions 依然是最简单、最兼容的选择。

Agent Run 流式协议：事件溯源、SSE 投影与断线恢复

Mon, 07 Sep 2026 10:30:00 +0800

很多 Agent 系统的流式输出，本质上是把模型服务的 chunk 直接转发给浏览器。这样做上线很快，但一旦遇到刷新页面、断线重连、审计和取消，就会立刻发现：前端消费的不是一个可恢复的事件流，而是一条一次性管道。

我现在的做法是把协议拆成三层：Runtime 先产出领域事件，Adapter 统一映射成 canonical 事件并落库，最后由 SSE 端点从事件库里做投影。这篇文章记录这套协议的实际形态，以及它为什么这样设计。

一、三层结构

整条链路可以这样理解：

Runtime / Runner
 └─ AgentEvent 执行器内部事件
 └─ Adapter 映射
 └─ AgentRunEvent canonical 事实，落库并分配 seq
 └─ SSE 端点 committed event 的投影
 └─ 前端

Runner 端口层

AgentEvent 是 Runtime 对外的最小事件模型，目前有 7 种类型：

类型	专用字段	含义
`state_change`	`state`	Runtime 内部状态迁移
`delta`	`content`	模型文本增量
`tool_call`	`tool_name` / `tool_call_id` / `tool_args`	工具调用开始
`tool_result`	`tool_name` / `tool_call_id` / `tool_result`	工具结果摘要
`artifact`	`artifact`	结构化产物元数据
`done`	`answer`	最终答案全文
`error`	`error_code` / `error_message`	失败

这一层有意做薄。不管 Runtime 是 LangGraph、DeepAgents，还是新接的沙箱执行器，只要转换成这 7 类事件，后端后面的所有逻辑都不用重复实现。

Canonical 层

Adapter 把 Runtime 事件映射成 canonical 事件。canonical 层不是照抄 Runtime 词汇，而是补齐运行生命周期：

Canonical 事件	来源	payload 要点
`run.started`	Adapter 生成	`started_at`
`message.started`	Adapter 生成	`message_id`、`role`
`message.delta`	`delta`	`message_id`、`content_index`、`delta`
`tool.call.started`	`tool_call`	`tool_call_id`、`tool_name`、`arguments`
`tool.call.completed`	`tool_result`	`result`、`result_checksum`
`artifact.created`	`artifact`	产物 metadata
`message.completed`	`done`	`content`、`content_checksum`
`run.completed`	`done` 后置	`message_id`
`run.failed`	`error`	`error.code`、`error.message`、`error.retryable`
`run.cancelled`	取消路径	`external_stop_confirmed`

落库后的 envelope 长这样：

{
 "run_id": "run_xxx",
 "seq": 4,
 "event_type": "message.delta",
 "occurred_at": "2026-09-07T10:30:00.123456",
 "recorded_at": "2026-09-07T10:30:00.126000",
 "agent_id": "freight_agent",
 "agent_snapshot_checksum": "...",
 "payload": { "message_id": "message_xxx", "delta": "..." },
 "payload_checksum": "...",
 "schema_version": 1,
 "trace_id": "...",
 "span_id": "..."
}

这里最重要的是 seq。Runtime 事件本身不携带权威序号；Adapter 只提交 candidate，repository 落库时按 last_event_seq + 1 分配。事件一旦提交，顺序就是系统事实。

二、SSE wire format

对外入口是：

GET /api/agent-runs/{run_id}/events

SSE 使用命名帧：

id: 4
event: message.delta
data: {"run_id":"run_xxx","seq":4,"event_type":"message.delta",...}

几个关键语义：

重放优先。 客户端可以用 ?after_seq= 查询参数，也可以用标准 SSE 的 Last-Event-ID 请求头；服务端取较大值，然后从事件库里回放。
游标安全。 游标为负，或大于当前 last_event_seq，返回 422，避免客户端拿着错误游标等一个永远不会来的事件。
实时推送。 端点每 250ms 从 committed repository 拉取新事件；发现序号 gap 就断流，不静默跳过。
keep-alive。 空闲 15 秒发送 SSE 注释帧 : keep-alive。
自然终止。 Run 进入终态且事件全部送完，连接主动关闭。

一次成功 Run 的典型序列：

id: 1 event: run.started
id: 2 event: message.started
id: 3 event: message.delta
id: 4 event: tool.call.started
id: 5 event: tool.call.completed
id: 6 event: message.delta
id: 7 event: artifact.created
id: 8 event: message.completed
id: 9 event: run.completed

失败或取消时，终态分别是 run.failed 或 run.cancelled。Adapter 用一个终态闸保证三者最多出现一个。

三、为什么先落库，再投影

这是整套协议的核心取舍。

断线恢复变成查询问题

客户端刷新页面后，不需要 Runtime 重跑一遍，也不需要服务端缓存整个连接状态。只要带上 Last-Event-ID: 5，服务端就查询 seq > 5 的事件继续发。断线恢复从连接层问题退化成数据库查询问题。

Runtime 崩溃不丢执行事实

事件写入 committed store 之后，Runtime 进程是否还活着，不影响前端重放历史。审计、排障和 UI 恢复消费的是同一份数据。

多 Runtime 共享同一套前端协议

不同执行器的事件风格可能差异很大。Adapter 负责把差异吸收在入口处，前端只认识 canonical 词汇。新增 Runtime 时，可以避免出现“沙箱一套流、业务 Agent 一套流”的分裂。

工具调用能稳定配对

tool_call_id 优先使用底层模型下发的 id。如果 Runtime 丢了开始事件，Adapter 会补发一个 tool.call.started，让 UI 仍然成对渲染。这个“配对自愈”很小心地只影响展示完整性，不把 Run 打成失败。

四、当前边界和改进方向

这套协议也有几个明显的边界。

SSE 出口是客户端胖投影。 目前 data 帧直接序列化完整 envelope，agent_snapshot_checksum、provenance、payload_checksum 等审计字段也被发给前端。短期省事，长期更适合收敛成只包含 seq、event_type、occurred_at、payload 的客户端投影。

实时性靠 250ms 轮询。 对文本流足够，但并发观看的连接多了，数据库查询会线性放大。合理演进是加一个进程内或跨实例 pub/sub，只负责“唤醒”轮询，不负责权威事件投递；事件仍然以数据库为准。

内容模型只有文本增量。 message.delta 目前只有 content_index 和文本，没有结构化 content block。未来要支持图片、图表卡片或分块富文本，应增量引入 block 类型，而不是扩出新的顶层事件。

state_change 是死词汇。 Runtime 端口定义了它，但 canonical Adapter 不会映射。后续应该删除或明确语义，避免接入方误以为它会被消费。

协议演进规则需要写死。 客户端对未知事件类型必须忽略，而不是报错。schema_version 目前存在，但配套演进策略还要补文档。

总结

这套协议不是行业标准，传输层用的也不是什么新东西，但它把几件事做对了：事件先成为带序号的事实，SSE 只是投影；Runtime 词汇保持最小，canonical 词汇保持稳定；断线恢复用标准 SSE 游标；工具调用、产物、失败、取消全部事件化。

如果要从这套设计里抽象一条通用经验，那就是：Agent 的远程流式接口不应该让客户端订阅“模型的输出过程”，而应该让客户端订阅“系统已经发生并且可恢复的执行事实”。管道可以丢，事实不应该丢。

给 Agent 接入 Web Search：四种做法，和一条我试过之后放弃的路

Mon, 07 Sep 2026 10:00:00 +0800

Agent 的知识止于训练数据。一旦问题涉及「最近」——新发布的版本、上周的新闻、当前的价格——就需要 web search。这件事看起来简单，做起来第一道坎是选型：给 Agent 接入搜索的方式五花八门，方案之间的差别比看起来大。

把主流做法按「搜索能力由谁提供」归类，其实只有五种：模型厂商内置的搜索工具、搜索 API 包成 function tool、MCP server、CLI+Skill，以及自托管元搜索引擎（SearXNG）。

我的判断：前四种都走得通，选哪种主要取决于你的模型入口（官方 API 还是自建端点）和工程形态（代码内工具、协议层还是命令行）；第五种 SearXNG 听起来是「免费、自主、无配额」的最优解，我搭过一套给 Agent 用，结论是不推荐——聚合并没有解决上游不稳定的问题，反而把不稳定的方差叠加进了每次搜索。下面逐条展开。

一、先想清楚：搜索在谁的进程里执行

五种方式的名义差别是「用什么产品」，本质差别是搜索这个动作发生在哪里：

方式	搜索在哪执行	你要维护什么	对模型入口的要求
厂商内置搜索工具	模型厂商侧	几乎为零	绑定官方 API
搜索 API + function tool	你的进程	一个 tool 和一个 API key	任何支持 function calling 的模型
MCP server	你的进程（协议层）	server 配置与进程	任何支持 MCP 的框架
CLI + Skill	Agent 的 shell 里	脚本与 SKILL.md	有 execute/shell 工具的 Agent
自托管 SearXNG	你自己的服务器	一整套搜索引擎运维	包成 tool 后同方式二

这个视角直接决定第一道筛选：如果你的模型跑在自建 vLLM 或其他 OpenAI 兼容端点上，第一种方式直接出局——厂商内置工具只在官方端点生效，vLLM 不提供搜索后端。这也是很多人（包括我）从官方 API 切到自建端点后，被迫重新做选型的原因。

另一个前置认知：搜索工具几乎必须配一个抓取（fetch）工具。搜索返回的是链接和摘要，Agent 要真正引用就得读全文。下面每种方式的讨论里，搜索和抓取都是成对出现的。

二、方式一：模型厂商内置的搜索工具

OpenAI Responses API 的 web_search、Claude API 的 web_search 工具、Gemini 的 google_search grounding 都属于这一类：搜索在厂商侧执行，返回结果自带引用，客户端零实现。

以 Claude 为例，全部接入代码就是声明一个工具：

from anthropic import Anthropic

client = Anthropic()
response = client.messages.create(
 model="claude-opus-4-8",
 max_tokens=4096,
 # Opus 4.8/4.7/4.6 与 Sonnet 4.6 用 web_search_20260209，
 # 更早的模型用基础版 web_search_20250305
 tools=[{"type": "web_search_20260209", "name": "web_search"}],
 messages=[
 {"role": "user", "content": "vLLM 最新版本支持哪些 OpenAI 兼容接口？"}
 ],
)

阿里云百炼也是这个形态，但接口协议有个容易踩的坑：联网搜索要走 OpenAI-compatible Responses API，而不是 Chat Completions。在 Chat Completions 里传 enable_search 这类参数，请求不会报错，但厂商侧搜索可能根本没触发——我就先在这里卡了一次：模型照样回答，正文看起来很专业，响应里却没有任何搜索来源。正确的接法是 tools 声明：

client = OpenAI(api_key=key, base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1")
response = client.responses.create(
 model="qwen3.7-flash",
 input="今天的 GitHub trending",
 tools=[
 {"type": "web_search"}, # 搜索
 {"type": "web_extractor"}, # 抓取正文，效果更完整但更慢
 ],
 stream=True,
)

来源也不混在正文里，而在 response.output 里 type == "web_search_call" 的元素中，action.sources 就是链接列表。流式事件同样能拿到：response.web_search_call.searching / completed 表示搜索阶段，response.output_text.delta 才是正文增量。

两个实测数字（同一问题「今天的 GitHub trending」，qwen3.7-flash）：只开 web_search 约 14 秒；web_search + web_extractor 约 46–67 秒。web_extractor 的定位就是搜索工具里的 fetch——它让模型读正文，代价是会触发多轮抓取。还有一个体验细节：阿里云的 SSE 事件有批量下发的情况，in_progress / searching 可能到搜索快结束时才一起到达，客户端如果要展示「正在搜索」，最好在请求发出时先本地打印一行。

OpenAI 和 Gemini 形态类似：tools 里声明一个类型，其余交给平台。没有客户端实现、没有 key 管理、引用自动带回，模型对这类原生工具的使用意愿也最强——不需要你教它什么时候搜。要注意的是这类参数是厂商扩展：换厂商就得换参数名和协议，自建 vLLM 不认识它们。

代价有三个：

绑定官方 API。换模型入口这条路就断了，前面说过。
按次计费。两大厂商目前都是 $10/千次搜索的量级（以官网为准），量大的场景要算清这笔钱和 token 账的关系。
可控性有限。allowed_domains/blocked_domains 这类过滤参数有，但缓存、代理、结果后处理这些深度定制没有。

适合的场景很明确：用官方 API、想零维护快速上线、搜索量不大。这是「能用」的天花板最低、起步最快的一条路。

三、方式二：搜索 API 包成 function tool（通用性最好）

找一个搜索 API，用 Agent 框架的工具机制包一层。这是模型无关的默认解，也是自建端点场景的主路。先选后端：

后端	定位	免费额度	备注
Tavily	专为 Agent 设计，直接返回清洗后的正文摘录	有月度免费额度	LangChain 有现成集成 `langchain-tavily`
Exa	语义/神经搜索	有	适合「找相似资料」而非关键词匹配
Jina（s.jina.ai）	搜索 + grounding	有	与 r.jina.ai 抓取配套
Serper / SerpAPI	Google 结果页的结构化代理	注册赠送	返回 SERP 结构，正文要自己抓
Brave Search API	传统搜索 API	有月度免费额度
博查（Bocha）、智谱 web-search-pro	国内可直连	少量	不想给 Agent 配代理出口时用
DuckDuckGo（`ddgs` 包）	免费无 key	无限（被限流）	质量与稳定性一般，适合原型验证

两个选型提醒：Bing Search API 已于 2025 年 8 月退役，按旧教程选型会踩空；各家额度与价格随时调整，动手前以官网为准。

接入的最短路径是现成集成：

# uv pip install langchain-tavily
from langchain_tavily import TavilySearch

search = TavilySearch(max_results=5)
agent = create_deep_agent(model=model, tools=[search], system_prompt=...)

要控制输出格式或随时换后端，就自己包一层。以 LangChain 为例：

from langchain_core.tools import tool
from tavily import TavilyClient

client = TavilyClient() # 读 TAVILY_API_KEY 环境变量
from datetime import datetime
TODAY = datetime.now().astimezone()

@tool
def web_search(query: str) -> str:
 """搜索互联网，返回最相关的网页标题、链接与内容摘录。
当问题涉及训练数据之后的信息（新版本、新闻、当前价格）时调用。"""
 result = client.search(
 query=f"{query} (current date: {TODAY:%Y-%m-%d})",
 max_results=5,
 time_range="week",
 )
 return "\n\n".join(
 f"[{r['title']}]({r['url']})\n{r['content']}"
 f"\npublished: {r.get('published_date') or 'unknown'}"
 for r in result["results"]
 )

注意工具的 docstring 不是注释，是模型判断「何时调用」的依据——触发条件必须写进描述里，这一点后面还会反复出现。

配套的 fetch 工具，最省事的版本是走 r.jina.ai 把网页转成 Markdown：

import httpx
from langchain_core.tools import tool

@tool
def fetch_url(url: str) -> str:
 """抓取网页并返回正文。拿到 web_search 的结果链接后，引用前先读全文。"""
 resp = httpx.get(f"https://r.jina.ai/{url}", timeout=30)
 return resp.text[:20000] # 截断保护，防止单页吃满 context

（需要更强的抓取能力再上 Firecrawl。）

三条工程经验：

**搜索和抓取分成两个工具。**合并成一个「搜了顺便读」的工具，模型的调用意愿和结果质量都会下降，排查问题也更难。
**时效性是检索约束，不是模型自觉。**我踩过一个很典型的坑：用 Tavily 搜「今天的 GitHub trending」，Tavily 返回的混合了旧博客、旧榜单和缓存页，模型把结果里的「2025」当成了当前年份，最后一本正经地回答「今天是 2025 年」。修法是把时间边界从模型手里拿走：system prompt 注入本机当前日期，搜索查询附带 current date，检索强制 time_range="week"，结果逐条带 published 字段。不要把 time_range 作为可选参数交给模型决定——它连今天几号都不确定。
**弱模型要强指令。**qwen 级别的开源模型对「何时该搜」并不敏感，光给工具不够，还要在 system prompt 里写明「问题涉及训练截止后的信息时，必须先调用 web_search，再回答」这类硬规则。
**网络环境要提前想好。**国内网络下 Tavily 等域名走代理即可；要求直连就选博查或智谱。

四、方式三：MCP server

搜索能力不写在 Agent 代码里，而是挂在 MCP server 上，Agent 通过标准协议发现并调用。现成的 server 很多：tavily-mcp、Brave 的官方 MCP、官方参考实现里的 fetch server，以及若干 SearXNG 的 MCP 封装。

LangChain 生态用 langchain-mcp-adapters 接入：

# uv pip install langchain-mcp-adapters
from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient(
 {
 "tavily": {
 "transport": "stdio",
 "command": "npx",
 "args": ["-y", "tavily-mcp"],
 "env": {"TAVILY_API_KEY": "..."},
 },
 "fetch": {
 "transport": "stdio",
 "command": "uvx",
 "args": ["mcp-server-fetch"],
 },
 }
)
tools = await client.get_tools()
# tools 是标准 LangChain 工具，直接进 create_deep_agent / LangGraph

什么时候它比方式二好：

换后端不改代码。从 Tavily 换到 Brave，改一段 server 配置就行，Agent 侧零改动。
多 Agent 共享工具栈。CLI Agent、IDE 插件、Web 服务共用同一份 MCP 配置，工具升级一处生效。
生态即插即用。搜索之外，抓取、爬虫、浏览器自动化都有现成 server，不写胶水代码。

代价是多一层进程管理和协议开销，调试链路变长——工具不工作时，得先分清是 server 挂了、配置错了还是适配层的问题。另外 MCP 不是唯一答案：2026 年的 Agent 工具生态里，MCP 和 CLI+Skill 是并列的两条路线，而不是替代关系，这正好引出下一种方式。

五、方式四：CLI + Skill

不给 Agent 专门的搜索工具，而是给它 shell 执行能力加一个搜索 CLI，再用 SKILL.md 教它什么时候用、怎么解析输出。飞书给 Agent 生态提供的 lark-cli 就是这条路线的实例——CLI 工具 + Skill 文档，不经过 MCP。

形态上，search.py 就是方式二里那个 API 调用，只是入口从 function tool 变成命令行：

skills/web-search/SKILL.md
---
name: web-search
description: 需要训练数据之后的最新信息时，用 CLI 搜索并阅读网页
---
# 网络搜索

需要最新信息时：
1. 执行 `python search.py "查询词"`，获取结果列表（JSON）
2. 挑选最相关的 2~3 个链接，执行 `python fetch.py <url>` 阅读正文
3. 回答时附上来源链接

现成的搜索 CLI（比如 ddgr）也可以用，但输出解析比结构化的 tool result 脆，自己包一层脚本输出 JSON 更稳。

这条路线的取舍：

优点是透明和复用。每一步都能手工复现，调试时直接跑同一条命令；已有 CLI 工具栈零成本接入；不挑 Agent 框架，版本管理走 git。
缺点是解析脆、权限面大。给了 shell 就是给了世界，生产环境必须配沙箱；整个流程依赖模型认真读 SKILL.md，弱模型更容易跳过文档直接编。

适合已经有 execute/shell 工具且沙箱化的 Agent 运行时（deepagents 类框架都是这个形态），以及团队偏好可审计的命令行工作流的情况。

六、方式五：自托管 SearXNG——我试过，放弃

SearXNG 是开源的元搜索引擎：自己不索引网页，把查询转发给 Google、Bing、DuckDuckGo 等上游引擎再聚合结果，自带 JSON API，无 key 无配额。

它的卖点写在项目首页上：免费、隐私可控、不依赖单一搜索巨头。「聚合多个上游，一个挂了还有别的」——这句话对 Agent 场景特别有说服力，我当时也是这么被说服的。搭完给 Agent 用了一段时间之后，我的结论是：这套卖点里的容错是「结果集层面」的，而 Agent 需要的是「结果质量层面」的稳定，聚合解决不了后者。

展开说三点。

**第一，聚合没有解决上游不稳定，反而放大了它。**元搜索的容错逻辑是：某个上游挂了，其他上游还能出结果，所以「总有东西返回」。但 Agent 对搜索的要求不是「多少有点结果」，而是每次都拿到质量稳定的相关结果——搜索结果的抖动会直接传导成 Agent 行为的抖动，而且极难归因：答案变差了，你分不清是模型的问题还是搜索的问题。实际表现就是这种抖动：上游今天 CAPTCHA、明天限流，结果时好时坏，且坏的时机无法预期。

**第二，自托管处在上游风控最不利的位置。**SearXNG 的出口是你的服务器：数据中心 IP、没有浏览器指纹、没有登录态。Google 和 Bing 对这类无头流量的限流和 CAPTCHA 是最狠的，而 Tavily、Brave 这类搜索 API 收的钱，本质上就是「由服务商维护合规的抓取出口」的成本。你省下的是 API 费，付出的是和一个风控体系长期对抗。

**第三，运维对象从「一个 API key」变成「一套搜索引擎」。**引擎启停配置、上游可用性监控、CAPTCHA 处理、结果字段映射，国内部署还要给上游引擎配代理出口。这些全是隐性成本，而且没有 SLA——坏了就是你自己修。

一句话总结：它解决的问题（隐私、成本）在 Agent 搜索场景里不是主要矛盾，它引入的问题（不稳定性）恰恰是 Agent 最不能接受的。

边界也说清楚：如果是强隐私合规、内网部署的硬约束，并且有专人维护，SearXNG 值得重新评估——它在那个场景里解决的问题才是真问题。但「给 Agent 加个搜索」这个需求，别从这里开始。

七、怎么选

决策表：

你的情况	推荐起点
用官方 API，要最快上线	方式一
自建/兼容端点（vLLM 等），要模型无关	方式二（Tavily 起步）
多 Agent 共享工具栈，要解耦	方式三
已有沙箱化的 execute 工具和 CLI 栈	方式四
想省钱/隐私，考虑自托管 SearXNG	先算隐性运维成本，默认不推荐

三个与具体方式无关的工程结论：

搜索和抓取永远是两个工具，一个查链接，一个读全文。
触发条件写进工具描述和 system prompt，弱模型尤其需要硬规则，否则工具躺在那里没人调。
搜索结果对 context 的消耗很可观：一次搜索五条结果就是一到两千 token，深度调研任务给独立的 researcher 子 Agent，让它搜完、读完、综合完再带回结论，别让原始搜索结果塞满主循环。
**永远区分「厂商侧搜索生效了没有」。**请求不报错不代表搜索被触发：响应里没有 web_search_call / 来源字段，模型就是在拿参数化记忆演戏。把来源列表当作搜索类回答的最低验收标准，没有来源就不要采信。

总结

五种方式按「搜索在谁的进程里执行」分层，前四种都能落地，选型看模型入口和工程形态。
自建 OpenAI 兼容端点是分水岭：厂商内置工具直接排除，搜索 API 包 function tool 成为默认解。
SearXNG 的聚合容错是结果集层面的，不解决 Agent 需要的结果质量稳定性，且自托管在上游风控里处于最不利的位置——实测后放弃，不推荐。
无论选哪种：search 和 fetch 成对出现，触发条件写进描述，重调研用子 Agent 隔离。

Agent 内容输出规范：本地给路径，远程给协议

Thu, 03 Sep 2026 10:00:00 +0800

把 Agent 从"本地脚本"变成"线上服务"时,第一个卡住你的往往不是模型,而是输出。

本地运行时,Agent 写完报告把路径 print 出来就行,人类看得懂;一旦换到远程,调用方是另一个程序,它拿到的必须是可以解析的结构化信息——Agent 调用工具了没有?调用了哪个?产物文件怎么下载?这些信息在本地靠肉眼,在远程必须靠协议。

这篇文章回答三个问题:Agent 到底输出什么、工具调用在消息协议里长什么样、远程接口该用什么方式把这些输出送出去。

一、一次运行的三类输出

一个 Agent 跑完一轮,输出永远是三类东西的组合:

① 自然语言流: 给用户看的解释、报告正文、流式增量文本
② 工具调用事件: 调用了哪个工具、参数是什么、结果是什么
③ 产物 (Artifact): 生成的文件——报告、音频、图片、数据库记录

本地和远程的差异,本质上是对这三类输出的投递方式不同:

输出	本地	远程
自然语言	`print` / 终端流式 / Streamlit	SSE 事件里的文本增量块
工具调用	肉眼观察日志	结构化事件(工具名、参数、结果)
产物	文件路径,直接可访问	独立下载端点 + 访问 URL

其中第②类最难标准化,它夹在"模型输出"和"程序输出"之间,是 Agent 独有的形态。先从它说起。

二、消息协议：工具调用在"线"上长什么样

主流 Agent 框架(OpenAI Agents SDK、LangChain、各种自研循环)底层都遵循 OpenAI 兼容的聊天消息格式。工具调用不是一段文字,而是一条结构化消息:

{
 "role": "assistant",
 "content": "我来搜索一下这个问题的答案。",
 "tool_calls": [
 {
 "id": "call_abc123",
 "type": "function",
 "function": {
 "name": "web_search",
 "arguments": "{\"query\": \"AG-UI protocol\", \"limit\": 5}"
 }
 }
 ]
}

模型说"我要调用 web_search",程序执行后,把结果以 tool 角色的消息回灌给模型:

{
 "role": "tool",
 "tool_call_id": "call_abc123",
 "content": "搜到 3 条结果：...（或被截断的文本）"
}

协议里两个必须知道的细节:

arguments 是 JSON 字符串,不是对象——这是协议约定,传输时不会被二次转义/改键序,接收方拿到后自行 json.loads。
tool 消息必须带 tool_call_id 回指——否则模型不知道自己拿到的是哪次调用的结果。

Anthropic 的 content-blocks 格式是另一套等价表达:tool_use / tool_result 作为内容块混合在 content 数组里,概念一致。

这一层是协议事实,不依赖某个框架。无论你手写循环、用 SDK、还是用 MCP 桥接工具,最终在"线"上走的都是这个形状。

三、两类 Agent 框架事件流（仓库实证）

上面是"一次调用"的静态格式;实际编程里,你可能直接在事件流里消费这些消息。有两种主流的流式事件体系,拿真实代码对比:

1. OpenAI Agents SDK 的事件类型 —— 在 awesome-llm-apps 的流式教程 openai_sdk_crash_course/4_running_agents/4_4_streaming_events/agent.py 中,事件按类型分发:

# OpenAI Agents SDK (agents 0.1.x) 流式事件
async for event in Runner.run_streamed(agent, "解释机器学习原理"):
 if hasattr(event, "type"):
 if event.type == "response_start":
 print("[EVENT] Response started")
 elif event.type == "tool_call_start": # ← 工具调用开始
 print("[EVENT] Tool call started")
 elif event.type == "tool_call_complete": # ← 工具调用完成
 print("[EVENT] Tool call completed")
 elif event.type == "response_complete":
 print("[EVENT] Response completed")

事件名是 response_start / tool_call_start / tool_call_complete / response_complete,SDK 在内部维护运行状态,把模型输出和工具执行切成事件抛给你。

2. Anthropic Messages API 的 content-block 流 —— 事件按内容块细分:

message_start → content_block_start → text_delta × N
→ content_block_stop → content_block_start(tool_use) → tool_use(...)
→ message_stop

模型吐一个字推一个字(text_delta),工具参数一段一段到达;结果是前一个事件驱动下一个:你先把参数收完整,再执行工具,再把结果作为 tool_result 发回。

两者的差别是粒度:OpenAI SDK 把你当"运行期观察者",Anthropic 把你当"消息流水线上的协作者"。用到自己的远程接口上,设计可以取其中任意一套——但命名要统一。

四、远程接口：三种投递方案

方案 A：非流式 REST——返回完整 transcript

POST /chat 传入 messages,Agent 全程跑完后把完整消息数组(含 tool_calls)一次性返回。简单、可缓存,但调用方是黑盒:埋头等十几秒,看不到过程,长任务容易超时。

// POST /chat → 200 OK
{
 "messages": [
 {"role": "assistant", "content": "我来搜索一下。", "tool_calls": [...]},
 {"role": "tool", "tool_call_id": "call_abc123", "content": "..."},
 {"role": "assistant", "content": "结论是……"}
 ]
}

适用:离线批处理、对延迟不敏感、调用方只需要最终答案的场景。

方案 B：SSE 流式——事件驱动的推荐方案

POST /chat 返回 text/event-stream,Agent 每做一个动作 yield 一个类型化事件。这是把 Agent 挂到线上最主流的姿势:死等变成边跑边看,工具调用可渲染、可中断、可审计。

事件类型直接复用上面第三节的命名体系。最小实现:

# 依赖: fastapi>=0.115, uvicorn
from fastapi import FastAPI, StreamingResponse
import json

app = FastAPI()

def agent_pump(user_input: str):
 """Agent 主循环：把模型输出和工具调用压成事件"""
 yield {"type": "message_start", "message": {"role": "assistant", "content": []}}
 yield {"type": "text_delta", "delta": "我先搜索一下。"}
 yield {"type": "tool_use", "name": "web_search", "input": {"query": user_input}}
 result = call_tool("web_search", {"query": user_input}) # 你的工具执行
 yield {"type": "tool_result", "tool_use_id": "call_1", "content": result}
 yield {"type": "text_delta", "delta": "找到 3 条结果，第一条是……"}
 yield {"type": "message_stop"}

@app.post("/chat")
async def chat(payload: dict):
 async def gen():
 for ev in agent_pump(payload["user_input"]):
 yield f"data: {json.dumps(ev, ensure_ascii=False)}\n\n"
 return StreamingResponse(gen(), media_type="text/event-stream")

调用方按 type 分发渲染:text_delta 追加文本,tool_use 显示"🔧 正在搜索……",tool_result 渲染结果。事件命名建议直接抄 Anthropic 体系(text_delta / tool_use / tool_result),生态里随处可以找到对照实现;用 OpenAI SDK 的话就抄 tool_call_start / tool_call_complete,跟你的运行框架一致比追求通用更重要。

方案 C：AG-UI / A2UI 标准协议——对接现成前端的正解

AG-UI 是 CopilotKit 发起的开源标准,Anthropic 也在推(A2UI),把事件命名固定下来并配上一套前端 SDK。事件类型是一份固定清单:agent_message_chunk、tool_call_start、tool_call_detail、tool_call_end、artifact、error、end……

awesome-llm-apps 的 ai-deep-research-agent 就是一个 FastAPI + AG-UI 的完整部署:把 LangGraph agent 注册成标准端点(代码截图):

# awesome-llm-apps/generative_ui_agents/ai-deep-research-agent/agent/main.py
agui_config = copilotkit_customize_config(
 emit_tool_calls=["research", "write_todos", "write_file", "read_file", "edit_file"],
)
add_langgraph_fastapi_endpoint(
 app=app, agent=LangGraphAGUIAgent(name="research_assistant", ...), path="/",
)

它展示了一个 AG-UI 特有的实用点——emit_tool_calls:只暴露你想让前端看到的工具,子 agent 内部的一堆工具噪声可以过滤掉。自己设计事件协议时会漏掉这一点,然后前端被内部工具刷屏。

五、产物文件：Agent 生成的文件怎么投递

文本和工具事件可以进流,二进制文件不适合塞进 SSH 流。产物通道要为两类对象解耦:

Agent 侧:写完文件 → 产出 artifact 记录(artifact_id + 元数据 + 访问 URL)
接口侧: GET /artifacts/{id} → 返回文件内容(支持 Range 分段下载)

事件流里只携带轻量的 artifact 信息,调用方拿到后知识它去 GET。支持 Range 的必要性在于:前端播放音频/视频需要分段请求,断点续传依赖它。

awesome-llm-apps 的 beifong 就是这个模式——/stream-audio/{filename} 端点用 StreamingResponse + Range 头做音频分段播放,Agent 跑完后把音频路径落库,前端拿 URL 再来拉。

# beifong 的 Range 处理（摘要）
header = request.headers.get("Range", "") # "bytes=0-1023"
start, end = parse(header, file_size)
return StreamingResponse(file_streamer(), status_code=206, headers={
 "Content-Range": f"bytes {start}-{end}/{file_size}", ...})

六、决策速查表

场景	方案	关键选型
离线批处理,只要最终答案	A 非流式 REST	返回完整 transcript 数组
线上对话,要过程可见/可中断	B SSE 流式	事件命名抄 Anthropic 或 OpenAI SDK
对接 CopilotKit 等现成前端	C AG-UI 标准	用 `emit_tool_calls` 过滤子 agent 噪声
产物文件(音频/报告/图片)	独立下载端点	artifact_id + URL,配 Range 分段
工具调用"线"格式	消息协议	`tool_calls`(JSON 字符串入参)+ `role: tool` 回灌

七、结论

Agent 输出规范的问题,本质是一个投递分层问题:

协议层(工具调用在消息里的形状)——由 OpenAI/Anthropic 兼容格式定义,不讨论,直接用。
投递层(怎么把三类输出送出去)——本地给路径,远程走事件流;事件命名跟着你的运行框架走,别自创。
标准层(要不要对齐 AG-UI)——自用方案 B 够用;要对接开源前端,直接上 AG-UI,别重新发明轮子。

先把没一行输出删除——把 Agent 的输出当协议设计,而不是当日志设计,是"能上生产"和"能跑 Demo"的分界线。

_{文中仓库实证来自 awesome-llm-apps:流式事件教程 openai_sdk_crash_course/.../4_4_streaming_events/agent.py、AG-UI 部署 generative_ui_agents/ai-deep-research-agent/agent/main.py、产物分段下载 beifong/main.py。}

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，开始有了一点产品的样子。

手，是给了。

笼子，也得跟上。

大时代啊，朋友们。

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

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

让用户选择指定 Skill：从社区实践到生产级 API 设计

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

最近在做 Agent 运行接口时，我碰到了一个看起来很小、真正实现起来却牵动整条运行链的问题。

系统已经加载了多个 Skill，模型也会根据用户问题自动挑选。现在产品希望再往前走一步，让用户在发送消息前直接选择「这次就用 freight-quote」。接口该怎么设计？是不是在请求里加一个 skill_id 就结束了？

我的判断是，skill_id 确实应该加，但它只是入口。一个能上线的显式 Skill 选择方案，还必须同时解决可见范围、授权、强制激活、版本快照、幂等和审计。否则界面看起来是用户选中了 Skill，Runtime 实际上仍可能没用它。

一、先分清三个经常混在一起的概念

讨论接口之前，先把 Skill 的三个状态拆开。

Agent 被允许使用哪些 Skill
 ↓
用户这次请求选择了哪个 Skill
 ↓
Runtime 最终激活了哪些 Skill

它们分别对应能力范围、用户意图和执行事实。

一个 Agent 可以被管理员配置为允许使用 freight-quote 和 document-recognition。用户本次只选择 freight-quote，Runtime 就应当加载它，并把最终激活结果记录下来。用户不能因为知道另一个 Skill 的名字，就越过 Agent 配置直接调用。

如果不做这层区分，后面很容易出现两类问题。

一类是权限问题。前端隐藏了 Skill，但用户手工构造请求仍能调用；另一类是事实问题。用户选择了 Skill，后端只是往 Prompt 里加了一句「请使用 freight-quote」，模型最后没有读取对应的 SKILL.md，系统却把这次执行展示成已使用。

所以，显式选择不只是一个 UI 功能，它是新的运行契约。

二、Agent Skills 规范解决了什么，又没解决什么

Agent Skills 开放规范定义的是 Skill 包格式。一个 Skill 至少包含一个 SKILL.md，front matter 中必须有稳定的 name 和用于发现的 description，还可以包含 scripts/、references/ 和 assets/。

它推荐渐进式披露。Agent 启动时只读取所有 Skill 的名称和描述；决定激活某个 Skill 后，再加载完整指令；执行过程中按需读取脚本和参考资料。这样既能保留大量能力，又不会一开始就把所有内容塞进上下文。

但规范没有定义 HTTP 请求应该长什么样，也没有规定 /skill-name、Picker 或 skill_id。这不是规范遗漏，而是边界划分。Skill 包应该能够跨宿主复用，至于谁能调用、怎么选择、如何审计，需要由 Codex、VS Code、Deep Agents 或业务平台自己决定。

因此，在自己的 API 中增加结构化 skill_id，不会破坏 Agent Skills 兼容性。真正需要避免的是把平台权限、运行状态等私有字段硬塞进通用 SKILL.md，让内容包和业务控制面耦合在一起。

三、开源社区的几种典型做法

1. Deep Agents，让模型根据描述自动选择

LangChain Deep Agents在创建 Agent 时接收 Skill 来源目录。

agent = create_deep_agent(
 model=model,
 skills=["/skills/"],
)

SkillsMiddleware 扫描目录，将每个 Skill 的 name 和 description 注入系统上下文。模型判断任务匹配后，再通过文件能力读取完整 SKILL.md。

这种模式很适合自动路由，也支持给不同 Agent 或 Subagent 配置不同 Skill 集合。但它没有提供一个通用的 invoke(skill_id=...) 契约。也就是说，Deep Agents 原生解决的是「哪些 Skill 可被发现」，不是「用户指定后如何强制激活」。

2. VS Code，把 Skill 变成可选择的 Slash Command

VS Code 的 Agent Skills同时支持模型自动加载和用户显式调用。用户可以在聊天框输入：

/webapp-testing for the login page

Skill 还可以通过 front matter 控制两个方向的调用权限。

配置	用户可调用	模型可自动调用	适用场景
默认	是	是	通用 Skill
`user-invocable: false`	否	是	只作为后台知识或流程
`disable-model-invocation: true`	是	否	必须由用户主动启动
两者同时设置	否	否	暂停或隐藏

这里最值得借鉴的不是 Slash Command 的外观，而是显式调用后的语义。宿主会直接加载对应 Skill 的完整指令，不会把 /webapp-testing 当成一段普通用户文字，再赌模型能不能正确理解。

3. Jan，把调用方式和能力白名单拆开

Jan 的 Skill Invocation支持 /release 和 /skill:release staging 这类显式命令，同时还提供独立的 Skill 白名单。

[skills]
enabled = ["release", "security-review"]

这体现了一个很重要的工程原则。Skill 是否启用，与这一次由用户还是模型触发，是两个正交维度。一个 Skill 必须先在 Agent 的可用集合里，之后才谈得上显式或自动调用。

4. Codex，允许自动选择，也允许用户点名

OpenAI 在 Codex app 的公开介绍中明确说明，用户可以要求 Codex 使用指定 Skill，也可以让 Codex根据任务自动选择。

社区方案看起来各不相同，但方向其实已经很清楚。产品一般不会在自动和手动之间二选一，而是同时保留两种入口，再由宿主系统负责权限和激活。

四、为什么只往 Prompt 里拼一句话不够

最省事的实现大概是这样。

question = f"请使用 {skill_id} skill。\n{user_question}"

它能在 Demo 里工作，却很难成为可信的运行边界。

模型可能看到了 Skill 名称，但没有读取 SKILL.md；用户输入也可能尝试覆盖前面的要求；Skill 内容更新后，历史 Run 无法证明当时使用的是哪个版本。更麻烦的是，审计日志只能证明系统发送过一句提示，不能证明 Runtime 真正激活过对应流程。

这里要承认一个边界。即使后端完整注入了 Skill 指令，也无法数学意义上保证概率模型百分之百遵守。不过平台至少应该保证三件可验证的事实。

用户选择的 Skill 经过了授权校验。
运行上下文确实加载了这个版本的完整 Skill。
执行记录保存了请求选择和实际激活结果。

把这三件事做好，才算把不确定性限制在模型执行层，而不是让接口和运行时本身也含糊不清。

五、一套适合生产系统的 API 设计

1. 先让前端查询这个 Agent 能用什么

建议提供 Agent 作用域下的 Skill 列表，而不是一个不带权限语境的全局列表。

GET /api/agents/{agent_id}/skills

{
 "items": [
 {
 "id": "freight-quote",
 "name": "运费报价",
 "description": "根据尺寸、重量和运输方式估算运费",
 "user_invocable": true,
 "model_invocable": true
 }
 ]
}

这个接口只返回当前用户可见、当前 Agent 已授权并且运行环境可用的 Skill。文件路径、服务器目录和内部凭据不应该出现在响应里。

2. Run 请求使用结构化选择

创建 Run 时可以引入 skill_selection。

{
 "agent_id": "agent_123",
 "skill_selection": {
 "mode": "required",
 "skill_id": "freight-quote"
 },
 "input": {
 "content": [
 {
 "type": "text",
 "text": "2 个箱子，每个 1×1×1 米，毛重 300kg"
 }
 ]
 }
}

我倾向于保留三种模式。

mode	Runtime 行为	适用场景
`auto`	从 Agent 允许集合中自动匹配	普通对话和兼容现有行为
`required`	强制加载指定 Skill	用户在 Picker 或 Slash Command 中点名
`none`	本次不向模型暴露 Skill	基础问答、隔离测试或安全场景

第一期如果想控制改动范围，也可以只增加可空的 skill_id，未传时等价于 auto。但显式 mode 更容易表达「不使用 Skill」，也为以后支持多个 Skill 留出了边界。

3. Slash Command 只是一种输入方式

前端完全可以提供熟悉的交互。

/freight-quote 帮我计算这票货

但发送前应该把它解析成结构化请求。数据库和 Runtime 不应依赖解析原始文本中的 / 命令，因为移动端 Picker、工作流节点和 API 客户端未必使用同一种文本语法。

六、Runtime 应该如何真正激活指定 Skill

对 auto 模式，可以继续使用 Deep Agents 默认的渐进式发现，让模型在允许集合中选择。

对 required 模式，我更推荐由宿主在 invocation 开始前读取并验证 SKILL.md，把完整指令放入受信任的运行上下文，同时只暴露该 Skill 所需且被授权的资源。这样做会失去一点渐进加载带来的 token 优势，但一次只加载一个指定 Skill，成本通常可控，语义也更明确。

如果系统在启动时编译一个包含全部 Skill 的 Agent 单例，还要再做一步改造。运行时实例应该按有效配置缓存，而不是让所有 Agent 和所有 Run 永远共用同一个 Skill 集合。

runtime_connection_id
+ runtime_source_agent_id
+ skill_bundle_checksum
+ model_configuration_checksum
= compiled agent cache key

这样既不必每次 Run 都重新构建 Agent，也不会让一个只允许使用 freight-quote 的 Agent 意外看到另一个部门的 Skill。

对于存在依赖的 Skill，可以把请求选择和有效集合分开。用户选择一个主 Skill，后端解析出它允许依赖的辅助 Skill，最终形成不可变的 effective bundle。不要允许客户端直接提交任意路径或任意依赖列表。

七、为什么 Skill 快照必须进入 Run

生产系统中的 Run 不只是一次临时函数调用，它往往还承担重放、审计、故障分析和结果归因。

建议在 Run 创建时冻结以下信息。

{
 "skill_selection": {
 "mode": "required",
 "requested_skill_id": "freight-quote",
 "effective_skill_ids": ["freight-quote"]
 },
 "skill_snapshots": [
 {
 "skill_id": "freight-quote",
 "version": "1.2.0",
 "content_checksum": "sha256:...",
 "source": "platform"
 }
 ]
}

这里的 checksum 很关键。Skill 作者明天修改了 SKILL.md，历史记录仍然能够说明昨天的 Run 看到了什么。它还应该进入幂等请求摘要，否则同一个 Idempotency-Key 在不同 Skill 下可能错误地重放同一条 Run。

如果 Skill 自带脚本和参考文件，仅计算 SKILL.md 并不总是够。更稳妥的做法是为整个可执行 Skill 包计算内容清单和 bundle checksum，至少覆盖本次可能读取的受管资源。

八、安全边界不能交给前端

用户选择 Skill 后，后端至少要执行下面这条校验链。

解析 skill_id
 ↓
确认 Skill 存在且版本可用
 ↓
确认当前用户有权运行该 Agent
 ↓
确认 Skill 属于该 Agent 的 allowed_skill_ids
 ↓
确认允许用户显式调用
 ↓
冻结快照并创建 Run
 ↓
Runtime 加载有效 Skill bundle

客户端只能传稳定 ID，不能传 skills_paths、SKILL.md 内容或本机目录。对普通用户，未找到和无权限最好采用防枚举语义，不泄露其他 Agent 安装了什么能力。

另外，Skill 的 allowed-tools 目前在开放规范中仍属于实验字段，不同宿主支持程度不同。生产系统不能只靠 front matter 当权限控制。真正的工具白名单、文件边界、网络访问和高风险操作确认，仍要由 Runtime 和基础设施层强制执行。

九、怎么分阶段落地

这项改造不需要一步做到完整市场和版本仓库，可以分成三个阶段。

阶段一，跑通单 Skill 显式选择

解析现有 SKILL.md 的 name 和 description
提供 Agent 作用域的 Skill 查询接口
Run 请求增加 skill_selection
校验 skill_id，并在 required 模式预加载完整 Skill
把 Skill ID 和内容 checksum 写入 Run 快照及幂等摘要

阶段二，建立 Agent 与 Skill 的授权关系

为 Agent 增加 allowed_skill_ids
管理端支持绑定和解绑
区分 user_invocable 与 model_invocable
Runtime 按有效 Skill bundle 缓存编译结果
事件或 Trace 中记录 Skill 激活事实

阶段三，再考虑版本和依赖治理

Skill 版本发布、启用与回滚
依赖解析和 bundle checksum
组织、部门和用户级可见性
风险分级、签名校验和供应链扫描
对 Skill 选择正确率、失败率和成本做评估

这里容易踩的坑，是一开始就做一个很重的 Skill Marketplace，却还没有证明用户为什么要选、选完后能否稳定执行。先把「选择、授权、激活、记录」这条最短闭环跑通，通常更划算。

十、我的判断

如果系统只是个人助手，用户在 Prompt 中写一句「使用某某 Skill」可能已经够用。它实现快，失败后影响也有限。

但只要系统出现多租户、多个 Business Agent、高风险工具或运行历史，Skill 就不再只是 Prompt 模板。它开始接近一个带权限、版本和执行策略的能力包。此时，显式选择必须成为结构化 API 和不可变运行事实。

我最终会采用这样的组合。

用 Agent Skills 规范维护可移植的内容包
用 Agent 的 allowed_skill_ids 管理能力边界
用 skill_selection 表达本次用户意图
用宿主预加载实现 required 语义
用 Skill snapshot 和 checksum 保证历史可追踪
用 Picker 或 Slash Command 改善交互，但不让文本语法成为后端契约

这套设计比简单增加一个字段多做了一些工作，但这些工作不是过度设计。它们正好对应一个生产 Agent 最难回答的几个问题：谁允许它做、用户要求它做什么、它运行时到底加载了什么，以及事后能不能证明。

总结

用户显式选择 Skill，真正要落地的是一条完整的执行链，而不是一句 Prompt。

Agent Skills 规范负责内容包和渐进加载，不负责业务 API。
社区主流是自动选择与显式选择并存，由宿主负责调用语义。
Agent 允许集合、用户请求选择和 Runtime 实际激活必须分开记录。
required 模式应该由后端加载完整 Skill，不能再交给模型二次决定。
Skill 版本和内容 checksum 应进入 Run 快照与幂等摘要。

界面上的 Skill Picker 很轻，背后真正有价值的，是把一次看似随意的模型选择，变成可以授权、复现和审计的运行事实。

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 都无需跟着重写。

数据库初始化与迁移：从创建那一刻就要钉死的三件事

Thu, 23 Jul 2026 11:21:08 +0800

一句话：版本 + 字符集 + 排序规则，三件事必须在 CREATE 那一刻写死。 之后任何跨环境、迁移、同步都建立在这三件事一致的基础上。

一、三件事在四个数据库里的标准值

数据库	版本	字符集	排序规则	改的代价
MySQL 5.7	`5.7.x` LTS	`utf8mb4`	`utf8mb4_general_ci`	单 ALTER
MySQL 8.0	`8.0.x` / `8.4.x`	`utf8mb4`	`utf8mb4_0900_ai_ci`	单 ALTER
PostgreSQL	`15.x` / `16.x`	`UTF8` (client)	ICU 默认	库级改不了
SQL Server	`2019` / `2022`	见 collation	`SQL_Latin1_General_CP1_CI_AS`	可改，需重建索引

永远显式写。不能依赖"实例默认值"——开发/测试/预发/线上四个环境经常不一样。

二、emoji 演示：`utf8` ≠ `utf8mb4`

INSERT INTO users (name) VALUES ('😀'); -- 字符: 4 字节

字符集	字节数上限	结果
`latin1`	1 字节	❌ 中文都存不了
`utf8`	3 字节 ⚠️	❌ emoji 报错 `ERROR 1366`
`utf8mb4`	4 字节	✅

MySQL 的 utf8 是历史包袱，只支持 3 字节。JDBC / ORM 里写 utf8 的，emoji 入库一律失败。永远写 utf8mb4。

三、四套初始化模板（直接复制）

MySQL 5.7

CREATE DATABASE my_app
 DEFAULT CHARACTER SET utf8mb4
 DEFAULT COLLATE utf8mb4_general_ci;

CREATE TABLE users (
 id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
 name VARCHAR(64) NOT NULL,
 email VARCHAR(128) NOT NULL,
 created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
 PRIMARY KEY (id),
 UNIQUE KEY uk_email (email)
) ENGINE=InnoDB
 DEFAULT CHARSET=utf8mb4
 COLLATE=utf8mb4_general_ci;

MySQL 8.0

CREATE DATABASE my_app
 DEFAULT CHARACTER SET utf8mb4
 DEFAULT COLLATE utf8mb4_0900_ai_ci;

CREATE TABLE users (
 id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
 name VARCHAR(64) NOT NULL,
 email VARCHAR(128) NOT NULL,
 payload JSON DEFAULT NULL,
 created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
 PRIMARY KEY (id),
 UNIQUE KEY uk_email (email),
 -- 8.0 才支持的表达式索引
 KEY idx_payload_user_id ((CAST(payload->>'$.userId' AS CHAR(64))))
) ENGINE=InnoDB
 DEFAULT CHARSET=utf8mb4
 COLLATE=utf8mb4_0900_ai_ci;

PostgreSQL

-- 库级字符集在 CREATE DATABASE 时定型,后续改不动!
CREATE DATABASE my_app
 WITH ENCODING 'UTF8'
 LC_COLLATE = 'en_US.UTF8'
 LC_CTYPE = 'en_US.UTF8'
 TEMPLATE = template0;

CREATE TABLE users (
 id BIGSERIAL PRIMARY KEY,
 name TEXT NOT NULL,
 email TEXT NOT NULL,
 payload JSONB DEFAULT NULL,
 created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
 UNIQUE (email)
);

CREATE INDEX idx_payload_user_id
 ON users ((payload->>'userId'));

PG 的字符集分两层：库级 ENCODING + 连接级 client_encoding。JDBC 必须显式：
jdbc:postgresql://host:5432/my_app?charSet=UTF8

SQL Server

-- 实例默认 collation 不一定是这个,必须显式写
CREATE DATABASE my_app
 COLLATE SQL_Latin1_General_CP1_CI_AS;
GO

CREATE TABLE users (
 id BIGINT IDENTITY(1,1) PRIMARY KEY,
 name VARCHAR(64)
 COLLATE SQL_Latin1_General_CP1_CI_AS NOT NULL,
 email VARCHAR(128)
 COLLATE SQL_Latin1_General_CP1_CI_AS NOT NULL,
 payload NVARCHAR(MAX) DEFAULT NULL,
 created_at DATETIME2(3) NOT NULL DEFAULT SYSUTCDATETIME(),
 UNIQUE (email)
);
GO

四、迁移报错 4 种「症状 → 原因 → 修复」

🔴 症状 1：emoji / 中文入库乱码或报错

-- 报错信息
ERROR 1366 (HY000): Incorrect string value: '\xF0\x9F\x98\x80' for column 'name'

项	内容
原因	表字符集不是 `utf8mb4`
修复	`ALTER TABLE users CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;`
预防	JDBC 连接串 `characterEncoding=utf8`、表级显式 `CHARSET=utf8mb4`

🔴 症状 2：`ORDER BY name` 顺序变了 / `WHERE col='...'` 命中行数变化

项	内容
原因	排序规则从 `general_ci` → `0900_ai_ci`，UCA 9.0 比较更激进
修复	`ORDER BY name COLLATE utf8mb4_bin` 锁定；或应用层排序
预防	业务层不依赖 DB 排序结果做正确性判断

🔴 症状 3：`INSERT` 截断字符串 → 整个应用雪崩

项	内容
原因	8.0 默认 `STRICT_TRANS_TABLES`，截断从 warning 变 error
修复	灰度期间 `SET GLOBAL sql_mode = 'STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION,...';`
预防	上线前用真实流量回放，发现 silent-truncate 全部修掉

🔴 症状 4：本地能连，CI/线上连不上

项	内容
原因	5.7 `mysql_native_password` → 8.0 `caching_sha2_password`
修复	升级 JDBC/ORM 驱动；禁掉 `mysql_native_password`
临时方案	`ALTER USER 'app'@'%' IDENTIFIED WITH mysql_native_password BY 'xxx';`

五、其他数据库的独有坑（速查）

数据库	坑	一句话修复
PG	字符串默认大小写敏感	`LOWER(name) = LOWER(?)` 或用 `citext`
PG	10+ 隐式类型转换收紧	所有比较显式 `CAST`
PG	`BIGSERIAL ≠ AUTO_INCREMENT`	跨库迁移重置序列或改 UUID
SQL Server	collation 在 3 个层级设置	列级 `COLLATE ...` 钉死
SQL Server	`DATETIME` vs `DATETIME2`	迁移时零日期映射为 `NULL`
SQL Server	`OFFSET` 在大表慢	永远用 keyset 分页（`WHERE id > last_id`）

六、迁移前 5 分钟 checklist（直接跑）

MySQL

-- 1. 实例信息
SELECT @@version, @@character_set_server, @@collation_server, @@sql_mode;

-- 2. 找出非 utf8mb4 的表
SELECT table_schema, table_name, table_collation, CCSA.character_set_name
FROM information_schema.tables T
JOIN information_schema.collation_character_set_applicability CCSA
 ON CCSA.collation_name = T.table_collation
WHERE table_schema NOT IN ('mysql','sys','information_schema','performance_schema')
 AND CCSA.character_set_name != 'utf8mb4';

-- 3. 找出表达式索引 (8.0+ 特性)
SELECT * FROM information_schema.statistics
WHERE expression IS NOT NULL
 AND table_schema NOT IN ('mysql','sys','information_schema','performance_schema');

-- 4. 找出 mysql_native_password 账号
SELECT user, host, plugin FROM mysql.user WHERE plugin = 'mysql_native_password';

PostgreSQL

SELECT version();
SELECT datname, datcollate, datctype
FROM pg_database WHERE datistemplate = false;
SELECT * FROM users WHERE length(name) = 0 OR name IS NULL;

SQL Server

SELECT SERVERPROPERTY('Collation') AS server_collation;
SELECT name, collation_name FROM sys.databases;
SELECT * FROM dbo.users WHERE created_at < '1900-01-01';

七、迁移流程（七步走）

1. 备份 (mysqldump --single-transaction --hex-blob)
 ↓
2. 准备目标实例 (兼容 sql_mode)
 ↓
3. 导入备份 (不要用 source,用 mysql ... < backup.sql)
 ↓
4. 跑上面的 checklist SQL
 ↓
5. CONVERT 字符集 + 验证表达式索引兼容
 ↓
6. 灰度切流量 5% → 20% → 100%
 ↓
7. 完全切完后再升级 ORM / 驱动

回滚三件套：

保留 7 天以上源端快照

迁移脚本幂等（跑两遍不报错也不丢数据）

DNS / 负载均衡能秒级切回

八、Agent 系统特别提醒

#	提醒	一句话
1	向量存储	别用原生 PG/MySQL 向量扩展做主索引,规模上来性能不行
2	对话历史	高频追加→单独 `messages` 表+定期归档
3	状态机持久化 (LangGraph checkpoint)	高频 UPDATE 同一行 → `SKIP LOCKED` + 多分片
4	审计 / Trace 表	可能比业务表大 10 倍 → 单独 schema + TTL + 列存

速查表

┌────────────────────────────────────────────┐
│ 创建数据库那一刻要钉死的三件事: │
│ │
│ VERSION → 5.7 / 8.0 / PG15 / 2019 │
│ CHARSET → utf8mb4 (永远,别用 utf8) │
│ COLLATION → utf8mb4_0900_ai_ci (8.0) │
│ │
│ 任何"看起来能跑"的 SQL 上生产前必查: │
│ │
│ EXPLAIN + CHARSET + COLLATION + TIMEOUT │
└────────────────────────────────────────────┘

下一篇：Tool Calling 工程化——从 schema 设计到 Human-in-the-loop 的具体落地。

参考

Agent 工程实战开篇：从 Demo 到生产还有多远

Thu, 23 Jul 2026 10:31:54 +0800

这是 Agent 工程实战系列的第一篇。我会把在生产环境里踩过的坑、验证过的方案，按主题整理成可复用的工程手册。

一句话定义 Agent 工程

Agent 工程 = 把一个在本地能跑 80% 的 LLM 循环，变成一个在真实流量下 99% 可用、可观测、可评估、可控成本的服务。

把这句话拆开，至少有五件事要做：

可控 — 输出可控、行为可控、失败可控
可观测 — 每一步都留下 trace，事后能复盘
可评估 — 不是"看着还不错"，是有数据证明它确实不错
可扩展 — 用户从 10 个到 10 万个，延迟和成本不会爆
可治理 — 安全、合规、可解释、可下线

下面聊聊从 Demo 走到生产最容易翻车的几个点。

1. 别再把 Prompt 当成"代码"

Demo 阶段你可以在 system prompt 里写一段 200 字的话，模型听话；但到了生产：

不同模型的 instruction-following 能力差异巨大
用户输入会污染 prompt 结构（prompt injection）
Prompt 一改，行为就会漂移，且没人能精确描述改了什么

工程化做法：

Prompt 模板独立仓库管理，版本化（每条上线记录到变更日志）
把"工具说明"、“角色设定”、“业务规则”、“用户输入"在拼接时显式分段，而不是塞进同一个 f-string
关键 prompt 用 LLM 评审 / 回归集 守门，而不是靠人肉感觉

2. Tool Calling 不是 `if name == "...":`

很多 Demo 是这样的：

if "天气" in user_input:
 return get_weather(...)

这种"伪 function calling"看起来工作，但生产里会立刻暴露问题：

用户可以构造输入绕过规则
没有 schema 校验，模型幻觉出来的参数会直接打到下游
没有权限隔离，所有工具对所有 prompt 开放

工程化做法：

用真正的 tool/function schema（OpenAI / Anthropic 风格），让模型输出结构化参数
用 Pydantic / Zod 在边界做参数校验
工具分级别：只读工具 / 写工具 / 外部副作用工具，按风险分桶调用
高风险工具强制 Human-in-the-loop 确认

3. Agent Loop 必须有上限

最经典的 bug：

用户问了一个含糊的问题 →
Agent 没拿到足够信息 →
Agent 又去调用工具 →
工具又返回模糊结果 →
Agent 再调工具 →
... → token 烧光 / 循环 100 次 / 超时

工程化做法：

显式设置 max_steps（建议 ≤ 10）
区分"成功终止”、“最大步数终止”、“循环检测终止”
检测到重复 state（同一组工具调用两次以上）→ 主动 break 并 fallback 到"我不知道"
关键决策点强制 reflection / self-critique，但要限制其调用次数

4. 可观测性：先有 Trace，再谈优化

没有 trace 的 Agent 优化就是"蒙眼调参"。生产里至少要有：

Span：每一次 LLM 调用、工具调用、记忆读写的输入 / 输出 / 耗时 / token
Trace ID：贯穿一次完整任务的所有 span
成本字段：每次调用的 input/output token 与单价
失败分类：timeout / 工具异常 / 解析失败 / 内容安全拦截

推荐起步就用 LangSmith、Langfuse、Arize Phoenix 这类平台之一，自建成本不低。

5. 评估不是上线后再想的事

生产里最容易回答不出的问题：“这个版本比上个版本到底好了多少？”

最小可用的评估体系：

离线评测集：50~200 个有标准答案或参考回答的 case，回归门禁
LLM-as-judge：用一个更强的模型给输出打分，但要注意：评分模型本身也会偏
线上指标：任务成功率、人工接管率、单任务成本、p95 延迟
红队 / 注入集：专门挑 prompt injection 与越权场景，定期跑

6. 成本治理：模型路由 + 缓存 + 流式

Agent 系统烧钱的速度比传统服务快得多，因为：

多轮 LLM 调用 × 长上下文 × 复杂工具链
“小问题用大模型"是常态浪费

工程化做法：

模型路由：简单任务走小模型（如分类、提取），复杂任务才走大模型
语义缓存：相似 query 直接返回上次结果，注意要带 cache key 的失效策略
流式输出：长生成场景下，TTFT 比总时长更重要
预算熔断：单任务 / 单用户 / 单租户的 token 上限，超限自动降级

7. 安全：默认假设你的 Prompt 会被攻破

不要把系统提示视为秘密，它一定会被泄露
不要让 LLM 决定要不要执行高风险工具（删库、转账、发邮件），必须硬规则守门
必须对工具返回值做清洗——它也是用户可控输入
必须审计日志：谁、什么时候、通过哪个 agent、调了哪个工具、传了什么参数

这个系列接下来会写什么？

按上面七个主题，每个都会展开成一篇实战文章，配可运行示例：

Prompt 工程化：从 f-string 到模板系统
Tool Calling 工程化：schema、权限、Human-in-the-loop
Agent Loop 设计：状态机视角的 ReAct
可观测性实战：Langfuse / LangSmith 接入
评估体系搭建：离线集 + LLM-judge + 线上指标
成本与性能：模型路由、缓存、流式
安全与合规：Prompt injection 防护与审计

如果你也在做 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/
《智能体编排设计工程师学习指南》(本系列前篇)

openclaw

Tue, 24 Feb 2026 17:41:27 +0800

部署

dokploy

修改env,记得,选择了那个提供商就要写 “提供商/模型名”

OpenClaw 能做什么：2026 年顶级 AI 生产力助手

一、核心能力：它如何彻底改变工作方式

OpenClaw 不是一个简单的聊天机器人，而是一个多智能体协作平台，可以同时协调多个 AI 专家为你工作。

自动化复杂工作流
- 智能任务分解：给它一个复杂项目，它能自动拆解成可执行步骤
- 并行处理：多个 AI Agent 同时处理不同子任务
- 结果整合：自动汇总所有结果，生成完整交付物
记忆与学习能力
- 长期记忆：记住你的工作习惯、偏好、历史问题
- 智能检索：需要时自动调用相关历史信息
- 持续优化：越用越了解你，越用越高效

二、具体能做什么：八大生产力场景

场景 1： 智能编程与代码开发

它能：

编写完整项目代码（全栈开发）
自动代码审查和优化
生成单元测试（覆盖率 85%+）
技术文档自动生成
Bug 智能诊断和修复建议
代码重构和架构优化

实例：你说"帮我开发一个电商网站"，它能：

设计数据库架构

编写后端 API

开发前端界面

配置部署脚本

编写测试用例

生成用户手册

场景 2： 智能分析与报告生成

它能：

自动收集网络信息（新闻、社交媒体、竞品数据）
情感分析和趋势预测
生成专业分析报告（市场分析、竞品分析）
数据可视化图表生成
实时监控和预警

实例：你说"分析一下最近 AI 行业的发展趋势"，它能：

收集最新行业新闻

分析技术发展路径

评估市场机会

生成图文并茂的报告

提供投资建议

场景 3： 会议与沟通效率提升

它能：

会议自动转录和摘要（1 小时会议→5 分钟要点）
提取行动项并分配责任人
自动生成会议纪要
后续跟进提醒
跨语言实时翻译

实例：一次国际团队会议后：

自动生成中英双语纪要

提取 10 个行动项分配给对应人员

同步到 Jira/Trello

设置跟进提醒

场景 4： 文档处理自动化

它能：

合同自动审查（找风险条款）
技术文档自动编写
多格式转换（Word→PDF→Markdown）
内容摘要生成
多语言翻译

实例：一份 50 页技术文档：

5 分钟生成执行摘要

自动检查一致性

生成常见问题解答

翻译成 3 种语言

场景 5： 学习与研究加速

它能：

学术论文自动阅读和摘要
研究趋势分析
知识点脑图生成
个性化学习计划
智能问答导师

实例：研究一个新领域时：

自动阅读 50 篇相关论文

提取核心观点

构建知识图谱

设计学习路线图

场景 6： 项目管理自动化

它能：

项目计划自动生成
任务分解和排期
进度跟踪和预警
风险评估
资源分配优化

实例：启动一个新项目：

自动创建项目计划

分解成 100+ 具体任务

分配时间线

监控风险点

每周自动报告进度

场景 7： 创意与内容创作

它能：

营销文案自动生成
社交媒体内容规划
视频脚本创作
广告创意生成
品牌故事编写

实例：产品发布前：

生成发布会演讲稿

创作 10 篇宣传文章

设计社交媒体活动

编写用户案例研究

生成 FAQ 文档

场景 8： 个人效率助手

它能：

日报/周报自动生成
邮件智能分类和回复
日程智能安排
会议准备材料整理
旅行计划制定

实例：每天工作开始：

自动生成今日重点任务

处理未读邮件（分类 + 草拟回复）

提醒重要会议和准备材料

晚上自动总结日报

三、跨平台协作能力

通讯工具集成
- 飞书/钉钉：直接在群里@它完成任务
- Slack：实时协作和提醒
- 微信/Telegram：移动端随时使用
开发工具集成
- GitHub：自动代码审查、PR 处理
- Jira/Trello：任务自动创建和更新
- Docker/K8s：部署脚本自动生成
办公软件集成
- Google Docs/Office：文档协作
- Notion/Confluence：知识管理
- Calendar：日程管理

四、多 Agent 团队协作模式

专家团队模式
你有专属的专家团队：
- 技术专家：负责技术问题
- 业务专家：负责商业分析
- 设计专家：负责 UI/UX
- 文案专家：负责内容创作
- 项目经理：协调所有工作
流水线模式

复杂任务自动流水线处理：输入 → 分析 → 设计 → 执行 → 测试 → 交付每个环节由专门 Agent 负责
辩论模式
重要决策时：
- 多个 Agent 从不同角度分析
- 进行虚拟"辩论"
- 最终给出最优方案

五、实际应用案例

案例 1： 创业公司 CTO 的一天
早上 9:00：
- OpenClaw 自动生成昨日技术日报
- 列出今日技术风险点
上午：
- 自动审查团队代码提交
- 生成架构优化建议
- 处理技术债务
下午：
- 参与产品讨论，自动记录和总结
- 编写技术方案文档
- 准备技术分享材料
结果：技术管理工作效率提升 300%
案例 2： 市场总监的营销活动
活动前：
- 自动分析目标用户画像
- 生成营销策略方案
- 创作各类宣传素材
活动中：
- 实时监控社交媒体反馈
- 自动调整投放策略
- 生成每日效果报告
活动后：
- 自动生成 ROI 分析报告
- 总结成功经验和教训
- 归档所有素材和文档
结果：营销效果分析时间减少 80%
案例 3： 学术研究者的研究过程
文献调研：
- 自动搜索相关论文
- 提取核心观点和结论
- 构建研究脉络图
实验设计：
- 协助设计实验方案
- 生成实验代码
- 设计数据收集方法
论文写作：
- 自动生成论文大纲
- 协助写作各章节
- 格式检查和优化
结果：研究效率提升 200%

六、独特的竞争优势

真·智能协作
- 不是简单问答，而是真正的团队协作
- 多个 AI Agent 各司其职
- 像有了一整个专业团队
记忆与学习
- 长期记忆你的偏好
- 越用越懂你的需求
- 工作质量持续提升
企业级可靠性
- 多模型备份（一个挂了自动切另一个）
- 任务状态持久化（断电不丢数据）
- 完整审计日志

七、适合谁用？

✅ 非常适合：
- 创业者/企业家：一人顶一个团队
- 开发者/工程师：编码效率翻倍
- 管理者/领导：决策支持 + 团队管理
- 研究人员/学者：研究加速器
- 创作者/营销人：内容生产机器
⚠️ 需要注意：
- 需要一定的技术理解能力
- 关键决策仍需人工审核
- 涉及安全信息需谨慎配置

八、开始使用建议

新手入门（第 1 周）：
1. 从一个具体任务开始
2. 体验智能分解的能力
3. 感受多 Agent 协作的效果
进阶使用（1 个月后）：
1. 配置专属工作流
2. 建立记忆库
3. 集成外部工具
专家级（3 个月后）：
1. 定制专属 Agent 团队
2. 自动化复杂业务流程
3. 建立企业级应用

一句话总结：OpenClaw 就像给你配备了一个 24 小时待命的AI 专家团队，把一个人变成一个高效的组织，让复杂变简单，让耗时变即时。

想先了解哪个场景的具体应用？我可以详细介绍那个场景的实战操作。

nl2sql

Sat, 21 Feb 2026 22:11:24 +0800

参考文献

https://zhuanlan.zhihu.com/p/1940183214875456279?share_code=OrKMQdXbyb9m&utm_psn=2008228722545804102 https://zhuanlan.zhihu.com/p/1939282632232896429?share_code=dBY13Eup1TyS&utm_psn=2008229699600532430 https://zhuanlan.zhihu.com/p/1958855721698436339?share_code=WMUESfzgF9zK&utm_psn=2008230269199591123 https://zhuanlan.zhihu.com/p/1915001536171476928?share_code=f1cneaAWmTOJ&utm_psn=2008230432307693135 https://zhuanlan.zhihu.com/p/706470524?share_code=E5JANjPbKiul&utm_psn=2008230704283136797 https://zhuanlan.zhihu.com/p/1932039631936915022?share_code=N8MZYAjAFPsu&utm_psn=2008230946713929572 https://zhuanlan.zhihu.com/p/693358371?share_code=1oWpl3ZkpqkpI&utm_psn=2008231003643212020

n8n

Tue, 23 Dec 2025 23:36:46 +0800

安装

docker run -itd –name n8n -p 5678:5678 n8nio/n8n

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
规则	人工硬编码	模型自主决策
灵活性	❌ 低	✅ 高
错误处理	需人工编码	模型可自主处理
适用场景	固定流程	不确定任务

参考资料

官方文档

本项目相关文章

学习网站

Learn Prompting - Prompt 工程教程
DeepLearning.AI - Andrew Ng 的 AI 课程
HuggingFace Course - NLP 和 Transformers 课程

社区与资讯

AI agent介绍：基于大模型的人工智能代理

Wed, 07 May 2025 14:34:02 +0800

参考：

知乎

智能代理Agent：AI 智能体

Agent基础知识介绍

背景介绍

AI Agent（人工智能代理）的背景可以从技术发展、理论基础和应用场景三个方面来阐述：

技术发展背景

AI Agent的概念起源于人工智能（AI）和计算机科学领域的进步，尤其是20世纪80年代以来，随着分布式系统、自主计算和智能系统的兴起，AI Agent逐渐成为研究和应用的热点。以下是关键技术发展的几个阶段：
- 早期AI与规则系统：20世纪50-60年代，AI研究主要集中在符号推理和专家系统上，这些系统通过预定义规则模拟智能行为，为后来的Agent奠定了基础。
- 分布式人工智能（DAI）：80年代，分布式计算和多Agent系统（Multi-Agent Systems, MAS）的研究兴起，强调多个自主实体协作解决问题，推动了AI Agent的理论发展。
- 机器学习与深度学习：21世纪以来，机器学习（尤其是深度学习）的突破使得AI Agent能够通过数据驱动的方式学习复杂行为，增强了其感知、决策和适应能力。
- 大语言模型（LLM）：近年来，以GPT、Llama等为代表的大语言模型赋予了AI Agent强大的自然语言处理能力，使其能理解和生成人类语言，广泛应用于对话系统、任务自动化等场景。
理论基础

AI Agent的核心理念是构建能够自主感知环境、推理决策并采取行动的智能实体。其理论基础包括：
- Agent定义：在AI领域，Agent通常被定义为“能够感知环境并通过行动影响环境的实体”。Russell和Norvig的《人工智能：一种现代方法》中将其形式化为感知-推理-行动循环。
- 自主性与交互性：AI Agent具有一定程度的自主性（独立决策能力）和交互性（与环境或其他Agent协作或竞争）。
- 多Agent系统：多Agent系统研究多个Agent如何通过协作、协商或竞争完成复杂任务，涉及博弈论、分布式计算等理论。
- 强化学习（RL）：强化学习为AI Agent提供了通过试错学习最优策略的框架，广泛应用于机器人、游戏AI等领域。
- 认知架构：如SOAR、ACT-R等认知架构为AI Agent提供了模拟人类认知过程的理论支持。
应用场景与背景

AI Agent的应用背景与现代社会对自动化、智能化和个性化的需求密切相关。以下是主要应用领域：
- 个人助手：如Siri、Google Assistant等，利用自然语言处理和任务规划技术，帮助用户完成日程管理、信息查询等任务。
- 游戏与仿真：AI Agent在电子游戏（如NPC）和仿真环境中扮演智能角色，通过强化学习等技术实现逼真的行为。
- 机器人与自动驾驶：机器人和自动驾驶汽车中的AI Agent通过传感器感知环境，结合路径规划和决策算法实现自主导航。
- 企业自动化：在金融、物流、客服等领域，AI Agent用于自动化交易、智能调度、聊天机器人等，提升效率并降低成本。
- 多Agent协作：如智能电网、智慧城市中，多个AI Agent协作优化资源分配，应对复杂动态环境。
当前趋势与挑战
- 趋势：
- 通用AI Agent：基于大模型的AI Agent正在向通用智能方向发展，能够跨领域执行多样化任务。
- 人机协作：AI Agent越来越注重与人类的自然交互，成为辅助工具而非完全替代。
- 开源生态：如LangChain、AutoGPT等开源框架降低了开发AI Agent的门槛。
- 挑战：
- 可解释性：AI Agent的决策过程往往是黑箱，难以解释。
- 安全性与伦理：自主性强的Agent可能引发误操作或伦理问题。
- 资源消耗：复杂AI Agent（如基于大模型的）需要大量计算资源。
总结

AI Agent的背景源于人工智能技术的演进、分布式系统和自主计算的理论发展，以及现代社会对智能自动化的需求。从早期的规则系统到如今的大模型驱动Agent，AI Agent在理论和应用上都取得了显著进步。未来，随着技术进一步成熟，AI Agent将在更多领域发挥重要作用，同时需要解决可解释性、安全性和资源效率等挑战。

为什么需要如Langchain、AutoGPT这样的框架？

LangChain这样的框架之所以被开发和广泛使用，是因为尽管大语言模型（LLM）本身已经非常强大，能够完成许多任务，但它们在某些复杂场景下存在局限性，而LangChain通过提供结构化的工具和模块，弥补了这些不足，增强了LLM的实用性和灵活性。以下从几个关键方面阐述为什么需要LangChain这样的框架，以及它如何解决LLM的局限性：

LLM的局限性

尽管LLM（如GPT、Llama等）在自然语言处理、生成文本、回答问题等方面表现出色，但在实际应用中仍面临以下挑战：
- 缺乏外部上下文整合能力：LLM的知识基于训练数据，截止某一时间点（例如，Grok的知识截至2025年5月），无法直接访问实时数据或特定领域的私有数据（如企业数据库）。
- 短期记忆限制：LLM的上下文窗口有限，难以处理超长对话或需要大量历史信息的任务。
- 复杂任务分解困难：LLM擅长单次生成或简单推理，但对于需要多步骤推理、工具调用或外部资源协调的复杂任务（如自动化工作流），其能力有限。
- 缺乏结构化交互：LLM的输出是文本流，难以直接与外部系统（如API、数据库）交互或实现自动化流程。
- 定制化与可控性不足：直接使用LLM难以实现特定业务逻辑的定制化，开发者需要额外的工程工作来整合模型与应用需求。
LangChain的核心作用

LangChain是一个开源框架，旨在通过模块化工具增强LLM的能力，使其更适合构建复杂的、面向应用的AI Agent或工作流。它解决了上述局限性，具体作用包括：

(1) 增强外部数据访问
- 问题：LLM无法直接访问实时数据或私有数据源。
- LangChain的解决方案：
- 工具调用（Tools）：LangChain允许LLM调用外部API（如天气服务、搜索引擎）或数据库，获取最新信息。例如，LangChain可以让LLM查询实时股票价格，而非依赖过时的训练数据。
- 文档加载与检索（Retrieval-Augmented Generation, RAG）：LangChain支持将外部文档（如PDF、网页）加载到向量数据库中，通过嵌入（embeddings）进行语义检索，让LLM基于特定文档回答问题。这对于企业知识库、法律文件分析等场景尤为重要。
- 示例：用户问“今天上海的天气如何？”，LangChain可以将问题路由到天气API，获取实时数据后由LLM生成自然语言回答。
(2) 扩展上下文管理
- 问题：LLM的上下文窗口有限，难以处理长文档或多轮复杂对话。
- LangChain的解决方案：
- 内存模块（Memory）：LangChain提供短期和长期记忆机制，跟踪对话历史或关键信息。例如，在多轮客服对话中，LangChain可以保存用户之前的请求，避免重复询问。
- 文档分块与摘要：对于超长文档，LangChain可以将内容分块处理，提取关键信息，减轻LLM的上下文负担。
- 示例：在法律咨询场景中，LangChain可以管理用户上传的合同全文，提取关键条款供LLM分析，而无需将整个文档塞入上下文。
(3) 支持复杂任务分解与工作流
- 问题：LLM难以直接处理需要多步骤推理或工具协调的复杂任务。
- LangChain的解决方案：
- 链（Chains）：LangChain允许开发者定义任务的执行流程，将多个LLM调用、工具调用和逻辑步骤组合成“链”。例如，一个链可以先检索文档、再调用LLM总结、再生成最终回答。
- 代理（Agents）：LangChain的Agent模块让LLM动态选择工具和行动路径，处理开放式任务。例如，一个Agent可以根据用户请求决定是查询数据库、调用API还是直接回答。
- 示例：用户要求“帮我规划一次旅行”，LangChain的Agent可以分解任务：1) 询问预算和偏好；2) 调用航班API查询票价；3) 调用酒店API推荐住宿；4) 生成完整行程。
(4) 与外部系统集成
- 问题：LLM的文本输出难以直接与外部系统交互。
- LangChain的解决方案：
- 工具集成：LangChain提供与多种外部工具的接口（如SQL数据库、Python解释器、Zapier自动化工具），使LLM的输出可以触发实际操作。
- 输出解析：LangChain可以将LLM的文本输出结构化为JSON等格式，便于系统处理。
- 示例：在电商场景中，LangChain可以将用户查询“最近的订单状态”转化为SQL查询，获取数据库中的订单信息，再由LLM生成用户友好的回答。
(5) 提高开发效率与可定制性
- 问题：直接使用LLM需要开发者手动处理数据管道、上下文管理和工具调用，开发成本高。
- LangChain的解决方案：
- 模块化设计：LangChain提供现成的组件（如文档加载器、嵌入模型、向量存储、提示模板），开发者可以快速组合构建应用。
- 提示工程（Prompt Engineering）：LangChain支持动态提示模板，优化LLM的输入以提高输出质量。
- 开源生态：LangChain与Hugging Face、Pinecone等工具兼容，降低了技术门槛。
- 示例：开发者可以用LangChain在几天内构建一个基于企业知识库的问答系统，而直接调用LLM可能需要数周的编码。
为什么LLM单独不够？

虽然LLM可以完成许多任务（如文本生成、翻译、问答），但它们更像是一个强大的“语言引擎”，而非完整的解决方案。LangChain将LLM从“通用语言模型”转变为“面向任务的智能系统”，具体优势包括：
- 场景适配：LLM是通用的，LangChain使其适配特定业务需求（如法律、金融、医疗）。
- 自动化与扩展性：LangChain支持自动化工作流和规模化部署，LLM单独难以实现。
- 用户体验：通过内存管理和外部数据整合，LangChain提升了交互的连贯性和准确性。
- 开发效率：LangChain降低了从原型到生产环境的开发难度。
实际案例对比
- 仅用LLM：用户问“我的订单在哪里？”，LLM可能回复“我不知道你的订单信息，请提供更多细节”，因为它无法访问数据库。
- 用LangChain：LangChain将问题路由到订单数据库，提取最新状态（如“您的订单已于5月6日发货”），再由LLM生成自然语言回答，提升用户体验。
其他类似框架

LangChain不是唯一的选择，其他框架如LlamaIndex、Haystack、AutoGPT等也有类似功能，但LangChain因其模块化、易用性和开源社区支持而广受欢迎。每个框架的侧重点不同：
- LlamaIndex：更专注于RAG和文档检索。
- AutoGPT：强调自主Agent的自动化任务执行。
- Haystack：专注于搜索和问答系统。
总结

LLM虽然强大，但其通用性和孤立性限制了它在复杂、动态和特定场景下的应用。LangChain通过提供外部数据整合、上下文管理、任务分解、工具调用和模块化开发等功能，极大地扩展了LLM的能力，使其从“语言模型”升级为“智能系统”。对于需要构建生产级AI应用的开发者来说，LangChain这样的框架是不可或缺的桥梁。

对于未来Agent的展望

未来AI Agent的发展前景广阔，将在技术、应用和社会影响等多个维度上持续演进。基于当前趋势和技术进步，以下从几个关键方面分析AI Agent的未来发展方向、潜力以及可能面临的挑战：

技术趋势与发展方向

(1) 通用智能Agent（General-Purpose Agents）
- 趋势：未来的AI Agent将从特定任务导向（如对话机器人、自动驾驶Agent）向通用智能方向发展，能够跨领域、跨任务执行复杂指令，类似人类的“全能助手”。
- 技术驱动：
- 大语言模型（LLM）升级：更强大的模型（如Grok 3的后续版本）将具备更强的推理、规划和上下文理解能力。
- 多模态能力：Agent将整合视觉、语音、文本等多种输入，处理多模态任务。例如，一个Agent可以同时分析图片、语音指令和文本数据，完成如“根据这张照片设计一个房间布局”的任务。
- 长上下文与记忆：通过改进内存管理（如扩展上下文窗口或外部记忆数据库），Agent将能处理超长对话或复杂项目，保持一致性。
- 示例：未来的Agent可能像《钢铁侠》中的JARVIS，能够无缝管理日程、分析数据、控制设备并与用户自然对话。
(2) 自主性与自我进化
- 趋势：Agent将具备更高的自主性和自我学习能力，能够在没有明确指令的情况下主动优化策略或发现新任务。
- 技术驱动：
- 强化学习（RL）与在线学习：Agent将通过与环境的持续交互优化行为，甚至在运行时自我调整模型参数。
- 元学习（Meta-Learning）：Agent将“学会学习”，快速适应新任务或环境，减少对大规模训练数据的依赖。
- 开源生态：框架如LangChain、AutoGPT的进一步发展将支持开发者构建自适应Agent。
- 示例：一个企业Agent可能自主监控供应链数据，预测中断风险并提出优化建议，而无需人工干预。
(3) 多Agent协作与分布式智能
- 趋势：多Agent系统（Multi-Agent Systems, MAS）将成为主流，多个Agent通过协作或竞争解决复杂问题，模拟人类社会分工。
- 技术驱动：
- 分布式计算：改进的通信协议和分布式架构将支持大规模Agent协作。
- 博弈论与协商机制：Agent将使用更复杂的协商算法（如基于博弈论的策略）优化资源分配。
- 去中心化Agent：区块链和去中心化AI技术可能催生自主运行的Agent网络。
- 示例：在智慧城市中，交通Agent、能源Agent和公共服务Agent协作，动态优化交通流量和能源分配。
(4) 人机协同与交互性
- 趋势：Agent将更注重与人类的自然交互，成为辅助工具而非完全替代，强调可解释性和信任。
- 技术驱动：
- 可解释AI（XAI）：Agent将提供决策的透明解释，增强用户信任。
- 情感计算：通过分析语音语调、面部表情，Agent将实现更具共情力的交互。
- 混合智能：Agent与人类专家协同工作，结合人类直觉和AI的计算能力。
- 示例：医疗Agent可能协助医生分析影像数据，解释诊断依据并根据医生反馈调整建议。
(5) 边缘计算与轻量化Agent
- 趋势：Agent将部署在边缘设备（如手机、IoT设备），实现低延迟、隐私保护的本地化智能。
- 技术驱动：
- 模型压缩：通过蒸馏、量化等技术，缩小模型体积以适应资源受限设备。
- 联邦学习：Agent在本地学习，保护用户数据隐私。
- 示例：智能家居Agent在本地处理语音指令，无需云端传输，降低延迟并增强隐私。
应用场景的扩展

AI Agent将在以下领域进一步深化应用，改变行业格局：
- 个人化服务：定制化的教育Agent根据学生进度调整教学内容；健康Agent实时监测生理数据，提供个性化建议。
- 企业自动化：Agent将推动“智能企业”，自动化从客服到供应链管理的全流程。例如，财务Agent自动分析报表并预测现金流。
- 创意与娱乐：Agent将协助创作音乐、电影剧本，甚至生成虚拟世界中的动态NPC，提升沉浸式体验。
- 科学研究：科学Agent将加速研究进程，例如通过自动化实验设计、文献分析推动药物发现。
- 社会治理：Agent将优化公共资源分配，如在灾难响应中协调救援物资和人力。
社会影响
- 正面影响：
- 效率提升：Agent将大幅降低重复性劳动成本，提高生产力。
- 普惠性：开源Agent框架和低成本部署将使中小企业和个人也能受益于AI。
- 创新加速：Agent将推动跨学科创新，如在气候变化、医疗等领域的突破。
- 潜在风险：
- 就业冲击：高度自动化的Agent可能取代部分低技能岗位，引发就业挑战。
- 伦理与安全：自主Agent可能因错误决策或恶意使用导致风险，如金融市场操纵或隐私泄露。
- 监管需求：Agent的广泛应用将需要新的法律框架，规范其行为和责任归属。
面临的挑战

尽管前景光明，AI Agent的发展仍需克服以下障碍：
- 计算资源与能耗：训练和运行复杂Agent需要大量算力，需开发更高效的算法和硬件。
- 可解释性：确保Agent的决策透明，避免黑箱问题。
- 安全性：防止Agent被黑客操控或生成有害内容。
- 伦理问题：平衡Agent的自主性与人类控制，避免过度依赖或失控。
- 标准化与互操作性：不同Agent系统间的兼容性需提高，以实现无缝协作。
未来5-10年的展望
- 短期（1-3年）：Agent将更广泛集成到现有系统中，如企业ERP、个人助手，框架如LangChain将进一步成熟，RAG和工具调用成为标配。
- 中期（3-5年）：通用Agent开始出现，能够处理跨领域的复杂任务；多Agent协作在交通、物流等领域实现规模化应用。
- 长期（5-10年）：Agent可能接近通用人工智能（AGI）水平，成为人类生活中不可或缺的伙伴，推动社会进入高度智能化阶段。
总结

未来AI Agent将朝着更通用、自主、协作和人性化的方向发展，深刻改变个人生活、企业运营和社会治理。其核心驱动力将是多模态AI、强化学习、分布式系统和人机协同技术的进步。然而，可解释性、安全性和伦理问题将是发展的关键制约因素。Agent的最终目标不仅是自动化任务，而是成为可信任的智能伙伴，与人类共同应对复杂挑战。

Agent示例与架构

阿里WebDancer：自主信息搜索Agent

阿里WebDancer：自主信息搜索Agent - csdn介绍

简单来说，WebDancer是阿里巴巴（模型即服务MaaS团队）开发的一个自主AI智能体（Agent）。

您可以把它想象成一个“AI搜索助理”。您不再是给它一个“关键词”，而是给它一个**“任务”**。

传统搜索： 您输入“AI Agent 最新进展”，得到一堆链接，您自己去点开、阅读、总结。
WebDancer： 您输入“帮我调研一下2025年AI Agent技术的最新进展和主要参与者”，它会像人一样去“上网”，自己浏览网页、点击链接、筛选信息、甚至打开新标签页，最后直接给您一份总结好的答案。

核心特点与能力

WebDancer之所以被称为“自主信息搜索Agent”，关键在于它的几个核心能力：

1. 高度自主性 (Autonomy) 这是它最大的特点。WebDancer可以自主理解您的复杂意图，并自动规划搜索步骤。它会自己决定先搜什么、再搜什么、哪些信息是相关的。
2. 拟人化网页交互 (Human-like Interaction) 它不是通过API爬取数据，而是模拟真实用户的行为在浏览器中操作，比如：
- 滚动页面（Scroll）
- 点击链接和按钮（Click）
- 在搜索框输入文字（Type）
- 切换标签页（Tab Switching）
3. 复杂任务拆解 (Complex Task Decomposition) 面对“帮我找几篇关于Llama 3的深度技术评测，并总结它们的优缺点”这样的复杂问题，它能将其分解为一系列子任务（比如：搜索评测、筛选来源、阅读并提取观点、对比总结），并按顺序执行。
4. 自我纠错与反思 (Self-Correction & Reflection) 这是它“智能”的关键。如果它发现一条搜索路径是死胡同（比如网页打不开、信息不相关，或者进入了广告页），它能够“反思”并尝试新的搜索策略，而不是卡住不动。
5. 跨网页信息整合 (Information Synthesis) 最终，它会把从多个网页（可能是几十个）中找到的零散信息，整合成一个连贯、全面的答案。

它与传统搜索有何不同？

您可以这样理解它们之间的区别：

传统搜索引擎 (如谷歌、百度):

角色： 信息索引员 (Indexer)

工作： 您输入关键词，它返回一个相关网页的“索引列表”。

用户负担： 用户需要自己完成“浏览、筛选、阅读、总结”的工作。

WebDancer (AI Agent):

角色： 研究助理 (Research Assistant)

工作： 您输入一个**“任务”或“问题”。它代您执行“搜索和浏览”的整个过程**。

用户负担： 用户直接获取**“最终答案”**。

总而言之，WebDancer代表了从“信息检索”（Information Retrieval）到“答案获取”（Answer Generation）的转变，是AI Agent技术在信息处理领域的一个重要应用。

ai返回数据的格式不稳定，存在解析错误的问题

Mon, 17 Mar 2025 09:33:58 +0800

开发心得

所选用的ai模型的性能起决定性的作用，如果用的模型不能按照你想要的格式返回数据，那么重试一万次也不能得到一个好的效果，带来的只能是Token的浪费…

我在开发这样一个agent 的时候，我传入了一些信息，我希望它能够按照我想要的格式返回数据，但是重试很多次他都不能返回，比如下面的结果

我使用的是7B的模型，但是回答很差，当然也有很多次它是回答的格式不对，我设置的重试3次，但是基本上都不会得到想要的结果

我换了qwq-32b模型，效果好了很多

一些模型的对比可以看：

参考
对比了几种大模型在相同任务下的表现

实战代码

示例代码一：输出解析器和多次尝试


import os
from langchain.chat_models import ChatOpenAI
from langchain.prompts import PromptTemplate
from langchain.output_parsers import StructuredOutputParser, ResponseSchema
from pydantic import ValidationError
from dotenv import load_dotenv
load_dotenv()
import os




# 密钥（替换为你的密钥，或通过环境变量获取） 这里我用的阿里云的

api_key = os.getenv("api_key")
base_url = os.getenv("base_url")
model = "qwq-32b"

# 定义期望的输出结构
response_schemas = [
 ResponseSchema(name="answer", description="回答内容，字符串类型"),
 ResponseSchema(name="confidence", description="置信度，0-1之间的浮点数")
]

# 创建输出解析器
output_parser = StructuredOutputParser.from_response_schemas(response_schemas)

# 定义提示模板
prompt_template = """
请分析以下句子的情感，并以指定的 JSON 格式返回结果：
{format_instructions}

句子：{sentence}
"""

prompt = PromptTemplate(
 template=prompt_template,
 input_variables=["sentence"],
 partial_variables={"format_instructions": output_parser.get_format_instructions()}
)

# 初始化语言模型
llm = ChatOpenAI(temperature=0.2, max_tokens=200,api_key = api_key , base_url = base_url,model = model,streaming = True)

# 定义解析和重试逻辑
def get_stable_output(sentence, max_attempts=3):
 chain = prompt | llm | output_parser

 for attempt in range(max_attempts):
 try:
 # 调用模型并解析输出
 result = chain.invoke({"sentence": sentence})
 return result
 except Exception as e:
 print(f"尝试 {attempt + 1}/{max_attempts} 失败: {e}")
 if attempt == max_attempts - 1:
 # 最后一次尝试失败，返回默认值
 return {"answer": "无法分析", "confidence": 0.5}

 return {"answer": "未完成分析", "confidence": 0.0} # 理论上不会到达这里

# 测试代码
def main():
 test_sentences = [
 "我今天感觉非常开心！",
 "这个世界真是让人失望。",
 "天气很好，适合出门散步。"
 ]

 for sentence in test_sentences:
 print(f"\n分析句子：{sentence}")
 result = get_stable_output(sentence)
 print(f"结果：{result}")

if __name__ == "__main__":
 main()

代码说明

输出结构定义：
- 使用 ResponseSchema 定义了期望的 JSON 结构：answer（字符串）和 confidence（浮点数）。
提示模板：
- 通过 PromptTemplate 构造提示，确保模型知道返回 JSON 格式。
- output_parser.get_format_instructions() 自动生成格式说明，例如：
```
The output should be a markdown code block formatted as JSON:
```json
  {
   "answer": "string",
   "confidence": "float"
  }
```
语言模型：
- 使用 ChatOpenAI，设置 temperature=0.2 减少随机性，max_tokens=200 限制输出长度。
解析与重试：
- get_stable_output 函数使用 LangChain 的链式调用（prompt | llm | output_parser）。
- 如果解析失败，会重试最多 3 次，最后返回默认值。

具体分析 - 如何减少解析错误

在使用 LangChain 开发 AI 应用时，AI 返回数据的格式不稳定并导致解析错误是一个常见问题。这通常与大语言模型（LLM）的输出不确定性有关，尤其是当模型生成的内容未严格遵循预期结构时。以下是一些解决方案和思路，帮助你应对这一问题：

1. 明确提示（Prompt）设计

问题原因：LLM 的输出很大程度上依赖于输入提示的清晰度。如果提示不够具体，模型可能会生成不一致或不符合预期的格式。
解决方法：
- 在提示中明确要求返回特定格式，例如 JSON 或其他结构化数据。例如：
```
请以 JSON 格式返回以下内容：{"key": "value"}
```
- 使用示例（Few-shot Learning）来引导模型输出一致的格式。例如：
```
输入：分析这句话的情感
输出：{"sentence": "这句话", "sentiment": "积极"}
```
- 添加约束性描述，如“确保输出是可解析的 JSON，且不包含多余文本”。

2. 使用输出解析器（Output Parsers）

问题原因：即使提示明确，LLM 有时仍会生成不符合预期的输出，导致解析失败。

解决方法：

LangChain 提供了内置的输出解析器（如 StructuredOutputParser 或 JsonOutputParser），可以用来规范化模型输出。

示例代码：

from langchain.output_parsers import StructuredOutputParser, ResponseSchema

response_schemas = [
 ResponseSchema(name="answer", description="回答内容"),
 ResponseSchema(name="confidence", description="置信度，0-1之间的浮点数")
]
parser = StructuredOutputParser.from_response_schemas(response_schemas)
prompt = f"请按照以下格式返回数据：\n{parser.get_format_instructions()}"

在提示中嵌入 parser.get_format_instructions()，让模型知道预期格式。
如果解析失败，可以捕获异常并重试。

3. 处理解析错误（Handle Parsing Errors）

问题原因：LLM 输出可能偶尔无法解析，例如缺少关键字段或格式错误。

解决方法：

在代理（Agent）或链（Chain）中启用错误处理机制。LangChain 支持通过 handle_parsing_errors 参数自定义错误处理逻辑。

示例代码：

from langchain.agents import initialize_agent, AgentType
from langchain.chat_models import ChatOpenAI

agent = initialize_agent(
 tools=[...],
 llm=ChatOpenAI(temperature=0),
 agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
 handle_parsing_errors=True # 自动忽略解析错误并重试
)

你也可以定义自定义回调函数来处理错误：

def custom_error_handler(error):
 print(f"解析错误: {error}")
 return "发生错误，请重试或检查输入"

agent = initialize_agent(..., handle_parsing_errors=custom_error_handler)

4. 后处理与验证

问题原因：即使使用了解析器，输出仍可能不符合预期。

解决方法：

在接收到模型输出后，使用 Python 的 try-except 块或数据验证库（如 pydantic）检查和修复数据。

示例代码：

from pydantic import BaseModel, ValidationError

class Response(BaseModel):
 answer: str
 confidence: float

def parse_response(raw_output):
 try:
 return Response.parse_raw(raw_output)
 except ValidationError as e:
 print(f"验证失败: {e}")
 return Response(answer="默认回答", confidence=0.5) # 回退值

raw_output = '{"answer": "是的", "confidence": "0.9"}'
result = parse_response(raw_output)

5. 调整模型参数

问题原因：模型的随机性（temperature）或输出长度（max_tokens）可能导致格式不稳定。
解决方法：
- 降低 temperature（如设为 0 或 0.2），减少输出的随机性。
- 设置合理的 max_tokens，避免输出被截断。
- 示例：
```
llm = ChatOpenAI(temperature=0.2, max_tokens=500)
```

6. 重试机制

问题原因：单次调用可能失败，但多次尝试可能成功。

解决方法：

实现一个简单的重试逻辑，确保在解析失败时重新请求。

示例代码：

def get_stable_output(prompt, max_attempts=3):
 for _ in range(max_attempts):
 try:
 response = llm(prompt)
 return parser.parse(response)
 except Exception:
 continue
 return "无法获取稳定输出"

总结

通过优化提示、使用 LangChain 的输出解析器、启用错误处理机制、后处理验证数据以及调整模型参数，可以有效解决 AI 返回数据格式不稳定和解析错误的问题。根据具体应用场景，你可能需要结合多种方法。例如，对于需要高可靠性的生产环境，建议同时使用解析器和重试机制；对于快速原型开发，则可以通过清晰的提示和简单后处理解决问题。

全量解码与增量解码：原理、区别以及应用

Fri, 14 Mar 2025 17:49:58 +0800

引言

在自然语言处理（NLP）领域，尤其是大语言模型（LLM）中，解码（decoding）是模型生成输出的核心步骤。你可能好奇：为什么模型接收到完整输入后，生成回复时却不是一次性吐出整个句子？答案在于解码方式的不同。本教程将详细讲解两种主要解码方式——全量解码和增量解码，包括它们的定义、原理、优缺点、区别，以及在大语言模型中的应用。

第一部分：什么是解码？

解码的定义

解码是大语言模型根据输入生成输出的过程。简单来说：

输入：用户给模型一个问题或句子（比如“请解释一下AI”）。
解码：模型根据内部表示（概率分布或隐藏状态），逐步或一次性生成回答（比如“AI是一种技术”）。

输入与解码的区别

输入阶段：
- 用户通常是一次性把完整输入（比如“我不太懂，模型输入不是一次性就输入进去了吗”）交给模型。
- 模型会通过编码器（如果是Encoder-Decoder架构，如T5）或直接通过自回归方式（像GPT）处理整个输入，生成某种内部表示（比如隐藏状态或上下文向量）。
解码阶段：
- 解码是模型根据输入生成输出的过程，也就是从内部表示逐步生成文本的过程。
- 即使输入是一次性给的，模型生成输出时并不一定一次性吐出整个答案，而是需要一步步决定每个词（或标记），这就是解码方式的重点。

换句话说，输入是一次性给模型的，但输出（解码）可以是逐步生成的。全量解码和增量解码的区别在于：模型是如何基于输入一步步生成输出的。

为什么解码不是一次性完成？

大语言模型（尤其是基于Transformer的模型）通常是自回归的，意味着它们生成输出的方式是序列化的：每生成一个词，模型会把这个词加入上下文，再预测下一个词。这种设计有以下原因：

1. 语言的序列性质： 自然语言是有序的，比如“我喜欢你”和“你喜欢我”意思完全不同。模型需要逐词生成，才能保证语法和语义的连贯性。如果一次性生成整个句子，模型需要同时决定所有词，这在计算上非常复杂，且难以保证一致性。

2. 模型架构限制： GPT这类模型是自回归的，当前词的预测依赖于之前生成的词。它们没有能力一次性输出整个序列，而是必须逐步构建。即使是Encoder-Decoder模型（如T5），解码器在生成时也是逐步进行的。

3. 概率分布： 模型每一步会输出一个概率分布（比如下一个词可能是“我”0.7、“你”0.2、“他”0.1），然后根据解码策略（贪心、采样等）选择一个词。这个过程天然是增量的，因为每一步的选择会影响下一步的概率。

第二部分：全量解码 (Full Decoding)

定义

全量解码是指模型一次性生成或评估整个输出序列，试图找到全局最优解。它强调对所有可能输出的全面考虑。

工作原理

接收完整输入（比如“你好”）。
计算所有可能的输出序列及其概率：
- “Hello” (0.9)
- “Hi there” (0.7)
- “Greetings” (0.5)
选择得分最高的序列（比如“Hello”）作为输出。

典型算法

束搜索 (Beam Search)：维护一组候选序列（束），每步保留得分最高的前k个，最终选最佳序列。
维特比算法 (Viterbi Algorithm)：在隐马尔可夫模型中寻找全局最优路径。
（注：真正的全量解码需要遍历所有可能性，但在实践中因计算量太大，通常用近似方法。）

优点

全局最优：考虑整个序列的上下文，结果更连贯。
高质量：适合需要精确输出的任务。

缺点

计算复杂度高：可能的序列组合随长度指数增长。
实时性差：需要等待完整计算，无法边生成边输出。

应用场景

机器翻译（追求高质量翻译）。
文本摘要（需要全局一致性）。

第三部分：增量解码 (Incremental Decoding)

定义

增量解码是指模型逐步生成输出序列，每一步只基于当前信息预测下一个词，而不依赖未来全局信息。它是一种“边解码边生成”的方式。

工作原理

接收输入（比如“你好”）。
逐步生成输出：
- 第一步：输出“Hello”。
- 第二步：根据“Hello”决定是否继续（如停止或加词）。
重复直到生成完整序列或达到终止条件。

典型算法

贪心解码 (Greedy Decoding)：每步选择概率最高的词。
采样解码 (Sampling)：根据概率分布随机选择词（如Top-k或Top-p采样）。

优点

高效：每步计算量小，适合快速响应。
实时性强：边输入边输出，用户体验好。
资源占用低：无需存储所有可能性。

缺点

局部最优风险：每步只看当前，可能偏离全局最优。
上下文不足：无法利用序列后部的完整信息。

应用场景

实时对话（聊天机器人）。
流式语音转文字（边说边转录）。

第四部分：全量解码与增量解码的对比

特性	全量解码	增量解码
生成方式	一次性生成整个序列	逐步生成序列
优化目标	全局最优	局部最优
计算复杂度	高（指数级）	低（线性或接近线性）
实时性	差（需完整输入和计算）	强（边输入边输出）
上下文依赖	依赖整个序列	只依赖当前和之前
典型算法	束搜索、维特比算法	贪心解码、采样解码

举例说明

输入：“I love you”。
全量解码：
- 计算所有可能翻译：
  - “我爱你” (0.9)
  - “我喜欢你” (0.6)
  - “我爱你们” (0.3)
- 输出：“我爱你”。
增量解码：
- 逐步生成：
  - “我” → “爱” → “你”。
- 输出：“我爱你”。

举例说明2

假设你输入：“请解释一下AI”。

输入阶段：模型一次性接收“请解释一下AI”，并理解其含义（通过编码器或自回归上下文）。
解码阶段：
- 增量解码（实际常用）：
  - 模型先输出“AI”，然后根据“AI”预测“是”，再根据“AI是”预测“一种”，逐步生成“AI是一种技术”。
  - 你可能会看到我逐词回复，像这样：AI→是→一种→技术。
- 全量解码（理论上）：
  - 模型计算所有可能的回答：
    - “AI是一种技术” (概率 0.9)
    - “AI是人工智能” (概率 0.85)
    - “AI很复杂” (概率 0.6)
  - 然后一次性输出“AI是一种技术”。
  - 但实际上，这需要巨大计算量，通常只用近似方法（如束搜索）。

第五部分：大语言模型中的解码方式

现状

现代大语言模型（如GPT、ChatGPT、Grok）主要基于自回归架构，天然倾向于增量解码，但会根据任务搭配不同策略。

常用解码策略

贪心解码：
- 每步选概率最高的词。
- 简单高效，但输出单一。
束搜索：
- 近似全量解码，保留多个候选序列。
- 用于高质量生成（如翻译）。
采样解码：
- Top-k采样：从前k个高概率词中随机选。
- Top-p采样：从累计概率达p的词中选。
- 增强多样性，常见于对话模型。
自回归生成：
- 逐步生成，每步依赖前文。
- 是增量解码的基础框架。

为什么偏向增量解码？

实时性：对话中需快速响应。
效率：避免指数级计算。
架构：自回归模型逐词生成。

全量解码的应用

在翻译、摘要等任务中，束搜索常用于追求高质量输出。
但真正的全量解码（遍历所有序列）因计算成本过高，几乎不用。

实际例子

ChatGPT：用Top-p采样+自回归，生成自然多样的回复。
Grok：类似增量解码，逐词输出，追求实时性。

第六部分：常见疑问解答

Q1：输入不是一次性给的吗？为什么解码不是一次性完成？

答：
- 输入确实是一次性给模型的，模型会理解完整上下文。
- 但解码是生成输出的过程，自回归模型需要逐词预测，因为：
  1. 语言的序列性要求逐步构建。
  2. 每步预测依赖前文输出。
  3. 一次性生成所有词的组合计算量太大。

Q2：大语言模型用哪种解码？

答：
- 主要用增量解码（自回归+采样），适合实时对话。
- 全量解码（如束搜索）用于特定任务，但多为近似形式。

第七部分：总结

全量解码：追求全局最优，计算成本高，适合高质量任务。
增量解码：高效实时，适合对话和流式应用。
大语言模型：以增量解码为主（如采样），灵活搭配策略，平衡质量与效率。

通过理解这两种解码方式，你可以更好地把握大语言模型的工作机制，并根据需求选择合适的策略。

相同LLM不同提示词的对比

Fri, 07 Mar 2025 16:10:38 +0800

提示词列表

有最好的模型就用最好的模型，模型与模型之间的差距比提示词大很多

提示词描述	提示词—类1	提示词-类2	提示词-类3
推广某一个产品	我想推广公司的新产品。我的公司名为百炼，新产品名为 Zephyr Z9，是一款轻薄便携的手机。帮我创建一条微博帖子。	请为我司“百炼”最新推出的“Zephyr Z9”轻薄便携手机设计一条吸引眼球的微博推广帖。内容需彰显Zephyr Z9的独特卖点，如极致轻薄设计、高性能配置及用户便利性，同时融入创意元素以提升观众兴趣和互动意愿。记得提及品牌声誉，激发受众好奇心，引导他们探索更多产品信息或直接进行购买。贴文应简洁有力，符合微博平台的风格与字数限制，适宜社交媒体传播。
cursor和trae的对比	请你完成一个演讲ppt，内容是什么是MoE，内容使用html生成	请你完成一个演讲ppt，内容是什么是MoE，内容使用html生成

推广某一个产品

Qwen

Grok

cursor和trae的对比-sonnet3.5

cursor和trae的对比-sonnet3.7

差不多，看来主要是模型的问题，模型好，问出来的答案效果就是会更好