AI Agent 工程实践（34）：企业 AI Agent 架构

系列：AI Agent 工程实践

上一篇：第 33 篇《Agent 如何监控》

下一篇：第 35 篇《我的 AI Engineering OS 最终架构》

从零件到系统，本文给出企业级 AI Agent 的完整架构图：一张端到端架构图、十一节点职责拆解，以及落地部署建议，帮你把散落的组件拼成一辆能跑的车。

一、开场：面试官问"你设计的系统长啥样"

面试 AI Agent 岗位，常被问："如果让你设计一个企业级 Agent 系统，你会怎么搭？"能脱口画出一张端到端架构图、说清每层职责的人，直接加分。前面 20 多篇讲了所有零件，这篇把它们拼成一张总图。

上篇（33）讲监控，这篇讲"全景"------企业 AI Agent 架构。

二、问题背景：零件齐全 ≠ 系统成型

前几阶段我们拆过：Gateway、Runtime、Planner、Memory、Knowledge、Provider、LLM、Tool、Trace、Database。但散着讲，容易"知道每个零件，画不出整辆车"。企业需要的是一张职责清晰、数据流明确的全链路图。

三、错误尝试：三种架构翻车

错误 1：堆功能不画边界

所有逻辑塞进一个服务，没有 Gateway/Runtime 之分，改一处崩一片，新人接手无从下手。

错误 2：Memory 与 Knowledge 混为一谈

把"用户偏好"和"企业知识库"放一个存储，检索噪声大、权限混乱，该私人化的泄露、该共享的找不到。

错误 3：Trace 当可选

觉得"能跑就行"，不上链路追踪，出问题只能盲猜，定位一次花半天。

四、关键观察：十一节点构成企业 Agent 骨架

一张合格的企业架构，至少包含这 11 个节点，每个职责唯一、上下游明确：

User → Gateway → Runtime → Planner → Memory
                              ↓
                          Knowledge
                              ↓
                          Provider → LLM
                              ↓
                            Tool
                              ↓
                            Trace
                              ↓
                         Database

• User：请求发起方（人/系统）。
• Gateway：统一入口，鉴权、限流、路由、协议转换。
• Runtime：编排中枢，驱动一次 Agent 执行的完整生命周期。
• Planner：决策层，决定下一步调什么工具/是否追问。
• Memory：用户与会话的记忆（短期+长期）。
• Knowledge：企业知识库（RAG 来源），与 Memory 隔离。
• Provider：模型调用抽象层，屏蔽具体 LLM 差异。
• LLM：底层大模型，通过 Provider 接入。
• Tool：外部能力（API/函数），由 Runtime 调度。
• Trace：全链路追踪，每一次调用可回溯。
• Database：持久化（记忆、知识、日志、配置）。

五、最终方案：逐节点职责 + 全链路图

完整请求流（Mermaid）：

数据流要点：请求自上而下穿过 Gateway→Runtime→Planner，Planner 按需向上游的 Memory/Knowledge/Provider/Tool 取能力，Trace 旁路记录全程，所有持久状态落 Database。

六、代码与配置示例

一次请求在各层的流转（伪代码）：

def handle(req):
    user = gateway.auth(req)            # Gateway 鉴权
    ctx = runtime.start(user, req)      # Runtime 起会话
    while not ctx.done:
        plan = planner.next(ctx)        # Planner 决策
        if plan.need_memory: ctx.load(memory.get(user))
        if plan.need_knowledge: ctx.inject(knowledge.search(req))
        if plan.need_tool: ctx.run(tool_registry.call(plan.tool))
        if plan.need_llm: ctx.reply(provider.chat(ctx))  # Provider→LLM
    trace.export(ctx.span)              # Trace 落库
    return ctx.answer

七、设计权衡：自建 vs 托管

节点	建议	理由
Gateway/Runtime/Planner	自建	业务逻辑核心，差异化所在
Memory/Knowledge	自建 + 托管存储	数据资产，自己掌控
Provider/LLM	托管为主	算力与模型交给云
Trace	托管方案优先	成熟标准（OpenTelemetry）
Database	托管优先	运维重，非差异化

原则：业务核心自建，重运维/非差异化买服务。把精力花在 Runtime/Planner 这类决定体验的地方，而不是重复造数据库轮子。

部署架构：11 个节点如何落地

上面的权衡决定了每个节点用自建还是托管，落到物理部署上，11 个节点并不需要 11 台独立机器。按耦合度与扩展性，可以分成三组：

• 合并部署（Gateway + Runtime + Planner）：三者同属编排链路，调用频繁、延迟敏感，建议作为一个应用进程部署，共享内存态上下文。中小规模下 2 个副本即可扛住日常流量。
• 独立服务（Memory + Knowledge + Provider + Tool）：它们是被上游按需调用的能力层，各自有独立的存储或外部依赖，建议拆成独立服务，便于单独扩缩容与权限隔离。Provider 作为模型抽象层，可再细分为同步网关与异步批处理两类实例。
• 旁路与底座（Trace + Database + LLM）：Trace 走旁路采集，建议独立部署并接入 OpenTelemetry Collector；Database 使用托管实例；LLM 完全走云上托管 API，不占用自建资源。

