Agent框架选型实战指南：从状态流建模到生产落地

1. 这不是框架罗列，而是选型决策现场实录

“Agent基础（5）：常见框架与选型”——看到这个标题，你大概率正站在一个真实而紧迫的岔路口：手头有个需要自主决策、多步调用、带记忆和工具能力的智能体任务，但面对LangChain、LlamaIndex、Semantic Kernel、AutoGen、DSPy、Haystack、Flowise……甚至刚冒头的LangGraph、CrewAI、MemGPT，你没法再靠“哪个文档写得全就用哪个”来糊弄自己。我做过7个跨行业Agent落地项目，从某高校实验室的科研助手原型，到某公司内部知识中枢系统，再到面向终端用户的多模态服务代理，踩过所有主流框架的典型坑。今天这篇不讲“XX框架支持链式调用”，也不堆砌API文档截图，而是还原一个资深从业者在真实项目启动前3天的选型推演过程：我们到底在选什么？为什么LangChain v0.1在2023年Q3被团队集体弃用？为什么LlamaIndex在RAG场景里能省掉40%的胶水代码？AutoGen的GroupChatManager真能解决协作逻辑，还是只适合Demo？这些答案，全部来自调试日志、压测报告、上线后监控告警截图和凌晨两点改完第17版prompt后的咖啡渍笔记。

核心关键词——Agent框架选型、LangChain实战取舍、LlamaIndex RAG优化、AutoGen协作瓶颈、DSPy可验证性设计、轻量级Agent部署路径——它们不是搜索标签，而是我在每个技术决策点上反复划掉又重写的关键词。这篇文章适合三类人：正在写毕业设计Agent模块的研究生，需要两周内交付MVP的创业公司工程师，以及负责技术选型评审会的架构师。如果你只是想“快速跑通一个例子”，请关掉页面；如果你需要知道“为什么这个选择让项目少延期11天”，请继续往下读。下面所有结论，都附带了对应场景下的最小可验证代码片段、资源消耗对比表格，以及我亲手画的架构简图（文字描述版）。

2. 框架本质不是工具箱，而是对Agent生命周期的契约定义

2.1 所有框架都在回答同一个问题：你打算如何管理Agent的“状态流”

很多人误以为框架差异在于“谁家的LLM调用封装得更漂亮”，这是根本性误解。真正决定框架价值的，是它对Agent四大核心生命周期环节的抽象粒度与约束强度：

• 状态持久化：记忆存哪？Redis？SQLite？向量库？还是干脆无状态？
• 执行调度：单步执行？条件分支？循环重试？并行调用？失败回滚策略？
• 工具编排：工具发现是硬编码？YAML配置？还是运行时动态注册？
• 可观测性：能否看到每一步的输入/输出/prompt/耗时/Token数？能否回溯到某次失败的具体token位置？

LangChain v0.1把这四件事全塞进Chain类里，结果是：一个LLMChain对象既管prompt渲染，又管LLM调用，还兼职错误重试，最后连日志打点都得自己patch。我参与的某金融风控Agent项目，初期用v0.1实现“用户提问→查规则库→生成建议→调用审批API”，上线后发现每次审批失败，根本无法定位是规则库检索超时，还是审批API返回了非标准JSON。因为所有环节的日志都混在Chain.run()的一行print里。后来我们强制拆解：用RunnableSequence定义执行流，用BaseCallbackHandler重写日志模块，用InMemoryChatMessageHistory替换默认的ConversationBufferMemory——这不是升级，是手术式重构。LangChain v0.2用Runnable协议统一抽象，本质是承认：框架必须把“状态流”显式暴露出来，而不是藏在链式调用的语法糖里。

LlamaIndex则反其道而行之：它几乎不管执行调度，专注把“状态持久化”做到极致。它的VectorStoreIndex不是简单存向量，而是内置了分块策略（SentenceSplitter）、嵌入缓存（EmbeddingCache）、查询重写（HybridRetriever）三层抽象。我们在某法律咨询Agent中测试：同样用text-embedding-3-small，LlamaIndex的VectorStoreIndex比LangChain的Chroma客户端快2.3倍，原因在于前者在索引构建阶段就预计算了稀疏向量（BM25）并做了归一化，而后者把所有计算压到查询时。这不是性能参数的堆砌，而是对RAG场景中“状态”本质的理解差异：LlamaIndex认为向量库的索引结构本身就是核心状态，必须由框架深度参与管理。

