106 lines
2.6 KiB
Markdown
106 lines
2.6 KiB
Markdown
|
# 金融 NL2SQL 工具接入说明
|
|||
|
|
|
|||
|
|
## 1. 工具定位
|
|||
|
|
|
|||
|
|
`query_financial_data` 是运营和投顾共用的金融只读 NL2SQL 工具。业务 Agent 只负责判断是否调用工具，不直接连库、不读取密钥、不自行写审计。
|
|||
|
|
|
|||
|
|
调用链固定为：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
业务 Agent -> BaseAgent.call_tool -> ToolExecutor -> query_financial_data -> 金融只读表
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 2. 工具声明
|
|||
|
|
|
|||
|
|
业务 Agent 的 `AgentDefinition.allowed_tools` 需要包含：
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
allowed_tools=("query_financial_data",)
|
|||
|
|
supported_intents=("financial_query", "general")
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
发布配置需要按意图开启工具白名单：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"namespace": "agent_tools",
|
|||
|
|
"config_key": "<agent_type>:financial_query",
|
|||
|
|
"value_json": {"allowed_tools": ["query_financial_data"]}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
工具权限码：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
financial:nl2sql:read
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
允许角色：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
advisor、operator、admin、super_admin
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 3. 调用示例
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
result = await self.call_tool(
|
|||
|
|
"query_financial_data",
|
|||
|
|
{"question": request.message, "dry_run": False, "limit": 50},
|
|||
|
|
intent="financial_query",
|
|||
|
|
context=context,
|
|||
|
|
)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
低置信度或模糊问题会返回：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{"status": "need_confirmation", "message": "请确认查询范围、指标口径和时间条件。"}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Agent 应把 `message` 原样返回给用户，等待用户补充或确认后再次调用，并传入 `confirmation`。
|
|||
|
|
|
|||
|
|
## 4. MVP 范围
|
|||
|
|
|
|||
|
|
当前纳入 NL2SQL 的表：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
sys_customer_assignment
|
|||
|
|
fin_customer_profile
|
|||
|
|
fin_risk_assessment
|
|||
|
|
fin_product
|
|||
|
|
fin_fee_rule
|
|||
|
|
fin_market_price
|
|||
|
|
fin_nav_history
|
|||
|
|
fin_holding
|
|||
|
|
fin_transaction
|
|||
|
|
fin_sim_order
|
|||
|
|
fin_sim_account
|
|||
|
|
fin_cash_ledger
|
|||
|
|
client_facing_content
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
第一期只支持只读查询；支持跨两个或三个业务域查询；支持历史范围查询。历史时点查询如果依赖当前快照表，例如 `fin_holding`、`fin_sim_account`、`sys_customer_assignment`，会拒绝执行。
|
|||
|
|
|
|||
|
|
## 5. 审计与持久化
|
|||
|
|
|
|||
|
|
工具输出包含 `audit`，其中有：
|
|||
|
|
|
|||
|
|
- `query_plan`：查询计划；
|
|||
|
|
- `generated_sql`：生成 SQL；
|
|||
|
|
- `permission_check`：权限校验结果；
|
|||
|
|
- `execution`：执行状态和返回行数。
|
|||
|
|
|
|||
|
|
`ToolExecutor` 会把这些摘要写入 `ToolCallRecord.output_summary`，公共运行持久化会最终写入 `conversation_message.tool_calls`。
|
|||
|
|
|
|||
|
|
## 6. 接入验收
|
|||
|
|
|
|||
|
|
运营或投顾 Agent 接入时至少验证：
|
|||
|
|
|
|||
|
|
- AgentDefinition 声明了 `query_financial_data`；
|
|||
|
|
- 发布配置按目标意图放行该工具；
|
|||
|
|
- 调用方角色具备 `financial:nl2sql:read`；
|
|||
|
|
- 模糊问题会先要求确认；
|
|||
|
|
- 生成 SQL 只包含 `SELECT`，且表名均在白名单内；
|
|||
|
|
- `conversation_message.tool_calls` 能看到查询计划、SQL 和权限校验摘要。
|