YG-Soft/X-Financial

Fork 0

Files

caoxiaozhu 4f3556a38b docs: 新增agent开发文档和风险评估文档

2026-05-15 06:58:21 +00:00

2.9 KiB

Raw Blame History

可观测性与 Agent Run Trace

1. 目标

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

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

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

2. Agent Run Trace

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

建议结构：

{
  "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. 需要记录的版本

每次运行都要记录：

ontology_schema_version
semantic_parser_prompt_version
model_name
model_version
rule_version
skill_version
mcp_version
knowledge_snapshot_version
orchestrator_version

原因：

用户可能问：

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

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

4. Tool Call Trace

每个工具调用都记录：

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

敏感字段应脱敏。

5. 运行状态

建议枚举：

pending
running
success
partial_success
failed
cancelled
waiting_confirmation

6. Hermes 可观测性

Hermes 任务需要额外记录：

task_code
schedule_time
data_snapshot_id
records_scanned
rules_executed
mcp_calls
risk_items_generated
knowledge_candidates_generated
retry_count

示例：

{
  "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 需要额外记录：

conversation_id
page_context
user_confirmation
draft_created
business_object_id

8. 前端审计视图

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

展示：

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

详情页展示：

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

9. 告警

需要告警的情况：

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

10. 开发步骤

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

2.9 KiB Raw Blame History Unescape Escape