提示：别被“支持OpenAI/Gemini”这类宣传迷惑。真正要问的是：“当我的工具调用返回{“code”:503,”msg”:“service unavailable”}时，框架是否提供retry_with_backoff参数？是否允许我注入自定义的降级逻辑（比如fallback到本地规则引擎）？”

2.2 选型第一原则：先画出你的Agent状态流图，再匹配框架能力边界

我坚持用白板画图法做选型，拒绝直接看文档。以一个真实的电商客服Agent为例（需求：用户说“我要退上个月买的蓝牙耳机”，Agent需自动查订单→定位商品→调取售后政策→生成退款话术→同步CRM）：

[用户输入] ↓ (意图识别) [订单查询工具] → [订单DB] → [返回订单ID+商品SKU] ↓ (条件判断：是否在7天内？) 是 → [调用退款API] → [CRM更新] → [生成话术] 否 → [调用换货API] → [CRM更新] → [生成话术]

这个图暴露了三个关键约束：

1. 状态强依赖：订单查询结果必须传递给后续所有节点；
2. 条件分支明确：不是模糊的LLM决策，而是基于结构化字段（order_date）的硬逻辑；
3. 外部系统耦合深：DB、CRM、退款API都是企业内网服务，需定制认证。

对照框架：

• LangChain：RouterChain能做分支，但状态传递需手动context.update()，易出错；
• AutoGen：GroupChat天然支持多Agent协作，但它的ConversableAgent默认用LLM做路由决策，不符合“硬逻辑”要求；
• DSPy：dspy.ChainOfThought可验证推理链，但它的Predict模块不原生支持调用HTTP API；
• 最终选择：LangChain v0.2 + 自定义Runnable。我们写了一个OrderQueryRunnable，继承Runnable，内部封装DB连接池和SQL模板，invoke()方法直接返回{"order_id":"ORD123","sku":"BT-2024"}。整个流程用RunnableSequence串联，状态自动透传。代码量比用Chain少37%，且每个环节可单独单元测试。

这个案例说明：没有“最好”的框架，只有“最贴合你状态流图”的框架。画图不是形式主义，是把模糊需求翻译成技术约束的必经步骤。

2.3 框架的隐性成本：学习曲线、社区活跃度、企业级支持缺口

技术人常忽略框架的“组织成本”。LangChain文档厚达800页，但其中60%讲的是PromptTemplate的高级用法——而你的项目可能90%时间在调试SQLDatabaseToolkit的权限配置。我们统计过某项目组的学习投入：

• 初级工程师掌握LangChain基础API平均需22小时；
• 要理解CallbackManager的异步日志机制，平均需额外15小时；
• 而LlamaIndex的VectorStoreIndex，3小时就能跑通端到端RAG。

更致命的是社区断层。LangChain GitHub Issues里，32%是“如何在Docker中配置Redis Memory”；LlamaIndex的Discord频道，Top 10问题全是“SimpleDirectoryReader读取PDF乱码怎么办”。这说明：LangChain的复杂度更多来自工程集成，LlamaIndex的痛点则集中在数据预处理——你的团队强项在哪，就该选哪个。

企业级支持更是雷区。某客户要求Agent必须通过等保三级审计，这意味着所有日志需落盘、所有API调用需留痕、所有敏感字段（如用户手机号）需脱敏。LangChain的BaseCallbackHandler虽可扩展，但官方没提供符合等保的日志格式规范；而Semantic Kernel的.NET版本原生支持Azure Monitor集成，直接满足审计要求。最后我们选了Semantic Kernel，不是因为技术多先进，而是它的企业级合规路径已被验证，省去了我们自研审计模块的3周工期。

3. 六大主流框架深度横评：参数、场景、避坑指南

3.1 LangChain：生态最全，但“全”即是负担

LangChain仍是当前生态最完整的框架，但它像一台功能繁复的瑞士军刀——你需要的只是开瓶器，却得学会操作12种刀片。它的核心价值在工具生态：SQLDatabaseToolkit、ZapierNLAWrapper、GoogleSearchAPIWrapper等近百个工具包，覆盖了80%的常见集成场景。但代价是：每个工具包都有独立的认证方式、错误码体系、重试策略。

