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 之分改一处崩一片新人接手无从下手。错误 2Memory 与 Knowledge 混为一谈把用户偏好和企业知识库放一个存储检索噪声大、权限混乱该私人化的泄露、该共享的找不到。错误 3Trace 当可选觉得能跑就行不上链路追踪出问题只能盲猜定位一次花半天。四、关键观察十一节点构成企业 Agent 骨架一张合格的企业架构至少包含这 11 个节点每个职责唯一、上下游明确User → Gateway → Runtime → Planner → Memory ↓ Knowledge ↓ Provider → LLM ↓ Tool ↓ Trace ↓ DatabaseUser请求发起方人/系统。Gateway统一入口鉴权、限流、路由、协议转换。Runtime编排中枢驱动一次 Agent 执行的完整生命周期。Planner决策层决定下一步调什么工具/是否追问。Memory用户与会话的记忆短期长期。Knowledge企业知识库RAG 来源与 Memory 隔离。Provider模型调用抽象层屏蔽具体 LLM 差异。LLM底层大模型通过 Provider 接入。Tool外部能力API/函数由 Runtime 调度。Trace全链路追踪每一次调用可回溯。Database持久化记忆、知识、日志、配置。五、最终方案逐节点职责 全链路图完整请求流Mermaid数据流要点请求自上而下穿过 Gateway→Runtime→PlannerPlanner 按需向上游的 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托管方案优先成熟标准OpenTelemetryDatabase托管优先运维重非差异化原则业务核心自建重运维/非差异化买服务。把精力花在 Runtime/Planner 这类决定体验的地方而不是重复造数据库轮子。部署架构11 个节点如何落地上面的权衡决定了每个节点用自建还是托管落到物理部署上11 个节点并不需要 11 台独立机器。按耦合度与扩展性可以分成三组合并部署Gateway Runtime Planner三者同属编排链路调用频繁、延迟敏感建议作为一个应用进程部署共享内存态上下文。中小规模下 2 个副本即可扛住日常流量。独立服务Memory Knowledge Provider Tool它们是被上游按需调用的能力层各自有独立的存储或外部依赖建议拆成独立服务便于单独扩缩容与权限隔离。Provider 作为模型抽象层可再细分为同步网关与异步批处理两类实例。旁路与底座Trace Database LLMTrace 走旁路采集建议独立部署并接入 OpenTelemetry CollectorDatabase 使用托管实例LLM 完全走云上托管 API不占用自建资源。推荐的最小集群规模1 个应用节点合并 Gateway/Runtime/Planner 1 个能力节点合并 Memory/Knowledge/Provider/Tool 1 个托管数据库 1 个托管 Trace 后端共 2 台自建机器起步即可支撑一个可用的企业级 Agent 系统。网络通信方式应用节点与能力节点之间走内部 gRPC保证低延迟与强类型契约能力节点访问外部 LLM 与 Tool 走 HTTPSTrace 通过 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:agentdatabase: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:agentdatabase:5432/agent depends_on: - database knowledge: image: agent-knowledge:latest environment: DB_DSN: postgres://agent:agentdatabase: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参考资料带用途说明本系列22Agent 项目应该如何分层Runtime/Memory/Provider/Tool 的目录边界源自22。本系列23Provider 抽象层本文 Provider→LLM 节点的设计细节见23。本系列24Tool RegistryTool 节点统一调度见24。本系列25Memory Service /15RAG 知识治理Memory 与 Knowledge 隔离的论证见这两篇。本系列28可观测性Trace 节点标准见28OpenTelemetry 实践。本文是 AI Agent 工程实践系列的第 34 篇第四阶段第十四篇。系列导航上一篇第 33 篇《Agent 如何监控》下一篇第 35 篇《我的 AI Engineering OS 最终架构》