group_fqcd_jr/docs/13-基金行情工具业务接入清单.md

基金行情工具业务接入清单

适用范围

客服、投顾、风控 Agent 如需查询场内基金行情，统一使用公共工具 query_fund_quote。 本清单只规范接入方式，不创建业务 Agent，也不替业务组实现具体意图。

业务组员需要完成的事项

1. 在 AgentDefinition 声明工具

allowed_tools=("query_fund_quote",)

工具权限不能通过数据库配置扩大。代码声明是上限，发布配置只能缩小范围。

2. 声明业务意图

在 supported_intents 中加入业务自己的意图，例如：

supported_intents=("fund_quote", "general")

然后在已发布配置中，将本 Agent 的 fund_quote 意图允许使用：

{
  "allowed_tools": ["query_fund_quote"]
}

配置键格式为：

agent_tools / <agent_type>:fund_quote

3. 在 handle 中调用公共工具

quote = await self.call_tool(
    "query_fund_quote",
    {"fund_codes": ["159511"], "limit": 20},
    intent="fund_quote",
    context=context,
)

不得导入 hq.py、httpx、东方财富 URL 或自行读取行情缓存。

4. 处理降级结果

必须识别以下字段：

• quote_source：eastmoney、cache 或 degraded；
• is_intraday：是否盘中数据；
• degraded：是否处于降级状态；
• nav_date：净值对应日期。

降级行情只能用于说明或分析，不能当作成交、委托、持仓或实时保证。

业务边界

• 客服：可以解释行情字段和数据时间；
• 投顾：可以基于行情做分析，但仍须通过适当性校验；
• 风控：可以查询行情辅助风险分析；
• 所有 Agent：不得代客下单、修改持仓、确认成交或改变交易数据。

提交前检查

• AgentDefinition.allowed_tools 包含 query_fund_quote；
• supported_intents 包含实际使用的意图；
• 发布配置只允许必要的工具；
• 正常、未授权、未配置白名单、超时和降级测试齐全；
• 回答没有把行情当成成交确认；
• 没有直接调用外部行情接口；
• 注册表契约测试通过。

底座负责人验收命令：

python -m pytest tests/contract/test_agent_factory_contract.py -q -p no:cacheprovider
python -m ruff check app tests tools alembic
python -m mypy app