327 lines
14 KiB
Markdown
327 lines
14 KiB
Markdown
# 从一次支付超时诊断看 Harness 如何控制 Agent
|
||
|
||
这篇文章不从组件清单开始，而是跟随一次真实请求，看 Agent 如何完成诊断，以及 Harness 在每个关键节点控制了什么。
|
||
|
||
先说最终结果：这次请求正常执行了两轮 Agent、调用了两个 Tool，两个 Tool 都返回了候选证据，但最终没有发布诊断结论，而是安全地返回了 Fallback。
|
||
|
||
这不是一次“什么都没做成”的失败。恰恰相反，它展示了 Harness 最重要的价值：**即使 Agent 已经写出答案，只要证据无法完成验真，答案就不能越过发布出口。**
|
||
|
||
第一次阅读只看第 1、2、8、9 和 13 节即可：先知道问题和主流程，再看为什么被挡下、用户最终收到什么。其余章节用于展开每一步的组件设计。
|
||
|
||
## 1. 这次诊断从什么问题开始
|
||
|
||
用户请求是：
|
||
|
||
> 支付接口最近出现超时。在给出结论前必须实际调用 `lookup_knowledge` 和 `query_logs` 各一次，日志范围使用 APPLICATION 并查询 `payment-service error slow database`；随后结束诊断，证据不足时明确说明缺口。
|
||
|
||
这是一个很典型的 AIOps 问题。用户看到的是“支付超时”，但可能原因很多：
|
||
|
||
- 数据库连接池耗尽；
|
||
- 下游服务响应过慢；
|
||
- Redis 或网络超时；
|
||
- JVM、线程池或 CPU 资源异常；
|
||
- 只是历史知识中的相似案例，并非当前生产故障。
|
||
|
||
如果只有 Agent，它可以查询资料、阅读日志并写出一个听起来合理的解释。但系统还必须回答：查询是否属于本次请求、结果能否被引用、引用是否支持结论，以及证据不足时应该怎样结束。
|
||
|
||
## 2. 先看完整故事
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
Q["用户报告支付超时"] --> R["创建 Run<br/>建立身份、预算和取消"]
|
||
R --> I["Router 判定为 DIAGNOSIS"]
|
||
I --> A1["Agent 第 1 轮<br/>选择知识库和日志 Tool"]
|
||
A1 --> T["ToolBoundary<br/>执行、投影并保存调用真相"]
|
||
T --> A2["Agent 第 2 轮<br/>根据观察结果生成 Draft"]
|
||
A2 --> E["EvidenceGuard<br/>验证引用真实性"]
|
||
E -->|"本次未通过"| F["SafeFallback<br/>不发布未经验证的根因"]
|
||
F --> U["SSE content + done FALLBACK"]
|
||
```
|
||
|
||
沿着这条线，可以把双方职责简单分开：
|
||
|
||
| 阶段 | Agent 在做什么 | Harness 在控制什么 |
|
||
|---|---|---|
|
||
| 请求开始 | 尚未参与 | 创建 Run，固定身份、deadline、预算和取消 |
|
||
| 意图路由 | 尚未诊断 | 限制 Router 输入、调用次数和重试 |
|
||
| 选择 Tool | 提出查询计划 | 检查 Run、进展协议、重复 scope 和 Tool 权限 |
|
||
| Tool 返回 | 阅读有界观察 | 保存 canonical truth，限制 bytes，只投影必要字段 |
|
||
| 生成 Draft | 写出候选报告 | 限制输出结构和大小，Draft 尚不可发布 |
|
||
| 验证发布 | 不再拥有决定权 | 验引用、验语义，决定报告或 Fallback |
|
||
| 请求结束 | 执行结束 | 固化终态、持久化结果、记录 Trace 和 Token |
|
||
|
||
下面逐步展开。
|
||
|
||
## 3. 第一步：Harness 先创建 Run
|
||
|
||
请求进入 `ChatApplicationUseCase` 后，系统不会立即调用 Agent，而是先创建本次执行的 `RunContext`。
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
S["sessionId<br/>多轮对话容器"] --> R["runId<br/>本次独立执行"]
|
||
R --> D["deadline"]
|
||
R --> B["RunBudget"]
|
||
R --> C["RunCancellation"]
|
||
R --> L["RunLifecycle"]
|
||
R --> P["ProgressTracker"]
|
||
```
|
||
|
||
为什么不能只使用 sessionId？因为同一个会话可以连续提出多个问题。Tool Call、Agent Step、Evidence 和最终结果都必须属于某一个精确 Run，否则上一轮日志可能被下一轮报告误引用。
|
||
|
||
为什么要在 Agent 之前创建预算和取消能力？因为 Router、Agent、Tool 和 SemanticGuard 都会消耗时间或资源。只有共享同一个 RunContext，系统才能统一回答“还能不能继续执行”。
|
||
|
||
这一阶段最重要的不是创建了几个对象，而是确定了一条规则：
|
||
|
||
> 后续任何模型调用、Tool 调用和发布动作，都必须证明自己仍属于这个 active Run。
|
||
|
||
## 4. 第二步：Router 只决定走哪条路
|
||
|
||
用户问题先经过 Intent Router。它只判断请求属于：
|
||
|
||
```text
|
||
SYSTEM_CHAT
|
||
KNOWLEDGE_QUERY
|
||
DIAGNOSIS
|
||
```
|
||
|
||
本次结果是 `DIAGNOSIS`，于是 `ChatApplicationUseCase` 将同一个 RunContext 交给 `DiagnosisChatExecutor`。
|
||
|
||
Router 不读取完整历史，不调用业务 Tool，也不尝试回答支付超时的根因。这样设计是为了避免“路由”在不知不觉中变成一个简化版诊断 Agent。
|
||
|
||
即便只是路由，Harness 仍然控制它的输入大小、timeout、Token、显式 retry 和 Trace。因为一次隐藏的模型重试，同样会造成成本和延迟无法解释。
|
||
|
||
## 5. 第三步：Agent 决定查什么，Harness 决定能不能查
|
||
|
||
Diagnosis Agent 第 1 轮读取用户问题和服务端注册的 Tool schema，随后发出两个 Tool Call：
|
||
|
||
```text
|
||
lookup_knowledge
|
||
query_logs
|
||
```
|
||
|
||
这里仍然由 Agent 负责业务判断：它认为需要先查排障知识，再查看应用日志。Harness 不会用固定工作流替它安排“先 RAG、再日志”。
|
||
|
||
但 Agent 发出 Tool Call 不等于后端会立即执行。调用先经过 `HarnessToolInterceptor`：
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
TC["Agent Tool Call"] --> A{"Run 仍 active?"}
|
||
A --> P{"上一轮进展协议正确?"}
|
||
P --> D{"scope 是否重复或已饱和?"}
|
||
D --> B{"ToolBoundary 权限与预算允许?"}
|
||
B -->|"全部通过"| X["执行 Tool backend"]
|
||
A -->|"否"| STOP["拒绝调用"]
|
||
P -->|"否"| STOP
|
||
D -->|"否"| STOP
|
||
B -->|"否"| STOP
|
||
```
|
||
|
||
这就是 Harness 与工作流引擎的区别：
|
||
|
||
- 工作流引擎决定下一步必须调用什么；
|
||
- Harness 不替 Agent 选下一步，只检查这一步是否满足执行条件。
|
||
|
||
## 6. 第四步：Tool 返回的不是一份数据，而是三种视图
|
||
|
||
两个 Tool 都通过 `ToolBoundary`。它统一完成 Run 归属、Tool 授权、只读约束、调用预算、结果 bytes、canonical 状态和长期审计检查。
|
||
|
||
后端原始结果不会直接返回给 Agent，而是形成三种用途不同的视图：
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
RAW["Tool Raw Result"] --> C["Canonical Invocation<br/>当前 Run 的短期完整真相"]
|
||
C --> CV["Control View<br/>状态、证据数量、scope"]
|
||
C --> MO["Model Observation<br/>Agent 可见的有界内容"]
|
||
C --> EG["EvidenceGuard<br/>独立验真来源"]
|
||
C -.-> AU["Durable Audit<br/>长期只保存元数据"]
|
||
```
|
||
|
||
为什么要分开？
|
||
|
||
- Agent 需要的是能继续推理的少量事实，不需要 Redis key、预算阈值和全部 raw；
|
||
- EvidenceGuard 需要独立于 Agent 上下文读取真实调用记录；
|
||
- 线上审计需要状态、耗时和 bytes，但不应该永久复制日志正文。
|
||
|
||
本次真实 Run 中：
|
||
|
||
| Tool | InvocationStatus | EvidenceStatus | 说明 |
|
||
|---|---|---|---|
|
||
| `lookup_knowledge` | `READY` | `EVIDENCE_FOUND` | 找到了候选排障知识 |
|
||
| `query_logs` | `READY` | `EVIDENCE_FOUND` | 返回了候选日志内容，但数据源明确为 Mock |
|
||
|
||
这两个结果只能证明“查询成功并返回候选内容”，不能证明“已经找到支付超时的生产根因”。尤其 Mock 日志不能被包装成生产环境事实。
|
||
|
||
## 7. 第五步：Agent 写出 Draft，但 Draft 还不是报告
|
||
|
||
Tool Observation 回到 ReAct 上下文后，Agent 进入第 2 轮模型调用并生成结构化 `DiagnosisDraft`。
|
||
|
||
真实 Trace 中可以看到：
|
||
|
||
```text
|
||
Agent Step 0：has_text=false，发出 lookup_knowledge 和 query_logs
|
||
Agent Step 1：has_text=true，不再调用 Tool
|
||
```
|
||
|
||
到这一步，Agent 的职责已经完成：它收集了观察结果，并根据这些内容写出候选结论、分析和限制。
|
||
|
||
但 Harness 把它称为 Draft，而不是 Report。原因是模型输出还没有证明：
|
||
|
||
- 引用的 `tool_call_id` 属于当前 Run；
|
||
- 引用对应的调用已经 `READY`；
|
||
- 引用内容确实存在于 canonical result；
|
||
- 真实证据足以支持用户可见结论。
|
||
|
||
如果此时直接通过 SSE 返回，前面所有 canonical store 和 Guard 设计都失去了意义。
|
||
|
||
## 8. 第六步：EvidenceGuard 挡住了这次发布
|
||
|
||
Release Pipeline 首先调用 EvidenceGuard。它不调用模型，而是通过代码检查 Draft 的结构、引用闭包、Run 归属、Tool 状态和 evidence 内容。
|
||
|
||
本次结果没有通过 EvidenceGuard。公开 SSE 没有泄露具体内部违规字段，只给出了稳定结果：
|
||
|
||
```text
|
||
FallbackType = EVIDENCE_VALIDATION_FAILED
|
||
message = 当前证据无法完成真实性校验，无法确认根因
|
||
verified_sources = []
|
||
```
|
||
|
||
这意味着系统不能把 Agent Draft 中的引用提升为已验真证据。既然第一层确定性验证都没有通过，后续 SemanticGuard 就没有可信输入，也不应继续讨论结论是否“语义上合理”。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
D["DiagnosisDraft"] --> E{"EvidenceGuard"}
|
||
E -->|"通过"| S["SemanticGuard<br/>检查证据是否支持结论"]
|
||
E -->|"本次未通过"| F["EVIDENCE_VALIDATION_FAILED"]
|
||
S -->|"SUPPORTED"| OK["发布原 Draft"]
|
||
S -->|"UNSUPPORTED"| SF["语义不支持 Fallback"]
|
||
```
|
||
|
||
这里最值得注意的是：两个 Tool 都成功了，Agent 也成功输出了 Draft，但 Release 仍然拒绝发布。
|
||
|
||
```text
|
||
Tool READY
|
||
不等于 EvidenceGuard 通过
|
||
EvidenceGuard 通过
|
||
不等于 SemanticGuard SUPPORTED
|
||
SemanticGuard SUPPORTED
|
||
才可能发布正常诊断报告
|
||
```
|
||
|
||
## 9. 第七步：Fallback 是安全结果，不是技术失败
|
||
|
||
EvidenceGuard 未通过后，`SafeFallbackFactory` 由代码构造公开内容。它没有让另一个模型“重新写得保守一点”，也没有复用 Draft 中未经验证的根因。
|
||
|
||
用户最终收到：
|
||
|
||
```json
|
||
{
|
||
"content_type": "SAFE_FALLBACK",
|
||
"fallback": {
|
||
"type": "EVIDENCE_VALIDATION_FAILED",
|
||
"conclusion": null,
|
||
"message": "当前证据无法完成真实性校验，无法确认根因",
|
||
"verified_sources": [],
|
||
"limitations": ["证据引用校验未通过"],
|
||
"next_steps": ["重新收集当前诊断范围内的证据后再发起诊断"]
|
||
}
|
||
}
|
||
```
|
||
|
||
SSE 顺序完整结束：
|
||
|
||
```text
|
||
metadata
|
||
-> status ROUTING
|
||
-> status DIAGNOSIS_RUNNING
|
||
-> status SAFETY_VALIDATING
|
||
-> content SAFE_FALLBACK
|
||
-> done FALLBACK
|
||
```
|
||
|
||
数据库记录则是：
|
||
|
||
```text
|
||
diagnosis_run.status = SUCCESS
|
||
diagnosis_run.release_outcome = FALLBACK
|
||
```
|
||
|
||
两者并不矛盾：`status=SUCCESS` 表示请求被系统正常、安全地处理完毕；`release_outcome=FALLBACK` 表示没有正常诊断结论可以发布。
|
||
|
||
## 10. 这次 Run 最终留下了什么
|
||
|
||
| 项目 | 真实结果 |
|
||
|---|---|
|
||
| sessionId | `mvp-demo-payment-timeout-stage7-20260722-1741` |
|
||
| runId | `363f481c-33b8-42e7-8699-428a6ec61806` |
|
||
| 总耗时 | 35,996 ms |
|
||
| 总 Token | 11,764 |
|
||
| Agent Step | 2 |
|
||
| Tool Invocation | 2 |
|
||
| Tool 结果 | 两次均 `READY / EVIDENCE_FOUND` |
|
||
| 最终内容 | `SAFE_FALLBACK` |
|
||
| ReleaseOutcome | `FALLBACK` |
|
||
| FallbackType | `EVIDENCE_VALIDATION_FAILED` |
|
||
|
||
长期审计保留的是 Run、Agent Step、Tool 状态、耗时和 Token 等有界信息。模型 Thought 保持为空，完整 Tool raw 也不会因为排障方便就永久进入普通 Trace。
|
||
|
||
因此这次 Run 虽然没有根因结论，却仍然可以回答：谁执行了什么、用了多少资源、在哪一层停止、为什么没有发布以及用户最终收到了什么。
|
||
|
||
## 11. 如果验证通过，后续会发生什么
|
||
|
||
本次真实路径在 EvidenceGuard 结束。为了理解完整设计，可以继续看通过分支：
|
||
|
||
1. EvidenceGuard 生成 `VerifiedEvidenceSnapshot`；
|
||
2. SemanticGuard 只接收用户问题、Draft 语义和已验真证据；
|
||
3. SemanticGuard 输出 `SUPPORTED / UNSUPPORTED`，不能改写报告；
|
||
4. 只有 `SUPPORTED` 才发布 Agent 原 Draft；
|
||
5. `UNSUPPORTED` 或 Guard 不可用时发布对应 SafeFallback。
|
||
|
||
这条分支不是本次支付超时 Run 的真实结果，因此这里只说明当前代码协议，不把它写成已经发生的事实。
|
||
|
||
## 12. 这次案例体现了哪些设计决策
|
||
|
||
### 决策一：Agent 拥有推理权，不拥有发布权
|
||
|
||
Agent 可以选择 Tool、解释 Observation 和撰写 Draft，但不能决定 Draft 是否直接交给用户。否则模型既是作者又是最终审批者。
|
||
|
||
### 决策二：Tool 成功与结论成立必须分层
|
||
|
||
`READY + EVIDENCE_FOUND` 只描述一次 Tool 调用。EvidenceGuard 和 SemanticGuard 分别处理引用真实性与结论支持度，避免一个含糊的 `SUCCESS` 贯穿全链路。
|
||
|
||
### 决策三：系统保留事实，模型只拿观察
|
||
|
||
Canonical Invocation 为当前 Run 保存完整真相；Agent Observation 只服务推理。Guard 不依赖模型看到的裁剪版本进行自证。
|
||
|
||
### 决策四：证据不足也应正常结束
|
||
|
||
不是所有诊断都能找到根因。Fallback 把“不能安全下结论”转换成稳定产品行为，而不是抛出技术异常或让模型猜一个答案。
|
||
|
||
### 决策五：审计记录控制事实，不复制思维过程
|
||
|
||
系统需要可回放，但不需要永久存储 Chain of Thought、完整 Prompt 和所有 raw payload。可观测性本身也必须有数据边界。
|
||
|
||
## 13. 用一句话复述这次案例
|
||
|
||
> 用户提出支付超时问题后，Harness 为请求建立独立 Run，允许 Diagnosis Agent 自主调用知识库和日志 Tool，并将完整调用事实保存在系统边界内；Agent 根据有界 Observation 写出 Draft 后，EvidenceGuard 发现引用无法完成真实性校验，Release 因此拒绝发布根因，转而返回确定性的 SafeFallback。整个请求正常结束、过程可回放，但未经验证的结论没有离开系统。
|
||
|
||
理解这句话，就理解了 Harness 的核心：**它不保证 Agent 每次都找到答案，但保证系统只对能够证明的答案负责。**
|
||
|
||
## 14. 事实来源与延伸阅读
|
||
|
||
本文案例数据来自：
|
||
|
||
- `mvp/demo/requests/payment-timeout-chat.json`；
|
||
- `mvp/demo/output/stage7-20260722-1741/chat-sse.txt`；
|
||
- `mvp/demo/output/stage7-20260722-1741/trace-response.json`；
|
||
- `devflow/projects/2026-07-22-single-react-cleanup-e2e/evidence.md`。
|
||
|
||
继续理解具体机制：
|
||
|
||
- [Harness 入门](README.md)
|
||
- [组件渐进式导读](components/README.md)
|
||
- [Tool 双视图](Harness-Tool双视图-从原始结果到可验证证据.md)
|
||
- [证据安全链](Harness证据安全链-从引用真实到结论可发布.md)
|
||
- [生命周期与状态](Harness生命周期与状态.md)
|
||
|
||
需要查看另一条真实 `SUCCESS` 路径及详细 Token、RAG 和 Trace 数据，阅读[一次诊断全流程 E2E 导读](../diagnosis/一次诊断全流程-E2E导读.md)。
|