文章目录
- 系列文章
- 从 LLM 到 AI Agent 的架构跃迁
- Agent 的核心四维架构
- 编排框架全景透视
- 主流开源编排框架横向评测
- 为何通用领域难以诞生“统治级”框架？
- 核心痛点：Plugins 与 Skills 的“巴别塔”困境
- 概念厘清：原子操作 vs 复合能力
- 各框架原生工具抽象的“不兼容”现状
- 生态破局：第三方工具市场与统一协议的崛起
- 协议级破局：MCP (Model Context Protocol)
- 平台级破局：Composio (跨框架 SaaS 集成)
- 自动化工作流复用：n8n / Activepieces
- 工程落地：构建高可扩展的 Agent 工具架构
- 本工程选型评估（多Agent审查系统）
- 结语
- 附录
- LangGraph 工程实践
- 项目概况与核心定位
- 工程落地实践指南
- DeepSeek Harness 工程实践
- 项目概况与核心定位
- 工程落地实践指南
- OpenClaw 个人开发者完全指南
Agent编排框架本身不负责Token生成，它仅驱动Agent主循环（思考→工具调用→观察→再次思考）、状态流转、子Agent任务分发、日志追踪；底层LLM请求统一转发到vLLM OpenAI兼容接口。
系列文章
CoT+RAG+AI推理·工程手记 篇一（含索引）：系统架构与工程结构概览
CoT+RAG+AI推理·工程手记 篇二：Hugging Face 与 DeepSeek 模型生态全景解析
CoT+RAG+AI推理·工程手记 篇三：Hugging Face 模型仓库结构全解析
CoT+RAG+AI推理·工程手记 篇四：DeepSeek-R1-0528-Qwen3-8B 模型解析
CoT+RAG+AI推理·工程手记 篇五：BGE-Large-ZH-V1.5 模型解析
CoT+RAG+AI推理·工程手记 篇六：模型加载和多轮流式对话实现
CoT+RAG+AI推理·工程手记 篇七：搜索增强生成（RAG）实现
CoT+RAG+AI推理·工程手记 篇八：流式AI对话API服务
CoT+RAG+AI推理·工程手记 篇九：日志和配置、测试工具等辅助代码及配置
CoT+RAG+AI推理·工程手记 篇十：纯推理和AI知识库问答简易前端
CoT+RAG+AI推理·工程手记 篇十一：Qwen3.8-27B 及其社区衍生版本深度解析与选型实践
CoT+RAG+AI推理·工程手记 篇十二：大模型推理引擎选型与vLLM生产级迁移实战
CoT+RAG+AI推理·工程手记 篇十三：单卡并发多AI对话
从 LLM 到 AI Agent 的架构跃迁
大语言模型（LLM）本身只是一个基于概率的文本生成引擎，而 AI Agent 则是赋予该引擎感知、规划与执行能力的复杂系统工程。
Agent 的核心四维架构
生产级 Agent 绝非简单的Prompt + LLM，而是由以下四个核心模块构成闭环系统：
- 大脑（Brain/LLM）：负责意图理解、逻辑推理与任务拆解（CoT）。
- 记忆（Memory）：包括短期记忆（当前对话上下文）与长期记忆（基于 RAG 的向量知识库或关系型状态存储）。
- 规划（Planning）：将复杂目标分解为可执行的子任务序列（如 ReAct、Plan-and-Solve 范式）。
- 工具（Tools/Action）：突破模型参数知识边界，与物理世界或数字系统交互的“手脚”。
工程箴言：Agent 的强大不在于模型参数有多大，而在于其“工具调用的可靠性”与“状态管理的鲁棒性”。模型决定了 Agent 智力的上限，而工程架构决定了其稳定性的下限。
编排框架全景透视
开源Agent编排框架可划分为两大类：SDK库（嵌入自有业务系统，无内置UI）、一体化平台（自带WebUI、任务调度、会话管理，开箱即用）。
当前 Agent 编排框架正处于“标准未定、诸子百家”的阶段。严格来说，通用领域目前不存在具备“事实统治力”的开源项目，但在细分场景下已出现准统治者。
主流开源编排框架横向评测
| 框架名称 | 类型 | 核心编排范式 | 优势与最佳适用场景 | 工程局限与避坑指南 |
|---|---|---|---|---|
| LangGraph | Python SDK | 基于图（Graph）的状态机 | 生产级复杂工作流。支持循环、条件分支、持久化检查点、嵌套子图与人工介入（Human-in-the-loop）；LangSmith全链路审计，企业落地案例丰富；Python生产复杂多Agent细分赛道具备事实统治地位。适合审查、合规类长链路任务。 | 学习曲线极陡，抽象层过重；原生工具强绑定 LangChain 生态，调试链路长。 |
| CrewAI | Python SDK | 角色扮演（Role-Playing） | 多智能体协作原型。内置任务委派与层级流程，API极简，声明式配置，少量代码即可搭建多Agent；原生支持MCP。适合内容生成、调研、模拟团队分工。 | 底层执行逻辑简单，缺乏精细的状态容错与错误恢复机制，高并发长任务稳定性存疑；复杂嵌套子Agent能力弱。 |
| AutoGen（AG2） | Python SDK | 对话式多 Agent 协作 | 学术研究与代码沙盒。微软主导，GroupChat群聊机制，支持多Agent对话辩论、代码自动执行，学术影响力大；模型无关。 | 架构偏重研究，生产部署复杂；项目进入维护模式，微软主推新一代Microsoft Agent Framework；v0.4重构带来生态过渡期，历史代码兼容性差；新项目不推荐选用。 |
| LlamaIndex Agents | SDK | RAG优先Agent | 文档解析、向量检索能力极强；Agent天然绑定检索增强，内置LlamaParse文档解析组件。适合知识库问答、文档精读类Agent。 | Agent编排不是主业，复杂多Agent协同、状态管理能力偏弱，通用性弱于LangGraph。 |
| smolagents | SDK | 极简薄抽象 | HuggingFace官方维护，Apache2.0；ToolCallingAgent/CodeAgent两类模型；抽象轻量化，本地模型友好，支持MCP与代码沙箱。适合单Agent快速原型验证。 | 缺少内置多Agent编排、状态持久化、Human-in-loop，上层业务逻辑需自研。 |
| OpenClaw（龙虾Agent） | 一体化Agent平台 | MCP工具优先 | 完整运行时、Agent主循环、MCP Hub、前端UI一体化；原生优先MCP协议，开箱复用海量社区MCP工具，支持对接vLLM。适合小团队本地助手、快速工具原型验证、文档自动化。 | 深度自定义复杂业务工作流、嵌套子Agent能力弱；企业审计、权限管控偏弱，偏向个人助手场景。 |
| DeepSeek Harness | 插件化Agent平台 | 一切皆插件（Cordis内核） | 模型后端、工具、沙箱、存储、UI全部可插拔；原生内置代码/命令沙箱、多Agent调度、完整日志审计；OpenAI兼容接口对接vLLM，MIT协议。适合自研Agent平台、深度插件定制，审查备选方案。 | 社区体量小于OpenClaw，公开文档、落地案例偏少，国内社区为主。 |
| Semantic Kernel | SDK | 插件规划 | 微软出品，跨语言.NET/Python；企业安全、权限模型完善，.NET生态插件成熟。适合.NET技术栈政企内部系统。 | Python生态体验弱于LangGraph；多Agent编排抽象较重。 |
| Dify.AI | 低代码一体化平台 | 可视化拖拽+BaaS架构 | 企业级低代码交付。内置RAG、工具管理全链路，国内企业开箱即用，低代码赛道准统治者；自带API、用户权限。 | 高度封装导致定制化天花板明显；复杂自定义多Agent逻辑受限，存在黑盒风险。 |
为何通用领域难以诞生“统治级”框架？
- 模型进化速度 > 框架迭代速度：当底层模型上下文与推理能力跃迁时，原本需要复杂多 Agent 编排的任务可能退化为单 Agent 即可完成，框架的“编排复杂度”反成负担。
- 场景碎片化极高：RAG问答、代码生成、数据分析、合规审查对状态机、容错、审计的需求截然不同，不存在“万能抽象”。
- 协议标准未完全收敛：A2A等多智能体通信协议仍处于早期；早期各框架自建工具体系，形成围墙花园。
核心痛点：Plugins 与 Skills 的“巴别塔”困境
对于 Agent 而言，Plugins（插件）和 Skills（技能）是决定其从“聊天玩具”走向“生产力工具”的生死线。然而，当前工具生态面临着严重的碎片化危机。
概念厘清：原子操作 vs 复合能力
- Plugins（插件/工具）：原子级操作。单一API/能力封装，输入输出结构化（如
search_web(query)、PDF读取、数据库查询），底层多基于Function Calling实现。说明：MCP Server属于Plugin，只解决外部调用，不包含业务编排逻辑。
- Skills（技能）：复合级能力。由多个Plugins组合而成，包含内部状态机、提示词模板、错误重试、多步规划逻辑。例如“法规条款比对”技能：文档分片→检索法规原文→条款对比→冲突校验→引用溯源。
跨框架可移植性：
- Plugin采用MCP协议后可跨框架复用；
- 原生框架Plugin为私有格式无法直接迁移；
- Skill只能复用提示词与业务思路，状态流转、子Agent逻辑需要适配框架，无法一键迁移。
各框架原生工具抽象的“不兼容”现状
每个编排框架为了绑定开发者，都设计了自己的一套 Tool 注册机制，原生状态下完全不兼容：
- LangChain / LangGraph：采用
@tool装饰器与BaseTool类。生态积累最丰富，但过度封装，版本升级容易触发依赖冲突。 - AutoGen：基于Python函数签名TypeHint自动推断JSON Schema，自成一套，跨框架迁移需要重写参数解析。
- Dify：可视化YAML配置+OpenAPI规范，闭环生态，插件不能直接导出给纯代码SDK框架。
- DeepSeek Harness：Cordis私有插件体系，仅DSH原生识别。
- OpenClaw：自有plugin.json清单格式，原生插件无法直接导入LangChain。
工程叹息：如果你用 LangChain 编写了一个复杂的
Regulation_Clause_Analyzer技能，当你想把底层框架换成 CrewAI 时，你必须重写该技能的注册、状态流转与鉴权代码。这种“重复造轮子”是Agent开发最大的阻碍。
生态破局：第三方工具市场与统一协议的崛起
为了解决框架间不兼容的痛点，业界正在通过“统一协议”和“中间件平台”两个方向破局。目前已有热度极高的独立第三方开源项目。
协议级破局：MCP (Model Context Protocol)
由Anthropic发起，现已移交Linux基金会Agentic AI Foundation，MCP正在成为Agent工具接入的“通用接口”。
- 核心逻辑：不再让Agent框架适配各类API，而是工具方实现标准MCP Server。Agent框架只要内置MCP Client，即可无缝调用全部MCP服务。
- 生态现状：热度爆发式增长。本地文件、PostgreSQL、Git、网页抓取等大量开源MCP Server；Cursor、Claude Desktop原生支持；LangGraph、CrewAI、smolagents、OpenClaw、DeepSeek Harness均已提供官方/社区MCP适配器。
第三方MCP资源仓库：Awesome-MCP-Servers、LobeHub MCP Marketplace、MCPFind.org；收录数千个MCP插件，属于中立独立的Plugin市场。Skill没有统一公共市场，仅分散在各框架Cookbook与Awesome列表。
平台级破局：Composio (跨框架 SaaS 集成)
目前最知名的跨框架第三方工具集成平台，充当“工具聚合器”。
- 核心逻辑：官方维护上百种主流SaaS（GitHub, Salesforce, Gmail等）鉴权与API封装，对外提供LangChain、CrewAI、AutoGen适配SDK。
- 工程价值：只需在Composio配置OAuth鉴权，一行代码即可将带鉴权状态的工具注入任意编排框架，规避业务代码硬编码Token刷新逻辑。
自动化工作流复用：n8n / Activepieces
- 核心逻辑：开源自动化工作流引擎，内置数百个生产验证的Actions，支持MCP暴露工作流为可调用工具。
- Agent 结合：复杂重型业务逻辑不在Agent代码内硬编码，Agent通过Webhook/MCP触发n8n工作流；n8n充当Agent的外部重型技能库。
工程落地：构建高可扩展的 Agent 工具架构
在实际工程中，建议放弃“寻找一个包含所有完美插件的单一框架”的幻想，采用“分层解耦”的工具架构设计：
| 架构层级 | 推荐技术选型 | 设计原则与工程考量 |
|---|---|---|
| 原子工具层 | MCP 协议 | 本地文件、数据库、标准SaaS接入全面拥抱MCP。工具与Agent编排框架物理解耦，工具提供方只需维护一份MCP Server，更换上层Agent框架无需重写底层工具。 |
| 复杂鉴权层 | Composio | 需要OAuth、多租户状态管理的第三方SaaS，由Composio托管鉴权，SDK桥接到编排框架，隔离鉴权复杂度。 |
| 重型技能层 | n8n / 自研微服务 | “生成报表并推送、多分支合规校验”这类包含大量条件分支与重试逻辑的Skills，封装为独立API或n8n工作流。Agent仅调用单一execute_workflow(id, params)插件。 |
本工程选型评估（多Agent审查系统）
底座：vLLM + Qwen3.8-9B + RAG；需求：任务拆解、子Agent分工、文档精读、引用校验、可审计日志、并发Agent调度。
- 方案A：LangGraph（优先推荐评估）
- 优势：状态可控、支持嵌套子Agent、断点续跑、LangSmith全链路追踪审计，高度适配合规审查场景；原生MCP集成。
- 代价：开发量更大，UI、业务工具封装需要自行搭建。
- 方案B：DeepSeek Harness
- 优势：插件体系，RAG检索封装为插件，内置沙箱，无需手写Agent主循环；国内社区友好。
- 劣势：社区落地案例少于LangGraph，文档偏少。
- 方案C：OpenClaw
- 优势：MCP工具一键接入，开箱可用UI，快速验证原型。
- 劣势：复杂子Agent任务拆分、长链路审计能力弱于LangGraph。
选型原则：长期迭代、强审计、复杂多子Agent协同，优先LangGraph；快速搭建完整平台、深度插件定制优先DeepSeek Harness；复用社区MCP工具、快速原型验证优先OpenClaw。
结语
Agent编排框架决定了 Agent“如何思考”，而工具生态（MCP、Composio、n8n）决定了 Agent“能做什么”。
当前最成熟的工程实践，是将“思考引擎”与“执行手脚”通过标准协议彻底解耦。在 Agent 范式完全收敛之前，保持架构的灵活性与可替换性，远比盲目追逐所谓的“统治级框架”更为重要。垂直行业（合规）场景中，框架仅作为编排骨架，核心业务能力（文档比对、风险提取等Skill）几乎都需要自研。
附录
LangGraph 工程实践
项目概况与核心定位
LangGraph 是由 LangChain 团队推出的开源 Agent 编排 SDK，专为构建有状态、多步骤、支持人工介入（Human-in-the-loop）的生产级 Agent 工作流而设计。核心抽象为有向循环图（Cyclic Graph）+ 持久化状态机，解决传统 DAG 编排无法原生处理循环推理、动态条件分支、断点恢复与历史回溯的工程痛点。底层可对接任意兼容 OpenAI 协议的推理后端，包括 vLLM、Ollama、OpenAI API。
- 官方资源：GitHub 仓库
langchain-ai/langgraph，官方文档站点 https://langchain-ai.github.io/langgraph - 核心特性：原生 Checkpointing（状态持久化）、Time Travel（历史状态回溯调试）、节点流式输出 Streaming、跨线程记忆管理；支持嵌套子图、中断暂停、全链路追踪；可接入 MCP Client，实现工具层与编排层解耦。
- 适用边界：适合企业级长链路复杂业务流，例如合规审查、客服工单处理、代码审查流水线、长周期数据分析；不适合简单单轮问答、无状态短 API 调用场景。
工程落地实践指南
阶段一：环境准备与快速开始（Quick Start）
- 安装核心依赖：通过 pip 安装基础运行包，持久化、特定工具按需扩展安装。
pipinstalllanggraph langchain-openai langchain-community# 生产环境PostgreSQL持久化扩展pipinstalllanggraph-checkpoint-postgres- 配置推理后端：实例化
ChatOpenAI时指向本地 vLLM/Ollama 兼容端点，配置base_url与 API 密钥，也可通过环境变量统一配置。 - 跑通最小化 Graph：定义仅包含
messages字段的基础状态，构建单 LLM 调用节点的最简图，通过graph.invoke()验证基础链路连通性。
fromlanggraph.graphimportStateGraph,MessagesState,START,ENDdefmock_llm(state:MessagesState):return{"messages":[{"role":"ai","content":"hello world"}]}graph=StateGraph(MessagesState)graph.add_node("llm_node",mock_llm)graph.add_edge(START,"llm_node")graph.add_edge("llm_node",END)graph=graph.compile()graph.invoke({"messages":[{"role":"user","content":"hi!"}]})阶段二：核心工作流与状态编排
- 定义状态模式（State Schema）：使用
TypedDict严格定义共享状态结构体（如AgentState），利用Annotated[list, add_messages]等内置 Reducer 处理状态合并，作为全工作流统一的数据契约，规避运行时类型异常。
fromtypingimportTypedDict,Annotated,Optionalfromlanggraph.graph.messageimportadd_messagesclassAgentState(TypedDict):messages:Annotated[list,add_messages]# 内置reducer自动合并消息plan_status:strhuman_feedback:Optional[str]reference_fragments:listrisk_list:list- 构建节点与边（Nodes & Edges）：将业务逻辑封装为无副作用纯函数节点，按职责拆分为任务拆解、文档精读、法规条款比对、引用校验等独立节点；使用
add_conditional_edges实现基于 LLM 输出或状态变量的动态路由。关键实践：节点内部不直接硬编码外部 API 调用，外部能力封装为独立 Tool/MCP 工具，仅通过状态传递结果，保证节点可测试、幂等。
- 工具绑定与执行：使用 LangGraph 提供的
ToolNode自动处理工具调用请求与结果回传，实现推理逻辑与执行逻辑分离。
阶段三：生产级特性增强
- 对接 vLLM 推理端点：将 LLM 实例替换为指向 vLLM 服务的
ChatOpenAI客户端，配置并发上限、请求超时与上下文窗口参数，统一接管高并发推理请求。 - 接入 MCP 工具适配器：引入 MCP Client，注册 PDF 解析、向量库检索、数据库查询等 MCP Server，将原子工具能力与 LangGraph 编排层物理级解耦，后续更换上层框架时底层工具无需重写。
- 配置持久化检查点（Checkpointer）：开发阶段使用
SqliteSaver，生产环境替换为PostgresSaver。在图编译时注入 Checkpointer，并在interrupt_before中指定需人工介入的节点，实现断点暂停与状态恢复，支撑 Human-in-the-loop 流程。 - 可观测性集成：接入 LangSmith 或部署 LangGraph Studio。通过可视化 Trace 视图监控节点状态变更、Token 消耗与链路延迟，替代低效的原始日志排查。
阶段四：测试、部署与运维
- 多层级测试策略：执行单节点单元测试 → 完整业务任务端到端验证 → 多 Agent 并发压测。
避坑提示：上线前必须执行“状态爆炸”压力测试，确保所有循环边都有明确退出条件，防止无限递归耗尽内存与算力。
- 容器化生产部署：将 Graph 封装为 FastAPI 服务并进行 Docker 容器化打包。对于批量或长耗时 Agent 任务，引入 Celery/RabbitMQ 等消息队列进行异步削峰与并发控制。
DeepSeek Harness 工程实践
项目概况与核心定位
DeepSeek Harness（简称 DSH）并非传统纯编排 SDK，而是基于 Cordis 内核、面向本地安全执行场景的一体化 Agent 运行时（Runtime），遵循一切皆插件设计理念。它补齐了通用编排框架在安全本地操作、隔离代码批量执行、国产模型指令对齐上的短板，原生内置沙箱、多 Agent 调度、日志审计模块，MIT 开源协议，原生支持 OpenAI 兼容接口，可对接 vLLM 本地推理服务。
- 官方资源：GitHub 仓库
deepseek-ai/DeepSeek-Harness，官方文档站点 https://harness-docs.deepseek.com - 核心特性：内置安全隔离沙箱（限制文件/网络访问）、PTC（Prompt-to-Code）批量执行模式、原生 Function Calling 优化，与 DeepSeek 系列模型深度指令微调对齐；模型后端、工具、存储、UI 模块均可插拔；原生 MCP 适配器支持接入第三方 MCP Server。
- 适用边界：适合本地文件处理、终端命令执行、批量数据清洗、开发者效率工具；可作为 LangGraph 上层编排的本地重型执行后端；不推荐直接作为高并发云端多 Agent 调度中心。
工程落地实践指南
阶段一：环境准备与快速开始（Quick Start）
- 安装与基础部署：两种部署方式可选：克隆官方仓库安装 Python 依赖，或直接使用官方提供的
docker-compose.yml快速拉起包含 Cordis 内核与基础沙箱的容器环境。生产环境优先推荐容器化部署，简化沙箱权限与依赖管理。- 克隆源码部署方式
- 克隆DeepSeek Harness仓库：
git clone https://github.com/deepseek-ai/DeepSeek-Harness.git - 进入项目目录：
cd DeepSeek-Harness - 安装Python依赖包：
pip install -r requirements.txt
- 克隆DeepSeek Harness仓库：
- docker-compose容器部署方式（推荐生产）
- 克隆DeepSeek Harness仓库或仅下载
docker-compose.yml文件 - 进入项目目录：
cd DeepSeek-Harness - 拉起容器服务：
docker-compose up -d - 查看容器运行状态：
docker-compose ps
- 克隆DeepSeek Harness仓库或仅下载
- 克隆源码部署方式
- 内核与基础插件初始化：启动 Cordis 内核，在配置文件中启用基础的 LLM 后端插件与存储插件，禁用未使用的内置插件以减少资源开销与攻击面。
- 跑通最小化 PTC 任务：通过内置 CLI 或基础 HTTP API 提交简单 Prompt-to-Code（PTC）任务（如“统计当前目录下所有 txt 文件的总行数”），验证沙箱代码生成、执行与结果捕获链路。
阶段二：安全沙箱与核心业务构建
- 环境隔离与安全沙箱配置：Harness 的核心价值在于安全受控的本地环境操作。必须在配置中严格设定文件路径白名单、禁止访问的网络域名黑名单、代码执行超时时间与内存上限。
安全红线：生产环境严禁以 root 权限运行，必须采用专用低权限用户 + Docker 容器双重隔离。
- 业务 Skill 开发与注册：将复杂业务逻辑（如法规条款比对、风险提取）封装为 Skill。每个 Skill 由提示词模板、工具调用序列、输出校验规则构成，并注册至平台的技能管理模块。
- PTC 批量任务编排（特色能力）：针对多文件分析、批量数据处理场景，优先采用 PTC 模式：让模型一次性生成完整 Python 业务脚本，在隔离沙箱中批量执行并捕获结构化输出。
关键实践：为 PTC 生成代码增加断言校验，Harness 可自动验证代码结果合法性后再输出，相比逐条 Function Calling 吞吐量显著提升，Token 消耗大幅降低。
阶段三：生产级特性增强
- 对接 vLLM 推理服务：修改 LLM 后端插件配置，填入 vLLM OpenAI 兼容地址与 API Key，配置并发限流策略，确保本地推理算力不被单一长任务耗尽。
- 注册 MCP 插件适配器：加载内置 MCP Client 插件，配置 RAG 检索、本地数据库查询等 MCP Server 连接参数，将原子工具统一注册至平台工具注册表。
- 权限、审计与兼容性配置：开启内置审计日志插件，完整记录 Agent 思考与工具调用链路。
避坑提示：Harness 与 DeepSeek 模型版本存在强关联，升级模型时必须同步更新 Prompt 模板与 Function Calling Schema；建议在 CI/CD 流水线中增加模型-Harness 兼容性自动化测试。
阶段四：集成、网关暴露与运维
- 上层编排框架集成：将 Harness 作为重型执行后端，封装
execute_harness_task(script, params)工具函数，供 LangGraph 等上层编排框架调用，实现“云端认知编排”与“本地安全执行”的解耦。 - 网关暴露与负载均衡：启用内置 API 网关或 UI 服务，外部业务系统通过 HTTP API 提交 Agent 任务。生产环境前端增加 Nginx 反向代理，实现请求负载均衡与基础限流。
- 沙箱边界压测：专门针对沙箱环境进行安全与性能压测，构造越权文件访问、恶意死循环代码注入等用例，验证沙箱隔离的可靠性与资源回收机制。
OpenClaw 个人开发者完全指南
参见：https://blog.csdn.net/zhiyuan411/article/details/158832130
