1. 从单智能体到多智能体任务分解、通信与失败恢复的真实差异如果你刚开始接触 AI 应用开发大概率是从「一个模型 一段系统提示词」起步的。这种单智能体Single-Agent模式在写文案、做翻译、回答知识问题时确实够用但一旦任务变成「先查资料、再算数据、最后生成报告并校验」单智能体就开始力不从心上下文越塞越长、指令互相打架、一处出错整条链路重来。多智能体系统Multi-Agent System简称 MAS解决的就是这个问题。它把一个大任务拆给多个各有所长的智能体每个智能体有自己的角色、工具和记忆通过通信协议和编排逻辑协作完成目标。你可以把它类比成一家小公司单智能体是「一个人干所有活」的自由职业者多智能体则是「产品经理 开发 测试」的协作团队。对初次接触的开发者来说最需要搞清楚的其实是三个维度的差异任务分解、通信协作、失败恢复。我用一张对照表先讲清楚再带你跑通一个最小可用的双智能体 demo。对比维度单智能体系统多智能体系统架构单体式一个模型一套指令分布式多个专业智能体协作任务分解靠提示词内部「脑补」拆解显式拆分为子任务并分派专业化通才型什么都会一点每个智能体专精一个领域通信方式无自己和自己对话消息传递、共享状态、任务委派失败恢复单点故障一处错全盘重来故障隔离可重试或换智能体接管可扩展性有限只能垂直堆模型高可水平增加智能体成本单次调用便宜但复杂任务要反复重试总 token 消耗更高但可混用大小模型任务分解上单智能体是把所有要求写进一个超长提示词模型自己在内部「想」怎么拆多智能体则是编排层显式地把任务切成子任务比如「检索 → 分析 → 撰写 → 校验」每个子任务交给对应角色的智能体。通信协作上单智能体没有通信概念多智能体需要智能体间通信消息传递、共享记忆交接时不丢上下文和编排逻辑谁在什么时候做什么。失败恢复上单智能体一旦中间步骤出错往往要从头再来多智能体可以把失败限制在某个子任务内重试该智能体或换一个智能体接管其余部分不受影响。理解了这三点你就明白为什么多智能体更适合复杂工作流也明白它为什么更贵、更难调。接下来我们先解决模型接入的问题再动手写代码。2. TaoToken 前置准备统一 Base URL 与 API Key 的接入方式多智能体 demo 要跑起来第一步是让每个智能体都能调用大模型。这里我用 TaoToken 作为统一接入层原因是它兼容 OpenAI 风格的接口Base URL 和 API Key 一套配置就能给 LangGraph、CrewAI、AutoGen 三个框架复用省得每个框架都去折腾不同的鉴权方式。你需要准备两样东西一个 API Key以及确认 Base URL。API 地址是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 OpenAI 兼容的 base_url 使用。API Key 可以在控制台的 API Keys 页面创建创建后复制保存后面三个框架的配置都会用到它。提示API Key 只在创建时完整显示一次建议创建后立刻存到本地环境变量或密码管理器里不要硬编码进提交到 Git 的代码。我习惯把配置写进环境变量这样切换环境时不用改代码。在项目根目录建一个.env文件# .env TAOTOKEN_API_KEYsk-你的实际key TAOTOKEN_BASE_URLhttps://taotoken.net/api然后在 Python 里用python-dotenv读取。如果你还没装依赖先建一个虚拟环境再装python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install python-dotenv openai装好后写一个最小的连通性测试确认 Key 和 Base URL 没问题再去装框架。这一步很关键因为后面框架报错时你至少能确定不是接入层的问题import os from dotenv import load_dotenv from openai import OpenAI load_dotenv() client OpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), ) resp client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 只回复两个字连通}], ) print(resp.choices[0].message.content)如果输出「连通」说明接入层已经通了。这里model参数填你要用的模型 ID具体可用模型以控制台或文档里列出的为准。跑通这一步之后三个框架的配置就都是在这套 Base URL Key 上做文章。注意不要把 API Key 写进前端代码或公开仓库。多智能体系统里每个智能体都会调用模型Key 泄露的风险比单智能体更高建议用服务端代理或环境变量隔离。接入层准备好后我们进入正题三个框架的初始化配置片段以及一个能本地跑通的双智能体协作 demo。3. 三大框架可复制配置LangGraph、CrewAI、AutoGen 初始化片段这一节给你三份可以直接复制的配置片段路径和字段都按各框架官方约定来写。先装依赖三个框架可以装在同一环境里但要注意版本兼容建议用独立的虚拟环境分别测试。pip install langgraph langchain-openai pip install crewai crewai-tools pip install autogen-agentchat autogen-ext[openai]3.1 LangGraph基于图的状态管理配置LangGraph 的核心是「状态图」每个节点是一个智能体或工具边决定流转方向。它用StateGraph管理共享状态适合需要精确控制流程的场景。配置模型时通过ChatOpenAI指定 base_urlimport os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langgraph.graph import StateGraph, END from typing import TypedDict load_dotenv() llm ChatOpenAI( modelgpt-4o-mini, api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), temperature0, ) class AgentState(TypedDict): task: str draft: str review: str def writer_node(state: AgentState): msg llm.invoke(f请根据任务写一段简短说明{state[task]}) return {draft: msg.content} def reviewer_node(state: AgentState): msg llm.invoke(f请审查以下内容并给出改进意见{state[draft]}) return {review: msg.content} graph StateGraph(AgentState) graph.add_node(writer, writer_node) graph.add_node(reviewer, reviewer_node) graph.set_entry_point(writer) graph.add_edge(writer, reviewer) graph.add_edge(reviewer, END) app graph.compile() result app.invoke({task: 解释什么是多智能体系统}) print(草稿, result[draft]) print(评审, result[review])这段代码里writer和reviewer就是两个智能体通过图的边连接状态在AgentState里共享。LangGraph 的检查点checkpoint机制还能让你在中途暂停、恢复这对失败恢复很友好。3.2 CrewAI基于角色的团队配置CrewAI 用「角色 任务 团队」的抽象写起来最接近自然语言。它独立于 LangChain配置模型时通过LLM类指定import os from dotenv import load_dotenv from crewai import Agent, Task, Crew, Process, LLM load_dotenv() llm LLM( modelopenai/gpt-4o-mini, base_urlos.getenv(TAOTOKEN_BASE_URL), api_keyos.getenv(TAOTOKEN_API_KEY), ) researcher Agent( role资料研究员, goal收集并整理关于多智能体系统的关键信息, backstory你擅长快速检索和归纳技术概念。, llmllm, verboseTrue, ) writer Agent( role技术写作者, goal把研究结果写成通俗易懂的说明, backstory你擅长把复杂概念讲给初学者听。, llmllm, verboseTrue, ) task1 Task( description整理多智能体系统与单智能体的三点核心区别。, expected_output三条带解释的区别说明。, agentresearcher, ) task2 Task( description基于研究结果写一段 200 字以内的科普说明。, expected_output一段通俗的科普文字。, agentwriter, ) crew Crew( agents[researcher, writer], tasks[task1, task2], processProcess.sequential, verboseTrue, ) result crew.kickoff() print(result)Process.sequential表示任务按顺序执行前一个任务的输出会作为上下文传给下一个。CrewAI 也支持Process.hierarchical由一个管理者智能体动态分派任务。3.3 AutoGen对话式多智能体配置AutoGen 的强项是「对话」智能体之间通过消息往来协作还内置代码执行能力。新版用autogen-agentchat和autogen-extimport os import asyncio from dotenv import load_dotenv from autogen_ext.models.openai import OpenAIChatCompletionClient from autogen_agentchat.agents import AssistantAgent from autogen_agentchat.teams import RoundRobinGroupChat from autogen_agentchat.conditions import TextMentionTermination load_dotenv() model_client OpenAIChatCompletionClient( modelgpt-4o-mini, base_urlos.getenv(TAOTOKEN_BASE_URL), api_keyos.getenv(TAOTOKEN_API_KEY), ) planner AssistantAgent( nameplanner, model_clientmodel_client, system_message你负责把任务拆解成步骤输出计划。, ) executor AssistantAgent( nameexecutor, model_clientmodel_client, system_message你负责执行计划完成后回复 TERMINATE。, ) team RoundRobinGroupChat( participants[planner, executor], termination_conditionTextMentionTermination(TERMINATE), max_turns6, ) async def main(): result await team.run(task用三步说明多智能体系统的价值。) for msg in result.messages: print(f[{msg.source}] {msg.content}) asyncio.run(main())RoundRobinGroupChat让智能体轮流发言TextMentionTermination在检测到「TERMINATE」时结束对话。AutoGen 的群聊模式非常适合需要多轮讨论、互相纠错的场景。三份配置的共同点是Base URL 都填https://taotoken.net/apiKey 都从环境变量读模型 ID 按需替换。这样你换框架时接入层不用动。4. 双智能体协作 Demo 验证从请求到成功结果的完整步骤配置写好了接下来跑一个最小可验证的双智能体协作 demo。我用 LangGraph 版本因为它对流程控制最直观也最容易观察状态流转。目标是一个「研究员」智能体负责收集要点一个「写作者」智能体负责成文两者通过共享状态交接。先确认依赖装好然后建一个demo.pyimport os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langgraph.graph import StateGraph, END from typing import TypedDict load_dotenv() llm ChatOpenAI( modelgpt-4o-mini, api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), temperature0, ) class State(TypedDict): topic: str points: str article: str def researcher(state: State): print( 研究员智能体开始工作) msg llm.invoke( f请列出关于「{state[topic]}」的三个关键要点每条一句话。 ) return {points: msg.content} def writer(state: State): print( 写作者智能体开始工作) msg llm.invoke( f根据以下要点写一段 150 字左右的说明\n{state[points]} ) return {article: msg.content} builder StateGraph(State) builder.add_node(researcher, researcher) builder.add_node(writer, writer) builder.set_entry_point(researcher) builder.add_edge(researcher, writer) builder.add_edge(writer, END) graph builder.compile() if __name__ __main__: out graph.invoke({topic: 多智能体系统}) print(\n 要点 ) print(out[points]) print(\n 成文 ) print(out[article])运行python demo.py预期你会看到类似这样的输出内容因模型而异 研究员智能体开始工作 写作者智能体开始工作 要点 1. 多智能体系统由多个专业智能体协作完成复杂任务。 2. 智能体之间通过通信和共享记忆保持上下文一致。 3. 相比单智能体它更易扩展但协调成本更高。 成文 多智能体系统是一种把复杂任务拆分给多个专业智能体协作完成的架构……看到「要点」和「成文」两段都正常输出说明双智能体协作链路已经跑通。这里的关键验证点是researcher的输出通过State传给了writer两个智能体各自调用模型但共享同一套 Base URL 和 Key。如果你想验证失败恢复可以故意把writer节点里的模型 ID 改成一个不存在的值再运行一次。你会看到researcher正常完成writer报错——这就是故障隔离研究员的结果还在你只需要修 writer 的配置重跑不用从头再来。这正是多智能体相比单智能体的优势所在。跑通之后你可以把researcher换成带检索工具的智能体把writer换成带格式校验的智能体逐步扩展成更完整的流水线。5. 本篇常见报错排查401、local proxy failed、reading choices 与 OAuth多智能体 demo 跑不起来八成是接入层或配置的问题。我把几个高频报错和对应排查方法列出来你对照着看。401 Unauthorized / invalid_api_key最常见。先检查.env里的TAOTOKEN_API_KEY是否复制完整有没有多余空格或换行。再确认代码里读的是不是同一个环境变量名。如果 Key 是在控制台刚创建的确认没有误删。还有一种情况是 Key 被硬编码在代码里但代码没重新加载改完记得重启进程。local proxy failed / connection error这类报错通常指向网络层。先确认base_url填的是https://taotoken.net/api没有多写或少写路径。如果你在本地配了其他网络工具可能会干扰请求建议先关掉再测。另外检查一下是不是公司网络限制了外部请求换个网络环境试试。reading choices / KeyError: choices这个报错说明请求返回的结构里没有choices字段通常是响应体是错误信息而不是正常结果。打印完整响应看看resp client.chat.completions.create(...) print(resp) # 看完整结构常见原因是模型 ID 写错了或者 base_url 指向了不兼容的端点。确认model参数是控制台里实际可用的模型 ID。OAuth / authentication 相关报错如果你用的是某些需要 OAuth 的工具链注意 TaoToken 走的是 API Key 鉴权不是 OAuth 流程。检查是不是把 Key 填到了 OAuth 的字段里。正确做法是Base URL 填https://taotoken.net/apiKey 填到 api_key 字段模型 ID 填到 model 字段这三件套对齐就不会出鉴权问题。框架特有的报错CrewAI 如果报LLM provider not found检查LLM类的model字段有没有加openai/前缀AutoGen 如果报model_client相关错误确认OpenAIChatCompletionClient的参数名是base_url而不是base_url拼错。LangGraph 如果报状态字段缺失检查TypedDict里定义的字段和节点返回的 key 是否一致。排查顺序建议是先跑第 2 节的最小连通性测试确认接入层没问题再逐个框架单独测最后才跑多智能体协作。这样能把问题范围缩小到具体某一层而不是在整条链路上瞎猜。6. 选型建议与下一步把多智能体接入你的真实工作流三个框架跑下来我的实际感受是LangGraph 适合需要精确控制流程和状态、要做失败恢复和人工介入的场景CrewAI 适合快速搭一个角色分工明确的团队写起来最省心AutoGen 适合需要多轮对话、互相纠错、甚至执行代码的场景。选型时先问自己我的任务更像「流水线」「团队协作」还是「圆桌讨论」。如果你打算把多智能体用到长期编码或 Agent 项目里建议先把接入层固定下来也就是统一用一套 Base URL 和 Key这样换框架、加智能体时不用反复改配置。模型调用频繁的话可以关注一下 Coding Plan 这类长期方案把成本控制住。下一步你可以做三件事第一把第 4 节的双智能体 demo 改成三智能体加一个「校验者」第二给研究员智能体接一个检索工具让它能查实时资料第三把跑通的流程封装成函数接入你现有的业务系统。每加一个智能体都回头看看第 1 节那张对照表确认你确实需要多智能体而不是把单智能体能做的事复杂化。多智能体不是银弹它用更高的协调成本和 token 消耗换取专业化和可扩展性。任务简单时单智能体反而更快更省。判断标准很简单当你的提示词开始互相打架、上下文长到模型记不住、一处出错就要全部重来时就是考虑多智能体的时候了。