通用智能体架构设计文档

文档定位

本手册是一份通用智能体（AI Agent）系统架构设计指南，基于对 Dify、OpenClaw、Claude Code 三个代表性开源项目的源码分析与架构拆解，提炼出智能体系统的通用设计模式与最佳实践。

三个项目分别代表智能体系统的三类典型形态：

• • Dify：AI 原生应用开发平台，侧重工作流编排与 LLM 应用全生命周期管理
• • OpenClaw：本地优先的个人 AI 助手网关，侧重行动式 AI 与系统集成
• • Claude Code：终端 AI 编程助手，侧重工具调用、记忆管理与多智能体协作

本手册旨在帮助架构师设计从“对话式 AI”到“行动式 AI”的智能体系统，覆盖感知、决策、行动、记忆全链路。

第1节 文档概述与目标

1.1 编写目的

本架构文档旨在为智能体系统的设计与开发提供系统性的架构指导，目标读者包括：

• • 系统架构师：理解智能体系统的整体架构设计模式与关键决策
• • 后端开发工程师：理解各模块的职责边界和接口契约
• • AI 应用开发者：理解 LLM 集成、工具调用、记忆管理等核心机制
• • 运维工程师：理解部署拓扑和可观测性方案
• • 安全与合规人员：理解安全控制点和审计机制

1.2 文档范围

本文档覆盖智能体系统的架构设计层面，包括：感知层、决策层、行动层、记忆层、编排层、安全与可观测性。详细设计（如类图、具体代码实现）不在本文档范围内。

1.3 术语表

1.4 参考文献

本文档参考以下开源项目及资料：

• • Dify 源码：github.com/langgenius/dify
• • OpenClaw 架构设计文档（社区版）
• • Claude Code 泄露源码分析系列
• • LangGraph 多智能体编排框架
• • MCP 协议规范
• • 《AI Agent 智能体技术发展报告》（中国工业互联网研究院，2026）

第2节 智能体核心架构模型

2.1 智能体的认知闭环

现代 AI 智能体构建在“感知 → 决策 → 行动 → 记忆”的认知闭环之上：

2.2 智能体系统的四层模型

现代 LLM 应用栈可解构为四个核心层次：

2.3 智能体的三种架构形态

基于对三个开源项目的分析，智能体系统可分为三类典型架构：

2.4 智能体成熟度四阶段

基于 Agent 架构演进分析，智能体系统可分为四个成熟度阶段：

设计新系统时，建议从阶段二或阶段三起步，根据业务需求决定是否需要多智能体协作。

第3节 总体架构设计

3.1 六层架构全景

综合三个项目的设计，智能体系统应采用以下六层架构：

┌─────────────────────────────────────────────────────────────┐│                      入口层（Entry Layer）                    ││   CLI / Web UI / SDK / 消息通道（Telegram/WhatsApp/Discord） │├─────────────────────────────────────────────────────────────┤│                     编排与决策层（Orchestration Layer）       ││   Agent 指挥官 / 任务规划器 / 多智能体协调器 / 工作流引擎     │├─────────────────────────────────────────────────────────────┤│                      推理执行层（Reasoning Layer）            ││   LLM 调用 / ReAct/TAOR 循环 / 提示词组装 / 流式处理         │├─────────────────────────────────────────────────────────────┤│                      工具与能力层（Tools & Skills Layer）     ││   内置工具 / 技能系统 / MCP 工具集成 / 插件化扩展             │├─────────────────────────────────────────────────────────────┤│                      记忆与状态层（Memory Layer）             ││   短期记忆 / 长期记忆 / 工作记忆 / 记忆整合/蒸馏机制         │├─────────────────────────────────────────────────────────────┤│                    基础设施与部署层（Infrastructure Layer）   ││   网关 / 消息队列 / 数据库 / 向量存储 / 容器编排 / 可观测性  │└─────────────────────────────────────────────────────────────┘

3.2 Dify 架构分析

Dify 采用领域驱动设计（DDD）的模块化架构，基于 Flask 框架构建：

api/├── core/               # 核心业务逻辑（领域层）│   ├── workflow/       # 工作流引擎（DAG 模型，节点级并行控制）│   ├── rag/            # RAG 检索增强生成│   ├── agent/          # Agent 智能代理实现│   └── tools/          # 工具集成（builtin/custom/plugin）├── controllers/        # API 控制器层├── models/             # 数据模型层├── services/           # 应用服务层└── extensions/         # 基础设施扩展

核心设计特征：

