企业官网建设流程全解析

企业级 Agent 平台从 0 到 1：技术选型、架构设计与核心模块拆解

很多团队的经历是相似的：三天跑通一个 Demo，半年上不了一个生产平台。

问题几乎从来不是"模型不够强"，而是把Agent 框架当成了Agent 平台。框架回答"模型怎么调工具、怎么循环推理"；平台回答"成百上千个 Agent 怎么被创建、发布、治理、计量和排障"。

这篇文章给出一套可落地的分层架构、一份经过取舍的选型矩阵，以及九个核心模块的设计要点和踩坑清单。

一、先划边界：企业级到底"级"在哪里

一个 Agent 框架的核心抽象通常只有四五个：模型、工具、消息、循环。而一个企业级平台要在此基础上再叠加三层能力，这三层才是真正难的部分：

1. 多租户—— 不同部门 / 客户的会话、知识、模型配额、工具权限必须隔离，且隔离要能论证。
2. 可治理—— 每一次模型调用、工具调用、数据访问都要可审计、可追溯、可追责。
3. 可运营—— 成本、质量、延迟必须被度量，并且能持续优化，而不是上线即失明。

由此可以倒推出平台的能力清单，以及哪些必须自建：

这里有一条贯穿全文的设计原则：控制面与数据面分离。

控制面是标准的企业级系统——CRUD、权限、审批、版本、租户，用 Java / Go 写最稳；数据面是 AI 运行时——编排、推理、检索，生态在 Python。把这两件事塞进同一个服务，最后一定会变成"既不敢改 AI 逻辑，也不敢改权限逻辑"的泥球。

二、技术选型

2.1 先问四个问题，再谈选型

选型矩阵本身没有意义，有意义的是约束。落地前先回答：

1. 团队主语言是什么？这一条能决定 80% 的选择。让 Java 团队维护 LangGraph 服务，或者让 Python 团队维护一套 Spring 权限体系，都是在给自己埋雷。
2. 自建还是先买？半年内要见效就买(Dify / RAGFlow)，要做长期平台资产就必须自建控制面和网关。
3. 规模预期？10 个 Agent 和 1000 个 Agent 对版本管理、调度、隔离的要求是两个量级。
4. 是否私有化 / 信创？直接排除一批 SaaS 依赖，也决定了模型接入方式。

2.2 推荐选型矩阵

2.3 三条落地路线

路线 A：Java 为主的企业团队(国内最常见)

用 Spring Boot 3 承载控制面，Spring AI Alibaba 做编排与模型接入，天然对接 Nacos(配置 / 注册)、Higress(网关)、DashScope 等国产模型。优势是与现有中台、运维、安全体系完全复用，评审和合规容易过；代价是 AI 新特性跟进慢半拍，复杂 Agent 的调试体验不如 Python 生态。

路线 B：Python / AI 团队

FastAPI + LangGraph + LiteLLM + Langfuse，开发效率最高。建议把租户、计费、审批这类企业事务单独拆一个 Java 或 Go 服务，不要让 Python 承担强一致性和复杂权限。

路线 C：先买后建

用 Dify / RAGFlow 在两个月内跑通业务，但自建模型网关和 MCP 工具层。这两层是"换平台也带得走"的资产。半年后根据规模和治理诉求，再决定是否替换编排层。

2.4 三个反直觉的结论

• 模型网关比编排框架重要。平台后期 90% 的痛点——模型切换、限流、成本归属、密钥泄露——都在网关。编排框架是可以换的，网关换起来伤筋动骨。
• 不要自研向量库和 embedding 模型。没有亿级规模就没有收益，直接用成熟组件。
• 多 Agent 不是银弹。先做单 Agent + 丰富工具，跑不通再拆。过早多 Agent 化会把调试成本放大一个数量级。

三、架构设计

3.1 分层架构

几个结构性要点：

• 控制面只下发配置，不参与请求链路。控制面挂了，已经在跑的 Agent 不应受影响。
• 所有模型调用必须经过网关，业务代码里不允许出现厂商 SDK 的直连。
• 工具调用统一经过工具中心，哪怕只有一个工具。这层是权限和审计的落点。

3.2 一次请求的完整链路

注意链路里的两个细节：版本在入口处就被 Pin 住(会话中途改配置不会导致行为漂移)；trace_id 从网关一路透传到工具层，否则出了问题只能靠猜。

3.3 控制面与数据面的契约

两者之间只有一份契约：Agent 定义(声明式配置)。

• 控制面负责编辑、审核、发布、灰度，产出一个不可变的版本快照。
• 数据面只认版本快照，不查控制面数据库，失败时读本地缓存。
• 配置变更通过配置中心 / 消息推送增量下发，数据面支持按版本号拉取。

这条契约让两个团队可以独立演进，也让"回滚"变成一次指针切换，而不是一次代码发布。

3.4 部署拓扑