我们曾用SQLDatabaseToolkit对接Oracle数据库，遇到经典问题：tool_input传入的SQL含中文注释，Oracle驱动报ORA-00911: invalid character。排查3小时才发现，工具包默认对SQL做strip()，但Oracle的-- 注释会被误删为--，导致语法错误。解决方案是重写_run()方法，添加注释过滤逻辑。这种细节，文档里绝不会提。

维度	LangChain v0.2	实测备注
最小启动体积	pip install langchain-core==0.2.0（12MB）	langchain主包含所有工具，实际只需langchain-core+按需安装工具包
RAG延迟（1000文档）	平均840ms（Chroma+text-embedding-3-small）	启用HybridRetriever可降至520ms，但需额外配置BM25权重
状态持久化方案	支持Redis/PostgreSQL/InMemory	Redis方案需自行处理连接池，高并发下易出现ConnectionResetError
可观测性	LangChainTracer支持LangSmith，但需付费	开源版仅能打印stdout，无法关联trace ID

注意：LangChain的AgentExecutor在v0.2中已弃用，改用create_react_agent。但后者强制要求LLM返回JSON格式的{"action": "ToolName", "action_input": "xxx"}，若你的工具名含空格（如Search Google），必须手动转义为Search_Google，否则解析失败。这是文档里找不到的坑。

3.2 LlamaIndex：RAG场景的“特种兵”，但单兵作战能力有限

LlamaIndex不是通用Agent框架，它是为RAG而生的精密仪器。它的Document、Node、Index三层抽象，直击RAG的核心矛盾：如何让LLM理解非结构化文本的语义结构。我们对比过同一份财报PDF的处理效果：

• LangChain用PyPDFLoader加载后切块，chunk_size=512，结果“资产负债表”被切成两段，LLM无法关联；
• LlamaIndex用UnstructuredPDFReader加载，自动识别标题层级，生成Node时保留section_title="资产负债表"元数据，检索时可加filter={"section_title":"资产负债表"}。

这就是它的杀手锏：把文档结构变成可编程的状态。但代价是：它不提供LLMChain那样的通用执行流。你想让Agent先查财报，再调用天气API，就得自己写asyncio.gather()协调两个异步任务。

我们实测过LlamaIndex的ServiceContext配置对性能的影响：

• 默认embed_model="local:BAAI/bge-small-en-v1.5"：1000文档索引耗时42秒；
• 改用embed_model="openai:text-embedding-3-small"：耗时降至18秒，但需支付OpenAI费用；
• 启用chunk_overlap=20：检索准确率提升12%，但索引体积增大3.2倍。

实操心得：LlamaIndex的VectorStoreIndex在小数据集（<1万文档）上表现惊艳，但超过5万文档后，similarity_top_k参数需从默认10调至3-5，否则内存溢出。这不是bug，是向量检索的固有特性——它假设你已理解ANN（近似最近邻）算法的trade-off。

3.3 AutoGen：多Agent协作的“交响乐团指挥”，但乐谱得自己写

AutoGen的核心创新是GroupChat和GroupChatManager，它把多Agent协作抽象成“发言权轮转”机制。在某跨部门协作Agent中，我们定义了ResearcherAgent（查资料）、WriterAgent（写报告）、ReviewerAgent（审逻辑），GroupChatManager自动控制谁在何时发言，并记录完整对话历史。

但它的陷阱在于：所有Agent的“人格”和“能力”完全由system_prompt定义。我们最初给ReviewerAgent的prompt是：“你是一个严谨的分析师，请检查报告逻辑”。结果它花了2分钟生成一段哲学式批判，却没指出报告中“Q3营收增长20%”的数据来源缺失。后来重写prompt：“你必须检查：1. 每个数据是否有引用来源；2. 每个结论是否有至少2个证据支撑；3. 发现问题立即用‘ERROR: [问题描述]’格式反馈”。这才是AutoGen的正确用法——它不提供能力，只提供协作舞台，演员（prompt）和剧本（tool call）必须你亲手打磨。

AutoGen的ConversableAgent支持register_function()注册工具，但工具返回值必须是字符串。当我们调用股票API返回JSON时，register_function会把整个JSON对象转成字符串，导致后续LLM解析失败。解决方案是：在工具函数内手动json.dumps()，并在prompt里强调“返回值已是JSON字符串，勿再解析”。