• • 前后端完全分离（React + RESTful API）
• • 领域驱动设计，核心业务与基础设施分离
• • 工作流编排引擎基于 DAG，支持条件分支与循环结构
• • 插件化架构，支持 50+ 内置工具和 100+ 模型提供商

3.3 OpenClaw 架构分析

OpenClaw 采用“云端大脑 + 本地肢体”的三层解耦架构：

┌─────────────────────────────────────────┐│   Orchestrator（云端大脑）               ││   - LLM 推理与任务拆解                   ││   - 通常部署在 GPU 集群或云端            │└─────────────────┬───────────────────────┘                  │┌─────────────────▼───────────────────────┐│   Gateway（协议桥）                      ││   - 消息调度与路由中心                   ││   - 鉴权、流量整形、上下文压缩           ││   - WebSocket 控制平面（127.0.0.1:18789）│└─────────────────┬───────────────────────┘                  │┌─────────────────▼───────────────────────┐│   Pi-embedded（本地执行端）              ││   - 运行在 Mac/Linux/树莓派             ││   - 沙箱隔离（Cell Isolation）          ││   - 动态加载 .ocskill 技能文件          │└─────────────────────────────────────────┘

OpenClaw 的四层核心架构：

3.4 Claude Code 架构分析

Claude Code 的五层架构（基于泄露源码分析）：

第4节 核心组件设计

4.1 编排与决策层

编排层是智能体系统的“指挥官”，负责任务的规划、分解和调度。

4.1.1 Agent 指挥官模式

在多智能体协作系统中，Agent 指挥官承担以下核心职责：

1. 1. 目标解析与任务分解：将用户业务目标转换成可执行的子任务队列，明确执行优先级和依赖关系
2. 2. 动态协作图谱生成：生成协作流程图，明确任务间的数据流与控制流，决定哪些 Agent 并行、哪些串行
3. 3. 任务调度与资源分配：使用优先级队列进行关键路径任务优先调度，动态分配子 Agent 负载

4.1.2 工作流引擎（Dify 实践）

Dify 的工作流编排引擎基于 DAG（有向无环图）模型实现节点级并行控制，支持条件分支与循环结构：

# 工作流节点类型（基于源码分析）workflow/├── nodes/│   ├── agent/          # Agent 节点（调用 Agent 策略）│   ├── llm/            # LLM 调用节点│   ├── code/           # 代码执行节点│   ├── http_request/   # HTTP 请求节点│   ├── knowledge_retrieval/  # 知识检索节点│   └── answer/         # 答案输出节点├── graph_engine/       # 图执行引擎└── variable_pool/      # 变量池（节点间数据传递）

工作流引擎设计要点：

• • 节点间通过变量池传递数据
• • 支持流式执行和异步执行
• • 内置重试机制和错误处理

4.1.3 消息处理流程（OpenClaw 实践）

OpenClaw 处理一条消息的完整流程包含十个关键步骤：

1. 1. 系统启动与初始化：扫描 skills/ 目录，将技能功能摘要注入 LLM 的 system prompt
2. 2. 消息接收与预处理：通过多种渠道（Telegram、WhatsApp、CLI 等）接收用户输入，统一消息格式
3. 3. 会话上下文加载：从 Memory 组件加载历史会话记录，构建完整对话上下文
4. 4. 意图识别与任务分解：LLM 分析用户意图，将复杂任务拆解为可执行子任务
5. 5. ReAct 推理循环启动：进入 Thought → Action → Observation 循环
6. 6. 技能匹配与参数准备：根据任务需求匹配 Skills，准备执行参数
7. 7. 权限检查与安全沙箱：验证权限，启动沙箱环境
8. 8. 技能执行与系统调用：调用 Python/TypeScript 脚本执行具体操作
9. 9. 结果整合与反馈：格式化执行结果，更新会话状态
10. 10. 响应生成与返回：生成最终用户响应，通过原始渠道返回

4.2 推理执行层

推理执行层是智能体的“思维核心”，负责 LLM 调用和决策循环。

4.2.1 ReAct/TAOR 范式

OpenClaw 严格遵循 ReAct（Reasoning + Acting）范式，通过以下循环实现智能决策：

• • Thought（思考） ：基于当前状态进行推理，生成下一步行动计划
• • Action（行动） ：选择并执行合适的工具调用
• • Observation（观察） ：收集执行结果
• • Repeat（重复） ：根据观察结果调整后续策略，形成闭环

Claude Code 采用类似的 TAOR（Think-Act-Observe-Repeat）循环，维持 Agent 行为节拍。

4.2.2 模型调用管道（Dify 实践）

