目前的agent架构
ReAct 的核心循环
1 | |
例子
1 | |
现代 Harness 实际上是,ReAct 是 Engine,Harness 是 Engine 外面的控制系统。
1 | |
普遍 Agent Framework 可以拆成 7 个模块
1 | |
skill tool mcp
1 | |
multi agent
1 | |
纯 ReAct, 非常灵活,但容易乱跑 , 通常两者和 Plan-and-Execute混合,外层 Plan-Execute,内层 ReAct,最外面再由 Harness 管住。
1 | |
plan
Planning 不是让 LLM 完全自由地“自己想”,而是用 Prompt + 程序结构约束它怎么拆、怎么执行。
1 | |
适用场景 : 出错代价大的地方,不要让模型自由规划。
- 任务不确定
- 场景变化大
- 需要语义理解
- 需要灵活拆解
实际工程里最常见
1 | |
Code:控制流程边界、LLM:负责动态决策、Validation:防止计划跑偏
- ReAct:不提前生成完整 Plan,而是每一步现想现做。
- Plan-Execute:先做宏观计划,再执行。
- Tool Routing:下一步 Tool 选择。
multiagent
单 Agent 的主要问题
1 | |
所以 Multi-Agent 的价值主要是:分工,并行,独立上下文
1 | |
- 冲突优先级必须显式定义,不能让 LLM 每次自己决定。
- 一个子 Agent 的失败,不应该阻塞整个任务。
动态调度时,Orchestrator 往往是一个 Supervisor Agent;固定调度时,Orchestrator 往往只是代码。Prompt 本身永远不是 Orchestrator,只是 Orchestrator Agent 的行为规则。
流程决策
1 | |
Agent 之间的 4 种主要交互方式
| 模式 | 怎样交互 | 适用场景 |
|---|---|---|
| ① Agent as Tool | 主 Agent 调用子 Agent,等待结果返回 | RAG、多专家分析、报告生成 |
| ② Handoff | Agent A 把控制权交给 Agent B,不一定自动返回 A;要返回时,需要额外设计交回控制权的路径。 | 客服分流、专业任务接管 |
| ③ Shared State / Graph | 不同 Agent 通过共享任务状态协作 | 固定工作流、并行与依赖调度 |
| ④ Message / A2A | Agent 之间通过消息或协议通信 | 跨进程、跨服务、跨框架 |
前两种是 OpenAI Agents SDK 明确支持的主要编排模式;后两种主要描述状态协作和通信机制,可以与前两种组合
需要区别 MCP 和 A2A:
- MCP:Agent 调用 Tool / Resource。
- A2A:独立 Agent 之间发现能力、委派任务和协作。
两者可以一起使用,并不冲突
共享 Memory 和共享 Context 是一回事吗?
不是。这是 Multi-Agent 很容易出现问题的地方。
| 数据类型 | 是否建议共享 | 原因 |
|---|---|---|
| System Prompt | 默认独立 | 各 Agent 职责不同 |
| 当前任务目标与约束 | 必须按需传递 | 防止偏离目标 |
| 完整聊天 Messages | 不建议默认共享 | Token 成本与上下文污染 |
| Task State | 推荐共享 | 协调任务进度 |
| 长期 Memory | 按权限检索共享 | 防止数据越权和冲突 |
| Artifacts | 推荐通过引用共享 | 避免大结果反复传输 |
尤其并行 Agent,如果都能修改 state["final_answer"],就可能产生竞态。
1 | |
Harness + ReAct + Plan-Execute 架构,我建议:Agent 并不是直接修改同一个全局 Dict。每个 Agent 读取状态快照,执行任务,返回局部更新;Runtime 将更新合并成新的共享状态。
- 单进程:Python
asyncio+ 内存 State,最简单。 - 需要断点恢复:LangGraph + PostgreSQL。
- 多进程或多节点:PostgreSQL 保存任务真实状态,Redis 或消息队列负责异步任务分发;Orchestrator 负责协调。
其中,PostgreSQL 是状态的持久化存储,不是 Agent 之间必须经过的通信总线;Redis 也不是必需品。
Agent 之间具体传递什么
建议不要直接把 Agent A 的全部 Messages 塞给 Agent B。更合理的是通过结构化的任务协议通信。
Async Agent Runtime
短任务:
1 | |
长任务:
1 | |
用户关闭浏览器: HTTP 生命周期 ≠ Agent 生命周期
1 | |
agent 循环打断机制
工具调用循环: 同一个工具反复调用,一直不进入总结
目标漂移。 做完主任务后不断扩展子任务,永远不交付
自我怀疑循环。 已经完成,但不断 Review / 重写 / 优化
幻觉性进展。 看起来一直在分析,实际上只是换说法重复
1 | |
context
Context 不是越大越好,关键是“信息保鲜
1 | |
特别是:
1 | |
context 分层
1 | |
context压缩
不要每轮对会都压缩一次。Compact 不只是减少 token,也是保持推理缓存稳定性的工程策略。
1 | |
summary
1 | |
例如
1 | |
核心原则:
压缩可以丢过程,但不能把以后无法恢复的关键约束压没。
不同的目标,压缩目的不一样, 例如长 Deep Research 更适合维护一个 Evolving Report / Research State:
1 | |
关键变化是:
从“保存发生过什么”变成“保存现在知道什么”。
token 数 怎么拿
1 | |
messages 不要无限增长,旧的原始结果可以留在日志/存储里,活跃 Context 里只保留压缩后的研究状态。
tool
考虑风险等级、幂等性、权限
Tool Router
先把几十个 Tool 缩成 1~5 个候选,再交给主 LLM 做最终 Tool Calling。
1 | |
-
tool < 5 , 就不需要, tool 5~20 apability/tag + embedding Top-K , Tool 20+ 使用混合路由
-
规则 / Tag 路由 ** ,最便宜、最稳定。每个 Tool 配 capability :适合意图非常明确的业务。**
1
2
3
4
5TOOLS = { "get_weather": ["weather", "天气", "温度"], "search_flights": ["flight", "机票", "航班"], "search_docs": ["document", "内部文档", "知识库"], } -
Embedding 路由 **,把 User Query 和 Tool description 做向量相似度:优点是便宜、快,而且不需要额外 LLM。**
1
2
3
4
5query embedding ↓ 和每个 Tool description embedding 比较 ↓ Top-K tools -
LLM Router:让一个小模型只做分类 : 优点是能理解复杂语义,缺点是多一次模型调用。
1
2
3
4
5
6
7
8
9
10
11
12可选能力: weather flight hotel document web_search 用户: “帮我看看明天北京天气,然后如果下雨帮我找个室内酒店” 输出: ["weather", "hotel"] -
Hybrid Router , tool 20+
1
2
3
4
5
6
7
8
9User Query ↓ 权限 / 场景硬过滤 ↓ Rule / Embedding 粗召回 ↓ Top 3~5 Tools ↓ Main LLM 最终选择
每个 Tool 至少有:
1 | |
Router 主要根据:
1 | |
筛候选。
稳定性
Tool 调用不是“模型输出 → 直接执行”,而是 路由 → 参数校验 → 执行 → 结果校验 → 错误分类 → Observation → Retry / 换策略 / 降级
最后可以再压缩成你自己的 Tool Stability 五层模型:
1 | |
减少错误发生:Tool Routing + Schema:不要把所有 Tool 都暴露给模型。
1 | |
Tool 名称唯一、无歧义
-
参数名统一
-
required / enum / type 明确
-
能用 strict JSON Schema 就使用
Tool 执行前:参数校验
1 | |
tool 调用失败,不同错误不能统一 retry
1 | |
Tool Failure 本身也是一种 Observation,不能被 try/except 静默吞掉。
所有 Tool 统一错误协议
1 | |
Tool Result 也要校验:Tool 没报错 ≠ 结果有效。
还要检查:空结果 / 登录墙/404 页面/广告页/格式错误/字段缺失/明显垃圾内容
处理:
1 | |
防止 Agent 基于“成功返回的垃圾”继续推理。
失败后的行为规则
确定性的 Retry / Validation / Loop / Budget 应由 Runtime 代码控制, 让失败后的 Agent 行为可预测、可测试。Prompt 只负责告诉模型“失败后如何换策略”。
Runtime 负责硬规则
1 | |
这些尽量用代码强制。
System Prompt 负责策略规则
1 | |
Loop Detection 循环检查
每次调用前记录:
1 | |
检查:
1 | |
命中后:
1 | |
降级必须透明
Tool 最终拿不到结果
1 | |
日志与 Badcase 闭环
1 | |
工具链训练
连续工具调用,让模型学会完整的 Plan → Tool Call → Observation → Next Tool → Final 轨迹。
工具链本质 。 训练数据真正关键的是“完整轨迹”
1 | |
先学会单工具
1 | |
多工具
1 | |
参数继承工具链核心能力
1 | |
半自动沙盒生成
1 | |
沙箱安全
不要相信 LLM 生成的代码,也不要指望黑名单覆盖所有攻击。正确方案是:白名单最小权限 + AST 静态检查 + OS 级沙箱 + 资源限制。
1 | |
Agent 行为审计:从安全控制到可追溯风险事件
Policy / Sandbox 负责阻止危险行为,Audit 负责识别、追踪和复核真实风险。
例如 Tool Policy 阻止了一次未授权文件读取,行为审计还需要记录是谁发起、命中什么规则、涉及什么资源以及最终如何处置。
flowchart LR
A["Trace / Tool Call"] --> B["规则命中"]
B --> C["语义风险判定"]
C --> D["证据聚合"]
D --> E["Risk Event"]
E --> F["告警 / 阻断 / 人工复核"]
Risk Event 数据结构
1 | |
重点能力:
- 从大量低保真告警中筛出高风险事件。
- 关联原始 Trace、工具调用和命中规则。
- 保留最小必要证据,敏感信息脱敏或受控访问。
- 根据严重等级进行告警、阻断或人工复核。
- 审计记录应可追溯,不依赖 LLM 自己描述执行结果。
原则:安全执行控制由 Runtime / Policy 强制实现,Agent Judge 可以辅助识别风险,但不能代替确定性的权限检查。
Memory 工程化
触发memory: 第一目标不是“精确判断有没有重要信息”,而是“低成本地控制提取频率”。
1 | |
每条记忆的重要性评分本身就有额外开销,事件密集时甚至可能更贵
1 | |
| 记忆层 | 内容 | 生命周期 | 载体/作用域 |
|---|---|---|---|
| Working Memory (工作记忆) | 当前消息、ReAct循环、临时变量 | 单次请求/推理期间 | AgentScope InMemoryMemory |
| Session Memory (会话记忆) | 完整对话历史、会话摘要 | 当前会话,历史可持久化 | Redis + MySQL |
| User Memory (用户记忆) | 用户偏好、背景、纠错历史 | 跨所有Agent共享,长期 | MemOS · user_profile |
| Agent Memory (Agent记忆) | 项目上下文(sys prompt)、任务模式、放到(skill , tools) | Agent内跨会话复用,长期 | MemOS · agent_{id} |
并行加载,提升效率
- 降级与容错:长期记忆查询失败时,仅记录日志并返回空结果,不影响主对话流程,将其视为“增强能力”而非核心依赖
短期记忆:Redis 缓存 + MySQL 兜底
- 存储:采用 Redis 作为热点缓存(最新200条,TTL 7天),MySQL 作为持久化存储,确保数据不丢失。
- 读取:优先从 Redis 读取,未命中或异常时回退到 MySQL。
- 写入:采用双写策略,先写 MySQL,成功后异步写入 Redis;Redis 写入失败不回滚 MySQL 写入。
- Token 窗口控制:读取时进行 Token 窗口裁剪,并为摘要预留预算(约2000 tokens),避免上下文超限
长期记忆:MemOS 语义检索 + 智能写入
-
load
-
同时检索
user_profile和agent_{agentId}两个 Cube。 -
使用
fast模式、相似度阈值0.45、MMR 去重 , 时间新鲜度 等参数控制召回质量。 -
检索后过滤低分(
score < 0.3)和过长(单条截断至1000字符)结果
-
- write
- 会话结束后,异步触发
- 调用 LLM 判断新增消息是否值得记忆,并决定记忆的类别、scope 和重要性
- 去重与冲突处理:
- 本地预去重:使用精确匹配、包含、Jaccard(阈值0.7)、Levenshtein(阈值0.8)等方法。
- 冲突解决:调用冲突检测服务,决定是写入新记忆、跳过,还是标记旧记忆待删除。
- “先写后删”策略:为确保数据不丢失,先向 MemOS 写入新记忆,成功后再删除冲突的旧记忆;删除失败仅记录警告,不影响已写入的新记忆
- del
- “有时效的信息”加 TTL;长期不使用、低重要性的记忆逐步降权或清理,避免 Memory 无限膨胀。
预算控制:Token 精细化分配
- 长期记忆:默认总预算为 4000 tokens。其中
user_profile最多占 60%,剩余预算分配给 Agent 记忆。 - 截断算法:采用按行截断,尽量保留完整语义,避免拆散单条记忆
可靠性与可观测性
- 幂等与并发控制:使用Redis 分布式锁(10分钟)防止同一会话被并发处理;使用消息 Hash (MD5) 实现去重,TTL 为7天。
- 可观测性:提供运行概览、记忆类型分布、时间趋势、Top Agents 等查询能力,用于日常巡检和异常定位。检索准确率、信息时效性、跨用户隔离、有效记忆占比
RAG
优化方向
| 方向 | 主要做法 | 解决什么问题 |
|---|---|---|
| 检索与索引 | BM25 + Embedding 混合检索;先召回再 rerank;索引分片、动态更新、元数据过滤 | 兼顾关键词匹配和语义覆盖,提高检索相关性,保持知识更新 |
| 生成控制 | 按任务设置 Prompt 模板;资料不足时明确说明;事实一致性校验;结构化输出、引用和副模型复核 | 减少无依据回答,提升输出一致性与可追溯性 |
| Query 理解与路由 | 意图识别、多轮上下文融合、Query 改写与扩展;选择知识库、联网或数据库路径 | 减少歧义和无效检索,让问题进入合适的处理链路 |
| 吞吐与稳定性 | 异步与批量调用;高频 Query 缓存;模块独立部署;延迟监控、超时熔断与降级 | 降低响应时间和调用成本,提高并发承载能力,避免局部异常拖垮系统 |
| 评估与反馈 | 自动离线评估;记录用户评分和失败案例;将高风险、低置信度回答纳入后续训练样本池 | 找到薄弱环节,持续改进 Query、检索和生成策略 |
原文列举的评估指标包括 BLEU、ROUGE、MRR、Coverage 和 Latency。
Query Understanding:先把问题读懂
规则 → 轻量分类模型 → 低置信度时 LLM 兜底
不要每个 Query 都拿大模型做分类。
1 | |
意图识别
1 | |
不确定性处理
1 | |
高准确率场景
1 | |
意图偏移
意图识别解决的是:当前这一轮是什么 意图?
1 | |
触发
1 | |
实体偏移
1 | |
Harness 需要保存这些state
1 | |
实体提取
一些像什么订单号等特定之类,其实可以直接前端之类直接传,不用走下面的流程
1 | |
LLM 复杂、上下文相关的抽取: 复杂语义补全,不是替代所有实体提取。
1 | |
Normalize / Entity Linking : 光提取字符串不够, 实体链接 需要一个实体库
1 | |
Validation / Confidence : 过度解析可能比不解析更危险,置信度不足时宁可回退原始 Query。
1 | |
| 环节 | 常用现成工具 | 适合干什么 |
|---|---|---|
| Entity Extraction / NER | spaCy、GLiNER、Transformers NER | 人名、公司、产品、行业等实体抽取 |
| 字符串 Normalize / Fuzzy Match | RapidFuzz | 别名、拼写差异、模糊字符串匹配 |
| 日期 / 数字 / 时间 Normalize | dateparser、Duckling 类解析器 | “昨天”“最近30天”“五十万”等转标准值 |
| Entity Linking | spaCy EntityLinker | mention → KB candidate → unique ID |
| Record / Entity Resolution | AWS Entity Resolution、Reltio、OpenRefine Reconciliation | CRM/customer/product 等跨库实体合并、去重 |
| 自定义企业实体库搜索 | Elasticsearch / OpenSearch + Vector DB | alias + BM25 + vector 候选召回 |
RAG 召回差,先别急着换 Embedding
1 | |
离线知识库决定上限
不要:
1 | |
更合理:
1 | |
Chunk 的目标不是“长度统一”,而是:
尽量做到一个 Chunk 是一个完整、可独立理解的语义单元。
Rerank 提升 Precision / Ranking,但前提是正确文档已经进入候选集。
这是比较标准的一套:
1 | |
如果业务明显偏向某一路:
1 | |
α 不靠感觉,应该:
1 | |
文章里的案例也是这么做,而不是拍一个固定权重
Generation 层也必须控制
正确文档召回了,不代表 LLM 一定会正确使用。
所以 Prompt 应明确:
1 | |
还可以做:
1 | |
但需要:
1 | |
避免 RAG 自己进入循环。
TextSQL
1 | |
Dynamic Schema , 不要把全库 Schema 都给模型 , 全部 Schema → Prompt
1 | |
Text2SQL 也需要自己的“小型 RAG”,但检索对象是 Schema。
SQL Validation 是硬约束
1 | |
结构
1 | |
这里应该用 Runtime 代码强制,不靠 Prompt。
Result Validation
1 | |
Text2SQL 失败也走 Agent 的 Tool 容错体系
agent 评测和优化
flowchart LR
A["离线评测<br/>守住已知问题"] --> B["上线 / 变更"]
B --> C["在线评测 + 在线监控<br/>发现未知问题"]
C --> D["Case 挖掘 + 归因<br/>定位问题"]
D --> E["修 Agent"]
D --> F["修评测标准 / 评测集"]
E --> A
F --> A
G["Trace / Observability"] --- A
G --- C
G --- D
flowchart LR
A["线上真实流量"] --> B["Trace / Monitoring"]
B --> C["Case Mining"]
C --> D["Good Case"]
C --> E["Bad Case"]
D --> F["Golden Set"]
E --> G["Root Cause Analysis"]
G --> H["Fix Agent"]
G --> I["Fix Rubric / Eval Set"]
H --> J["Offline Regression"]
I --> J
F --> J
J --> K{"Gate PASS?"}
K -->|Yes| L["Shadow / A-B"]
K -->|No| H
L --> A
1 | |
1 | |
评测资产则主要是:
1 | |
Trace → Trajectory:统一评测数据底座
Trace 侧重调用链与性能观测,Trajectory 侧重完整任务执行过程;两者都可以用于调试、评估和归因。
- Trace:通过 Span 记录 LLM、Tool、RAG 等调用关系、耗时、Token、错误及上下文信息。
- Trajectory:按时间顺序组织 Agent 的任务输入、交互步骤、Tool Call、Observation 和最终结果。
- ATIF(Agent Trajectory Interchange Format):标准化 JSON 轨迹格式,统一表示不同 Agent 的执行记录,便于评估、回放、可视化和训练。
数据标准化流程
flowchart LR
A["Agent Framework"] --> B["OTel Trace / 原生日志"]
B --> C["转换与标准化"]
C --> D["ATIF Trajectory"]
A -->|原生支持| D
D --> E["Evaluation / Dataset / RCA"]
- 采集层:通过 OTel、SDK、Hook 或框架原生能力获取运行数据。
- 标准化层:统一调用关系、步骤、工具输入输出和标识符。
- 轨迹层:按 ATIF 或自定义统一 Schema 保存任务过程,通过
extra扩展业务字段。 - 消费层:评估与回放系统不必逐一适配底层 Agent Framework。
ATIF 是数据交换格式,不是采集框架,也不是执行引擎。
注意:格式统一不代表可以完整复现。 仍需额外管理外部环境、工具响应、Context Snapshot 和相关版本。
数据管线:CPU 规则清洗 + LLM 语义加工
flowchart LR
A["Trace / Trajectory"] --> B["CPU 规则清洗"]
B --> C{"需要语义分析?"}
C -->|否| D["规则标签 / 统计"]
C -->|是| E["LLM 语义加工"]
D --> F["Case Pool / Dataset"]
E --> F
| CPU 确定性处理 | LLM 语义加工 |
|---|---|
| Schema 标准化 | 意图识别 |
| 精确去重 | 主题聚类 |
| 错误码、超时识别 | 复杂失败分类 |
| Token / Latency 统计 | 业务语义标注 |
| 脱敏、规则过滤 | 风险语义判断 |
不需要把所有 Trace 都交给 LLM。 确定性问题直接用规则识别,只有需要语义理解的 Case 才进入 LLM 加工。
回放需要保存什么
至少关联:
task_id / session_id / run_id / trace_idagent_version / model_version / prompt_versiontool_name / tool_args / tool_resultcontext_snapshot / environment_snapshotsteps / observation / final_answer / outcome
原始 Trace 保留可追溯引用;Trajectory 用于下游结构化消费。
关键:统一数据格式不等于能够完全复现。 回放还必须控制模型版本、工具响应、外部环境和执行时可用的证据。
Agent 评测到底评什么
长程 Agent 不能只看 Final Answer。
| 层级 | 关注什么 | 例子 |
|---|---|---|
| Result / Outcome(任务执行结束后,真实环境最终变成了什么状态。而不是单单模型输出) | 最终事情有没有办成 | 文件是否真正生成、订单是否真正创建 |
| Trajectory / Process | 中间路径是否合理 | Tool 是否选对、步骤是否多余 |
| Efficiency | 成本是否合理 | Token、耗时、Tool Calls、Steps |
| Risk / Safety | 有没有越权或危险动作 | 非授权写操作、错误删除数据 |
长期 Agent 最终应该验证 Environment State / Outcome,不能只验证模型自己声称“完成了”。
短程 Agent 主要评“Answer”,长程 Agent 要同时评“Trajectory (整条执行轨迹) + Outcome(最终转态)”。
不只看 Task Success 平均值,还看失败率分布、严重问题比例、不同任务类型与执行阶段的变化,逐层下钻到 Trace 和 Evidence。
所以评测数据从:
短agent
1 | |
长agent
逐渐变成:
1 | |
这正是长程 Agent 评测最核心的变化
Agent-as-a-Judge:工具增强型评估
传统 LLM-as-a-Judge 主要根据输入、输出和 Rubric 评分。
Agent-as-a-Judge 将评估器本身设计为 Agent,可以调用 Tool、Skill 和企业知识验证真实执行结果。
| 方式 | 适用场景 |
|---|---|
| Code Judge | Schema、规则、实际环境状态等确定性检查 |
| LLM Judge | 回答质量、语义相关性等 |
| Agent Judge | 需要工具调用、外部事实核验的复杂业务任务 |
| Human Judge | 高风险案例、争议判定和评估器校准 |
flowchart LR
A["Task + Trajectory + Rubric"] --> B["Agent Judge"]
B --> C["调用 Tool / Skill / Knowledge"]
C --> D["核验执行证据"]
D --> E["Score + Reason + Evidence"]
例如 Coding Agent 声称完成代码修复:
- LLM Judge:判断代码和文字说明是否合理。
- Code Judge:运行测试、检查文件和程序退出状态。
- Agent Judge:根据任务要求选择必要的验证工具,结合测试结果和业务约束完成综合评估。
优先使用确定性验证,不要让 LLM Judge 代替可以用代码检查的事实。
Judge 自身也需要版本管理
建议记录:
1 | |
- 固定输入和证据 Snapshot,对比 Judge V1/V2。
- Judge 改版不等于 Agent 质量提升。
- 高风险评分需要人工校准,重点关注误报、漏报和严重分歧。
- Judge 输出必须能够关联原始证据,支持复核。
Agent Judge 的执行边界: 默认使用只读 Tool、证据快照和隔离环境进行验证。涉及写操作时,应通过 Mock、Sandbox 或受控测试环境执行,避免评估过程本身修改真实业务状态。
评测集怎么设计
一个 Task 基本可以理解成:
1 | |
rubrics 复杂标准要拆成二元的
| 类型 | 回答什么问题 |
|---|---|
| E2E Evaluation | 这件事情最终有没有办成 |
| Process Evaluation | 如果没办成,中间哪一步坏了 |
客观指标和 LLM Judge 不应该二选一:高频、结构化、可规则化的部分尽量客观评测;开放性和复杂业务判断使用主观评测,并用人工对齐机器评测
| 场景 | 评测方式 |
|---|---|
| Schema 是否正确 | 代码 |
| Tool 是否调用正确 | Trace Rule |
| 是否越权 | Policy Rule |
| SQL 是否执行成功 | 程序 |
| 文件是否创建 | Environment Check |
| 回答是否自然 | Human / LLM Judge |
| 分析是否有洞察 | Expert / LLM Judge |
| 是否忠实使用证据 | Rule + LLM Judge |
相同输入、相同 Rubric 下的人工与 LLM 独立评分:严重问题检出能力 , 误报情况,评测标准是否足够明确、是否分歧严重程度、严重评分反转比例、F1 score
Weighted Kappa 则考虑评分偏差有多严重,并校正随机一致带来的影响。
对于有序的 0/1/2 分数,可以使用 Quadratic Weighted Kappa(QWK)。
| 分歧 | 严重程度 | 二次加权惩罚 |
|---|---|---|
| 0 vs 0 | 无 | 0 |
| 0 vs 1 | 轻 | 0.25 |
| 0 vs 2 | 严重 | 1.00 |
数据集生命周期:Baseline / Test / Regression / Post-train
现有的黄金集、错题集、挑战集、必过集是按样本特征与风险划分。
还需要按工程用途管理:
| 数据集 | 主要用途 |
|---|---|
| Baseline(基准集) | 模型切换、大版本变更时进行质量基线比较 |
| Test(测试集) | Bad Case 复现、局部修复与优化验证 |
| Regression(回归集) | Prompt / Tool / Skill / Knowledge 变更后防止历史问题复发 |
| Post-train(后训练集) | 从高质量轨迹与专家标注中构造 SFT / RL 数据 |
flowchart LR
A["线上 Trajectory"] --> B["Case Mining / 标注"]
B --> C["Baseline / Test / Regression"]
B --> D["Post-train"]
C --> E["评估 / 回归验证"]
D --> F["模型后训练"]
关键原则:
- 数据集必须版本化,保存来源、标注、Rubric 和适用任务。
- 参与优化的样本与最终独立验证样本应合理隔离,避免数据泄漏。
- Good Case 不等于天然正确的训练样本,仍需验证其 Outcome 和过程质量。
- Post-train 数据需要额外进行质量筛选、格式转换与安全审查。
离线/在线评测
离线
-
模型、Prompt、Skill、Memory、Context Manager 等任何东西改变,都应该重新跑固定评测集
-
要控制变量,多次测试(agent随机性)
在线
- 在线评测主要有:
1 | |
- 监控主要看:
1 | |
Evaluation Harness
跑评测:准备 Task、执行/回放、收集 Trace/Outcome、调用 Grader、汇总结果
你的 Harness 最好至少记录,最低要求:一个 Bad Case 出来以后,你能不能完整复现它到底发生了什么。
保证评测的是当时真实可用的证据,而不是回放时重新检索出的新数据。需要更严格地区分输入变化和评测器变化(最好版本控制)。
使用同一份 Snapshot 对比 Judge V1/V2
测试集保存字段
1 | |
Release Gate:评测结果怎样决定是否发布
Gate 不只是判断平均分是否上升,而是同时验证质量、成本、稳定性和安全边界。
| 维度 | 判定要求 |
|---|---|
| Task Success | 达到预设业务成功率目标 |
| Critical Regression | 核心必过样本不得退化 |
| Safety | 高危越权和严重违规不得放行 |
| Cost | 单次成功任务成本不能超出预算 |
| Latency | P95 / P99 满足业务要求 |
| Reliability | Tool 错误率、超时率不能明显恶化 |
Gate 执行原则
- 锁定 Baseline:固定评测集、Rubric、环境及旧版本。
- Offline Regression:验证已知任务和历史失败案例,通过离线门禁。
- Shadow / 小流量 A/B:在真实业务分布中验证候选版本;涉及写操作时需要防止影子流量产生副作用。
- Release Gate:根据线上质量、成本、稳定性和安全指标决定是否扩大流量。
- Release / Rollback:通过后逐步放量,发现重大退化立即停止或回滚。
对于成功率、时延等有波动的指标,需要结合样本量、置信区间和多次运行结果,不要依赖一次随机测试。
硬门禁与软指标分开:
- 硬门禁:严重安全违规、关键必过案例失败,直接阻断。
- 软指标:成本、延迟、一般质量变化,根据业务阈值与统计证据判断。
核心目标:防止局部优化导致整体退化。
flowchart LR
A["候选版本"] --> B["离线回归"]
B --> C{"Offline Gate"}
C -->|通过| D["Shadow / 小流量 A-B"]
C -->|失败| X["拒绝"]
D --> E{"Release Gate"}
E -->|通过| F["逐步放量"]
E -->|失败| G["停止 / 回滚"]
Case 处理
线上出现:用户投诉 (只能发现用户主动反馈的问题),监控异常(发现有指标的问题),Judge Fail,规则命中(只能发现你已经想到的问题),随机抽样(发现你完全没想到的问题)
都应该进入:Case Pool
1 | |
不能只收 Bad Case, 这样好和差才有标准。强调随机抽样不能完全去掉
定位问题不能,随便改。Bad Case 也可能是 Rubric 判错了,而不是 Agent 错了。
1 | |
Experience Loop:从失败修复到经验资产化
现有两个闭环:
- Agent Loop:发现失败 → RCA → 修改 Agent → 回归。
- Evaluation Loop:发现评测盲区 → 修改 Rubric / Dataset → 重新验证。
还可以增加:
- Experience Loop:从真实轨迹提取有效经验 → 验证 → 沉淀为可复用的 Skill / Rule / Strategy。
flowchart LR
A["线上真实 Trajectory"] --> B["成功 / 失败案例分析"]
B --> C["经验提取"]
C --> D["Skill / Rule / Strategy"]
D --> E["离线回归"]
E --> F{"验证通过?"}
F -->|Yes| G["版本化经验库"]
F -->|No| B
G -->|按需召回| H["下一次 Agent 执行"]
Memory、Skill、Experience 的区别
| 概念 | 主要保存什么 |
|---|---|
| Memory | 用户、任务、历史环境等事实信息 |
| Skill | 可复用的任务执行方法或操作流程 |
| Experience | 从实际执行结果中总结并验证的有效经验 |
例如 Coding Agent 多次处理 CUDA Kernel 性能问题:
1 | |
经验不能直接自动写入 Skill
必须检查:
- 适用条件:什么任务、环境和输入下有效?
- 执行证据:是否真的改善了 Outcome?
- 失败边界:在哪些场景下不适用?
- 版本依赖:依赖什么 Tool、Model、环境?
- 回归结果:是否对其他任务造成退化?
Agent 自进化的三个阶段
| 阶段 | 实现方式 |
|---|---|
| 专家优化 | 专家复盘、修改 Prompt / Tool / Skill |
| AI 辅助优化 | AI 根据归因生成建议,人工审核并验证 |
| 经验驱动复用 | 验证通过的经验沉淀到 Skill / Rule / Strategy,按需加载 |
这里的自进化不等于 Agent 自己修改模型权重。
本质是让成功经验持续进入下一次执行,使 Agent 的运行能力能够在明确边界内逐步改善。
生产上建议:先实现经验自动提取和人工审核,再考虑自动发布,避免错误经验污染整个系统。
工程问题
Agent 失败不是只有模型问题。
1 | |
不同层对应不同恢复方式。Recovery 必须有 Budget, 不能无限重试
| Layer | Recovery |
|---|---|
| API | retry / backoff / fallback model |
| Context | compact / repair history |
| Tool | retry / fallback / validation |
| Control Flow | checkpoint / cancel / resume |
| Environment | permission check / human approval |
Trace First Error
问题定位 : 固定其他变量
- 交换模型,观察性能变化,判断系统是否严重依赖模型能力。
- Harness 组件不同组件关闭,定位哪个 Harness 组件真正贡献
不要看最后错误,要找到第一次偏离正确轨迹的位置。
例如最终:
1 | |
可能原因:
1 | |
Evaluation 指标
1 | |
断开
SSE 断了,但 Agent 服务器还活着
-
Checkpoint 能告诉你:Agent 当前 State
-
但不能告诉客户端:断线期间漏掉了哪些 streaming token/event
run_id + resumable stream
1 | |
客户端保存: thread_id 表示“一条长期会话/状态线”;run_id 表示“这条状态线上某一次具体执行”。
1 | |
断线前:
1 | |
重连:
1 | |
Server: 从 103 开始补
Agent Server 自己 Crash
容器重启:
1 | |
当前 Node 可能从头重跑。所以 Tool side effects 必须幂等的
主动停
interrupt() 恢复以后:不是从 interrupt() 下一行精确恢复 CPU 指令。而是:重新进入包含 interrupt 的 Node
执行到这里:
1 | |
用户半小时后点:
1 | |
你:
1 | |
就继续
机制
1 | |
取消
把 Run 状态直接改成 cancelled,并不能让正在执行的代码、线程或远程 Tool 自动停下来。
1 | |
Worker 至少要在:尽快阻止后续步骤。
1 | |
结果提交也必须防“迟到成功” : 谁先在数据库事务里完成有效提交,谁赢。
还可能发生:
1 | |
所以最终提交必须再次检查:
1 | |
提交
使用idempotency_key (客户端这次业务意图 ID,通常是调用方在“用户产生一次新的业务意图”时生成,最常见就是随机 UUID。), 防止创建多个任务 UNIQUE (org_id, idempotency_key)
使用 same key + same input hash 这是同一次请求重试。相同key,不同hash (409 IDEMPOTENCY_CONFLICT)
为什么不用 input_hash 作为唯一键
因为:同样输入,不一定代表同一次执行意图
比如用户觉得第一次生成不好,点:重新生成
输入完全相同,但这是一次新的业务动作。