隔离原则：沙箱单独一个 namespace 并限制网络出口；运行时无状态、可水平扩缩容；控制面与数据面的数据库实例分离。

四、核心模块的关键设计点

4.1 Agent Runtime：状态机，而不是 while 循环

最容易被低估的模块。很多团队的第一版就是：

while not done: resp = llm.invoke(messages) if resp.tool_calls: messages.append(execute(resp.tool_calls)) else: done = True

这段代码在 Demo 里能跑，在生产里会同时暴露五个问题：进程重启丢任务、无法人工介入、无法限预算、无法重放、无法审计。

正确的抽象是"带持久化检查点的状态机"：

关键设计点：

上下文工程值得单独强调。生产 Agent 的失败大多不是"模型不会推理"，而是"该给的信息没给、不该给的塞了一堆"。实践中的四条规则：

1. System prompt 只放稳定约束，动态信息放消息体。
2. 超过 N 轮自动摘要，但保留原始工具调用记录用于审计。
3. 工具返回值先裁剪再入上下文(大 JSON 只留模型真正需要的字段)。
4. 检索结果按相关度截断，不要把 Top-50 全塞进去。

注意事项：

• 多 Agent 编排(supervisor / handoff)会显著增加不可控性，先把单 Agent 的工具边界做清楚。
• 工具执行必须设超时，且超时后要能告诉模型"失败了、为什么"，而不是直接抛异常中断整个流程。
• 所有 LLM 输出都要能解析失败并降级，不要假设模型一定返回合法 JSON。

4.2 模型网关：平台最不该省的一层

网关的职责不是"转发请求"，而是把模型的不确定性收敛成平台可控的接口。

必须具备的能力：

容易踩的坑：

• 流式透传：SSE 的 chunk 边界和 tool_call 增量拼接很容易出错，必须原样透传并单独测。
• 结构化输出兼容性：不同厂商对 JSON Schema 的支持程度差异巨大，网关要做能力探测和降级策略。
• 多模态：图片、音频的 token 计费规则不同，成本统计不能只算文本。
• 重试语义：LLM 调用天然可重试，但工具调用不可盲目重试——两者要分开处理。
• 语义缓存：跨租户命中就是数据泄露，缓存 key 必须包含 tenant_id + 模型版本。

4.3 工具层：MCP 是协议，治理才是平台

工具是 Agent 的"手"。这一层的核心矛盾是：开放能力和最小权限天然对立。

建议结构：

关键设计点：

• 工具描述就是 Prompt。工具名、描述、参数 schema 的写法直接决定调用准确率。要求：动词开头、说明副作用、参数带单位与示例、明确"什么时候不该用"。
• 两级权限：工具级(能不能调这个工具)+ 数据级(能查哪些行、哪些字段)。后者通常要实现成"参数注入"，而不是让模型自己填租户 ID。
• 结果裁剪：工具返回给模型的内容要过滤掉内部字段、主键、敏感信息，同时控制体积。
• 错误分层：可恢复错误(参数错、查无数据)以结构化结果返回给模型自我修正；不可恢复错误(权限不足、系统故障)才终止流程并上报。
• 幂等键：写操作类工具必须支持幂等，否则重试就是事故。
• 沙箱：代码执行、文件操作类工具必须在隔离环境运行，且网络出口白名单化。

4.4 知识库 / RAG：权限过滤必须发生在检索时

RAG 的链路很长，每一段都能成为瓶颈：

关键设计点：

• 混合检索：BM25 + 向量，用 RRF 融合。纯向量在专有名词、编号、代码场景上很差。
• 权限过滤前置：ACL 必须以 metadata filter 的形式进入检索条件。先检索再过滤会造成两个问题：召回数量塌陷，以及过滤逻辑写错就泄露。
• 增量更新：文档要支持增删改与版本，删除必须同时清理向量和缓存，否则会出现"已删除的知识仍被召回"。
• 切分策略：不是越小越好。按语义结构(标题层级、表格、代码块)切，chunk 之间保留重叠，并在每个 chunk 中带上文档标题与章节路径。
• 表格与图片：必须单独处理(表格转结构化、图片走 OCR / 多模态)，否则企业知识库里最有价值的部分恰好丢了。
• 评测：分别度量召回率、重排收益、答案忠实度。只测最终答案无法定位问题在检索还是在生成。

4.5 记忆系统：写入策略比存储更重要

把"记忆"当成"把聊天记录存下来"是最常见的误解。生产记忆要分三层：

注意事项：

• 谁来决定写什么？让 LLM 自由抽取记忆会产生大量噪声和错误事实。建议：显式记忆(用户主动说"记住")+ 规则抽取 + 定期人工审核。
• 冲突与遗忘：同一事实的新旧版本要能覆盖，且要有 TTL 和删除接口。
• 隐私：记忆是合规重灾区。必须支持按用户查看、导出、删除，并纳入审计。

4.6 工作流与人工审批