Dify 的模型调用管道完整覆盖从提示词构建到响应处理的整个流程：

# 模型调用管道核心流程1. 提示词消息构建   ├── 用户输入   ├── 系统指令   ├── RAG 上下文   ├── 会话记忆   └── 多模态文件2. 模型调用   ├── 流式模式（逐步返回）   ├── 阻塞模式（一次返回）   └── 结构化输出模式（JSON Schema）3. 响应处理   ├── 推理内容提取（reasoning_content）   ├── 工具调用解析（tool_calls）   └── Token 用量追踪

4.2.3 动态提示词组装

Claude Code 的引擎层负责动态提示词组装，根据不同的运行模式注入数百个提示碎片，其中安全守则就高达 5,677 个 token。这种设计体现了：

• • 上下文自适应：根据任务类型动态加载相关提示
• • 模块化提示碎片：可复用、可组合的提示单元
• • 安全优先：安全规则作为最高优先级的提示注入

提示词工程最佳实践：

• • 使用系统消息定义角色和约束
• • 使用 few-shot 示例引导输出格式
• • 使用思维链（CoT）提升复杂推理
• • 使用 XML 标签或 JSON Schema 结构化输出

4.3 工具与能力层

工具与能力层是智能体的“手脚”，决定了智能体与现实世界的交互能力。

4.3.1 工具系统设计（Claude Code 实践）

Claude Code 内置约 40 个独立工具，分为五大类：

工具定义规范（示例） ：

{"name":"read_file","description":"读取指定路径的文件内容","parameters":{"type":"object","properties":{"path":{"type":"string","description":"文件路径"},"encoding":{"type":"string","default":"utf-8"}},"required":["path"]},"permissions":["filesystem:read"],"timeout_ms":30000}

4.3.2 技能系统（OpenClaw 实践）

OpenClaw 的 Skills 作为执行单元，具有以下特性：

• • 模块化设计：易于扩展和复用
• • 标准化接口定义：YAML/JSON 描述文件
• • 社区驱动的技能生态：可动态加载和卸载
• • 沙箱隔离：Cell Isolation 机制确保安全执行

技能描述文件示例（skill.yaml） ：

name:send_emailversion:1.0.0description:发送电子邮件author:communitydependencies:-python:">=3.9"-pip: ["smtplib", "email"]inputs:-name:recipienttype:stringrequired:true-name:subjecttype:string-name:bodytype:stringoutputs:-name:successtype:boolean-name:message_idtype:stringpermissions:-network:smtpexecution:runtime:pythonentrypoint:main.py

技能加载流程：

1. 1. 系统启动时扫描 ./skills/ 目录
2. 2. 读取所有 YAML/JSON 描述文件
3. 3. 验证依赖和权限
4. 4. 将技能功能摘要注入 LLM 的 system prompt
5. 5. Agent 根据任务需求动态匹配和调用技能

4.3.3 MCP 协议集成

MCP（Model Context Protocol）作为连接模型与数据源、工具的标准接口，被誉为 AI 时代的“USB-C”接口。

MCP 核心概念：

• • Resources：暴露数据源（文件、数据库、API）
• • Tools：提供可调用的函数
• • Prompts：预定义的提示模板
• • Sampling：允许服务端请求模型生成

Claude Code 的 MCP 配置加载优先级：

1. 1. --mcp-config 命令行参数
2. 2. 企业配置（Enterprise MCP）
3. 3. 项目配置（.mcp.json）
4. 4. 用户配置（~/.claude/mcp.json）

MCP 集成示例：

{"mcpServers":{"filesystem":{"command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/workspace"],"env":{}},"github":{"command":"npx","args":["-y","@modelcontextprotocol/server-github"],"env":{"GITHUB_TOKEN":"{{secret}}"}}}}

4.3.4 Agent 策略模式（Dify 插件 SDK）

Dify 的 Agent 扩展点采用策略模式设计：

# Agent 策略抽象基类classAgentStrategy(ABC):"""实现 Agent 逻辑，编排 LLM 调用和工具调用"""    @abstractmethoddef_invoke(self, parameters: Dict) -> Generator:"""核心 Agent 策略逻辑，流式返回"""passdef_init_prompt_tools(self, tools: List[ToolEntity]) -> List[PromptMessageTool]:"""将 ToolEntity 转换为 LLM 可理解的 PromptMessageTool"""passdef_convert_tool_to_prompt_message_tool(self, tool: ToolEntity) -> PromptMessageTool:"""转换为 OpenAI function calling 格式"""return PromptMessageTool(            name=tool.name,            description=tool.description,            parameters=tool.parameters        )