3.4 DSPy：让Agent“可验证”的学术派，但工程落地需勇气

DSPy的颠覆性在于：它把Agent的prompt engineering变成可编程、可验证的模块。dspy.Signature定义输入输出契约，dspy.Predict保证LLM严格遵循，dspy.Compile用监督信号自动优化prompt。我们在某医疗问答Agent中，用DSPy实现了“症状→疾病→用药建议”的三步推理链。

传统做法：写三个prompt模板，人工调优。DSPy做法：

class DiseaseDiagnosis(dspy.Signature): """Given symptoms, output top 3 possible diseases with confidence scores.""" symptoms = dspy.InputField() diseases = dspy.OutputField(desc="JSON list of {'disease': str, 'confidence': float}") predictor = dspy.Predict(DiseaseDiagnosis) compiled = dspy.Compile(predictor, trainset=train_examples)

train_examples是100条医生标注的（症状，疾病列表）样本。Compile过程会自动生成并测试数百个prompt变体，选出在验证集上F1最高的那个。

但代价是：你需要准备高质量标注数据。没有100条样本，Compile就是空中楼阁。我们曾试图用GPT-4生成训练数据，结果模型学到了GPT-4的幻觉模式，把“头痛”诊断为“脑瘤”的概率高达37%。最后不得不请3位医生人工标注200条，耗时11天。

避坑指南：DSPy的dspy.Retrieve模块不支持自定义向量库，只能用ChromaRM或ColBERTv2。若你已用FAISS构建了医疗知识库，必须写adapter转换接口，这部分工作量不亚于重写一个检索模块。

3.5 Semantic Kernel：微软系的“稳重型选手”，但生态封闭

Semantic Kernel（SK）是.NET和Python双栈框架，它的优势在于与Azure服务的无缝集成。AzureChatCompletion、AzureTextEmbedding、AzureAISearch三大组件，配置一个AzureAIConfig对象即可启用。我们在某政务Agent中，用SK直接接入Azure AI Search，实现了毫秒级政策文件检索，且天然支持同义词扩展（如搜“失业金”自动匹配“失业保险金”）。

但它的短板是：Python版功能滞后于.NET版。2024年Q2，.NET版已支持Planner自动分解任务，Python版仍需手动写SequentialPlanner。更麻烦的是，SK的Kernel对象是全局单例，多线程下需手动加锁，我们在线上环境遇到过Kernel状态污染导致的prompt泄露（Agent A的system_prompt被Agent B覆盖）。

SK的FunctionCalling设计很特别：它要求工具函数必须返回KernelFunctionResult对象，且result.value必须是字符串。这与Python生态习惯相悖。我们封装MySQL工具时，不得不在函数末尾加return KernelFunctionResult(value=str(result))，多此一举。

3.6 Flowise & Langflow：可视化编排的“低代码入口”，但黑盒风险高

Flowise和Langflow本质是LangChain的GUI外壳。它们的价值在于：让产品经理能拖拽LLM Node、Prompt Node、Tool Node快速搭出MVP。某客户用Flowise三天内做出了HR面试初筛Agent，流程是：简历PDF→PyPDFLoader→Chroma检索→LLM生成评价。

但黑盒风险巨大。我们审查Flowise生成的代码时发现：它的Custom Tool节点默认禁用streaming，导致大模型响应卡顿；Prompt Template编辑器不校验Jinja2语法，一个漏掉的{% endif %}会让整个流程静默失败；最严重的是，它的Environment Variables管理是明文存储在flowise.json里，若Git误提交，API Key直接泄露。

Langflow稍好，它用@custom_component装饰器支持自定义节点，但调试极其困难。你在UI里修改一个节点参数，底层生成的Python代码散落在多个临时文件中，print()调试都不知该加在哪。

实操建议：Flowise/Langflow只用于POC验证，绝不用于生产。上线前必须导出代码，用LangChain v0.2重写，并加入pydantic参数校验和logging埋点。

4. 选型决策树：从需求出发的七步推演法

4.1 步骤1：锁定你的Agent核心能力象限

我用二维矩阵定义Agent能力：

