多智能体 AI 工具平台
技术底座与框架选型

背景与价值：为什么是"多 Agent + 工具集"

单 Agent 工具站、SaaS 工具集、纯 RAG 助手各有局限

多 Agent 协作 + 工具可插拔是当前唯一可扩展的形态。

• 单 Agent 的天花板 · 单 Agent 受限于上下文窗口与单次推理深度；面对多步、多工具、长流程任务时，指令遵循度与稳定性快速下降。上下文超过 32K 后指令漂移明显；多工具并行易产生循环调用；错误难定位、重放困难。
• SaaS 工具站的局限 · 各工具彼此孤立，无统一身份与权限模型；缺乏跨工具的工作流编排；用户必须自己串脚本。工具间数据不互通；计费 / 权限 / 审计分散；无法沉淀组织级 Agent 资产。
• 多 Agent 平台的优势 · 任务拆分到专用 Agent，工具按 Agent 粒度注册；通过协议（ACP / MCP）互通；天然适合企业级权限、计费、可观测。分工明确、可独立评测；工具可插拔，生态可扩展；统一 Trace、计费、权限。

4 大核心能力 · 决定我们要选什么、怎么搭

这 4 个能力象限决定了我们选什么、怎么搭、能不能撑住企业级落地。

1. 工具可插拔统一工具注册中心与协议适配层（Function Calling / MCP / OpenAPI），新增工具不改核心代码。决定技术栈：FastAPI / TS 工具网关 + JSON Schema。
2. 模型可路由多 LLM 厂商（OpenAI / Anthropic / 通义 / DeepSeek）按成本、延迟、能力动态路由，模型升级无感。决定技术栈：LiteLLM / 自研 Gateway + 降级策略。
3. Agent 可协作监督 / 对等 / 流水线 / 任务市场 4 种协作模式，复杂任务拆解为可独立执行的子任务流。决定技术栈：LangGraph / AutoGen 编排 + 消息总线。
4. 可观测可调试全链路 Trace、Token 用量、工具调用日志、Replay 回放、A/B 评估；让 Agent 行为可解释、可回滚。决定技术栈：Langfuse / OpenTelemetry + Replay Store。

整体架构：5 层解耦 + 协议分层

自上而下分层，每层独立演进；层间通过明确定义的协议（HTTP / JSON-RPC / gRPC）解耦。

每一层的职责边界

• L1 · 交互层统一对外暴露：Web 工作台、IDE 插件、IM Bot、API Gateway。
• L2 · Agent 编排层多 Agent 协作引擎：状态机、群聊、Planner / Executor、Memory、Scheduler。
• L3 · 工具生态层把工具以协议形式接入：Function Calling / MCP / OpenAPI 适配，注册中心与沙箱执行。
• L4 · 模型层屏蔽厂商差异：LiteLLM 统一接入，支持公有云 API 与私有 vLLM 自托管。
• L5 · 基础设施层云原生底座：数据库、消息、对象存储、向量库、容器编排、可观测体系。

Agent 框架选型：LangGraph 主选 · AutoGen 辅助

主流 4 个框架各有侧重；从工程可控性、社区成熟度、编排能力三方面看，LangGraph 为主、AutoGen 为辅是当前最务实的组合。

抽象一层 AgentRuntime 接口，未来可平滑替换底层框架。

选型结论：以 LangGraph 作为主编排框架（显式状态、人机协作、可观测性强）；针对需要开放群聊探索的场景引入 AutoGen 作为辅助；抽象一层 AgentRuntime 接口，未来可平滑替换底层框架。

Agent 编排层 4 大核心模块

每个 Agent 实例由这 4 个模块组合而成；接口标准化后可被多个上层 Agent 复用。

Planner · 任务规划器

把目标拆解为可执行子任务 DAG。

// Planner 接口
interface Planner {
  plan(goal: Goal, ctx: Context): Promise<TaskDAG>
  replan(dag: TaskDAG, feedback: Feedback): Promise<TaskDAG>
}

