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. 接入流程

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

3.1 定义 Agent

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

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。执行前的鉴权、配置、记忆召回和意图 分类由底座完成；执行后的引用校验、敏感信息脱敏、禁止表达审查和审计由底座完成。

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

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

3.3 接入基金行情工具

如果业务需要查询基金行情，在 AgentDefinition 中声明：

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

然后在配置中心对应的已发布版本中允许：

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

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

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: 净值对应日期

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

4. 注册 Agent

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

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

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

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

输入校验
→ 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 调用格式：

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 至少覆盖：

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

提交前运行：

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》为准。