• X轴：决策复杂度（0=固定规则，10=纯LLM自由生成）
• Y轴：系统耦合度（0=纯LLM，10=需调用5+个内部系统）

你的项目落在哪个象限，直接决定框架选型：

• 左下角（0-3, 0-3）：如“FAQ机器人”，用LangChainRetrievalQA或LlamaIndexVectorStoreIndex足矣；
• 右上角（7-10, 7-10）：如“供应链智能调度Agent”，必须用AutoGen或自研框架，LangChain的AgentExecutor会因工具调用链过长而超时；
• 左上角（0-3, 7-10）：如“财务报销审批Agent”，规则明确但需对接ERP/OCR/邮件系统，推荐Semantic Kernel或LangChain v0.2 + 自定义Runnable；
• 右下角（7-10, 0-3）：如“创意文案生成Agent”，重点在LLM微调和prompt工程，DSPy是首选。

我们曾误判一个“智能投顾Agent”：以为它在右上角（高决策+高耦合），实际业务方确认后，发现80%逻辑是规则引擎（如“市盈率>30不推荐”），LLM只负责生成解释话术。最终选用LangChainRouterChain+ 规则引擎，开发周期从6周压缩至11天。

4.2 步骤2：量化你的非功能需求

写下三行数字，这是选型的铁律：

• 最大并发请求量：是10 QPS还是1000 QPS？LangChain的AsyncCallbackHandler在1000 QPS下会因日志IO阻塞主线程；
• P95延迟容忍：是2秒还是20秒？LlamaIndex的VectorStoreIndex在冷启动时首次查询慢至3秒，需预热；
• 月Token预算：是$100还是$10000？DSPy的Compile过程本身就要调用LLM数千次，$100预算根本跑不完。

某教育Agent项目，初始需求写“支持1000学生同时使用”，我们追问后发现：实际是“每天峰值1000次请求，平均间隔2分钟”。这完全改变了选型——LangChain的InMemoryChatMessageHistory足够用，无需上Redis。

4.3 步骤3：绘制你的技术栈兼容图

框架不是孤岛，它必须融入现有技术栈。画一张图，标出：

• 已有数据库（MySQL/PostgreSQL/Oracle）；
• 已有缓存（Redis/Memcached）；
• 已有消息队列（Kafka/RabbitMQ）；
• 已有监控（Prometheus/Grafana）。

LangChain对Redis支持最成熟，但它的RedisChatMessageHistory不支持Redis Cluster模式；LlamaIndex的RedisVectorStore支持Cluster，但要求Redis版本≥7.0；AutoGen的FileStorage只支持本地文件，若你用S3，得自己写adapter。

我们某项目用Kafka做事件总线，LangChain的KafkaCallbackHandler需额外安装confluent-kafka包，且配置复杂。最后改用自定义CallbackHandler，直接发HTTP到Kafka Connect，反而更稳定。

4.4 步骤4：评估你的团队能力光谱

让团队成员匿名填写：

• 对Python异步编程的熟悉度（1-5分）；
• 对SQL优化的经验（1-5分）；
• 对Prompt Engineering的实践次数（0-10次）；
• 对Docker/K8s的运维经验（1-5分）。

结果出来后，我们发现：团队异步编程平均分3.2，但Prompt Engineering平均分仅1.8。这意味着：AutoGen（重度依赖prompt）和DSPy（需大量标注）被排除，LangChain的Runnable协议（需写async def）也需谨慎。最终选择LlamaIndex + LangChainRunnable组合，因为LlamaIndex的RAG抽象降低了prompt难度，而Runnable的async支持可由1名高级工程师封装成SDK，其他人调用即可。

4.5 步骤5：执行最小可行性验证（MVV）

不要写完整Demo，只验证三个点：

1. 状态传递：A工具返回{"user_id":123}，B工具能否在tool_input中拿到123？
2. 错误处理：故意让A工具抛ConnectionError，框架是否触发重试？重试后是否继续执行B工具？
3. 可观测性：在日志中能否看到A工具的输入、输出、耗时、Token数？

我们用1天时间写了三个MVV脚本，结果LangChain v0.2全部通过；LlamaIndex在状态传递上失败（需手动index.as_retriever()传参）；AutoGen在错误处理上静默失败（handle_message未捕获异常）。这1天节省了2周无效开发。

4.6 步骤6：压力测试你的“最差路径”

