187 lines
2.9 KiB
Markdown
187 lines
2.9 KiB
Markdown
# 可观测性与 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: 增加异常告警规则
|
||
```
|
||
|