1. 从手动实践到框架开发为什么必须跨过这道坎如果你正在做大模型应用开发或者刚接触智能体Agent这个方向大概率经历过这样一个阶段一开始用最原始的方式手动拼接提示词、手动管理对话历史、手动调用工具函数、手动解析模型返回结果。一个简单的任务跑通之后你会觉得“好像也没那么难”。但当你试图把两三个工具串起来、加上条件判断、再加上失败重试和状态记录的时候代码就会迅速膨胀成一团乱麻。这个从手动实践到框架开发的转折点几乎是每个Agent开发者都会遇到的瓶颈。我自己在这个阶段卡了很久。最早做的一个小项目是帮团队内部做一个文档问答助手需求很简单用户提问模型判断是否需要检索如果需要就调用检索工具拿到结果后再生成回答。手动写的时候我用了一个while循环加一堆if-else状态存在一个字典里工具调用靠正则表达式从模型输出里抠JSON。刚开始只有两个工具勉强能跑。后来加了第三个工具、第四个工具还要支持多轮对话和上下文压缩代码直接失控——一个文件八百多行改一处逻辑要花半小时确认不会影响其他地方。这就是典型的“手动实践的天花板”。框架开发解决的正是这个问题。它把Agent运行过程中反复出现的模式抽象出来状态管理、节点编排、条件路由、工具注册、记忆持久化、错误处理。你不再需要自己造轮子而是把精力放在业务逻辑本身。目前主流的Agent开发框架里LangGraph和AutoGen是两个绕不开的选择。LangGraph走的是图编排路线把Agent的执行流程建模成状态图节点是计算步骤边是流转条件特别适合需要精细控制流程的场景。AutoGen则更偏向多智能体对话协作让多个Agent通过消息传递来协同完成任务。两者各有侧重后面我会详细拆解。这篇文章适合谁看如果你已经用Python写过一些大模型调用代码对提示词工程有基本了解但还没系统使用过Agent框架那这篇内容就是为你准备的。我会从手动实践的痛点讲起一步步拆解框架开发的核心思路然后用LangGraph和AutoGen分别给出可运行的代码示例最后分享我在实际项目中踩过的坑和排查技巧。整篇内容基于我自己的项目经验代码都可以直接复制运行环境依赖也会写清楚。2. 手动实践阶段的核心痛点拆解2.1 状态管理为什么最容易失控手动做Agent开发第一个绕不过去的问题就是状态管理。一个Agent在执行任务时需要维护的状态包括对话历史、当前步骤、已调用的工具及结果、中间变量、错误信息、重试次数等等。刚开始你可能用一个字典就搞定了但随着逻辑变复杂这个字典会变成什么都能往里塞的“垃圾堆”。更麻烦的是当你要在多个函数之间传递这个状态时Python的字典是可变对象某个函数不小心修改了它另一个函数读到的就是被污染的数据。这种bug排查起来极其痛苦因为错误现场和错误原因往往隔了好几个调用层级。我遇到过一个典型场景Agent在调用检索工具失败后应该把错误信息写入状态并触发重试逻辑。但因为状态字典在工具函数里被直接修改了重试逻辑读到的错误信息是上一次的残留值导致重试一直失败。这种问题在手动实践中非常普遍根本原因是你没有对状态变更做集中管理。框架开发的做法是定义一个明确的状态结构比如TypedDict或Pydantic模型所有状态变更都通过框架提供的机制进行每次变更都有迹可循。2.2 流程编排的复杂度爆炸手动写流程编排本质上是在用代码模拟一个状态机。你会有各种条件分支如果模型返回了工具调用请求就走工具执行分支如果工具执行成功就走结果整合分支如果失败就走重试或降级分支。这些分支用if-else写出来短流程还能看一旦超过五个节点代码的可读性就急剧下降。更致命的是你很难在代码层面直观地看到整个流程的全貌——哪个节点连哪个节点什么条件下走哪条边全靠脑补。LangGraph这类框架的价值就在这里。它让你用图的方式定义流程节点是函数边是流转规则条件边用函数返回值来决定走向。整个Agent的执行逻辑变成一张可视化的图你一眼就能看出流程从哪里开始、经过哪些节点、在哪里分叉、在哪里结束。这种表达方式不仅让代码更清晰也让团队协作变得容易——新人拿到代码看图就能理解逻辑不用逐行读if-else。2.3 工具注册与调用的重复劳动手动实践中每加一个工具你都要做几件事写工具函数、写工具描述给模型看的schema、在提示词里告诉模型有哪些工具可用、解析模型返回的工具调用请求、根据工具名分发到对应的函数、处理工具返回结果并塞回对话历史。这些步骤在每个工具上都要重复一遍而且很容易出错。比如工具描述的格式写错了模型就识别不了工具名和函数名对不上分发逻辑就找不到对应函数。框架开发通常提供工具注册机制你只需要用装饰器标注一个函数是工具框架自动生成schema、自动处理调用分发、自动把结果写回状态。这省下来的不仅是代码量更是心智负担。你可以把注意力放在工具本身的逻辑上而不是工具和模型之间的胶水代码上。2.4 记忆与上下文管理的困境Agent需要记忆这是共识。但记忆怎么存、存多少、什么时候压缩、什么时候检索手动实现起来非常琐碎。最简单的做法是把所有对话历史都塞进上下文但模型有token限制对话一长就爆了。你需要实现滑动窗口、摘要压缩、关键信息提取等策略。每种策略都有自己的适用场景和副作用手动实现和调试的成本很高。框架开发一般会提供记忆管理的抽象层。比如LangGraph支持checkpointer机制可以自动持久化每一步的状态支持从任意检查点恢复执行。AutoGen则有对话历史管理和上下文窗口控制的内置逻辑。这些机制不能完全替代你对记忆策略的思考但至少把基础设施搭好了你只需要配置参数和选择策略。3. 框架开发的核心思路与选型考量3.1 LangGraph的图编排模型解析LangGraph的核心思想是把Agent的执行流程建模成一个有向图。图由节点和边组成节点是计算步骤可以是调用模型、执行工具、处理数据等边定义了节点之间的流转关系。状态在节点之间传递每个节点接收当前状态返回状态更新。这种模型非常贴近人类对流程的直觉认知也便于调试和可视化。LangGraph的几个关键概念需要理解清楚。首先是StateGraph它是图的容器你通过add_node和add_edge往里添加节点和边。其次是状态定义通常用TypedDict或Pydantic模型来定义每个字段代表流程中需要维护的一项数据。第三是条件边通过add_conditional_edges添加它接收一个函数函数的返回值决定下一步走哪个节点。最后是checkpointer用于持久化状态支持中断恢复和人工介入。LangGraph和LangChain的关系经常被问到。简单说LangChain是一个大而全的LLM应用开发框架提供了模型调用、提示词模板、工具、检索器等组件。LangGraph是LangChain生态中的一个子项目专注于Agent的流程编排。你可以单独使用LangGraph也可以和LangChain的组件配合使用。LangGraph比LangChain更底层、更灵活适合需要精细控制流程的场景。LangChain的AgentExecutor虽然也能用但它的流程是固定的你很难插入自定义逻辑。LangGraph则把流程的控制权完全交给你。3.2 AutoGen的多智能体协作模式AutoGen的出发点和LangGraph不同。它关注的是多个Agent之间的对话协作。在AutoGen里你可以定义多个角色每个角色有自己的系统提示词和工具集它们通过消息传递来协同完成任务。比如一个典型的模式是用户代理负责理解需求助手代理负责生成方案批评者代理负责审查方案三者循环对话直到达成共识。AutoGen的优点是上手快多Agent协作的样板代码很少你定义好角色和初始消息它就能自动跑起来。但它的缺点也在这里——流程控制相对粗放你很难精确指定“在什么条件下切换到哪个Agent”。AutoGen适合那些任务边界清晰、可以通过对话自然推进的场景比如代码生成加审查、多轮辩论、任务分解与执行。如果你的流程需要严格的状态机和条件分支LangGraph会更合适。3.3 选型对比与决策依据选LangGraph还是AutoGen我的经验是看三个维度。第一流程是否需要精细控制。如果你的Agent有明确的状态流转和条件分支选LangGraph。如果任务可以通过多轮对话自然推进选AutoGen。第二是否需要多Agent协作。单Agent任务用LangGraph更简洁多Agent协作场景AutoGen更省事。第三团队的技术背景。LangGraph的概念更多学习曲线稍陡但一旦理解就非常灵活。AutoGen上手快但深入定制时可能会遇到框架限制。实际项目中两者也可以结合使用。比如用LangGraph做外层流程编排在某个节点里调用AutoGen的多Agent对话来完成子任务。这种混合模式在复杂项目中很常见。对比维度LangGraphAutoGen核心模型状态图编排多智能体对话流程控制精细支持条件边和循环相对粗放靠对话推进状态管理显式状态定义支持持久化对话历史管理学习曲线中等偏陡较平缓适用场景复杂流程、需要精确控制多Agent协作、对话式任务与LangChain关系同生态可配合使用独立框架4. 实操过程与核心环节实现4.1 环境准备与依赖安装先把环境搭起来。我用的Python版本是3.11LangGraph和AutoGen都支持3.9以上。建议用虚拟环境避免依赖冲突。python -m venv agent-env source agent-env/bin/activate # Windows用 agent-env\Scripts\activate pip install langgraph langchain-openai autogen-agentchat autogen-ext[openai]LangGraph的核心包是langgraph配合langchain-openai来调用模型。AutoGen的新版本拆成了autogen-agentchat和autogen-ext安装时注意版本。我实测下来LangGraph 0.2.x和AutoGen 0.4.x的API比较稳定建议锁定版本。pip install langgraph0.2.60 langchain-openai0.2.14 pip install autogen-agentchat0.4.5 autogen-ext[openai]0.4.5模型方面我用的是OpenAI的接口你也可以换成其他兼容OpenAI协议的服务。需要设置环境变量export OPENAI_API_KEY你的密钥 export OPENAI_BASE_URL你的接口地址注意不要把密钥硬编码在代码里用环境变量或配置文件管理。我见过有人把密钥提交到代码仓库结果被扫到后产生意外费用这个坑一定要避开。4.2 用LangGraph搭建一个带工具调用的Agent先定义一个简单的场景Agent可以调用两个工具一个是查询天气一个是计算数学表达式。用户提问后Agent判断是否需要调用工具如果需要就调用拿到结果后生成最终回答。第一步定义状态结构。我用TypedDict来定义包含消息列表和当前步骤计数。from typing import Annotated, TypedDict from langgraph.graph.message import add_messages class AgentState(TypedDict): messages: Annotated[list, add_messages] step_count: int这里messages字段用了add_messages注解这是LangGraph提供的消息合并机制新消息会追加到列表而不是覆盖。step_count用来记录执行步数防止无限循环。第二步定义工具函数。用LangChain的tool装饰器来标注。from langchain_core.tools import tool tool def get_weather(city: str) - str: 查询指定城市的天气 weather_data { 北京: 晴25度, 上海: 多云28度, 深圳: 阵雨30度 } return weather_data.get(city, f暂时没有{city}的天气数据) tool def calculate(expression: str) - str: 计算数学表达式支持加减乘除 try: result eval(expression, {__builtins__: {}}, {}) return f计算结果{result} except Exception as e: return f计算失败{str(e)}注意eval有安全风险生产环境要用更安全的表达式解析库比如asteval或sympy。这里为了演示简化了。第三步绑定工具到模型。from langchain_openai import ChatOpenAI llm ChatOpenAI(modelgpt-4o-mini, temperature0) tools [get_weather, calculate] llm_with_tools llm.bind_tools(tools)第四步定义节点函数。两个节点一个调用模型一个执行工具。from langchain_core.messages import ToolMessage def call_model(state: AgentState): messages state[messages] response llm_with_tools.invoke(messages) return {messages: [response], step_count: state.get(step_count, 0) 1} def call_tools(state: AgentState): messages state[messages] last_message messages[-1] tool_messages [] for tool_call in last_message.tool_calls: tool_name tool_call[name] tool_args tool_call[args] if tool_name get_weather: result get_weather.invoke(tool_args) elif tool_name calculate: result calculate.invoke(tool_args) else: result f未知工具{tool_name} tool_messages.append(ToolMessage(contentstr(result), tool_call_idtool_call[id])) return {messages: tool_messages}第五步定义路由函数决定模型调用后是走工具执行还是结束。def should_continue(state: AgentState): messages state[messages] last_message messages[-1] if hasattr(last_message, tool_calls) and last_message.tool_calls: return tools return end第六步组装图。from langgraph.graph import StateGraph, START, END workflow StateGraph(AgentState) workflow.add_node(agent, call_model) workflow.add_node(tools, call_tools) workflow.add_edge(START, agent) workflow.add_conditional_edges(agent, should_continue, {tools: tools, end: END}) workflow.add_edge(tools, agent) app workflow.compile()第七步运行测试。result app.invoke({messages: [(user, 北京天气怎么样顺便帮我算一下 23*47)], step_count: 0}) for msg in result[messages]: print(f{msg.type}: {msg.content})跑下来你会看到Agent先调用get_weather查北京天气再调用calculate算23*47最后整合两个结果生成回答。整个流程在图上清晰可见START - agent - tools - agent - END。如果模型判断不需要工具直接走agent - END。4.3 用AutoGen实现多Agent协作同样的场景用AutoGen的多Agent模式来实现。定义三个Agent用户代理负责发起请求助手代理负责调用工具执行代理负责实际执行工具。from autogen_agentchat.agents import AssistantAgent from autogen_agentchat.teams import RoundRobinGroupChat from autogen_agentchat.conditions import MaxMessageTermination from autogen_ext.models.openai import OpenAIChatCompletionClient model_client OpenAIChatCompletionClient(modelgpt-4o-mini) async def get_weather_func(city: str) - str: weather_data {北京: 晴25度, 上海: 多云28度, 深圳: 阵雨30度} return weather_data.get(city, f暂时没有{city}的天气数据) async def calculate_func(expression: str) - str: try: result eval(expression, {__builtins__: {}}, {}) return f计算结果{result} except Exception as e: return f计算失败{str(e)} assistant AssistantAgent( nameassistant, model_clientmodel_client, tools[get_weather_func, calculate_func], system_message你是一个助手可以查询天气和计算数学表达式。需要时调用工具。 ) termination MaxMessageTermination(max_messages10) team RoundRobinGroupChat([assistant], termination_conditiontermination) async def main(): result await team.run(task北京天气怎么样顺便帮我算一下 23*47) for msg in result.messages: print(f{msg.source}: {msg.content}) import asyncio asyncio.run(main())AutoGen的代码量明显更少但流程控制也更粗放。它靠对话轮次和终止条件来推进适合任务边界清晰的场景。如果你需要精确控制每一步的流转条件LangGraph更合适。4.4 状态持久化与中断恢复LangGraph的checkpointer机制是生产环境必备的。它可以把每一步的状态存到数据库或内存中支持从任意检查点恢复执行。这在长流程Agent中非常有用——如果某一步失败了不用从头重跑。from langgraph.checkpoint.memory import MemorySaver memory MemorySaver() app workflow.compile(checkpointermemory) config {configurable: {thread_id: user-001}} result app.invoke({messages: [(user, 北京天气怎么样)], step_count: 0}, config)用thread_id来区分不同用户的会话。生产环境可以把MemorySaver换成SqliteSaver或PostgresSaver状态就持久化了。我实测下来SqliteSaver在中小规模场景完全够用配置也简单。from langgraph.checkpoint.sqlite import SqliteSaver with SqliteSaver.from_conn_string(checkpoints.db) as memory: app workflow.compile(checkpointermemory) config {configurable: {thread_id: user-001}} result app.invoke({messages: [(user, 北京天气怎么样)], step_count: 0}, config)注意checkpointer存储的是完整状态包括所有消息。对话长了之后数据库会膨胀。建议定期清理旧会话或者实现状态压缩逻辑。5. 常见问题与排查技巧实录5.1 模型不调用工具怎么办这是最常见的问题。模型返回的响应里没有tool_calls直接给了文本回答。原因通常有三个工具描述不够清晰、提示词没有引导模型使用工具、模型本身能力不足。排查步骤先打印模型的原始响应看它到底返回了什么。如果响应里有工具调用但格式不对检查工具schema是否正确。如果响应里完全没有工具调用意图优化工具描述和系统提示词。我一般会在系统提示词里明确写“当用户询问天气或需要计算时必须调用对应工具不要自己编造答案”。还有一个坑是工具名冲突。如果你定义了两个同名工具或者工具名和模型内置的某些标识符冲突模型可能会混淆。工具名用下划线命名法保持唯一性。5.2 无限循环怎么破Agent在agent和tools之间来回跳停不下来。原因通常是模型反复调用同一个工具或者工具返回的结果让模型认为还需要继续调用。解决办法有两个一是加步数限制在状态里记录step_count超过阈值就强制结束二是在路由函数里加判断如果连续两次调用同一个工具且参数相同就终止。def should_continue(state: AgentState): if state.get(step_count, 0) 10: return end messages state[messages] last_message messages[-1] if hasattr(last_message, tool_calls) and last_message.tool_calls: return tools return end提示步数阈值不要设太小否则复杂任务跑不完。我一般设10到15步根据任务复杂度调整。5.3 状态字段丢失或类型错误LangGraph的状态更新是合并式的节点返回的字典会合并到当前状态。如果你在节点里返回了一个状态里没有的字段它会被忽略。如果返回的字段类型和定义的不一致可能会报错。排查时先检查状态定义确认所有字段都声明了。然后用print大法在每个节点入口打印当前状态看数据是否符合预期。另一个常见问题是messages字段没有用add_messages注解导致新消息覆盖旧消息。这个错误很隐蔽因为流程能跑通但模型看不到历史对话。一定要确认messages字段加了Annotated[list, add_messages]。5.4 AutoGen的终止条件配置AutoGen如果不配终止条件对话会一直进行下去。常见的终止条件有MaxMessageTermination最大消息数、TextMentionTermination提到特定词终止、TokenUsageTerminationtoken用量超限终止。我一般组合使用from autogen_agentchat.conditions import MaxMessageTermination, TextMentionTermination termination MaxMessageTermination(max_messages20) | TextMentionTermination(TERMINATE)用|操作符组合多个条件满足任一就终止。TextMentionTermination让Agent在任务完成时输出TERMINATE这样能自然结束。问题现象可能原因排查方法解决方案模型不调用工具工具描述不清、提示词未引导打印原始响应优化描述和提示词无限循环模型反复调用同一工具查看消息历史加步数限制和重复检测状态字段丢失未在状态中声明检查状态定义补全字段声明消息覆盖messages未加add_messages检查注解添加Annotated注解AutoGen不终止未配终止条件检查termination组合多个终止条件5.5 性能优化的几个实操心得第一个心得是减少不必要的模型调用。在路由函数里能判断的逻辑不要交给模型。比如工具返回结果后如果结果明确表示失败可以直接走错误处理分支不用再让模型判断。第二个心得是控制上下文长度。对话历史长了之后每次模型调用的token消耗很大。我一般会保留最近10轮对话更早的做摘要压缩。LangGraph可以在节点里实现这个逻辑AutoGen有内置的上下文窗口管理。第三个心得是工具执行加超时。外部API调用可能卡住给工具函数加超时机制避免整个Agent挂起。Python的signal模块或concurrent.futures都可以实现。import signal def timeout_handler(signum, frame): raise TimeoutError(工具执行超时) def call_tool_with_timeout(tool_func, args, timeout10): signal.signal(signal.SIGALRM, timeout_handler) signal.alarm(timeout) try: result tool_func.invoke(args) signal.alarm(0) return result except TimeoutError: return 工具执行超时请稍后重试注意signal只在主线程有效如果你在多线程环境里跑要用concurrent.futures的ThreadPoolExecutor加timeout参数。6. 从框架开发再往前一步的思考框架开发解决了手动实践的很多痛点但它不是银弹。用了框架之后你依然需要理解Agent的基本原理——模型怎么决策、工具怎么调用、状态怎么流转。框架只是把这些原理封装成了更易用的接口底层的逻辑没有变。我见过一些人上来就用框架结果遇到问题完全不知道从哪里排查因为他不理解框架背后做了什么。我的建议是先手动写一遍最简单的Agent循环理解每一步在干什么。然后再用框架重写一遍对比两者的差异。这样你既有了底层认知又有了工程效率。LangGraph和AutoGen都是很好的工具但它们不是唯一的选择。随着这个领域的快速发展新的框架和模式会不断出现。重要的是掌握核心概念——状态、节点、边、工具、记忆、路由——这些概念在不同框架里是相通的。另外Agent的安全性和可控性值得持续关注。工具调用的权限控制、敏感操作的二次确认、输出内容的过滤这些在生产环境里都是必须考虑的。框架提供了一些机制但最终的责任还是在开发者身上。我在项目里一般会给工具调用加一层权限校验高风险操作需要人工确认后才执行。这个逻辑可以用LangGraph的中断机制实现——在关键节点前暂停等待人工输入后再继续。最后分享一个我常用的调试技巧把Agent的每一步执行都打上日志包括输入状态、模型响应、工具调用、输出状态。日志用结构化格式比如JSON方便后续分析和回放。LangGraph的checkpointer天然支持这个AutoGen也有消息历史记录。有了完整的执行日志排查问题会快很多。