Agent Runtime v1 设计

本文档定义货代行业通用智能 Agent 平台的 Runtime v1：以 ai_service 作为业务真相源，统一承载客服协同、单证智能、工具执行、自动任务与治理发布能力。

1. 设计结论

平台定位是行业 Agent Runtime，不是单点聊天应用。
运行时与控制面分层，低代码主要服务治理，不替代代码能力。
OCR、单证解析、定时任务、系统联动统一纳入插件协议。
用户操作与业务结果必须沉淀为长期记忆并可跨会话检索。
API 优先与自定义页面并存，前端实现可替换。
AI 生成代码是扩展加速器，但必须经过评测门禁与审批。

2. 产品目标与边界

2.1 目标能力

人机协同客服：AI 主答、人工接管、协作建议。
文档智能：OCR、分类、字段抽取、结构化落库。
多 Agent 协作：按角色分工处理复杂业务链路。
自动任务：定时触发与事件触发并存。
业务记忆：用户历史处理过程可沉淀与回溯。
系统互联：通过 MCP 与企业内外部系统打通。
定制交付：代码优先与低代码配置双轨协同。

2.2 主要用户角色

业务用户：消费稳定能力，关注效率与准确性。
管理员与实施团队：配置能力、发布策略、治理风险。
平台开发团队：维护内核、插件协议、评测体系。

2.3 非目标

不追求让终端业务用户直接编写复杂插件代码。
不在 v1 追求全自动无人审批的代码上线。
不将 demo 网关作为长期业务主入口。

3. 总体架构

3.1 分层模型

flowchart LR
  subgraph UseLayer[使用层]
    EndUser[业务用户]
    Operator[管理员与实施]
  end

  subgraph ExperienceLayer[体验层]
    OpenApi[开放接口]
    CustomUi[自定义页面]
    AdminUi[管理控制台]
  end

  subgraph ControlLayer[控制层]
    CapabilityConfig[能力配置]
    PolicyCenter[策略中心]
    ReleaseCenter[发布与回滚]
    EvalCenter[评测中心]
  end

  subgraph RuntimeLayer[运行时]
    ApiService[AI Service API]
    AgentKernel[Agent Kernel]
    MultiAgentRouter[多 Agent 路由]
    HilStateMachine[人机协同状态机]
    MemoryEngine[业务记忆引擎]
    PluginRuntime[插件运行时]
  end

  subgraph DataLayer[数据层]
    Postgres[PostgreSQL]
    Qdrant[Qdrant]
    Minio[MinIO]
    MemoryStore[Memory Store]
    AuditTrace[审计与追踪]
  end

  EndUser --> OpenApi
  EndUser --> CustomUi
  Operator --> AdminUi

  OpenApi --> ApiService
  CustomUi --> ApiService
  AdminUi --> CapabilityConfig

  CapabilityConfig --> ApiService
  PolicyCenter --> ApiService
  ReleaseCenter --> ApiService
  EvalCenter --> ApiService

  ApiService --> AgentKernel
  AgentKernel --> MultiAgentRouter
  AgentKernel --> HilStateMachine
  AgentKernel --> MemoryEngine
  AgentKernel --> PluginRuntime

  MemoryEngine --> MemoryStore
  PluginRuntime --> Postgres
  PluginRuntime --> Qdrant
  PluginRuntime --> Minio
  AgentKernel --> AuditTrace

3.2 真相源原则

ai_service 是唯一业务真相源。
前端、网关、适配层可以替换，不持有核心业务状态。
任意关键操作必须可追踪到 agent_id、session_id、trace_id。

4. Runtime 核心职责

4.1 AgentKernel

AgentKernel 负责稳定内核职责：

上下文装配与状态推进。
记忆召回与历史证据注入。
多 Agent 路由与调用预算控制。
策略执行与风险拦截。
插件结果聚合与回复生成。
统一审计与指标上报。

4.4 用户业务记忆系统

记忆分层

SessionMemory：单会话短期上下文。
UserMemory：用户长期偏好与历史处理习惯。
EntityMemory：业务实体记忆，如 shipment_no、bl_no、客户、航线。
TenantMemory：租户共享经验与规则沉淀。

写入机制

在 OCR、单证解析、工具执行、人工处理后抽取事实卡片。
事实卡片包含：事实类型、实体标识、结果摘要、证据来源、置信度。
所有记忆写入必须绑定 tenant_id、user_id、trace_id。

读取机制

