Multi-Tenant Agent Service

多租户智能助手服务系统 — 架构总览

接 入 层
🌐

Web Chat UI

主要交互界面，支持富文本、文件上传、流式输出

Next.js shadcn/ui SSE / WebSocket
📱

Mobile / 小程序

移动端入口，复用同一套 API

React Native REST API
🤖

IM Webhook

飞书 / 钉钉 / Slack / 企业微信 Bot 接入

Webhook OAuth 2.0
⚙️

Open API

第三方系统集成，支持 API Key 认证

REST API Key
网 关 层
🛡️

API Gateway

统一入口：JWT 认证 → 租户识别 → 速率限制 → 路由分发。所有请求经过这里，实现租户级隔离和流量控制。

FastAPI Nginx / Traefik JWT Rate Limiter Redis
核 心 服 务
🧠

Agent Engine

核心循环：接收用户消息 → 组装 Context → 调用 LLM → 解析 Tool Use → 执行工具 → 循环直到完成

Claude API Tool Use Async Loop
💭

Memory Service

三大能力：
1. 自动提取 — 每轮对话后台异步提取记忆
2. 向量检索 — 语义相似度 + 关键词 + 时间衰减
3. 分类存储 — user / preference / project / reference / knowledge

Embedding pgvector Haiku (提取) Hybrid Search
📖

Knowledge Service

外部知识整合：
用户文档 → Parse (PDF/DOCX/XLS) → Chunk → Embed → Store
网络检索 → Search → Extract → 结构化缓存
统一 RAG 检索注入对话上下文

unstructured Voyage-3 pgvector S3 / MinIO Web Search
能 力 层
⚡

Skill System

YAML/Markdown 定义技能，安装/卸载/市场分发。每个 Skill 包含 prompt + 所需 tools + 触发条件。

YAML Frontmatter Skill Store
🔧

Tool Runtime

标准化工具接口：JSON Schema 定义输入，统一 execute() 执行。内置 + 自定义 + MCP 工具。

JSON Schema MCP Sandbox
💬

Session Manager

会话持久化 + 自动压缩。超过 token 阈值时用 LLM 摘要历史，保留最近消息 + 重新注入关键文档。

Context Compact PostgreSQL Redis Cache
🏢

Tenant Manager

租户隔离：独立配置 / 模型选择 / Token 额度 / 工具权限 / Skill 安装 / 计费统计

PostgreSQL Row-Level Security
基 础 设 施
💾

PostgreSQL + pgvector

租户/用户/配置/会话 + 记忆&文档的向量检索

⚡

Redis

会话缓存 / 速率限制 / 实时消息队列

📦

S3 / MinIO

用户上传文档的原始文件存储

🚀

Celery Workers

异步任务：文档解析 / 记忆提取 / 定时任务

🐋

Docker / K8s

容器化部署，按租户弹性扩缩容

Agent 核心循环流程

📩 用户发送消息
(含可选文件上传)
入口处理：文件上传 → 解析 → 分块 → Embedding 存储
文本消息进入 Agent Loop
🔍 检索相关记忆
Memory Retrieval
混合检索：向量相似度(0.7) + BM25关键词(0.2) + 时间衰减(0.1)
返回 Top-5 相关记忆，注入 System Prompt
📚 检索外部知识
Knowledge RAG
语义检索 + 重排序：从文档库与网络检索中获取相关知识片段
Token 预算控制 (~5000 tokens)，截断策略
🏗️ 组装 Context
Context Builder
System Prompt = 基础指令 + 租户配置 + Skill Prompt + 记忆 + 知识片段
Messages = 会话历史（可能已压缩） + 当前用户消息
💡 调用 LLM
Claude API (tool_use)
流式响应：SSE 推送给前端
判断：stop_reason == "end_turn" → 结束
       stop_reason == "tool_use" → 进入工具执行
↩ tool_use: 执行工具后回到 LLM
🛠️ 执行 Tool
权限检查 → 执行 → 返回结果
权限模型：deny → allow → ask (租户级 + 用户级)
执行沙箱：工具在隔离环境运行，结果追加到 messages
循环：结果返回 LLM，继续推理（最多 20 轮）
✅ 返回响应
后处理（并行、不阻塞响应）：
1. 保存会话 + 按需触发 Context Compact
2. 异步提取记忆（Haiku 模型，低成本）
3. 用量统计 + 计费记录
Multi-Tenant Agent Service Architecture — 2026.04