# 可观测性与 Agent Run Trace

## 1. 目标

Agent 系统必须可追踪、可回放、可解释。

财务系统中尤其需要回答：

- 为什么 Agent 得出这个结论？
- 用了哪个模型？
- 用了哪个规则版本？
- 调用了哪些 MCP？
- 查了哪些数据？
- 谁确认了动作？
- 失败在哪里？

## 2. Agent Run Trace

每次 Agent 运行都生成一个 run_id。

建议结构：

```json
{
  "run_id": "",
  "source": "user_message",
  "agent": "user_agent",
  "user_id": "emp_001",
  "raw_input": "",
  "ontology_json": {},
  "route_decision": {},
  "permission_result": {},
  "tool_calls": [],
  "final_output": "",
  "status": "success",
  "started_at": "",
  "finished_at": ""
}
```

## 3. 需要记录的版本

每次运行都要记录：

```text
ontology_schema_version
semantic_parser_prompt_version
model_name
model_version
rule_version
skill_version
mcp_version
knowledge_snapshot_version
orchestrator_version
```

原因：

用户可能问：

```text
为什么昨天和今天的结论不一样？
```

只有记录版本，才能解释。

## 4. Tool Call Trace

每个工具调用都记录：

```json
{
  "tool_call_id": "",
  "run_id": "",
  "tool_type": "mcp",
  "tool_name": "invoice_verify",
  "request_json": {},
  "response_json": {},
  "status": "success",
  "duration_ms": 820,
  "error_message": ""
}
```

敏感字段应脱敏。

## 5. 运行状态

建议枚举：

```text
pending
running
success
partial_success
failed
cancelled
waiting_confirmation
```

## 6. Hermes 可观测性

Hermes 任务需要额外记录：

```text
task_code
schedule_time
data_snapshot_id
records_scanned
rules_executed
mcp_calls
risk_items_generated
knowledge_candidates_generated
retry_count
```

示例：

```json
{
  "task_code": "daily_risk_scan",
  "records_scanned": 2146,
  "rules_executed": 8,
  "mcp_calls": 436,
  "risk_items_generated": 19,
  "status": "success"
}
```

## 7. User Agent 可观测性

User Agent 需要额外记录：

```text
conversation_id
page_context
user_confirmation
draft_created
business_object_id
```

## 8. 前端审计视图

建议后续增加“Agent 运行记录”页面。

展示：

- 运行时间。
- Agent 类型。
- 用户或任务。
- 语义解析结果。
- 调用工具。
- 运行状态。
- 耗时。
- 错误。

详情页展示：

- 原始输入。
- 本体 JSON。
- 路由决策。
- 工具调用链。
- 最终输出。

## 9. 告警

需要告警的情况：

- Hermes 任务连续失败。
- MCP 健康检查失败。
- 语义解析低置信度比例过高。
- 某规则误报率过高。
- Agent 调用耗时异常。
- 权限拒绝次数异常。

## 10. 开发步骤

```text
Step 1: 增加 agent_runs 表
Step 2: 增加 agent_tool_calls 表
Step 3: Orchestrator 每次执行创建 run_id
Step 4: 工具网关记录 tool call
Step 5: 前端增加运行记录页面
Step 6: 增加异常告警规则
```