推荐的最小集群规模：1 个应用节点（合并 Gateway/Runtime/Planner）+ 1 个能力节点（合并 Memory/Knowledge/Provider/Tool）+ 1 个托管数据库 + 1 个托管 Trace 后端，共 2 台自建机器起步，即可支撑一个可用的企业级 Agent 系统。

网络通信方式：应用节点与能力节点之间走内部 gRPC，保证低延迟与强类型契约；能力节点访问外部 LLM 与 Tool 走 HTTPS；Trace 通过 OTLP 协议上报到 Collector，再异步写入后端存储；Database 由应用与能力节点通过连接池访问，避免频繁建连。

下面给出一份最小集群的 docker-compose.yml 示例，把合并部署的应用节点、独立服务的能力节点、Trace Collector 与 Database 都编排进来：

version: "3.9"
services:
合并部署：应用节点（Gateway + Runtime + Planner）
app:
image: agent-app:latest
ports:
- "8080:8080"          # Gateway 对外入口
environment:
RUNTIME_MODE: merged
MEMORY_ADDR: memory:50051
KNOWLEDGE_ADDR: knowledge:50052
PROVIDER_ADDR: provider:50053
TOOL_ADDR: tool:50054
DB_DSN: postgres://agent:agent@database:5432/agent
OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4317
depends_on:
- memory
- knowledge
- provider
- tool
- database
- otel-collector
独立服务：能力节点（Memory + Knowledge + Provider + Tool）
memory:
image: agent-memory:latest
environment:
DB_DSN: postgres://agent:agent@database:5432/agent
depends_on:
- database
knowledge:
image: agent-knowledge:latest
environment:
DB_DSN: postgres://agent:agent@database:5432/agent
depends_on:
- database
provider:
image: agent-provider:latest
environment:
LLM_API_KEY: ${LLM_API_KEY}   # 云上托管 LLM 密钥
depends_on:
- otel-collector
tool:
image: agent-tool:latest
environment:
OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4317
depends_on:
- otel-collector
旁路：Trace Collector
otel-collector:
image: otel/opentelemetry-collector-contrib:latest
ports:
- "4317:4317"          # OTLP gRPC 接收端
- "4318:4318"          # OTLP HTTP 接收端
command: ["--config=/etc/otel-collector-config.yaml"]
volumes:
- ./otel-collector-config.yaml:/etc/otel-collector-config.yaml
depends_on:
- database
底座：Database
database:
image: postgres:16
environment:
POSTGRES_USER: agent
POSTGRES_PASSWORD: agent
POSTGRES_DB: agent
volumes:
- pgdata:/var/lib/postgresql/data
ports:
- "5432:5432"
volumes:
pgdata:

网络依赖关系说明：app 依赖 memory/knowledge/provider/tool/database/otel-collector，通过内部 gRPC 调用能力节点；memory 与 knowledge 依赖 database 做持久化；provider 与 tool 依赖 otel-collector 上报链路；otel-collector 依赖 database 异步写入 Trace 数据。所有服务默认处于同一 compose 网络，容器名即服务名，可直接作为内部地址解析。

八、总结

• ✅ 零件齐全 ≠ 系统成型，企业需要职责清晰、数据流明确的全链路图。
• ✅ 三种翻车：堆功能不画边界、Memory/Knowledge 混淆、Trace 当可选。
• ✅ 十一节点骨架：User→Gateway→Runtime→Planner→Memory/Knowledge→Provider→LLM→Tool→Trace→Database。
• ✅ 数据流：请求自上而下，Planner 向上游取能力，Trace 旁路，状态落库。
• ✅ 自建业务核心，买重运维/非差异化服务。

下一篇，把这张企业图收进我的 AI Engineering OS 框架，做系列总结。（35）

---

参考资料（带用途说明）

• 本系列（22）Agent 项目应该如何分层：Runtime/Memory/Provider/Tool 的目录边界源自（22）。
• 本系列（23）Provider 抽象层：本文 Provider→LLM 节点的设计细节见（23）。
• 本系列（24）Tool Registry：Tool 节点统一调度见（24）。
• 本系列（25）Memory Service /（15）RAG 知识治理：Memory 与 Knowledge 隔离的论证见这两篇。
• 本系列（28）可观测性：Trace 节点标准见（28）OpenTelemetry 实践。

---

本文是 AI Agent 工程实践系列的第 34 篇（第四阶段第十四篇）。

---

系列导航

上一篇：第 33 篇《Agent 如何监控》

下一篇：第 35 篇《我的 AI Engineering OS 最终架构》