88 lines
2.3 KiB
Markdown
88 lines
2.3 KiB
Markdown
|
# 基金行情工具业务接入清单
|
|||
|
|
|
|||
|
|
## 适用范围
|
|||
|
|
|
|||
|
|
客服、投顾、风控 Agent 如需查询场内基金行情，统一使用公共工具 `query_fund_quote`。
|
|||
|
|
本清单只规范接入方式，不创建业务 Agent，也不替业务组实现具体意图。
|
|||
|
|
|
|||
|
|
## 业务组员需要完成的事项
|
|||
|
|
|
|||
|
|
### 1. 在 AgentDefinition 声明工具
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
allowed_tools=("query_fund_quote",)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
工具权限不能通过数据库配置扩大。代码声明是上限，发布配置只能缩小范围。
|
|||
|
|
|
|||
|
|
### 2. 声明业务意图
|
|||
|
|
|
|||
|
|
在 `supported_intents` 中加入业务自己的意图，例如：
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
supported_intents=("fund_quote", "general")
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
然后在已发布配置中，将本 Agent 的 `fund_quote` 意图允许使用：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"allowed_tools": ["query_fund_quote"]
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
配置键格式为：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
agent_tools / <agent_type>:fund_quote
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3. 在 handle 中调用公共工具
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
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` 包含实际使用的意图；
|
|||
|
|
- [ ] 发布配置只允许必要的工具；
|
|||
|
|
- [ ] 正常、未授权、未配置白名单、超时和降级测试齐全；
|
|||
|
|
- [ ] 回答没有把行情当成成交确认；
|
|||
|
|
- [ ] 没有直接调用外部行情接口；
|
|||
|
|
- [ ] 注册表契约测试通过。
|
|||
|
|
|
|||
|
|
底座负责人验收命令：
|
|||
|
|
|
|||
|
|
```powershell
|
|||
|
|
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
|
|||
|
|
```
|