回复前按 tenant_id + user_id + entity_id + intent 检索记忆。
采用结构化过滤加向量召回的混合检索。
模型输出建议时必须引用记忆证据，避免无依据推断。

4.2 多 Agent 编排推荐模板

FrontDeskAgent：意图识别、任务分发、澄清提问。
KnowledgeAgent：知识检索与引用生成。
DocumentAgent：OCR 与单证结构化抽取。
ActionAgent：工具调用与外部系统动作执行。
ComplianceAgent：规则核验、输出把关、风险阻断。

4.3 人机协同状态机

stateDiagram-v2
    [*] --> AI_ACTIVE
    AI_ACTIVE --> HUMAN_ACTIVE: agent_takeover
    HUMAN_ACTIVE --> AI_ACTIVE: agent_release
    HUMAN_ACTIVE --> CO_PILOT: copilot_enable
    CO_PILOT --> HUMAN_ACTIVE: copilot_disable
    CO_PILOT --> AI_ACTIVE: agent_release

运行要求：

每次状态切换必须落审计记录。
每次回复必须标记责任来源。
管理台必须支持会话回放与关键事件时间线。

5. 货代行业能力模型

5.1 行业能力域

能力域	标准能力	产出形式
客服协同	智能问答、接管、协作建议	对话消息、处理建议
单证智能	OCR、分类、字段抽取、结构化校验	JSON 结构化结果
知识运营	文档入库、切分、检索、引用	引用片段、证据链
业务记忆	历史事实沉淀、跨会话回溯、经验建议	记忆事实、回溯建议
系统联动	MCP 工具调用、状态回写、通知推送	工具调用记录
自动任务	定时任务、批处理、失败重试	任务报告、异常清单

5.2 v1 必备插件

OCRDocumentParserPlugin
FreightDocumentExtractionPlugin
FreightRuleValidationPlugin
ScheduleTaskDispatcherPlugin
ExternalSystemActionPlugin

6. 插件协议与扩展模型

6.1 插件协议目标

稳定约束输入输出与生命周期。
不限制内部算法、模型与实现细节。
支持插件版本演进与兼容性治理。

6.2 统一契约示例

from dataclasses import dataclass
from typing import Any

@dataclass(frozen=True)
class AgentRequest:
    agent_id: str
    session_id: str
    user_input: str
    attachments: list[dict[str, Any]]
    context: dict[str, Any]
    trace_id: str

@dataclass(frozen=True)
class AgentResponse:
    output_text: str
    tool_calls: list[dict[str, Any]]
    citations: list[dict[str, Any]]
    events: list[dict[str, Any]]
    metrics: dict[str, Any]
    trace_id: str

6.3 插件接口建议

from typing import Protocol

class SkillPlugin(Protocol):
    plugin_name: str
    plugin_version: str

    def validate(self, runtime_context: dict) -> None: ...
    def execute(self, agent_request: AgentRequest) -> AgentResponse: ...

6.4 插件元数据最小集

每个插件必须声明：

版本号与兼容范围。
输入输出 schema。
超时、重试、幂等策略。
权限范围与风险等级。
可观测字段映射。

7. API 与页面双轨交付

7.1 API 优先原则

所有核心能力先定义 API 契约，再提供 UI 封装。
自定义页面只做体验编排，不承担核心状态存储。
内外系统集成优先走 API 与事件接口。

7.2 页面自定义原则

页面通过 PageSchema 描述字段、动作、权限、数据源。
页面配置与业务能力解耦，可跨租户复用。
页面变更走灰度发布，确保可回滚。

8. 低代码与代码协同

8.1 角色分工

开发者：实现插件、复杂流程、适配器。
管理员：配置挂载、编排策略、发布审批。
业务用户：使用稳定功能并反馈业务规则变化。

8.2 低代码定位

低代码聚焦治理而非替代开发，主要包括：

能力开关与挂载。
权限与多租户隔离。
流程编排与执行策略。
灰度发布与回滚。
评测触发与报告查看。

9. AI 生成代码闭环

9.1 目标

把新增功能周期从“周级”压缩到“天级”，同时保持生产可控。

9.2 标准流程

管理员输入业务需求与验收条件。
AI 生成插件草稿与测试样例。
平台执行契约校验与安全扫描。
评测中心跑离线数据集并生成报告。
人工审批后灰度发布。
线上监控通过后全量放开。

9.3 不变约束

AI 生成代码不得绕过评测门禁。
高风险能力必须双人审批。
所有发布动作必须写审计日志。

10. 自动任务与调度模型

10.1 数据模型建议

