group_fqcd_jr/docs/14-Agent组员统一接入说明书.md

# Agent 组员统一接入说明书

> 版本：v1.0  
> 适用对象：客服、投顾、风控及其他业务 Agent 开发人员  
> 阅读要求：组员开发 Agent 前必须完整阅读本文。

本文是业务组员接入底座的统一入口，整合了底座启动、Agent 注册、公共执行链、模型、意图、工具、
适当性、基金行情和提交验收要求。接口字段以《05-接口文档.md》为准，数据库以《00-新数据库基线设计.md》
和《02-数据库建表设计.md》为准。

## 1. 你负责什么，底座负责什么

业务 Agent 属于 MVC+S 架构的 Service 层。组员只负责业务意图、业务编排和业务输出，不负责重建公共底座。

组员负责：

- `AgentDefinition`；
- 继承 `BaseAgent` 的业务类；
- `handle()` 内的业务判断和编排；
- 业务只读工具声明及测试；
- 注册表登记；
- 业务边界和权限测试。

底座负责：

- JWT、RBAC、入口和客户范围校验；
- 配置快照和记忆召回；
- 意图分类和低置信处理；
- 模型路由、密钥引用和 fallback；
- 工具权限、超时、审计和来源引用；
- 适当性校验；
- 合规审查、敏感信息脱敏；
- 运行持久化、Outbox、SSE 和恢复。

业务范围只包括场内基金模拟交易。场外运营必须独立建表、独立接口，不得写入场内交易表。

## 2. 接入前提

项目使用 Python 3.13：

```powershell
conda activate jr_py313
pip install -r requirements.txt
```

复制配置模板并填写本机环境：

```powershell
Copy-Item .env.example .env
```

启动 HTTP 服务和 Worker：

```powershell
python -m uvicorn app.main:app --host 127.0.0.1 --port 8099
python -m app.worker
```

数据库迁移只能通过 Alembic：

```powershell
alembic upgrade head
python tools/audit_schema.py
```

`.env`、JWT 私钥、模型 API Key 不得提交到 Git。

## 3. 定义 Agent

`agent_type` 必须使用小写蛇形命名，例如 `customer_service`、`advisor`、`risk`。
`supported_intents` 列出该 Agent 支持的全部意图；配置中心不能扩大代码中声明的工具上限。

```python
from app.core.contracts import AgentDefinition, AgentRequest, CoreResult, RequestContext
from app.service.agent.base import BaseAgent


class AdvisorAgent(BaseAgent):
    definition = AgentDefinition(
        agent_type="advisor",
        version="1.0.0",
        allowed_roles=("customer", "advisor", "operator", "admin"),
        allowed_portals=("api",),
        allowed_tools=("query_fund_quote",),
        supported_intents=("fund_quote", "general"),
    )

    async def handle(self, request: AgentRequest, context: RequestContext) -> CoreResult:
        return CoreResult(text="业务处理结果")
```

业务类只实现 `handle()`。不要覆盖 `execute()`、鉴权、配置、记忆、意图分类、模型、工具或合规方法。

## 4. 注册 Agent

在 `app/service/agent/bootstrap.py` 的统一注册入口登记：

```python
factory.register(
    AdvisorAgent.definition,
    lambda _context: AdvisorAgent(AdvisorAgent.definition),
)
```

HTTP 服务和 Worker 使用同一个工厂，不能各自维护注册表。构造器必须返回 `BaseAgent`，且实例的
`AgentDefinition` 必须与注册定义完全一致。

注册完成后必须通过：

```powershell
python -m pytest tests/contract/test_agent_factory_contract.py -q -p no:cacheprovider
```

未注册的 Agent 类型会返回 `404 AGENT_TYPE_NOT_FOUND`。

## 5. 公共执行顺序

每次运行固定经过：

```text
输入校验
→ JWT/RBAC/入口/客户范围校验
→ 读取发布配置
→ 召回授权记忆
→ 自动意图分类
→ 执行 handle()
→ 模型、工具和适当性治理
→ 引用、禁止表达和敏感信息审查
→ complete_run 同事务持久化、审计和 Outbox
→ 查询/SSE 返回结果
```

组员只能读取 `self.config`、`self.memories`、`request` 和服务端生成的 `context`。客户身份以 `context`
为准，不信任客户端自行传入的身份字段。

## 6. 意图分类

组员不需要创建 `IntentClassifier`、调用 `ModelRouterService` 或传 `endpoints`。底座会在 `handle()`
前从当前激活的模型端点自动分类，并把结果写入 `CoreResult.intent`。

模型输出必须是严格 JSON：