• 输入用户目标 + 会话上下文 + 可用工具清单
• 输出TaskDAG（含依赖、并行度、超时）

Executor · 任务执行器

驱动 LLM 调用、工具调用、状态推进。

// Executor 接口
interface Executor {
  run(node: TaskNode, state: AgentState): AsyncIterable<StepEvent>
  cancel(runId: RunId): Promise<void>
}

• 输入TaskNode + AgentState（checkpoint）
• 输出流式 StepEvent（token / tool_call / result）

ToolSelector · 工具选择器

从工具库中匹配最相关工具 + 构造参数。

// ToolSelector 接口
interface ToolSelector {
  retrieve(query: string, k: number): Promise<Tool[]>
  invoke(tool: Tool, args: JsonSchema): Promise<ToolResult>
}

• 输入当前步骤意图 + TopK 工具
• 输出工具调用结果（含 trace 上下文）

MemoryManager · 记忆管理器

短期 / 长期 / 语义记忆三层。

// MemoryManager 接口
interface MemoryManager {
  shortTerm: SlidingWindowStore     // 最近 N 轮
  longTerm:  VectorStore            // 用户画像 / 偏好
  domain:    RAGRetriever           // 领域知识
}

• 输入当前会话 ID + 查询
• 输出合并后的记忆上下文（结构化）

LLM 统一接入 + 工具协议适配

LLM Gateway · 关键能力

屏蔽厂商差异，提供统一路由、降级、限流、计费；自研薄壳 + LiteLLM 适配层是性价比最高的方案。

多模型路由

• 按任务类型路由（代码→DeepSeek、长文→Claude、快速→GPT-4o-mini）
• 按成本 / 延迟权重动态切换
• 支持私有 vLLM / Ollama 推理节点

容灾降级

• 主备厂商 + 健康检查（每 10s）
• 429 / 5xx 自动切换到备份模型
• 用户级熔断：单用户失败率超阈值暂停 60s

限流与计费

• Token 桶限流（按用户 / 租户 / API Key）
• 实时 Token 计量 + 月度对账
• 成本中心：按部门 / 项目分摊

Function Calling 抽象

// 统一 OpenAI 兼容协议，屏蔽各厂商差异
type ChatRequest = {
  model: string                  // 逻辑模型名，如 "smart" / "fast" / "code"
  messages: Message[]
  tools?: ToolSpec[]            // JSON Schema
  tool_choice?: 'auto' | 'required' | { name: string }
  stream?: boolean
  // 扩展：路由策略、计费标记、SLA 等级
  __meta?: { tenant: string; priority: number; cost_center?: string }
}

选型建议：LiteLLM（已支持 100+ 模型、含路由 / 重试 / fallback）作为基座，外层用 FastAPI 薄壳包一层做：租户限流、计费埋点、Prompt 注入检测、敏感词过滤。关键指标：P99 延迟增加 ≤ 50ms，故障切换时间 ≤ 3s。

工具协议：3 种并存，按场景选

内部工具走 OpenAPI 包装；外部生态走 MCP；高频原子能力走原生 Function Calling。

• Function Calling · 原生协议，模型直出结构化参数。优点：零适配开销，延迟最低。缺点：参数必须 JSON Schema，重工具 / 大参数易爆。适用：高频、参数小的原子工具（搜索、SQL、HTTP 调用）。推荐用于 平台内置
• MCP (Model Context Protocol) · Anthropic 主导的开放标准，进程级工具服务。优点：解耦工具开发与 Agent，热插拔、生态可复用。缺点：需独立部署 MCP Server，调试链路长。适用：跨团队共享的稳定工具（数据库、设计稿、CI/CD）。推荐用于 外部生态
• OpenAPI Adapter · 把 OpenAPI 3.x 描述自动转为工具。优点：复用现有 API 文档，零额外工作。缺点：复杂 API 的 schema 适配困难，鉴权需额外处理。适用：内部业务系统接入（CRM、ERP、工单）。推荐用于 存量系统

Tool Registry · 工具注册中心

