金融 NL2SQL 工具接入说明

1. 工具定位

query_financial_data 是运营和投顾共用的金融只读 NL2SQL 工具。业务 Agent 只负责判断是否调用工具，不直接连库、不读取密钥、不自行写审计。

调用链固定为：

业务 Agent -> BaseAgent.call_tool -> ToolExecutor -> query_financial_data -> 金融只读表

2. 工具声明

业务 Agent 的 AgentDefinition.allowed_tools 需要包含：

allowed_tools=("query_financial_data",)
supported_intents=("financial_query", "general")

发布配置需要按意图开启工具白名单：

{
  "namespace": "agent_tools",
  "config_key": "<agent_type>:financial_query",
  "value_json": {"allowed_tools": ["query_financial_data"]}
}

工具权限码：

financial:nl2sql:read

允许角色：

advisor、operator、admin、super_admin

3. 调用示例

result = await self.call_tool(
    "query_financial_data",
    {"question": request.message, "dry_run": False, "limit": 50},
    intent="financial_query",
    context=context,
)

低置信度或模糊问题会返回：

{"status": "need_confirmation", "message": "请确认查询范围、指标口径和时间条件。"}

Agent 应把 message 原样返回给用户，等待用户补充或确认后再次调用，并传入 confirmation。

4. MVP 范围

当前纳入 NL2SQL 的表：

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

2.6 KiB Raw Blame History Unescape Escape