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: 增加异常告警规则
|
|||
|
|
```
|
|||
|
|
|