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 和权限校验摘要。
|