AI Agent开发速查清单：LangGraph、AutoGen、CrewAI与MCP核心要点

1. 这份速查清单到底解决什么问题做AI应用开发的人大概都有过这种体验项目里同时用着LangGraph编排流程、AutoGen跑多智能体对话、CrewAI做角色分工还要接MCP协议打通外部工具结果每隔两周回头看自己的代码就得重新翻文档确认某个API到底叫什么、参数怎么传。更麻烦的是这些框架的迭代速度极快上个月还能跑的写法这个月可能就废弃了。我自己的做法是维护一份活页速查表把每个框架的核心概念、最小可运行代码、常见坑点都记下来用的时候直接翻不用每次都去啃官方文档。这份速查清单就是基于这个思路整理的。它覆盖了当前主流的几个AI Agent开发框架——LangGraph、AutoGen、CrewAI以及正在快速普及的MCP协议同时把OpenAI API的接入要点、工具链配置、资源获取渠道都串在一起。适合两类人看一类是刚接触Agent开发、面对一堆框架不知道从哪下手的新手另一类是用过其中一两个框架、但需要横向对比或者补齐知识盲区的开发者。我不会写成官方文档的复读机而是按实际项目里怎么用、哪里容易翻车的角度来组织内容。先说清楚一个前提这些框架没有绝对的优劣选型取决于你的场景。LangGraph适合需要精细控制流程和状态的项目AutoGen适合快速搭建多Agent对话系统CrewAI在角色分工明确的协作任务上更顺手MCP则是解决Agent怎么调用外部工具这个通用问题的协议层方案。下面逐个拆。2. LangGraph状态图编排的核心逻辑与实操2.1 为什么LangGraph用图而不是链LangChain早期的Chain是线性的A调用B、B调用C流程固定。但真实Agent场景里经常需要循环、条件分支、人工介入后回到某一步线性结构表达起来很别扭。LangGraph把流程建模成有向图节点是处理函数边是流转条件状态在节点间传递和累积。这个设计的好处是你可以随时在图上加一个检查点让流程暂停等人工确认确认完再从断点继续。我在做一个客服工单分类Agent时就靠这个机制实现了AI初判→人工复核→AI执行的混合流程比硬编码状态机清爽得多。核心概念就三个State贯穿全图的数据结构通常是个TypedDict、Node接收State返回State更新的函数、Edge决定下一个走哪个节点。条件边用add_conditional_edges注册配合一个返回节点名的路由函数。2.2 最小可运行示例与关键参数from langgraph.graph import StateGraph, END from typing import TypedDict class AgentState(TypedDict): messages: list next_step: str def classify(state: AgentState): # 实际项目里这里调LLM做意图识别 return {next_step: search} def search(state: AgentState): return {messages: state[messages] [搜索结果]} def route(state: AgentState): return state[next_step] graph StateGraph(AgentState) graph.add_node(classify, classify) graph.add_node(search, search) graph.set_entry_point(classify) graph.add_conditional_edges(classify, route, {search: search, end: END}) graph.add_edge(search, END) app graph.compile() result app.invoke({messages: [], next_step: })这段代码跑通只需要装langgraph一个包。注意compile()之后得到的是可调用对象invoke传初始State返回最终State。如果要支持中断恢复compile(checkpointerMemorySaver())加上checkpointer然后调用时传config{configurable: {thread_id: xxx}}。2.3 工具调用在LangGraph里的正确姿势LangGraph本身不绑定工具调用方式但和LangChain的Tool体系配合最顺。定义工具用tool装饰器然后有两种接法一种是把工具绑到LLM上让模型自己决定调不调llm.bind_tools(tools)另一种是在节点里手动判断该调哪个工具。前者适合开放式任务后者适合流程可控的场景。我踩过的坑是用bind_tools时如果模型返回的tool_call参数格式不对节点里直接执行会报错稳妥做法是加一层参数校验校验不过就回退到让模型重新生成。还有一个容易忽略的点LangGraph的State如果包含不可序列化的对象比如数据库连接用checkpointer持久化时会失败。解决办法是把连接放在节点函数内部创建State里只存必要的数据。3. AutoGen与CrewAI多Agent协作的两种思路3.1 AutoGen的对话驱动模型AutoGen的核心抽象是ConversableAgent一切皆对话。你定义几个Agent给它们不同的system message和角色然后让它们互相发消息。最典型的是AssistantAgent负责生成方案加UserProxyAgent负责执行代码或调用工具两者循环对话直到任务完成。这个模式在代码生成场景特别顺手因为UserProxy可以直接执行Assistant写的代码并把结果反馈回去。from autogen import AssistantAgent, UserProxyAgent assistant AssistantAgent(assistant, llm_config{model: gpt-4}) user_proxy UserProxyAgent(user_proxy, code_execution_config{work_dir: coding}) user_proxy.initiate_chat(assistant, message写一个快速排序并测试)AutoGen的坑主要在code_execution_config上。默认它会在本地执行代码生产环境必须换成Docker容器执行否则模型生成的代码可能删你的文件。配置use_dockerTrue并指定镜像虽然启动慢一点但安全边界清晰。3.2 CrewAI的角色分工范式CrewAI把多Agent协作抽象成团队每个Agent有role、goal、backstoryTask有description和expected_outputCrew把Agent和Task绑在一起按顺序或层级执行。它的优势是语义清晰写出来的代码像在描述一个组织架构非技术人员也能看懂。比如做一个市场调研任务你可以定义研究员负责搜集信息、分析师负责提炼洞察、写手负责出报告三个Task串起来。from crewai import Agent, Task, Crew researcher Agent(role研究员, goal搜集竞品信息, backstory资深市场分析师) task Task(description调研三款竞品的功能差异, agentresearcher, expected_output对比表格) crew Crew(agents[researcher], tasks[task]) result crew.kickoff()CrewAI的expected_output字段很关键它直接影响Agent的输出质量。我试过写一份报告和写包含五个维度的对比表格每维度至少三条数据后者产出质量明显更高。另外CrewAI默认用顺序执行如果要并行得用Process.hierarchical并指定manager。3.3 三个框架怎么选维度LangGraphAutoGenCrewAI核心模型状态图对话循环角色团队流程控制精细中等粗粒度上手难度中低低适合场景复杂分支流程代码生成、对话角色分工任务状态持久化原生支持需自行实现有限支持我的经验是如果流程里有大量条件判断和循环选LangGraph如果核心是让几个Agent聊出结果选AutoGen如果任务能清晰拆成几个角色的职责选CrewAI。三者也能混用比如用LangGraph做外层流程控制某个节点内部起一个CrewAI团队干活。4. MCP协议Agent调用外部工具的统一接口4.1 MCP到底解决什么问题在没有MCP之前每个Agent框架调工具的方式都不一样LangChain有Tool、OpenAI有function calling、各家IDE插件有自己的扩展机制。结果是同一个数据库查询工具你要为每个框架写一遍适配。MCPModel Context Protocol的思路是定义一套标准协议工具提供方实现一次MCP Server任何支持MCP的客户端都能调用。这就像USB-C统一了充电接口之前每个品牌一个口现在一根线通吃。MCP的核心概念Server暴露工具、资源、提示词、ClientAgent侧连接Server并调用、Transport通信方式常见的是stdio和HTTPSSE。一个MCP Server可以暴露多个tool每个tool有name、description、inputSchema。4.2 写一个最小MCP Serverfrom mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import Tool, TextContent app Server(demo-server) app.list_tools() async def list_tools(): return [Tool(namequery_db, description查询数据库, inputSchema{type: object, properties: {sql: {type: string}}})] app.call_tool() async def call_tool(name, arguments): if name query_db: # 实际执行查询 return [TextContent(typetext, text查询结果)] async def main(): async with stdio_server() as (read, write): await app.run(read, write, app.create_initialization_options())这个Server通过stdio通信客户端启动它作为子进程通过标准输入输出交换JSON-RPC消息。如果要走网络换成SSE transport。4.3 客户端接入的常见问题把MCP接入Codex、通义灵码这类工具时最容易卡在授权和路径上。stdio类型的Server需要在客户端配置里写清楚启动命令和参数比如{command: python, args: [server.py]}路径要用绝对路径相对路径在不同工作目录下会找不到。HTTP类型的Server要确认端口没被占用以及客户端是否支持该transport。热词里提到的codex无法找到mcp这类问题九成是配置文件路径或格式问题。建议先用MCP官方的inspector工具单独测试Server能不能正常列出工具确认Server没问题再排查客户端配置。另外注意不同客户端对MCP协议版本的支持程度不一样Server端尽量用稳定版本的SDK。5. OpenAI API接入与工具链配置要点5.1 API Key获取与环境变量管理OpenAI的API Key在平台后台的API Keys页面创建创建后只显示一次务必立即保存。管理上绝对不要硬编码在代码里用环境变量export OPENAI_API_KEYsk-...代码里用os.environ[OPENAI_API_KEY]读取。团队协作时用.env文件配合python-dotenv但.env要加进.gitignore。我见过有人把key提交到公开仓库几小时内就被刷爆额度这个教训很贵。5.2 模型选择与成本控制不同任务用不同模型是基本操作。复杂推理用能力强的模型简单分类、格式化输出用便宜的小模型。设置max_tokens限制输出长度设置temperature控制随机性做数据提取时设0做创意生成时设0.7以上。批量任务用Batch API能省一半成本代价是延迟高。另外记得在代码里加token计数和费用日志不然月底账单会让你措手不及。5.3 依赖安装的坑热词里出现的missing optional dependency openai/codex-win32-x64这类报错本质是平台相关的可选依赖没装上。解决办法通常是删掉node_modules和lock文件重新npm install或者显式安装对应平台的包。Python侧类似的问题常见于某些包对特定Python版本或系统库有要求用虚拟环境隔离能减少这类冲突。我的习惯是每个项目独立venvrequirements.txt里锁定版本号避免昨天还能跑今天就不行。6. 资源清单与日常维护习惯工具和框架的文档更新很快与其收藏一堆可能过期的链接不如建立自己的信息获取渠道。官方文档永远是第一手资料GitHub的release notes能提前知道哪些API要变issue区能看到别人踩的坑。我每周花半小时扫一遍常用框架的更新日志把影响自己项目的变更记到速查表里。速查表本身建议用Markdown维护按框架分节每节包含核心概念一句话、最小示例、常见错误、版本注意事项。放在项目仓库里团队共享。这样新人入职不用从零摸索老手也不用凭记忆猜API。工具是死的维护习惯是活的这份清单的价值不在于它现在写了什么而在于你能持续往里补充自己踩过的坑。