4.4 记忆与状态层

记忆是智能体区别于传统聊天机器人的核心能力。智能体需要具备对历史场景的感知能力，通过记忆功能和知识库实现连续对话与跨会话的上下文延续。

4.4.1 三层记忆架构

Claude Code 实现三层记忆架构：

核心设计原则： “按需拉取，绝不塞满” —— 避免将全部历史内容填入上下文窗口。

4.4.2 Auto-Dream 记忆整合机制

Claude Code 的基础设施层内置了一个名为“做梦”的后台进程。每 24 小时或 5 次会话后，系统会启动子代理进行记忆整合、清理噪声，将模糊表述固化为确定知识。

整合流程：

1. 1. 扫描长期记忆中的相关条目
2. 2. 识别重复、矛盾或过时信息
3. 3. 合并相似内容，删除冗余
4. 4. 生成摘要和关键事实
5. 5. 写回向量数据库并更新索引

4.4.3 OpenClaw 的本地记忆系统

OpenClaw 采用本地 Markdown 文件作为记忆存储，适合隐私敏感场景：

• • 持久化会话历史（~/.openclaw/memory/conversations/）
• • 支持跨会话上下文（通过文件索引）
• • 实现个性化记忆（用户画像存储）
• • 保障数据隐私安全（完全本地，不上传）

4.4.4 上下文压缩机制

OpenClaw 的 Gateway 层实现了上下文压缩（Context Pruning）：

• • 提取意图，过滤掉无用的对话历史
• • 滑动窗口 + 关键帧压缩管理超大上下文
• • 保留最近 50K token 完整上下文
• • 历史内容采用摘要压缩（LLM 生成摘要）
• • 分层索引（文件级、函数级、代码块级三级索引），支持 O(log n) 检索
• • 注意力热力图：基于注意力机制识别重要内容，延长其保留时间

压缩策略示例：

defcompress_context(history: List[Message], max_tokens: int = 100000) -> List[Message]:# 1. 保留最近 N 条完整消息    recent = history[-20:]# 2. 对更早的消息生成摘要    old = history[:-20]if token_count(old) > max_tokens - token_count(recent):        summary = llm.summarize(old)return [summary] + recentreturn history

4.5 多智能体协作

面对需多领域协同的复杂任务，单一 Agent 往往力不从心。多智能体系统（MAS）通过将任务拆解并交由不同专长的 Agent 协作完成，实现“1+1>2”的集体智能。

4.5.1 多智能体架构模式

业界已形成三类成熟的多智能体架构：

4.5.2 Coordinator 协调器模式

Claude Code 采用 Coordinator（协调器）模式处理复杂任务规划和工具调用：

任务分解策略：- 基于依赖图的自动分解：分析任务间的数据依赖关系- 基于角色的分解：按能力领域分配子任务- 基于规模的分解：大任务递归拆分到可执行粒度调度算法：- 优先级队列：关键路径任务优先- 负载均衡：动态分配子 Agent 负载- 故障转移：子 Agent 失败时自动重试或降级结果聚合：- 并行合并：无依赖结果直接合并- 顺序组合：有依赖结果按序组装- 冲突解决：检测并解决结果冲突

4.5.3 Agent 间通信协议

推荐使用 A2A（Agent-to-Agent Protocol） 草案或自定义轻量协议：

{"protocol":"a2a/1.0","message_id":"uuid","sender":"coordinator","recipient":"code_agent","type":"task","payload":{"task_id":"task_001","action":"analyze_code","params":{"path":"/src"}},"context":{"parent_trace_id":"trace_xyz"}}

4.5.4 多智能体协作示例

# 伪代码：多智能体协作工作流deforchestrate(user_request):    coordinator = CoordinatorAgent()# 1. 分解任务    subtasks = coordinator.decompose(user_request)# 结果: [{"type": "research", "query": "..."}, {"type": "code", "spec": "..."}]# 2. 分配子任务    research_future = executor.submit(ResearchAgent, subtasks[0])    code_future = executor.submit(CodeAgent, subtasks[1])# 3. 等待结果    research_result = research_future.result(timeout=60)    code_result = code_future.result(timeout=120)# 4. 聚合与冲突解决    final = coordinator.aggregate([research_result, code_result])return final

第5节 数据架构

5.1 数据模型设计

智能体系统的核心数据实体包括：

5.2 向量数据库设计

向量数据库用于长期语义记忆存储，是 RAG 的核心组件。

选型考量：

集合设计示例：