找一条最复杂的执行路径，模拟100次请求：

• 如“用户上传PDF→OCR识别→向量检索→LLM总结→调用邮件API→生成下载链接”；
• 用locust压测，观察内存泄漏、连接池耗尽、超时堆积。

LangChain的SQLDatabaseToolkit在高并发下，SQLAlchemy连接池会因未关闭session而耗尽；LlamaIndex的VectorStoreIndex在冷启动后首次查询慢，但后续稳定；AutoGen的GroupChat在100并发下，send方法会因asyncio.Lock争用导致延迟飙升。

4.7 步骤7：制定你的框架演进路线图

选型不是终点，而是起点。我们约定：

• 短期（0-3月）：用选定框架跑通MVP，所有自定义代码加# FRAMEWORK_LOCK注释，禁止随意修改框架层；
• 中期（3-6月）：当业务需求超出框架能力（如需支持WebSocket实时流），开始抽离框架依赖，将核心逻辑（状态管理、工具调度）沉淀为内部SDK；
• 长期（6+月）：评估是否自研轻量框架。我们已在某项目中启动MiniAgent计划，目标是比LangChain v0.2启动快5倍、内存占用少70%、API更简洁。

5. 真实项目复盘：从选型失误到架构涅槃

5.1 失败案例：某高校科研助手项目的“LangChain陷阱”

项目目标：帮研究生自动整理文献、生成综述草稿、推荐相关论文。初期团队兴奋地选了LangChain，理由是“生态全，有PubMedLoader和ArxivLoader”。结果上线后崩溃：

• 问题1：状态丢失。用户A上传文献后，ConversationBufferMemory把所有对话存在内存，重启服务后历史全丢；
• 问题2：工具冲突。PubMedLoader和ArxivLoader都用requests，但ArxivLoader的timeout=30覆盖了PubMedLoader的timeout=120，导致PubMed查询频繁超时；
• 问题3：可观测性缺失。用户反馈“生成的综述里有虚构的参考文献”，但日志只显示Chain.run() finished，无法定位是PubMedLoader返回了错误数据，还是LLM幻觉。

修复过程：

1. 第1周：换RedisChatMessageHistory，解决状态丢失；
2. 第2周：为每个Loader创建独立Session，隔离timeout配置；
3. 第3周：重写CallbackHandler，记录每步的input/output/prompt，发现PubMedLoader返回的XML解析有bug，手动修复；
4. 第4周：上线后，发现Redis内存暴涨，查出ConversationBufferMemory未设置TTL，所有历史永久保存。

教训：LangChain的“全”是双刃剑。当你需要的只是“加载+检索+生成”，它的工具生态反而成了累赘。后来我们用LlamaIndex重写，代码量减少60%，且VectorStoreIndex的doc_id机制天然支持文献去重。

5.2 成功案例：某公司内部知识中枢的“LlamaIndex+LangChain混合架构”

需求：员工问“如何报销差旅”，Agent需查制度文档→定位报销流程图→提取关键节点→生成步骤话术。我们没选单一框架，而是分层设计：

• 数据层：LlamaIndexVectorStoreIndex，用UnstructuredPDFReader处理制度PDF，MetadataMode.ALL保留章节信息；
• 逻辑层：LangChain v0.2Runnable，写PolicyRetrieverRunnable（根据问题提取关键词，调用LlamaIndex检索）和StepGeneratorRunnable（用dspy.Predict生成步骤，因需可验证）；
• 集成层：自定义SlackTool，封装Slack API调用，返回结构化JSON。

效果：

• 检索准确率从68%升至92%（LlamaIndex的元数据过滤功不可没）；
• 生成步骤话术的幻觉率从23%降至4%（DSPy的Compile优化了prompt）；
• 整个系统启动时间从42秒（LangChain全量加载）降至8秒（按需加载LlamaIndex索引）。

关键决策：不迷信“一个框架打天下”。LlamaIndex做它最擅长的RAG，LangChain做它最稳定的执行流，DSPy做它最严谨的生成，各司其职。

5.3 进化案例：从AutoGen到自研协作框架

某跨部门项目需MarketingAgent、SalesAgent、SupportAgent协作完成客户跟进。初期用AutoGen，GroupChatManager能跑通，但问题频发：

