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

## 适用范围

客服、投顾、风控 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
```