task_definition：任务定义、触发条件、执行策略。
task_run：执行状态、耗时、trace、错误信息。
task_artifact：结构化结果、报告、附件快照。

10.2 调度原则

幂等优先：同一窗口只执行一次有效任务。
可恢复：支持退避重试与人工补偿。
可追踪：每次调度与执行都有完整链路。

11. 用户业务记忆模型

11.1 数据模型建议

memory_fact：记忆事实主表，保存事实摘要、类型、实体、责任来源。
memory_event_link：记忆与会话事件映射表，用于追溯证据。
memory_feedback：用户对建议结果的反馈表，用于记忆强化与衰减。

建议关键字段：

tenant_id、user_id、agent_id、session_id、trace_id
memory_scope、entity_type、entity_id
fact_payload_json、confidence_score、importance_score
created_at、last_accessed_at、expires_at

11.2 检索与排序策略

先按租户与权限过滤，再按实体与时间窗口过滤。
综合相似度、置信度、重要度、时效性进行重排。
命中结果超阈值时触发回溯建议模板。

11.3 生命周期策略

记忆支持 TTL 到期归档。
记忆支持用户删除与租户级清理。
高风险记忆项需要脱敏后方可共享。

12. 记忆能力 API 草案

12.1 写入接口

POST /memory/facts: 写入事实卡片。
POST /memory/events/link: 绑定事实与会话事件。
POST /memory/feedback: 记录建议反馈。

12.2 读取接口

POST /memory/search: 记忆检索与重排。
GET /users/{user_id}/memory/timeline: 用户记忆时间线。
GET /entities/{entity_type}/{entity_id}/memory: 实体历史回溯。

12.3 治理接口

DELETE /memory/facts/{memory_id}: 删除指定记忆。
POST /memory/purge: 按范围执行批量清理。
POST /memory/archive: 执行归档任务。

13. 数据与审计设计

13.1 数据分层

PostgreSQL：业务主状态与关系数据。
Qdrant：向量检索索引与过滤。
MinIO：原始文档与解析产物。

13.2 审计要求

会话级审计：输入、输出、责任来源。
工具级审计：参数、结果、错误、耗时。
发布级审计：版本、审批人、变更摘要。

14. 评测与发布门禁

14.1 三层评测

Agent 层：任务成功率、接管率、端到端时延。
RAG 层：召回率、引用准确率、无依据生成率。
Tool 层：调用成功率、超时率、参数校验通过率。

14.2 门禁示例阈值

Agent 任务成功率 >= 0.85
RAG Recall@5 >= 0.80
引用准确率 >= 0.90
Tool 调用成功率 >= 0.98
P95 端到端时延 <= 8s
Memory 命中后建议采纳率 >= 0.60
Memory 回溯证据准确率 >= 0.90

说明：阈值需要根据实际业务容错逐步收敛。

15. 与当前代码基线的映射

当前仓库中已具备以下基础能力：

Agent 与会话 API 能力。
知识库与文档入库能力。
MCP 服务挂载与审计能力。
RAG 检索与编排基础能力。
用户业务记忆能力尚未落库，需要新增模型与接口。

v1 下一步重点补齐：

任务调度模型与执行器。
OCR 与单证解析标准插件。
控制面低代码编排与发布能力。
AI 生成代码的评测与审批闭环。
记忆事实写入、召回、回溯与治理闭环。

16. 90 天落地计划

P0 第 1 到 3 周

冻结请求响应协议与插件元数据规范。
打通 trace_id 全链路。
建立最小评测闭环与报告输出。
完成记忆数据模型设计与首版写读接口。

P1 第 4 到 8 周

上线 OCR 与单证解析插件首版。
落地人机协同状态机审计视图。
实现定时任务定义、执行、重试、审计。
上线记忆检索重排与回溯建议模板。

P2 第 9 到 12 周

上线低代码治理控制面首版。
建立插件版本兼容与签名校验机制。
发布 AI 生成代码内测闭环。
上线记忆治理能力与记忆质量评测看板。

17. 架构验收标准

任意会话可回放并定位责任来源。
任意插件异常可追踪输入输出与耗时。
任意能力变更必须经过评测门禁。
任意前端替换不影响业务主状态完整性。
新行业需求可通过插件扩展，无需改动内核主流程。
任意建议可回溯到对应历史记忆证据。

延伸阅读

Agent Runtime 架构实现指南 - 基于 Chameleon 代码基线的详细实现方案，包含领域模型、编排引擎、数据流设计等