企业场景里，纯自主 Agent 只能覆盖一部分。真正高频的是"固定流程 + 若干智能节点 + 人工审批"。

• 流程编排用 DAG + 条件分支，不要用 Agent 的自由循环去模拟业务流程。
• 长事务用 Temporal：等待审批、等待外部回调、跨天任务，必须有 Durable Execution。
• 人工节点要能做到：展示上下文、支持修改、支持拒绝并附带理由，拒绝理由要回流到后续节点。
• 补偿事务：流程中某步失败，前面的写操作要能回滚或标记，不能留下半成品数据。

4.7 可观测与评测：上线第一天就要有

Agent 是概率系统，"没报错"不等于"做对了"。

Trace 要覆盖四类 span：LLM 调用(模型、token、延迟、成本)、检索(query、命中、分数)、工具(参数、结果、耗时)、编排(节点、分支、重试)。用 OpenTelemetry GenAI 语义约定，避免后期返工。

指标分三层：

评测体系：离线数据集(覆盖典型任务 + 边界 + 对抗样本)+ 自动评分(规则 / LLM-as-judge)+ 人工抽检。把评测接入 CI，Prompt 或模型变更必须过回归门禁。

4.8 安全与治理：把"信任模型"变成"不信任模型"

这是企业级和 Demo 最大的分水岭。核心思路是：假设模型会被诱导，所有安全控制放在模型之外。

• 多租户隔离：全链路强制tenant_id，数据库行级隔离或独立 schema；向量库、缓存、对象存储的 key 都要带租户前缀。
• 权限模型：RBAC 管功能，ABAC / OPA 管数据。工具调用的鉴权要在服务端做，不能依赖 Prompt 里写"你只能查本公司数据"。
• Prompt 注入：输入侧分类器 + 工具最小权限 + 输出侧过滤，三者缺一不可。特别注意间接注入——RAG 检索到的文档、工具返回的内容都可能是攻击载荷。
• 数据安全：落库前脱敏、DLP 检测、审计日志留存。日志里不要存完整 Prompt 中的敏感信息。
• 模型安全：内容审核、越狱检测、敏感话题策略。
• 沙箱：代码执行、文件操作、网络访问必须隔离，出口白名单。

4.9 发布与版本：配置即代码

Agent 的行为由Prompt + 模型 + 工具集 + 知识库 + 参数共同决定，任何一项变化都可能导致行为漂移。所以：

• Agent 定义用声明式配置，纳入 Git，走 Code Review。
• Prompt、模型版本、工具 schema、知识库快照都要能独立版本化。
• 发布支持灰度：按租户 / 按流量比例 / 按用户白名单。
• 会话入口 Pin 版本，运行中不切换。
• 回滚是指针切换，秒级生效。

一份 Agent 定义大致长这样：

apiVersion: platform.example.com/v1 kind: Agent metadata: name: contract-reviewer tenant: legal-dept version: 1.4.2 spec: model: primary: qwen-max fallback: [deepseek-chat] params: { temperature: 0.2, max_tokens: 4096 } prompt: ref: prompts/contract-reviewer@v7 tools: - ref: tools/contract-db@v3 scopes: [read] - ref: tools/doc-parser@v2 knowledge: - ref: kb/legal-clauses@2026-09 topK: 8 rerank: true runtime: maxSteps: 12 maxTokens: 60000 timeoutSeconds: 180 humanApproval: before: [tools/contract-db.write] observability: sampleRate: 1.0

五、工程化：非功能指标与阶段路线

5.1 建议的 SLO

5.2 分阶段路线

不要在第一阶段就做工具市场和多 Agent 编排。先用一个真实场景把链路跑穿，比先搭一个"什么都能做"的空壳平台有价值得多。

六、失败模式清单

上线前对照检查，命中三条以上就要返工：

• 业务代码里存在厂商 SDK 直连，绕过网关
• Agent 循环没有步数 / token / 时长上限
• 工具调用没有幂等设计
• RAG 先检索后过滤权限
• 语义缓存没有按租户隔离
• 长任务状态只在内存里，重启即丢
• 没有 trace，排障靠翻日志
• Prompt 变更没有版本和回归评测
• 代码执行工具没有沙箱和出口限制
• 成本无法按租户归集
• 会话中途配置变更导致行为漂移
• 多 Agent 编排早于单 Agent 工具治理

七、结语

搭建企业级 Agent 平台，真正的工作量不在"让 Agent 变聪明"，而在把概率系统装进确定性的工程框架里：用网关收敛模型的不确定性，用状态机收敛执行的不确定性，用权限和沙箱收敛工具的不确定性，用 trace 和评测收敛效果的不确定性。

如果只能记住一句话：先把模型网关、MCP 工具层、可观测这三件基础设施做扎实，编排框架反而是最后可以替换的部分。这三层决定了平台能不能撑住企业级要求，而编排框架只决定开发效率。