{"collection_name":"agent_memories","vectors":{"size":1536,// 取决于 embedding 模型"distance":"Cosine"},"payload_schema":{"user_id":"string","session_id":"string","type":{"type":"keyword","options":["fact","preference","episode"]},"importance":"float","timestamp":"int","ttl":"int"}}

检索策略：

• • 混合检索：向量相似度 + 关键词过滤（BM25）
• • 重排序：使用 Cross-encoder 精排 top-k
• • 时间衰减：降低旧记忆的权重

5.3 知识库管理（RAG）

Dify 的 RAG 管道设计：

文档上传 → 文档加载 → 文本分割 → 向量化 → 索引存储 → 检索 → 上下文增强

文本分割策略：

• • 按段落分割（保留语义完整性）
• • 按固定大小分割（512/1024 tokens）带重叠（10-20%）
• • 递归分割（优先按句子、段落边界）

检索增强：

• • 检索 top-k 相关片段（k=5~10）
• • 与用户问题拼接为增强上下文
• • 限制总 token 数（不超过模型上下文的一半）

5.4 数据生命周期管理

第6节 LLM 集成与提示词工程

6.1 模型选择策略

模型路由策略：

• • 简单任务（问候、FAQ）→ 轻量模型
• • 中等任务（工具调用、摘要）→ 平衡模型
• • 复杂任务（代码生成、多步推理）→ 旗舰模型
• • 敏感数据（隐私相关）→ 本地私有模型

6.2 提示词模板管理

三层提示词架构：

1. 1. 系统级提示（不可覆盖）：安全规则、身份定义
2. 2. 场景级提示（可配置）：角色扮演、任务上下文
3. 3. 动态提示（运行时注入）：检索结果、工具描述、历史记忆

提示词版本管理：

• • 使用 Git 管理提示词模板
• • 支持 A/B 测试不同提示词
• • 记录提示词变更与模型效果关联

6.3 结构化输出

强制 LLM 输出结构化数据以便后续程序化处理：

# 使用 JSON Schema 约束输出response_format = {"type": "json_schema","json_schema": {"name": "task_plan","schema": {"type": "object","properties": {"steps": {"type": "array", "items": {"type": "string"}},"estimated_time": {"type": "integer"}            },"required": ["steps"]        }    }}

6.4 成本控制

第7节 安全架构

7.1 安全设计原则

7.2 三道防线详解

防线一：命令黑名单

直接拦截 LLM 输出的危险命令模式，不经用户确认：

DANGEROUS_PATTERNS = [r'\brm\s+(-[a-zA-Z]*f[a-zA-Z]*\s+|.*--no-preserve-root)',  # rm -rfr'\brm\s+(-[a-zA-Z]*r[a-zA-Z]*\s+)?/',  # rm /r'\bmkfs\b',        # 格式化磁盘r'\bdd\s+.*of\s*=\s*/dev/',  # 覆写磁盘r'>\s*/dev/sd[a-z]',  # 重定向到磁盘设备r'curl.*\|\s*bash',  # 管道执行远程脚本r'wget.*-O\s+\/etc\/',  # 覆写系统配置]

防线二：用户确认

对于非黑名单但潜在敏感的操作，弹出确认框让用户决定 Allow 或 Deny。这是人机协作的安全边界。

敏感操作示例：

• • 删除非临时目录文件
• • 修改系统配置
• • 网络请求到非白名单域名
• • 安装软件包

防线三：输出截断

限制命令输出大小，防止 LLM 陷入循环或输出过大的内容撑爆上下文窗口。

MAX_OUTPUT_LINES = 10000TRUNCATE_KEEP_HEAD = 2500TRUNCATE_KEEP_TAIL = 2500deftruncate_output(output: str) -> str:    lines = output.splitlines()iflen(lines) <= MAX_OUTPUT_LINES:return outputreturn"\n".join(        lines[:TRUNCATE_KEEP_HEAD] +        [f"... (truncated {len(lines) - TRUNCATE_KEEP_HEAD - TRUNCATE_KEEP_TAIL} lines) ..."] +        lines[-TRUNCATE_KEEP_TAIL:]    )

7.3 沙箱隔离

OpenClaw 的 Pi-embedded 实现了 Cell Isolation 沙箱机制：

• • 执行前先快照当前环境变量
• • 动态加载 .ocskill 文件
• • 在独立的 venv 中运行技能，需明确定义 dependencies
• • 执行临时 Python 进程，将本地传感器权限挂载进去

容器级沙箱（推荐用于生产）：

# 使用 gVisor 或 Kata Containers 增强隔离FROM alpine:3.19RUN apk add --no-cache python3COPY skill.py /skill.pyUSER nobodyENTRYPOINT ["python3", "/skill.py"]

7.4 权限管理模式

Claude Code 支持三种权限模式：

细粒度权限（建议设计）：

permissions:  - filesystem:read:/workspace/*  - filesystem:write:/workspace/tmp/*  - network:https:api.github.com  - process:run:node

7.5 审计与监控

所有工具调用记录至审计日志，定期自动生成安全报告推送用户。

审计日志条目：

{"timestamp":"2026-04-04T10:30:00Z","traceId":"a1b2c3d4e5f6","user_id":"user123","session_id":"sess_abc","action":"tool_call","tool_name":"execute_command","parameters":{"command":"ls -la"},"result":"success","output_truncated":false,"permission_mode":"default","risk_level":"low"}

第8节 可观测性设计

8.1 可观测性三支柱

智能体系统需要建立完整的可观测性体系：

8.2 关键指标

8.3 链路追踪设计

OpenClaw 默认开启了性能上报，支持完整的调用链追踪：

用户请求 → Gateway → Agent 决策 → 技能调用 → 系统执行 → 结果返回    │          │          │           │          │    └──────────┴──────────┴───────────┴──────────┘                         │                    统一 traceId

Span 设计示例：

with tracer.start_as_current_span("agent_execute") as span:    span.set_attribute("user_id", user_id)    span.set_attribute("model", "gpt-4o")with tracer.start_as_current_span("llm_call"):        response = llm.invoke(prompt)with tracer.start_as_current_span("tool_call", attributes={"tool": "search"}):        result = search(query)    span.set_attribute("total_tokens", response.usage.total_tokens)

8.4 调试与追踪工具

第9节 部署架构

9.1 部署模式

9.2 OpenClaw 部署模型

OpenClaw 推荐“每台主机一个 Gateway”的部署模型：

• • 每台主机一个 Gateway，保持单一事实源
• • WebSocket 默认仅绑定 loopback（ws://127.0.0.1:18789）
• • 非 loopback 绑定必须显式携带 token
• • 节点通过 WebSocket 连接 Gateway（LAN、Tailnet、SSH 隧道）

9.3 容器化配置示例

Dockerfile：

FROM node:20-slim AS builderWORKDIR /appCOPY package*.json ./RUN npm ci --only=productionFROM node:20-slimWORKDIR /appCOPY --from=builder /app/node_modules ./node_modulesCOPY . .RUN apt-get update && apt-get install -y python3 git && rm -rf /var/lib/apt/lists/*EXPOSE1878918793ENV NODE_ENV=productionUSER nodeCMD ["node", "gateway.js"]

Kubernetes Deployment：

apiVersion:apps/v1kind:Deploymentmetadata:name:agent-gatewayspec:replicas:3selector:matchLabels:app:agent-gatewaytemplate:metadata:labels:app:agent-gatewayspec:containers:-name:gatewayimage:agent-gateway:latestports:-containerPort:18789env:-name:REDIS_URLvalueFrom:secretKeyRef:name:redis-secretkey:urlresources:requests:memory:"512Mi"cpu:"250m"limits:memory:"2Gi"cpu:"1000m"livenessProbe:httpGet:path:/healthport:18789readinessProbe:httpGet:path:/readyport:18789

9.4 高可用设计

9.5 环境配置管理

使用 ConfigMap 和 Secret 管理配置：

# configmap.yamlapiVersion:v1kind:ConfigMapmetadata:name:agent-configdata:app.config:|    llm:      default_model: gpt-4o      fallback_model: gpt-4o-mini      timeout: 60    memory:      vector_store: qdrant      embedding_model: text-embedding-3-small    security:      require_confirmation: true      max_output_lines: 10000

第10节 性能与成本优化

10.1 性能优化策略

10.2 成本优化策略

10.3 Token 预算管理

classTokenBudget:def__init__(self, max_total_tokens: int = 8000):self.max_total = max_total_tokensdefallocate(self, system_prompt: str, user_input: str, context: str) -> dict:        total = count_tokens(system_prompt + user_input + context)if total > self.max_total:# 按优先级截断：优先保留 system，其次 user，最后 context            context = truncate(context, self.max_total - count_tokens(system_prompt + user_input))return {"system_prompt": system_prompt,"user_input": user_input,"context": context,"total_tokens": count_tokens(system_prompt + user_input + context)        }

第11节 测试与评估体系

11.1 测试层次

11.2 评估指标

任务成功率：

• • 定义：Agent 正确完成用户请求的比例
• • 评估：人工标注 + 自动化断言（如单元测试输出对比）

工具调用准确率：

• • 定义：Agent 选择的工具是否合适、参数是否正确
• • 评估：对比期望工具与实际调用

幻觉检测：

• • 使用 Faithfulness 指标（RAGAS 框架）
• • 检测 LLM 输出是否与检索内容矛盾

效率指标：

• • 平均步骤数：完成任务所需的 ReAct 循环次数
• • Token 效率：每任务消耗的 token 数

11.3 评估数据集构建

• • 黄金数据集：100-500 个典型用户问题 + 期望答案/操作序列
• • 边界案例集：歧义输入、错误格式、超长输入
• • 安全测试集：prompt 注入、越狱尝试、危险指令

11.4 持续评估

# CI/CD 流水线中的评估步骤evaluate:stage:testscript:-python-magent.evaluate--dataset./tests/golden.json-python-magent.evaluate--safety./tests/safety.jsonartifacts:reports:metrics:metrics.jsonrules:-if:$CI_MERGE_REQUEST_ID-if:$CI_COMMIT_BRANCH=="main"

第12节 异常处理与容错

12.1 异常分类

12.2 重试与退避策略

classRetryConfig:    max_retries = 3    initial_delay = 1# seconds    backoff_factor = 2    retryable_exceptions = (RateLimitError, TimeoutError, ServerError)asyncdefcall_with_retry(func, *args, **kwargs):    delay = initial_delayfor attempt inrange(max_retries):try:returnawait func(*args, **kwargs)except retryable_exceptions as e:if attempt == max_retries - 1:raiseawait asyncio.sleep(delay)            delay *= backoff_factor

12.3 降级与熔断

from circuitbreaker import circuit@circuit(failure_threshold=5, recovery_timeout=60)asyncdefcall_llm(prompt):# 主模型调用try:returnawait gpt4_call(prompt)except Exception:# 降级到备用模型returnawait gpt35_call(prompt)

12.4 错误恢复

当 Agent 执行陷入循环或错误时：

1. 1. 检测循环：相同 Thought-Action 重复超过 3 次
2. 2. 注入恢复提示："You seem to be stuck. Please try a different approach or ask for clarification."
3. 3. 人工介入：敏感任务或多次失败后请求用户协助
4. 4. 保存状态：将当前任务状态持久化，允许后续恢复

第13节 核心技术决策（ADR 范式）

ADR-001：智能体执行范式选择

状态: 已接受

上下文：需要选择智能体的核心执行范式，决定系统如何将用户意图转化为行动。

决策：采用 ReAct（Reasoning + Acting） 范式作为核心执行模型，具体实现为 Thought → Action → Observation 循环。

理由：

1. 1. 经 OpenClaw 和 Claude Code 验证，ReAct 范式能有效处理开放域任务
2. 2. 思考与行动的交替使执行过程可追踪、可调试
3. 3. 相比纯链式调用，ReAct 具备更强的适应性

备选方案：

• • Plan-and-Execute：先规划后执行，但缺乏中间反馈调整能力
• • 纯 Function Calling：仅适合简单工具调用场景

ADR-002：编排层架构选型

状态: 已接受

上下文：需要选择任务的编排和调度机制，决定如何处理复杂多步骤任务。

决策：采用 DAG 工作流引擎 + ReAct Agent 循环 的双层编排架构：

• • 确定性任务使用 DAG 工作流编排
• • 探索性任务使用 ReAct Agent 自主规划

理由：

1. 1. DAG 模型提供可预测性，适合标准化流程（SOP 智能体）
2. 2. ReAct Agent 提供灵活性，适合开放问题求解
3. 3. 两种模式可混合使用，实现最佳效果

备选方案：

• • 纯 Agent 自主规划：灵活性高但不可预测，Token 消耗大
• • 纯工作流编排：可预测但灵活性差

ADR-003：记忆架构设计

状态: 已接受

上下文：需要设计记忆系统，支持跨会话的上下文延续和知识积累。

决策：采用 三层记忆架构 + Auto-Dream 整合机制：

并实现 Auto-Dream 机制定期进行记忆整合与压缩。

理由：

1. 1. 三层架构实现“按需拉取，绝不塞满”
2. 2. Auto-Dream 机制将模糊表述固化为确定知识
3. 3. 滑动窗口 + 关键帧压缩有效管理超大上下文

备选方案：

• • 单一向量存储：检索性能好但缺乏状态管理
• • 全量上下文保留：Token 消耗大，成本高

ADR-004：工具调用与技能系统设计

状态: 已接受

上下文：需要设计工具调用机制，支持动态扩展能力边界。

决策：采用 插件化技能系统 + MCP 协议集成 的双层能力架构：

• • 核心技能：内置，标准化接口，沙箱隔离
• • 扩展技能：通过 MCP 协议集成第三方工具
• • 技能描述采用 YAML/JSON 声明式配置

理由：

1. 1. 插件化架构实现模型提供商与核心代码的完全解耦
2. 2. MCP 协议提供标准化的工具接入方式
3. 3. 声明式配置降低技能开发门槛

备选方案：

• • 硬编码工具调用：简单但不可扩展
• • 纯 MCP 依赖：依赖生态成熟度

ADR-005：安全与权限控制

状态: 已接受

上下文：Agent 具备执行系统操作的能力，必须设计严格的安全控制机制。

决策：采用 三道防线 + 最小权限 的安全架构：

1. 1. 防线一（命令黑名单） ：直接拦截危险模式
2. 2. 防线二（用户确认） ：敏感操作需用户二次确认
3. 3. 防线三（输出截断） ：限制工具输出大小

同时遵循最小权限原则，所有工具调用均在白名单内。

理由：

1. 1. 三道防线由外到内逐层过滤，兼顾安全与用户体验
2. 2. LLM 可能因幻觉或 prompt 注入执行危险操作，必须有防御机制
3. 3. OpenClaw 和 Claude Code 均采用类似设计

备选方案：

• • 完全禁止系统操作：过于保守，丧失核心能力
• • 完全信任 LLM：风险过高

ADR-006：模型路由与成本控制

状态: 已接受

上下文：不同任务对模型能力要求不同，需要平衡效果与成本。

决策：实现 动态模型路由：

• • 简单任务（分类、提取）→ 轻量模型（GPT-4o-mini、Llama 8B）
• • 中等任务（工具调用、摘要）→ 平衡模型（GPT-4o-mini、Claude 3 Haiku）
• • 复杂任务（代码、推理）→ 旗舰模型（GPT-4o、Claude 3.5 Sonnet）

理由：

1. 1. 可节省 40-60% 的 API 成本
2. 2. 不影响核心复杂任务的效果
3. 3. 可根据用户等级或场景配置策略

备选方案：

• • 统一使用旗舰模型：成本高，但简单
• • 完全本地模型：成本低但效果可能下降

第14节 架构师工具箱

14.1 架构设计决策要点

设计智能体系统时需回答的核心问题：

1. 1. 能力组合：工具和技能如何组织？如何扩展？
2. 2. 状态持续：跨会话的记忆如何管理？上下文如何压缩？
3. 3. 风险控制：安全边界如何定义？如何防止 LLM 执行危险操作？
4. 4. 成本与效果平衡：模型路由策略是什么？如何优化 Token 消耗？
5. 5. 可观测性：如何追踪 Agent 的“思考”过程？如何调试失败案例？

14.2 架构评估清单

核心能力检查：

• • 是否定义了清晰的感知-决策-行动-记忆认知闭环？
• • 是否选择了合适的执行范式（ReAct/DAG 混合）？
• • 是否实现了三层记忆架构？
• • 工具调用系统是否支持插件化扩展？
• • 是否集成了 MCP 协议？

安全与合规检查：

• • 是否实现了命令黑名单机制？
• • 敏感操作是否有用户确认机制？
• • 工具输出是否有限制截断？
• • 是否有完整的审计日志？
• • 是否遵循最小权限原则？

可观测性检查：

• • 是否有 traceId 全链路贯穿？
• • 关键指标是否可监控？
• • Token 用量和成本是否可追踪？
• • 是否支持调试 Agent 决策过程？

部署与运维检查：

• • 是否支持本地优先部署？
• • 是否支持容器化？
• • Gateway 默认绑定是否安全？
• • 是否支持高可用？

测试与评估检查：

• • 是否有评估数据集？
• • 是否持续评估任务成功率？
• • 是否有对抗性测试？

14.3 参考开源项目

14.4 推荐阅读

• • [AI Agent 智能体技术发展报告]（中国工业互联网研究院，2026）
• • 吴恩达《Building AI Agents》课程（Agent Workflow 框架）
• • Claude Code 泄露源码分析系列（五层架构解析）
• • MCP 协议规范（Model Context Protocol）
• • 《Designing Autonomous AI》by Kence Anderson
• • RAGAS：RAG 评估框架文档