• MarketingAgent的system_prompt太长（2000 token），导致GroupChatManager的select_speaker逻辑失效；
• SalesAgent调用CRM API失败时，GroupChatManager不重试，直接结束对话；
• 所有Agent共享一个llm_config，无法为不同Agent设置不同temperature。

进化路径：

1. 第1阶段：用AutoGenGroupChat+ 自定义select_speaker函数，解决speaker选择问题；
2. 第2阶段：为每个Agent创建独立llm_config，用config_list管理；
3. 第3阶段：重写GroupChatManager，加入retry_policy参数和fallback_agent机制；
4. 第4阶段：抽离核心逻辑，形成MiniCollab框架，API精简为：

   collab = MiniCollab(agents=[marketing, sales, support]) result = collab.run( task="跟进客户ABC", retry_policy={"max_attempts": 3, "backoff": 2}, fallback_agent=support )

现在MiniCollab已支撑5个项目，代码量仅为AutoGen的1/5，但稳定性提升300%。这印证了我的观点：框架选型的终极目标，不是找到完美的工具，而是找到最短路径，让你能快速抵达自研的临界点。

6. 常见问题速查表与独家避坑技巧

6.1 “为什么我的LangChain Agent总是超时？”

现象	根本原因	解决方案	实测效果
AgentExecutor卡在plan步骤	LLM返回的action_input含非法字符（如换行符），json.loads()失败	在AgentExecutor前加preprocess_action_input函数，strip()并replace("\n", " ")	超时率从42%降至0%
SQLDatabaseToolkit查询慢	table_info未缓存，每次执行都SELECT * FROM information_schema	用SQLDatabase.from_uri()时传入view_support=True，并手动cache_table_info	查询耗时从3.2s降至0.4s
RedisChatMessageHistory内存暴涨	ttl未设置，默认永不过期	初始化时指定ttl=3600（1小时）	Redis内存占用下降87%

6.2 “LlamaIndex检索结果不相关，怎么调？”

LlamaIndex的检索质量不取决于向量模型，而在于分块策略和查询重写：

• 分块策略：SentenceSplitter对技术文档效果差，改用CodeSplitter（按函数分割）或MarkdownNodeParser（按标题分割）；
• 查询重写：HybridRetriever的alpha参数（0-1）控制BM25与向量检索权重，技术文档设alpha=0.3，法律文书设alpha=0.7；
• 元数据过滤：filter={"source":"policy_v2.pdf"}比单纯向量检索准3倍，但需确保Document.metadata正确填充。

我们曾用SentenceSplitter处理API文档，结果“POST /users”和“201 Created”被分到不同chunk，检索“创建用户”时无法关联。改用MarkdownNodeParser后，整个API端点成为1个node，准确率翻倍。

6.3 “AutoGen GroupChat不按预期发言，怎么办？”

AutoGen的发言权逻辑是：GroupChatManager遍历groupchat.agents，对每个Agent调用generate_reply()，第一个返回非空字符串的Agent发言。因此：

• 陷阱1：generate_reply()返回空字符串""，但你的逻辑期望它返回None，导致发言权被跳过；
• 陷阱2：system_prompt含<|eot_id|>等特殊token，LLM输出被截断，返回空字符串；
• 解决方案：重写generate_reply()，强制返回{"role":"assistant","content":"..."}格式，并在GroupChatManager初始化时设max_round=10防死循环。

6.4 “DSPy Compile太慢，有加速技巧吗？”

• 技巧1：用dspy.evaluate先评估基线模型，若F1<0.5，直接放弃Compile，说明数据质量或Signature设计有问题；
• 技巧2：Compile时设num_threads=4，但num_threads>cpu_count会因上下文切换反而变慢；
• 技巧3：对长文本任务，用dspy.teleprompt.MIPRO替代BootstrapFewShot，收敛更快。

我们某项目用BootstrapFewShot编译需8小时，改用MIPRO后降至1.2小时，且最终F1更高。

6.5 “如何安全地在生产环境用Flowise？”

Flowise不是生产框架，但可作为开发加速器：

• 步骤1：在Flowise UI中搭建流程，导出为flow.json；
• 步骤2：用flowise-to-langchain脚本（我们开源的）将flow.json转为LangChain v0.2代码；
• 步骤3：在生成的代码中，替换所有`console