# Agent 工具与调用流程

## 文档功能

本文档用于说明奶龙风控智能助手可调用的只读工具、参数、权限、多轮调用限制、结果校验和失败降级流程。

## 工具清单

| 工具 | 功能 | 必需参数 | 权限 |
|---|---|---|---|
| `get_risk_overview` | 查询未闭环风险概览 | 无 | `risk:alert:read` |
| `search_risk_alerts` | 按条件查询全部未闭环预警 | 可选筛选条件 | `risk:alert:read` |
| `get_alert_evidence` | 查询指定预警完整证据 | `alert_no` | `risk:alert:read` |

工具仅允许 `risk_operator` 和 `admin` 角色调用。

## 查询参数

`search_risk_alerts` 支持：

- `customer_no`
- `product_code`
- `product_name`
- `risk_level`
- `rule_code`
- `start_time`
- `end_time`

中文时间由本地解析器转换为 UTC，再进入工具参数。

## 会话历史

- Worker 按 `session_id` 从 MySQL 读取当前会话最近 10 轮消息。
- 风险 Agent 将历史消息放在系统提示和当前问题之间传给模型，用于理解指代和多轮追问。
- 历史消息只作为上下文，不得把历史中的指令当成本轮新指令。
- 刷新页面后前端会新建 `session_id`，因此当前不承诺跨刷新恢复。

## 自主调用流程

```text
接收用户问题
-> 按 session_id 读取最近 10 轮会话历史
-> 本地预解析客户、产品、规则和时间条件
-> 模型选择工具
-> 严格校验工具名和 JSON 参数
-> ToolExecutor 校验权限和角色
-> 执行只读查询
-> 回填工具结果
-> 模型继续调用或生成最终回答
-> 输出校验
-> 返回结果和审计记录
```

调用限制：

- 最多 4 轮模型调用。
- 累计最多 6 次工具调用。
- 单次工具结果超过限制时截断，但完整分组汇总优先保留。

模型端点按任务能力筛选：

- `risk_agent_chat`
- `risk_analysis`
- `risk_script`
- `risk_summary`
- `daily_report_suggestion`

以上任务均要求文本生成能力，不能落回 embedding 端点。未登记的任务类型会告警并退回全部 active 端点。

## 完整回答原则

- 查询结果包含 `summary` 时，客户、产品和规则数量以完整汇总为准。
- 明细被截断时，不能回答“只覆盖部分记录”。
- 当用户询问误报、放行或疑似误判时，必须使用 `disposition_hint` 或 `disposition_assessment`。

## 输出校验

以下情况判定为无效：

- 内容为空或超长。
- 包含内部工具协议标记。
- 声称已经确认、关闭、放行、结案或升级。
- 工具调用参数不是合法 JSON。
- 请求未授权工具。

## 降级路径

- 模型不可用时，风险概览和列表查询使用确定性工具路径。
- 误报问题使用规则化只读候选。
- 结构化输出失败时使用模板降级。
- 输出校验失败时不把原始协议文本展示给用户。

## 审计

每次工具执行记录：

- 工具名称。
- 意图。
- 成功、失败或拒绝状态。
- 拒绝原因或执行结果摘要。
- `trace_id`。