170 lines
6.4 KiB
Markdown
170 lines
6.4 KiB
Markdown
|
# 业务组员 Agent 接入使用说明书
|
|||
|
|
|
|||
|
|
> 版本：v1.0｜适用对象：客服、投顾、风控及其他业务 Agent 开发人员
|
|||
|
|
|
|||
|
|
## 1. 先记住三条原则
|
|||
|
|
|
|||
|
|
1. 业务 Agent 是 MVC+S 中的 Service，只负责业务意图和业务编排。
|
|||
|
|
2. Agent 必须继承 `BaseAgent`，只能由公共 `AgentFactory` 创建。
|
|||
|
|
3. 业务代码不得自行创建模型客户端、读取密钥、创建数据库连接或绕过工具、记忆、合规、审计流程。
|
|||
|
|
|
|||
|
|
当前业务范围是场内基金模拟交易；场外运营必须使用独立表和独立接口，不得写入场内交易表。
|
|||
|
|
|
|||
|
|
## 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` 为准。
|
|||
|
|
|
|||
|
|
## 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/查询返回结果
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 意图分类
|
|||
|
|
|
|||
|
|
组员不需要创建分类器或传 `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》为准。
|