你肯定见过这样的场景一个刚接触 Agent 开发的工程师兴奋地调通了一个大模型的 API然后开始疯狂地往提示词里塞各种指令试图让它“理解”复杂的任务。结果呢任务稍微一长模型就开始“失忆”逻辑稍微一绕输出就变得不可预测。最后项目变成了一个由无数if-else和字符串拼接组成的“屎山”维护成本高得吓人。问题出在哪很多人把 Agent 开发等同于“调 API 写提示词”这就像试图用一把瑞士军刀去盖一栋大楼。工具本身没错但用错了方法。真正的 Agent 开发核心不是“让模型变得更聪明”而是如何把复杂、不确定的任务拆解成一套稳定、可观测、可迭代的执行流程。今天我们不谈那些玄乎的概念就从三个最具体、也最能代表不同开发阶段的“形态”入手LangGraph、MCP和Workflow。它们分别对应着 Agent 开发的三个核心命题状态管理、能力扩展和流程编排。更重要的是我们会深入一个常被忽略但至关重要的设计模式渐进式披露 Skills以及与之配套的Harness 架构。理解了这些你才能从“调 API 的脚本小子”进化成能设计健壮 Agent 系统的工程师。1. 别再“一把梭”认清 LangGraph、MCP、Workflow 的三种角色很多人一上来就纠结“选哪个框架”这其实是个伪命题。LangGraph、MCP 和 Workflow 不是三选一的单选题而是解决 Agent 系统不同层面问题的三种“形态”或“组件”。用错了地方事倍功半。1.1 LangGraph为 Agent 装上“状态大脑”和“记忆回路”LangGraph 的核心价值是解决了 Agent 开发中最头疼的状态管理和循环控制问题。传统痛点你用 LangChain 或其他库写个 Agent每次调用都是独立的。你想让 Agent 记住上一步的结果或者根据中间结果决定下一步做什么比如“如果搜索结果不理想就换一个关键词再搜”就需要自己写一堆代码来维护状态、判断分支。代码很快变得混乱不堪。LangGraph 的解法它引入了StateGraph的概念。你可以把整个 Agent 任务定义为一个有向图。图中的节点Node是一个个具体的操作比如“调用搜索工具”、“分析结果”、“生成报告”边Edge定义了节点之间的流转条件。最关键的是它维护了一个全局的State对象在各个节点间传递和更新。这带来了什么改变可视化与可调试你的任务逻辑变成了一张图哪里卡住了、循环了几次一目了然。这对于复杂流程的调试是革命性的。内置循环与中断实现“思考-行动-观察”的 ReAct 循环或者满足某个条件才退出的循环变得非常简单。你不再需要手动写while循环和状态标志。清晰的关注点分离你只需要关心每个节点“做什么”以及节点之间“在什么条件下流转”。状态管理的脏活累活LangGraph 帮你干了。简单来说LangGraph 是 Agent 的“神经系统”和“短期记忆”。它负责协调各个功能模块按照既定逻辑有序工作并记住工作过程中的上下文。它不关心“搜索”这个功能具体是怎么实现的那是 MCP 或 Skills 的事它只关心“在某个状态点需要触发搜索功能”。1.2 MCP打破“能力孤岛”实现工具的动态集成如果说 LangGraph 是神经系统那么 MCP 就是让神经系统能控制手、脚、眼睛的“标准接口协议”。MCP 全称是Model Context Protocol。它的核心思想是标准化。在没有 MCP 之前每个 AI 应用如 Claude Desktop、Cursor想要接入外部工具如数据库、GitHub、Jira都需要和工具提供商进行一对一的深度集成开发成本极高且用户无法灵活组合。MCP 做了什么它定义了一套简单的、基于 JSON-RPC 的通信协议。任何工具只要实现一个 MCP Server对外暴露自己的“能力”比如查询数据库、创建日历事件任何兼容 MCP 的 AI 应用MCP Client就可以自动发现并使用这些能力。对开发者的意义你写的工具Skill只需要适配 MCP 协议就能被所有支持 MCP 的 Agent 平台或应用使用。反过来你在构建自己的 Agent 时也可以像插拔 USB 设备一样动态地接入或移除由 MCP Server 提供的各种 Skills而无需修改核心 Agent 代码。MCP 是 Agent 的“外设标准”和“能力总线”。它解决了工具生态的碎片化问题让 Agent 的能力可以像乐高一样自由组合、即插即用。在 LangGraph 的图中一个调用 MCP 工具的节点其背后的具体实现可能是本地的一个 Python 脚本也可能是远程的一个专业服务。1.3 Workflow从单次任务到可复用、可监控的业务流程当你用 LangGraph 设计好了一个任务流程图并通过 MCP 集成了各种工具后这个“智能流程”如何变成一个团队可协作、业务可依赖的“服务”这就是 Workflow 要解决的问题。这里的 Workflow 不是指某个具体叫workflow的库而是一种工程化形态。它关注的是编排与调度如何定时、按需或由事件触发这个 Agent 流程监控与可观测性每个步骤的执行状态、耗时、输入输出是什么哪里失败了版本管理与回滚我的 Agent 流程迭代了如何平滑升级出问题了如何快速回退权限与审计谁可以触发这个流程执行记录是否可追溯你可以使用像Airflow、Prefect、Dagster这样的通用工作流编排引擎也可以使用为 AI 优化的如LangGraph Studio云服务或Solon Flow等框架来将你的 LangGraph 图“托管”起来。Workflow 是 Agent 的“生产车间”和“控制塔”。它将一个实验性的、在笔记本里运行的智能脚本变成了一个高可用、可运维的企业级服务。形态核心解决什么问题类比在 Agent 系统中的地位LangGraph状态管理与流程控制神经系统与短期记忆编排层定义“怎么干”的逻辑和顺序MCP工具能力的标准化与动态集成外设接口标准USB能力层提供“用什么干”的标准化工具Workflow流程的工程化、运维与调度生产车间与控制塔运维层保障“稳定干”和“持续干”理解了这三者的分工你就知道在 Agent 开发的不同阶段应该聚焦什么。接下来我们深入到最体现设计水平的细节如何优雅地管理和使用那些“工具”Skills。2. 技能Skills管理的核心难题为什么不能一次性全给 Agent有了 MCP我们可以轻松集成几十上百个 Skills。一个自然的想法是“我把所有 Skills 的描述都塞进系统提示词System Prompt里让 Agent 自己选不就行了” 这是新手最容易掉入的“万能提示词”陷阱。这么做的灾难性后果上下文爆炸每个 Skill 都有名称、描述、参数说明。几十个 Skill 的描述文本会急剧膨胀严重挤占本应用于任务分析和思考的上下文窗口。决策瘫痪面对一长串功能相似的技能列表比如5个不同的“搜索”技能Agent 会陷入困惑做出随机或错误的选择。提示词工程地狱你需要精心设计提示词来区分这些技能维护成本极高。安全与成本不必要的技能暴露可能带来误操作风险如删除数据且每次调用都携带巨大上下文浪费 tokens。正确的思路是渐进式披露Progressive Disclosure。即不要一开始就把所有技能都暴露给 Agent而是根据任务的当前上下文和执行阶段动态地、按需地提供最相关的少数几个技能。3. 渐进式披露 Skills像导航一样只显示当前需要的选项渐进式披露不是一个新概念但在 Agent 设计中至关重要。它的实现依赖于一个核心组件Skill Router或称为 Tool Router/Selector。3.1 Skill Router 的工作原理技能注册与分类所有 Skills 在系统启动时向一个中央注册表注册并携带丰富的元数据名称、描述、功能分类、适用场景、输入输出格式、权限等级等。上下文感知当 Agent 执行到某个节点需要决定下一步行动时Skill Router 会介入。它接收当前的State任务状态、历史记录、用户目标等。路由决策Router 根据预定义的策略可以是规则引擎、向量检索相似度甚至是一个小型的决策模型从所有已注册的技能中筛选出与当前上下文最相关的Top N例如3-5个技能。动态提示只将这 N 个技能的描述注入到本次 Agent 调用的提示词中。Agent 在这个精简、精准的列表中选择和执行。# 概念性伪代码展示 Skill Router 在 LangGraph 节点中的角色 def planning_node(state): 规划节点决定下一步做什么 # 1. 获取当前完整状态 current_context state[messages] state[intermediate_results] # 2. 调用 Skill Router获取当前最相关的技能列表 relevant_skills skill_router.route(current_context, top_k3) # 3. 构建只包含相关技能的提示词 prompt build_prompt_with_skills(relevant_skills, current_context) # 4. 调用 LLM让它从这3个技能中选择或提出新想法 llm_response call_llm(prompt) # 5. 更新状态决定下一个节点 state[next_action] parse_llm_response(llm_response) return state # 后续的 execution_node 只会收到 state[“next_action”] 指定的具体技能去执行。3.2 这样做的好处上下文高效每次决策都在清晰的选项中进行极大节省 tokens提升推理质量。决策精准Agent 不再需要从海量工具中“大海捞针”。易于维护新增一个 Skill只需要注册即可无需修改核心提示词。安全可控高权限技能如delete_database可以设置路由规则仅在特定任务状态下才被披露。渐进式披露的本质是将“工具选择”这个复杂问题从 LLM 的提示词工程转移到了更可控、更可编程的 Skill Router 逻辑中。这是 Agent 系统设计从“艺术”走向“工程”的关键一步。4. Harness 架构驾驭复杂 Agent 的“缰绳与鞍具”当我们把 LangGraph流程、MCP Skills能力、Skill Router调度组合在一起时系统复杂度开始上升。如何让这些组件优雅地协作而不是变成一团乱麻这就需要Harness 架构。Harness原意是“马具”引申为“驾驭、控制”的框架。在 Agent 开发中Harness 指的是一套封装了核心执行逻辑、状态管理、工具调用、路由决策和异常处理的运行时框架。它不是某个具体库而是一种设计模式。一个典型的 Harness 架构包含以下层次|-----------------------------| | Workflow 层 | -- 调度、触发、监控 (e.g., Airflow, 自定义服务) |-----------------------------| | Harness 核心层 | | ------------------------- | | | LangGraph (StateGraph) | | -- 流程与状态中枢 | ------------------------- | | | Skill Router | | -- 动态技能路由 | | Memory Manager | | -- 长/短期记忆管理 | | Guardrails | | -- 安全与合规检查 | ------------------------- | |-----------------------------| | MCP 适配层 | -- 与各种 MCP Server 通信 |-----------------------------| | 外部工具/服务 | -- 数据库、API、自定义函数等 |-----------------------------|4.1 Harness 的核心职责生命周期管理初始化 Agent注入配置启动任务优雅停止。状态托管作为 LangGraph State 的持有者和持久化管理者如存入数据库。技能路由执行集成 Skill Router在适当的节点调用它并将路由结果转化为对具体 MCP Skill 的调用。统一异常处理捕获 Skill 执行失败、LLM 响应异常、网络超时等错误并决定重试、降级或失败处理策略。可观测性埋点自动记录每个节点的输入输出、耗时、技能调用详情方便日志追踪和性能分析。提供统一接口对外暴露一个干净的 API如harness.run(task_input)隐藏内部所有复杂细节。4.2 为什么需要 Harness直接写 LangGraph 不行吗可以但会很痛苦。想象一下你的 LangGraph 每个节点里都需要写重复的代码调用 Router、处理异常、记录日志、更新特定格式的状态。Harness 将这些横切关注点Cross-cutting Concerns抽象出来让你专注于业务逻辑图的设计。Harness 是你与底层复杂组件LangGraph, MCP之间的“适配器”和“缓冲层”。它让 Agent 的核心逻辑保持简洁同时具备了生产环境所需的健壮性。5. 实战推演从零设计一个支持渐进式披露的新闻分析 Agent让我们把以上所有概念串起来设计一个“新闻分析Agent”。它的目标是给定一个主题自动搜索最新信息总结观点并评估其可信度。5.1 第一步定义 Skills 并实现 MCP Server我们注册几个技能web_search(query: str): 通用网页搜索。academic_search(query: str): 学术数据库搜索。summarize_text(text: str): 文本总结。sentiment_analysis(text: str): 情感分析。fact_check(claim: str, source: str): 事实核查高权限需谨慎使用。每个技能都实现为一个 MCP Server提供标准的list_tools和call_tool接口。5.2 第二步设计 LangGraph StateGraph定义状态Stateclass AgentState(TypedDict): topic: str search_results: List[Dict] summary: str credibility_score: float messages: List[BaseMessage] # 对话历史 next_step: str # 由 Router 和 LLM 决定设计图节点plan_search: 规划搜索策略需要 Skill Router。execute_search: 执行搜索调用web_search或academic_search。analyze_results: 分析结果决定是继续搜索还是进入总结。generate_summary: 生成总结调用summarize_text。assess_credibility: 评估可信度可能调用sentiment_analysis和fact_check。5.3 第三步实现 Skill RouterRouter 的策略可以很简单在plan_search节点只披露web_search和academic_search。在analyze_results节点如果结果包含争议性陈述则披露fact_check否则披露sentiment_analysis和summarize_text。fact_check技能设置高权限阈值除非明确需要否则不披露。5.4 第四步构建 Harness创建一个NewsAnalysisHarness类在__init__中构建上述 LangGraph并传入配置好的 Skill Router。run方法接收主题初始化 State运行 Graph并返回最终结果。在 Harness 内部每个节点调用前后自动添加日志记录。对fact_check的调用添加额外的用户确认或审核流程Guardrails。5.5 第五步嵌入 Workflow最后将这个NewsAnalysisHarness包装成一个可执行单元提交到 Airflow 或 Prefect。配置为每天定时运行或由消息队列触发。Workflow 系统负责监控每次运行的成功与否、耗时并存储最终的分析报告。6. 避坑指南与进阶思考在实践这套架构时有几个关键点必须注意Skill Router 的质量决定上限如果 Router 总是选错技能整个 Agent 就会跑偏。初期可以用基于关键词和规则的 Router后期可以考虑用一个小型微调模型或 embedding 相似度来提升路由精度。状态设计要精简LangGraph 的 State 应该只包含必要信息。避免把整个对话历史或大量中间数据全塞进去这会影响性能和图的可读性。考虑将大数据单独存储State 中只保留引用 ID。MCP Server 的稳定性Skill 作为独立进程或服务必须有良好的错误处理和重试机制。Harness 层需要对 MCP 调用超时、无响应等情况有降级策略。测试策略不要只测试端到端。要分层测试单独测试每个 Skill测试 Skill Router 的决策测试 LangGraph 各个节点的状态转换最后进行集成测试。从简单开始不要一开始就追求完美的渐进式披露和复杂的 Harness。先用 LangGraph 把核心流程跑通然后逐步引入 MCP 标准化工具再根据需要添加 Router 和 Harness 的增强功能。真正的 Agent 开发其复杂度不在于调用哪个大模型的 API而在于如何像设计一个分布式系统一样设计好组件的边界、通信协议、状态流和异常处理。LangGraph、MCP、Workflow 提供了优秀的底层积木而渐进式披露和 Harness 架构则是将这些积木搭建成稳固大厦的蓝图和粘合剂。下一次当你启动一个新的 Agent 项目时不妨先问自己三个问题1我的任务状态图是什么LangGraph 2我需要哪些标准化工具MCP 3我如何让它成为一个可靠的服务Workflow Harness。想清楚这些代码写起来才会有的放矢系统才会真正健壮、可维护。