group_fqcd_jr/docs/11-业务组员Agent接入使用说明书.md

# 业务组员 Agent 接入使用说明书

> 版本：v1.0｜适用对象：客服、投顾、风控及其他业务 Agent 开发人员
>
> 📌 **接入请以 `docs/14-Agent组员统一接入说明书.md` 为准**（它是唯一推荐入口）。
> 本文是同一套教学序列的**早期版本**，保留作历史参考；两者冲突时以 `14` 为准。

## 1. 先记住三条原则

1. 业务 Agent 是 MVC+S 中的 Service，只负责业务意图和业务编排。
2. Agent 必须继承 `BaseAgent`，只能由公共 `AgentFactory` 创建。
3. 业务代码不得自行创建模型客户端、读取密钥、创建数据库连接或绕过工具、记忆、合规、审计流程。

当前业务范围是场内基金模拟交易；场外运营必须使用独立表和独立接口，不得写入场内交易表。

## 1.1 当前可用的公共行情工具

底座已经注册公共只读工具 `query_fund_quote`，可供客服、投顾和风控 Agent 使用。它已经接入
`ToolRegistry → ToolExecutor → AgentFactory`，会统一执行权限、角色、意图白名单、参数校验、
超时、审计、来源引用和行情降级处理。

注意：工具已在底座注册，不代表所有业务 Agent 自动拥有它。业务 Agent 必须在代码和发布配置中
显式声明后才能调用；当前没有注册的业务 Agent 仍不能直接提交运行。

## 2. 组员需要提交什么

每个 Agent 接入至少提交以下内容：

- `AgentDefinition`：类型、版本、角色、入口和支持的意图；
- 一个继承 `BaseAgent` 的类，只实现 `handle()`；
- 业务输入/输出 DTO（如有）；
- 业务只读工具声明和处理器（如有）；
- 在公共注册入口登记的一行 `factory.register(...)`；
- 单元测试、权限测试、低置信意图测试和业务边界测试。

不得修改 `BaseAgent.execute()`、`classify_intent()`、`generate_with_model()`、`call_tool()`、
鉴权、记忆召回和合规审查逻辑。

## 3. 接入流程

```text
定义 AgentDefinition
→ 实现 BaseAgent.handle()
→ 在公共 bootstrap 注册
→ 配置 Agent 意图和工具白名单
→ 编写契约/业务测试
→ 运行全量验收
```

### 3.1 定义 Agent

`agent_type` 使用小写蛇形命名，例如 `customer_service`、`advisor`、`risk`。
`supported_intents` 必须列出所有允许的意图；数据库配置不能扩大这份代码声明的权限。

```python
class AdvisorAgent(BaseAgent):
    definition = AgentDefinition(
        agent_type="advisor",
        version="1.0.0",
        allowed_roles=("customer", "advisor", "operator", "admin"),
        allowed_portals=("api",),
        allowed_tools=("check_suitability",),
        supported_intents=("fund_explanation", "risk_check", "general"),
    )
```

### 3.2 实现 `handle()`

业务类只实现 `handle(request, context)`，返回 `CoreResult`。执行前的鉴权、配置、记忆召回和意图
分类由底座完成；执行后的引用校验、敏感信息脱敏、禁止表达审查和审计由底座完成。

```python
async def handle(self, request: AgentRequest, context: RequestContext) -> CoreResult:
    if request.message.strip() == "":
        raise ValidationAgentError("业务消息不能为空")
    return CoreResult(text="业务处理结果")
```

不要在 `handle()` 中读取 `request` 之外的客户端身份字段。客户身份以服务端生成的 `context` 为准。

### 3.3 接入基金行情工具

如果业务需要查询基金行情，在 `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"]}
```

业务代码通过底座方法调用：

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

返回结果中的关键字段：

```text
quote_source: eastmoney | cache | degraded
is_intraday: 是否盘中行情
degraded: 是否降级
nav_date: 净值对应日期
```