每个工具在注册中心维护 4 类元数据：

• 元数据 · 名称 / 描述 / 版本 / 协议 / 鉴权 / SLA
• Schema · 输入输出 JSON Schema + 示例
• 权限 · 租户可见性 / 调用配额 / 审批
• 运行时 · Sandbox / 超时 / 重试 / 监控

三层记忆 + 向量库选型 + 4 种协作模式

三层记忆架构

不同生命周期 / 语义粒度的记忆需要分层存储；向量库选型在精度、规模、运维成本间权衡。

• 短期记忆 · Sliding Window · 存储：Redis List（最近 N 轮对话）；容量：单会话 ≤ 8K tokens；TTL：会话结束 24h 后过期。
• 长期记忆 · User Profile · 存储：PostgreSQL + 向量（用户画像、偏好、习惯）；由 Agent 在对话中显式 / 隐式提炼；用户可查看、编辑、删除。
• 领域知识 · RAG · 存储：向量库（文档 / 代码 / 表格）；支持多租户隔离 + 权限继承；混合检索：BM25 + 向量 + 重排序。

向量库选型对比

Agent 协作 · 4 种模式

没有万能模式；按任务结构、容错要求、并行度需求选择，必要时可混合编排。

① 监督式 · Supervisor

主 Agent 分配任务、子 Agent 汇报。

Supervisor ──┬──→ Researcher
             ├──→ Coder
             └──→ Reviewer
        ↑___________________|
            (汇总 → 决策 → 派发)

适用：任务结构清晰、需集中决策的中等复杂度流程。

② 对等辩论 · Debate

多 Agent 立场对辩，投票/裁判收敛。

Pro  Agent ──┐
            ├──→ 共享消息总线 ──→ Judge
Con  Agent ──┘
    (轮次 N，直至 Judge 给出结论)

适用：开放性决策、风险评估、方案评审（牺牲成本换质量）。

③ 流水线 · Pipeline

DAG 严格顺序，前置产出为后置输入。

[需求解析] → [架构设计] → [编码] → [单测] → [评审]
   ↓ JSON      ↓ Spec      ↓ Code   ↓ Diff    ↓ OK/NOK
              (任一失败可触发重试/回退)

适用：SOP 明确的工程任务（软件开发、数据 ETL）。

④ 任务市场 · Marketplace

任务发布到消息队列，Agent 自由接单。

TaskBoard (Kafka)
  ├── Agent A (空闲) ──claim──→ 任务1
  ├── Agent B (空闲) ──claim──→ 任务2
  └── Agent C (忙碌)           ← 任务3 等待
        (按能力 + 负载匹配)

适用：大规模并发、独立子任务（如批量内容生成、批量数据分析）。

工作台、可观测与基础设施

前端工作台 · IDE 风格而非聊天框

不是聊天框，是 IDE 风格的工作台；让用户看清 Agent 在做什么、能改、能暂停。

核心视图

• ① 流式对话 · Markdown / 代码块 / 表格 / 图表逐 token 渲染；支持重新生成、分支、改写。
• ② 思考链可视化 · 折叠 / 展开 ReAct 步骤，灰显中间推理，高亮决策点。
• ③ 工具调用 Timeline · 横向甘特图：工具名 / 耗时 / 入参 / 出参 / 错误堆栈，点击跳转详情。
• ④ Prompt & 参数面板 · System Prompt / 工具集 / Temperature / 模型切换，diff 视图比较版本。

技术栈选型

• Next.js 15 App Router + RSC
• Tailwind + shadcn/ui 风格基线
• Zustand 状态 / SWR 数据
• Monaco Editor 写 Prompt 与代码
• React Flow 绘制思考链 DAG
• WebSocket / SSE 流式通信

可观测 · 5 项能力

Agent 系统的可观测 ≠ 传统 APM；必须把"推理过程"作为一等公民记录下来。

