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：

conda activate jr_py313
pip install -r requirements.txt

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

Copy-Item .env.example .env

启动 HTTP 服务和 Worker：

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

数据库迁移只能通过 Alembic：

alembic upgrade head
python tools/audit_schema.py

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

3. 定义 Agent

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

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 的统一注册入口登记：

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

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

注册完成后必须通过：

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

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

5. 公共执行顺序

每次运行固定经过：

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

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

6. 意图分类

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

模型输出必须是严格 JSON：

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

底座会校验：

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

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

7. 模型调用

模型链路固定为：

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

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

result = await self.generate_with_model(endpoints, prompt)

禁止：

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

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

8. 公共工具调用

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

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

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

9. 基金行情工具

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

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

9.1 代码和配置声明

在 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"]}

9.2 调用方式

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

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

统一验收命令：

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》→ 对应业务域流程文档。本文不替代接口文档和数据库基线。