`degraded=true` 时只能进行说明和分析，不能把结果表述为成交、委托、持仓或实时保证。
组员不得直接导入 `hq.py`、调用东方财富 URL、导入 `httpx` 或自行读取行情缓存。

## 4. 注册 Agent

在 `app/service/agent/bootstrap.py` 的统一注册位置登记。HTTP 服务和 Worker 会使用同一个工厂。
构造器必须返回定义完全一致的 `BaseAgent` 实例。

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

注册后必须通过 `tests/contract/test_agent_factory_contract.py`。未注册类型受理时返回
`404 AGENT_TYPE_NOT_FOUND`。

## 5. 底座自动执行的完整顺序

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

### 公共基金行情工具

底座已提供只读工具 `query_fund_quote`，权限码为 `fund:quote:read`，允许角色包括
`customer`、`advisor`、`operator`、`risk_operator` 和 `admin`。该工具内部负责外部行情请求、
盘中/收盘判断、短缓存和降级标记。组员只需在自己的 `AgentDefinition.allowed_tools` 和发布的
意图白名单中声明它，然后通过 `self.call_tool(...)` 调用，不得导入外部行情脚本。
行情白名单和缓存 TTL 可由已发布的 `fund_market/default` 配置调整；配置缺失或非法时底座自动使用
安全默认值，组员无需读取或解析配置中心。

### 意图分类

组员不需要创建分类器或传 `endpoints`。底座从当前激活的 `model_endpoint_config` 读取模型端点，
在 `handle()` 前自动分类，并把结果写入 `CoreResult.intent`。低于阈值时
`needs_clarification=true`，不得把低置信结果当成确定意图。

### 模型生成

模型调用只能通过底座注入的 `generate_with_model(...)`。模型路由、fallback、密钥解析和错误处理
由底座负责；组员不得导入 `httpx`、供应商 SDK 或直接读取环境变量密钥。

### 工具调用

工具必须是只读工具，并声明 Pydantic 输入模型、权限码、允许角色和超时。Agent 调用格式：

```python
value = await self.call_tool(
    "check_suitability",
    {"customer_risk_level": 3, "product_risk_level": 3},
    intent="risk_check",
    context=context,
)
```

底座会检查意图白名单、角色、权限和参数，记录脱敏摘要、来源引用及 `interaction_audit`。
工具不得执行下单、修改持仓、审核方案、关闭预警或改变客户资料。

### 适当性校验

必须调用公共 `SuitabilityService` 或已注册的 `check_suitability` 工具，不得复制 C1-C5/R1-R5
规则。客户风险等级低于产品风险等级、测评过期时必须拒绝；通过和拒绝都会审计。

## 6. 配置和权限

业务 Agent 的 `allowed_tools` 是代码上限，发布配置只能缩小权限。意图配置使用
`agent_intent_config`，工具白名单使用发布版本绑定的 `platform_config_item`。

所有写操作需要 JWT、权限和 `Idempotency-Key`；配置更新还需要 `If-Match`。业务 Agent 不得自行
绕过统一鉴权或创建管理接口。

## 7. 禁止事项

- 禁止覆盖 `execute()`、`validate_access()`、`resolve_config()`、`recall_memory()`、
  `classify_intent()`、`generate_with_model()`、`call_tool()`；
- 禁止直接访问 SQLAlchemy Session、MySQL、Redis、Milvus、Neo4j Driver；
- 禁止把模型 API Key 写入代码、数据库明文、日志或接口响应；
- 禁止伪造 `SourceReference`、引用未授权记忆或客户端传来的客户身份；
- 禁止 Agent 代客下单、确认成交、审核方案、处置/关闭风险预警；
- 禁止修改已有表名和已有字段；数据库需求只能新增表或字段，并先对照基线。

## 8. 测试和提交前检查

业务 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
```

接口字段以《05-接口文档.md》为准，数据库以《00-新数据库基线设计.md》和《02-数据库建表设计.md》为准。