• Trace · 端到端 Span 树：用户请求 → Planner → Executor → LLM → Tool。技术：OpenTelemetry + Langfuse
• Token 计量 · 按会话 / 用户 / 工具统计 input/output token，秒级上报。技术：Prometheus 指标 + Grafana
• 工具调用日志 · 入参 / 出参 / 耗时 / 错误码 / 重试次数，结构化 JSON。技术：ClickHouse / ELK
• Replay · 完整 Checkpoint 持久化；可从任意节点重放，复现 / 分支 / A/B。技术：PostgreSQL + S3
• Eval · 离线评测集 + 在线抽样评估；指标含成功率、Token 成本、用户反馈。技术：Langfuse / 自研 Eval

端到端 Trace 示例（伪代码）

// 一次完整对话的 Span 树
user.request              1200ms
└─ agent.run              1180ms
   ├─ planner.plan         320ms   // tokens: 850 in / 120 out
   ├─ executor.step[1]     180ms   // tool: web_search
   ├─ executor.step[2]     240ms   // tool: code_interpreter
   ├─ llm.generate         410ms   // model: gpt-4o, 2300 in / 380 out
   └─ evaluator.score      30ms    // score: 0.87

部署与基础设施

云原生优先；无状态服务容器化，有状态中间件用托管或 Operator，Agent 执行节点需要弹性伸缩。

运行时

• Kubernetes · 核心编排；Agent Runtime 用 HPA 按队列深度扩缩
• Knative / KEDA · 突发型工具调用（如批量数据处理）
• Argo Workflows · 长流程 Agent DAG 的可靠执行
• Service Mesh (Istio) · mTLS、灰度、流量镜像

消息 & 存储

• Kafka · Agent 间消息总线、事件溯源、任务市场
• Redis Streams · 轻量队列、会话状态、限流计数
• PostgreSQL 16 · 业务数据、用户、工具元数据
• MinIO / S3 · Trace / Replay / 训练数据归档
• Milvus / Qdrant · 向量库（M2+）

CI / CD & GitOps

• GitHub Actions · PR 检查、单元 / 集成测试、Eval
• ArgoCD · 声明式部署，自动同步到 K8s
• Helm + Kustomize · 多环境（dev / staging / prod）
• 特性开关（LaunchDarkly / 自研） · Agent 行为可灰度

可观测体系

• Prometheus + Grafana · 指标 / 告警
• Loki / ELK · 日志聚合
• Jaeger / Tempo · 分布式追踪
• Langfuse · LLM 专用观测（Token / Prompt / Score）
• Sentry · 前端错误监控

安全与合规设计

Agent 调用工具等同于给 LLM 颁发"操作权限"；必须从认证、授权、审计、注入防护、数据脱敏五个维度构建。

身份与鉴权

• SSO（OIDC / SAML）+ MFA，企业用户接入
• API Key + Service Account，自动化场景
• 短期 Token（≤ 1h），自动轮换
• 工具调用携带用户身份（on-behalf-of）

细粒度授权

• RBAC + ABAC：用户、租户、工具、资源的四元组权限
• 工具白名单：每个 Agent 仅可调用授权范围内的工具
• 二次确认：高敏感操作（删除、扣款）需用户确认
• 配额管理：按租户 / 工具 / 成本中心设置上限

Prompt 注入防护

• System Prompt 与用户内容物理隔离（不同 message role）
• 工具输出不可信原则：所有 ToolResult 重新过滤 + 沙箱渲染
• 敏感操作走"二次 LLM 审计"：独立模型判定意图
• 定期红队测试 + 注入攻击样本库

审计与合规

• 全量操作日志：who / when / what / which tool / which data
• 日志不可篡改（WORM 存储 / 区块链存证）
• 数据脱敏：PII 在入库与跨租户时自动打码
• 支持 GDPR / 个保法：用户可导出 / 删除所有数据
• SOC 2 / ISO 27001：定期第三方审计

4 类关键风险 + M1 / M2 / M3 里程碑

不回避问题；明确暴露 + 可执行缓解是评审通过的前提。

风险与缓解

迭代路径 · M1 / M2 / M3

Q&A · 谢谢，期待你的反馈与挑战。