```json
{"intent":"fund_quote","confidence":0.92}
```

底座会校验：

- 意图必须属于 `supported_intents`；
- `confidence` 必须在 0 到 1；
- 低于配置阈值时 `needs_clarification=true`；
- 非法 JSON、未声明意图和空输入失败关闭。

低置信结果不能当作确定意图继续执行高风险业务。

## 7. 模型调用

模型链路固定为：

```text
ConfigRelease → ModelRouterService → ModelGateway → 主端点/受控 fallback
```

业务 Agent 只能调用底座注入的方法：

```python
result = await self.generate_with_model(endpoints, prompt)
```

禁止：

- 导入 `httpx` 或供应商 SDK；
- 自己读取模型密钥；
- 自己选择未批准端点；
- 把模型原始异常返回给用户。

模型密钥只能使用 `secret_ref`，不能写入代码、数据库明文、日志或接口响应。

## 8. 公共工具调用

工具必须通过工厂注入的 `ToolExecutor` 调用：

```python
value = await self.call_tool(
    "工具名",
    {"参数": "值"},
    intent="当前意图",
    context=context,
)
```

每个工具必须声明 Pydantic 输入模型、权限码、允许角色、只读属性和超时。底座统一执行参数校验、
意图白名单、角色权限、超时、脱敏摘要、审计和来源引用。

## 9. 基金行情工具

底座已提供公共只读工具：

```text
工具名：query_fund_quote
权限码：fund:quote:read
允许角色：customer、advisor、operator、risk_operator、admin
```

### 9.1 代码和配置声明

在 AgentDefinition 中声明：

```python
allowed_tools=("query_fund_quote",)
supported_intents=("fund_quote", "general")
```

在已发布配置中声明：

```text
namespace: agent_tools
config_key: <agent_type>:fund_quote
value_json: {"allowed_tools": ["query_fund_quote"]}
```

### 9.2 调用方式

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

返回结果重点关注：

- `quote_source`：`eastmoney`、`cache` 或 `degraded`；
- `is_intraday`：是否盘中行情；
- `degraded`：是否降级；
- `nav_date`：净值对应日期。

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

禁止直接导入 `hq.py`、调用东方财富 URL、使用 `httpx` 或自行读取行情缓存。

## 10. 适当性校验

投顾相关流程必须调用公共 `SuitabilityService` 或 `check_suitability` 工具，不得复制 C1-C5/R1-R5
规则。客户风险等级低于产品风险等级、测评过期时必须拒绝；专业投资者也不能绕过审计。

通过和拒绝决定都会写入 `interaction_audit`，服务只读，不修改交易、产品或客户风险资料。

## 11. 记忆、关系和转人工

- 记忆提取由 `complete_run()` 在同一事务写入 Outbox，组员不直接调用提取服务；
- 记忆只能读取当前客户授权范围；
- Neo4j 查询必须经过 `RelationshipService` 和关系白名单；
- Agent 只能提出转人工请求，不能分配、接单、解决或关闭工单；
- 不能伪造 `SourceReference`，只能引用本次授权召回或工具真实返回的数据。

## 12. 禁止事项

- 禁止绕过 `AgentFactory`、`BaseAgent`、统一鉴权、记忆、模型、工具、合规、审计和事件流程；
- 禁止直接创建 SQLAlchemy Session、访问 MySQL、Redis、Milvus 或 Neo4j Driver；
- 禁止代客下单、确认成交、修改持仓、审核方案、处置或关闭风险预警；
- 禁止把场外运营数据写入场内交易表；
- 禁止重命名、删除或修改已有数据库表和字段；数据库需求只能新增表或字段并先对照基线。

## 13. 提交前测试

业务 Agent 至少覆盖：

- 正常意图、低置信意图和模型格式错误；
- 未授权角色、入口、权限和客户范围；
- 工具白名单、参数错误、超时和失败关闭；
- 适当性通过、风险不匹配和测评过期；
- 行情正常、缓存、降级和非交易时段；
- 禁止表达、敏感信息脱敏、来源引用和最终持久化。

统一验收命令：

```powershell
python -m pytest -q -p no:cacheprovider
python -m ruff check app tests tools alembic
python -m mypy app
python tools/check_authoritative_docs.py
python tools/audit_schema.py
```

## 14. 当前状态

公共行情工具 `query_fund_quote` 已注册并可供业务 Agent 使用，但业务 Agent 必须完成自己的代码声明、
意图白名单配置和注册后才能调用。当前没有注册的业务 Agent 不能直接提交运行。

推荐阅读顺序：本文 → 《05-接口文档.md》→ 对应业务域流程文档。本文不替代接口文档和数据库基线。