企业官网建设流程全解析

先说结论：这两年只要聊到AI应用，十个技术方案里八个在谈Agent。但大多数人做的Agent其实是个"单机版"——一个能调用工具、能回答问题的对话机器人，离真正的"协作系统"还差得远。我最近用LocalClaw重新搭了一套多Agent协作系统，跑了大概两周，把过去攒下的单个Agent脚本全部打散重组，效果比预期的好不少。这篇文章就把完整的踩坑过程、架构思路和可复现代码一次性放出来。

这套东西适合谁？如果你手上已经有几个能跑的Agent脚本，但发现单Agent做不了复杂任务——比如既要做信息检索、又要分析归纳、还要生成报告、最后还得质检校对，一个Agent在上下文里来回切换角色，效果和稳定性都撑不住，那你就需要一套多Agent协作系统。LocalClaw这个框架主打本地优先、轻量可编排，不需要背一整套重型依赖，适合在普通开发机或小规模服务器上跑。下面我会从架构设计到完整代码，一步步说清楚。

1. 先搞清楚：多Agent系统到底解决什么问题、LocalClaw是什么

1.1 为什么不能只靠一个"超级Agent"

先说个很典型的场景。我之前做过一个行业情报总结的自动化脚本，最初方案很简单：一个Agent，给它一段提示词，让它扮演研究员、分析师、写手、校对员四个角色，读完资料直接输出周报。听起来很省事，实际跑起来一堆问题。

第一个问题是上下文污染。单个Agent处理长任务，检索来的原始材料、中间分析、半成品草稿全部堆在同一上下文里，token占用率居高不下，生成质量随着对话轮数增加肉眼可见地下滑。第二个问题是角色切换生硬。让它"先分析再写"还好，但让它"先分析、再批判自己的分析、再重新分析"，很多时候它只是换了一套话术重复前面内容，并没有真正完成多轮反思。第三个问题是失败不可定位。最终报告出了问题，你很难判断是检索环节的问题还是分析环节的问题，整条链路黑盒化。

多Agent系统的核心思路不是把任务拆给多个提示词，而是把角色、职责、上下文边界都物理隔离到不同的Agent实例里。每个Agent只维护自己那一小块上下文，任务通过消息在Agent之间流转。这样单个Agent的上下文压力大幅下降，中间环节可观测、可替换、可单独测试，某一步挂了不会拖垮整个链路。

1.2 LocalClaw的定位：本地优先的轻量编排框架

我选择LocalClaw而不是那些大而全的编排框架，原因比较实际。

这套框架的设计目标很明确：本地优先、去中心化编排、轻依赖。它不强制你使用某个特定的模型厂商，也不要求必须部署独立的Agent服务端。所有Agent定义在Python进程内，通过内置消息总线通信，数据默认不出内网环境，适合对数据出境敏感的业务场景。

LocalClaw的几个关键特性值得说一下：

• 进程内编排：Agent之间通过内部消息队列通信，不需要起一堆独立微服务，部署成本直线下降。等单机性能不够了，再平滑迁移到持久化队列方案（后面会讲）。
• 插件式模型后端：底层统一走OpenAI兼容的接口协议，本地推理服务和各类线上API服务都能接，切换模型只改一行配置。
• 内置协作策略：Chain、Router、Parallel、Debate四种模式开箱即用，不用自己实现Agent间通信协议。
• 工作区机制：每个任务分配独立工作目录，Agent产出的中间文件、结构化数据都落到工作区，方便审计和断点续跑。

实际体验下来，LocalClaw的定位有点像"Agent版的Flask"——不搞全家桶，把编排基础能力做扎实，具体业务逻辑全部留给你自己写。这种风格对我来说省心很多：我不需要追着框架升级走，核心代码基本不受框架版本迭代影响。

1.3 适合谁来学、能解决什么场景

从适用人群来说，这套方案适合三类人：一是已经在用单个Agent做自动化任务、但觉得效果不稳定的开发者；二是需要在内部环境搭建AI工作流的业务团队，LocalClaw的数据本地化特性比较友好；三是做AI应用课程或毕设项目的学生，用它实现多Agent协作Demo可以省掉大量底层通信代码，把精力集中在业务逻辑本身。

从场景覆盖来看，我目前用这套系统跑了三个方向：行业资讯汇总与周报生成、客服工单自动分类与分流、技术方案的多角色评审。这三个场景刚好涵盖了多Agent系统最常见的三种形态——流水线式协作、路由式分发、评审式对抗。后面第4章我会把第一个场景的完整代码展开讲。

2. 技术选型对比与整体架构设计思路

2.1 主流多Agent编排方案横向对比

在敲定LocalClaw之前，我把市面上主流的几类方案都过了一遍。这里不点名批评，只谈通用经验。

第一类是"全流程框架型"，大而全，内置记忆、工具调用、人机交互面板，开箱即用，但随之而来的是概念众多、抽象层次厚。你要深入定制某个环节，得先啃完整个框架源码，对于中小型项目来说学习成本偏高。

第二类是"微软式编排型"，核心思路是用代码显式编排多个Agent之间的协作，灵活度高、可控性强，但一切都要自己写，适合有研发资源、需要深度定制协作逻辑的团队。

第三类是"流程引擎型"，与其说是Agent框架，不如说是把大模型调用节点编排进一个工作流引擎，带可视化的画布拖拽界面。这类方案非常适合业务人员上手，但流程一旦复杂，节点之间传递数据的配置会非常繁琐。

LocalClaw在这三类里属于第二类的轻量化改良版：保留了代码编排的灵活性和可控性，同时把一些高频通用能力（消息路由、协作策略、工作区）内置掉了。对比下来它不追求"什么都能做"，而是把"多Agent任务协作"这件事做扎实。

2.2 这套系统的整体架构拆解

我搭的多Agent协作系统，整体分四层：

• 接入层：接收外部任务请求，比如一段待分析的文本、一条工单记录、一个调研主题。负责把非结构化输入转为结构化任务对象。
• 编排层：系统的核心大脑，由Orchestrator（编排器）实例承担。负责解读任务、拆解子目标、按协作策略把子任务分发给对应Agent，并汇总结果、处理失败重试。
• 执行层：若干Worker Agent，每个Agent干一件特定的事，比如检索、分析、写作、审校。Agent之间不直接互相调用，全部通过编排器转发消息，保证流程可控和可观测性。
• 存储层：任务工作区（本地目录）+ 共享记忆存储 + 结果归档。用于Agent之间交换中间产物，也用于断点续跑。

这个架构最核心的一条原则是Agent之间禁止私聊。所有消息都经过编排器，虽然牺牲了一点点效率，但换来了极强的可观测性——任何一个环节出问题，我能立即在日志里看到任务流转到哪个Agent、输入输出是什么。调试多Agent系统时，这一点比什么都重要。

2.3 协作模式选型：Chain、Router、Parallel与Debate

LocalClaw内置四种协作策略，实际项目里怎么选是有套路的。

**Chain（流水线）**是最直观的模式，适合有严格先后顺序的任务：A的输出作为B的输入，B的输出再作为C的输入。情报周报场景就是典型Chain：检索→分析→写作→审校，每步依赖上一步结果。

**Router（路由）**适合做分类和派单。入口Agent先做意图识别，然后把任务分发给下游不同Agent。比如客服工单场景，先判断是物流问题、质量问题还是退换货问题，再转给对应处理Agent。

**Parallel（并行）**适合可拆分的独立子任务。比如做竞品分析，需要让多个Agent分别调研不同竞品，最后汇总。并行模式能显著降低总耗时，但要小心下游汇总Agent的上下文压力。

**Debate（评审）**是我个人最常用也最喜欢的模式。让两个或多个Agent扮演不同立场，对同一份材料进行多轮质询和反驳。这种模式能明显减少幻觉和倾向性错误，代价是token消耗翻倍、运行时间变长。适合用在报告输出前的质检环节。

这几种模式可以混用。实际系统里，我一个Orchestrator内部可以设计成先Router判断任务类型，再Chain走生产流程，最后Debate做质检，并不冲突。选型的关键不是越复杂越好，而是刚好匹配任务的依赖关系。

3. 环境准备与基础配置

3.1 运行环境与依赖安装

运行环境建议Python 3.10以上，操作系统不限，Windows、macOS、Linux都行。LocalClaw的安装可以直接通过pip完成，依赖较少，不会拖一堆重型库进来。

# 建议先建独立虚拟环境 python -m venv .venv source .venv/bin/activate # 安装LocalClaw框架 pip install localclaw # 如果需要对接Redis做持久化队列（可选，后面会讲） pip install redis

装完验证一下版本，确保框架正常导入：

python -c "import localclaw; print(localclaw.__version__)"

如果你的机器上已经跑了一些单个Agent脚本，我建议把它们整理成独立的工具函数或类，方便后续统一注入到Worker Agent里。LocalClaw里的Agent本质上是一个增强版LLM调用封装，你可以给它挂工具、设系统提示词、配模型参数。

3.2 模型服务接入：本地推理与线上API两条路线

LocalClaw对模型后端没有强绑定，底层兼容OpenAI接口协议。这意味着两条路线都能接：

路线一：本地推理服务。在自己机器或内网服务器上跑一个7B/14B量级的开源对话模型推理服务，然后让LocalClaw指向本地的接口地址。优势是数据不出内网环境、无额外API费用、离线可用；劣势是小型模型的推理质量比顶尖线上模型还是有差距，复杂推理任务可能吃力。我的实践建议是，本地模型适合做检索、分类、抽取这类"体力活"Agent，不适合做写作、评审这类"脑力活"Agent。

路线二：合规的线上API服务。通过与OpenAI协议兼容的各种合法API服务商对接，配置好密钥和接口地址就能用。优势是模型能力强、不用担心推理质量；劣势是每轮调用都要消耗额度，多Agent协作会放大token消耗量，成本需要提前估算。

我的实际做法是混用：体力型功能走本地模型省钱，脑力型功能走线上API保质量。这个思路帮我把整套系统每月的模型成本控制在一个比较合理的水平。

3.3 第一个最小Demo：让两个Agent跑通对话

在写复杂系统之前，我先用一个最小Demo验证框架的编排流程是否通顺。

from localclaw import Agent, Orchestrator, ChainStrategy # 定义第一个Agent researcher = Agent( name="研究员", system_prompt="你是一名严谨的信息收集员。用户给你主题，你输出相关事实清单，每行一条。", llm_config={ "base_url": "http://127.0.0.1:11434/v1", # 本地推理服务地址 "model": "local-model-7b", # 改为你的模型名 "temperature": 0.2, }, ) # 定义第二个Agent writer = Agent( name="写手", system_prompt="你是一名简洁明了的文案写手。把输入的事实清单扩写成一段通顺的介绍文字，不超过200字。", llm_config={ "base_url": "https://api.example.com/v1", # 线上API服务地址 "model": "cloud-model", # 改为你的模型名 "temperature": 0.7, "api_key": "your-api-key", }, ) # 用Chain策略编排：研究员先干活，写手再干活 strategy = ChainStrategy(steps=[researcher, writer]) orchestrator = Orchestrator(strategy=strategy) # 执行任务 result = orchestrator.run("介绍一下LocalClaw框架") print(result.final_answer)

这段代码跑通，说明你的Agent定义、模型后端、编排链路都没问题。第一次跑经常遇到两类错误：一类是本地推理服务的接口地址或模型名不匹配，报连接错误；另一类是线上API服务需要额外配置一些请求头参数，LocalClaw的Agent配置里要按文档加上。这些细节每套服务略有差异，对照你使用的服务商文档调一下就行。

4. 完整代码实现：舆情周报自动生成系统

4.1 场景定义与任务分解

我拿实践中跑得最久的"行业舆情周报自动生成系统"当完整案例。需求背景是：某团队每周需要汇总行业资讯，提炼关键动态，输出一份结构化周报。人工做法需要两三个小时，自动化后十几分钟跑完，而且口径一致性更好。

任务分解为四个子任务：

1. 采集：根据配置的主题词列表，从资讯接口拉取本周相关条目，清洗去重。
2. 提炼：逐条阅读资讯，提取"事件主体、关键数据、影响范围、相关方"四个维度的结构化要点。
3. 成稿：基于提炼出的要点，按固定模板生成周报正文。
4. 质检：检查周报是否有事实性错误、遗漏重点、表述含糊，输出修订意见并自动修订。

这四个子任务依赖关系明确：采集→提炼→成稿→质检，是典型Chain模式。采集可以并行拉取多个渠道，但后续环节必须等前面完成。每个环节一个Worker Agent，各司其职。

4.2 定义Worker Agent

先看Agent定义，一共四个Worker和一个编排器，全部代码加在一起不到200行。

from localclaw import Agent, Orchestrator, ChainStrategy from localclaw.tools import HttpFetchTool, DedupTool # 采集Agent：负责拉取资讯并清洗 collector = Agent( name="采集员", system_prompt=( "你是资讯采集助手。你会收到一个主题列表，请调用资讯检索工具获取最近7天的相关文章。" "对返回结果做去重和基础过滤，过滤掉广告、纯转发、少于80字的碎片信息。" "最终输出一个干净的资讯清单，按发布时间倒序排列，每条包含标题、来源、时间、正文前200字摘要。" ), llm_config={ "base_url": "http://127.0.0.1:11434/v1", "model": "local-model-7b", "temperature": 0.1, }, tools=[ HttpFetchTool(max_items=50), DedupTool(key_field="title", threshold=0.85), ], ) # 提炼Agent：输出结构化事件要点 analyst = Agent( name="分析师", system_prompt=( "你是行业分析师。你会收到一篇资讯的标题、来源、时间和正文摘要。" "请提炼该事件的要点，按如下JSON格式输出：" '{"event": "事件概述（一句话）", "subject": "主体", "impact": "影响分析", "stakeholders": ["相关方"]}' "只输出JSON，不要输出额外说明。" ), llm_config={ "base_url": "http://127.0.0.1:11434/v1", "model": "local-model-14b", "temperature": 0.1, "response_format": {"type": "json_object"}, # 强制JSON输出 }, ) # 写稿Agent：汇总生成周报 writer = Agent( name="写手", system_prompt=( "你是资深行业周报撰稿人。你会收到本周所有事件的JSON要点列表。" "请按以下结构生成周报：一、本周行业概述（150字）；二、关键事件追踪（每事件3-5行，" "按影响程度排序）；三、趋势研判（3条）。" "语言专业但不堆砌术语，多用数据说话。直接输出正文，不需要Markdown格式以外的装饰。" ), llm_config={ "base_url": "https://api.example.com/v1", "model": "cloud-model", "temperature": 0.5, }, ) # 质检Agent：审校并修订 reviewer = Agent( name="审校员", system_prompt=( "你是严格的审校编辑。你会收到一版周报草稿。请从三个维度检查：" "1. 是否存在超出事实范围的主观臆断；2. 关键数据是否缺失或含糊；3. 段落结构是否清晰。" "输出修改意见列表，然后直接输出修订后的完整周报。如果不需要修改，直接输出原文。" ), llm_config={ "base_url": "https://api.example.com/v1", "model": "cloud-model", "temperature": 0.3, }, )

几个配置细节值得说明：

• 采集员的temperature设到0.1，因为采集属于事实性任务，创造性越低越可靠。
• 分析师用了本地14B模型，比7B模型的结构化抽取稳定性明显更好，14B在普通显卡上跑也够用。
• 写稿和审校用云端大模型，靠模型能力保证生成质量和批判性检查的有效性。
• 审校员的提示词末尾要求"直接输出修订后的完整周报"，否则它会只输出意见不输出成品，这个细节是实践里踩出来的坑。

4.3 编排器与协作流程

Agent定义好之后，编排器不需要写复杂逻辑。LocalClaw的ChainStrategy会按steps列表顺序依次执行，前一个Agent的输出自动作为后一个Agent的输入。

# 组装编排器 chain_strategy = ChainStrategy(steps=[collector, analyst, writer, reviewer]) orchestrator = Orchestrator( strategy=chain_strategy, workspace_dir="./runs/weekly_report", max_retries=2, )

这里的核心亮点在批量处理逻辑。ChainStrategy默认是把整段文本透传，但我们的场景里，采集员输出的是一堆资讯清单，分析师要把每条资讯逐条提炼成JSON要点。如果直接把整个清单塞给分析师，上下文压力大、JSON容易大面积解析失败。

解决办法是自己实现一个中间步骤：把采集员的输出按条目拆分，逐条调用分析师模型，再把所有JSON要点汇总成一个列表，交给写稿Agent。LocalClaw允许在ChainStrategy中插入自定义处理节点：

from localclaw import PipelineStep # 自定义批量提炼节点：遍历清单，逐条调用analyst class BatchAnalyzeStep(PipelineStep): def execute(self, context): items = context.get_from_shared("collector_output").split("\n---\n") results = [] for item in items: if not item.strip(): continue single_result = analyst.run(item.strip()).final_answer results.append(single_result) context.set_to_shared("analysis_results", results) return "\n".join(results) batch_step = BatchAnalyzeStep(name="批量提炼") # 最终编排：采集 -> 批量提炼 -> 写稿 -> 审校 orchestrator = Orchestrator( strategy=ChainStrategy(steps=[collector, batch_step, writer, reviewer]), workspace_dir="./runs/weekly_report", )

批量处理之后，每个资讯条目都得到独立的模型推理上下文，互不干扰，JSON输出成功率大幅提升。如果仍然有解析失败的条目，我会在BatchAnalyzeStep里加一个fallback逻辑：解析失败就重试一次，仍然失败则跳过并记录日志，不影响整体流程。

4.4 主程序与运行结果

主程序负责接收任务配置、调用编排器、归档结果。

# main.py import json, time from datetime import datetime, timedelta from localclaw import Orchestrator, ChainStrategy, PipelineStep # 上面定义的Agent和批量节点省略，直接组合 def build_weekly_report(topics: list[str]) -> dict: orchestrator = Orchestrator( strategy=ChainStrategy(steps=[collector, batch_step, writer, reviewer]), workspace_dir=f"./runs/weekly_report_{datetime.now().strftime('%Y%m%d')}", ) start_time = time.time() task_payload = { "topics": topics, "time_range": { "start": (datetime.now() - timedelta(days=7)).strftime("%Y-%m-%d"), "end": datetime.now().strftime("%Y-%m-%d"), }, } result = orchestrator.run(task_payload) # 拉取工作区中间产物，便于审计 collector_raw = result.context.get_from_shared("collector_output", default="") analysis_json = result.context.get_from_shared("analysis_results", default="[]") return { "weekly_report": result.final_answer, "raw_items_count": len(collector_raw.split("\n---\n")), "analysis_count": len(json.loads(analysis_json)), "elapsed_seconds": round(time.time() - start_time, 2), } if __name__ == "__main__": topics = ["人工智能", "低代码平台", "开源社区"] output = build_weekly_report(topics) with open("./output/weekly_report.md", "w", encoding="utf-8") as f: f.write(output["weekly_report"]) print(f"生成完成，原始条目 {output['raw_items_count']} 条，" f"分析要点 {output['analysis_count']} 条，耗时 {output['elapsed_seconds']}秒")

跑一趟完整流程，从采集到现在，耗时大约十到十五分钟，取决于采集到的资讯条数。如果采集到40条资讯，批量提炼环节会调用40次本地模型，单次要两三秒，这个环节是大头。写稿和审校各调用一次云端模型，大概十秒左右。

输出周报的格式大致长这样：

一、本周行业概述：本周人工智能领域关注焦点从模型训练转向应用落地，多家机构发布轻量化部署方案。低代码平台进入企业级市场加速期。开源社区生态活跃度持续上升。

二、关键事件追踪：

1. 事件一：某开源社区发布新版本框架，支持多Agent协作。影响：降低开发者构建复杂AI应用的门槛。
2. 事件二：低代码平台陆续开放AI生成接口。影响：非技术人员可快速搭建业务原型。
3. 事件三：某研究团队推出轻量化推理方案。影响：中小团队部署大模型应用的成本进一步下降。

三、趋势研判：1. 多Agent系统将在半年内成为AI应用开发的主流范式之一。2. 数据本地化的Agent方案在企业场景会加速渗透。3. Agent的工具调用能力是下一阶段竞争重点。

整个系统跑通后有两点体验很重要：一是工作区目录里能清楚看到每个环节的中间产物，出了问题能精准定位；二是每个Agent职责单一，单独替换某个Agent的模型或提示词不影响其他环节。这两点带来的维护便利性是单Agent方案完全没法比的。

5. 协作机制深度解析：消息路由、记忆管理与上下文控制

5.1 Agent之间是怎么通信的

多Agent系统最容易翻车的地方是Agent之间的通信协议。LocalClaw走的是消息总线模式：所有Agent不直接持有其他Agent的引用，只和编排器交换消息。每个消息带类型、来源、目标槽位、负载数据和时间戳。

# 消息结构示意 { "type": "task_result", "from": "采集员", "to": "批量提炼节点", "payload": {"items": ["..."]}, "ts": "2025-01-15T10:30:00Z" }

这个设计的两个关键优势在于：第一，链路可观测。任何一步出问题，查看消息流转日志就能确定责任Agent。第二，局部可替换。某个Agent升级、换模型、下线，都不需要改其他Agent的代码，只要编排器里的路由映射更新就行。

如果你的项目需要Agent之间互相协商（类似Debate模式中两个Agent来回辩论），消息总线也能支持双向通信，但需要设置最大轮数限制，否则两个Agent可能陷入无限互相反驳的循环。这个限制我在第6章会详细讲。

5.2 共享记忆与工作区设计

多Agent系统里"记忆"是个容易被误解的概念。它不应该是Agent提示词里的那一句"记住之前的对话"，而应该是一种结构化的外部存储，让各个Agent能够读写共享的工作上下文。

我在系统里做了两级存储：

• 任务工作区（一级）：每次运行任务时创建独立目录，存放采集结果、结构化JSON、草稿、最终报告。文件命名规范按"序号_环节名_内容描述"来，方便回溯。
• 共享记忆存储（二级）：跨任务长期存储，比如行业词典、历史报告归档、常用结论。用于让新任务能参考过去的知识积累。

# 工作区目录结构示例 runs/weekly_report_20250115/ ├── 01_raw/ │ ├── collector_output.json │ └── fetch_log.txt ├── 02_analysis/ │ ├── analysis_results.json │ └── failed_items.log ├── 03_draft/ │ └── report_draft.md ├── 04_review/ │ └── report_final.md └── task_meta.json

这个目录结构帮我解决了一个实际问题：批量提炼环节偶尔有单条数据解析失败，有了失败日志，我能快速找到失败原因而不需要重跑整个流程。工作区设计看起来是个不起眼的细节，但在多Agent系统里，它的价值等同于是系统的"黑匣子"，严重事故时能救命。

5.3 Token成本控制：摘要压缩与上下文裁剪

多Agent系统的token消耗增长很快，尤其是Parallel和Debate模式。我跑了一个月之后，总结出三个成本控制的有效手段。

第一个手段是局部摘要替代全局透传。Chain模式下，下游Agent往往只需要上游的结构化产物，不需要原始材料。比如写稿Agent只需要分析结果的JSON要点，不需要阅读40篇原始资讯全文。这一步能省掉80%以上的token。

第二个手段是分段处理再汇总。面对大批量数据，不要试图让一个Agent一次读完。按批次喂入，每批次产出一个摘要，最后再合并摘要。代价是总耗时会增加，但token消耗和上下文压力都大幅缓解。

第三个手段是模型分级。简单任务用本地小模型、复杂任务用云端大模型，而不是所有Agent都用最强的模型。有些高频小任务甚至可以用更轻量的模型，成本差异会非常明显。

下面是一个成本对比的实测数据，处理40条资讯，不同策略的用量的差别非常大：

从表格可以看出，结构化提取后透传的性价比最理想。这也是为什么我在第4章的BatchAnalyzeStep里不惜多写一点代码，把采集结果逐条转为JSON要点再往下传。

6. 常见问题与排查技巧实录

6.1 Agent陷入无限循环怎么办

Debate模式最常踩的坑就是Agent之间来回反驳，停不下来。两个Agent各有立场，互相找茬，理论上可以进行到天荒地老。

解决方案分两层。第一层是硬性轮数限制：编排器限制任务最大执行轮数，到点强制终止。LocalClaw配置里可以直接设置：

orchestrator = Orchestrator( strategy=debate_strategy, max_rounds=4, # 最多4轮辩论 termination_keywords=["同意", "接受", "采纳", "无异议"], # 提前终止条件 )

第二层是协商收敛信号：在辩论Agent的系统提示词里明确要求，当对方论点确实成立时，要明确表达"同意"或"接受"，不要为了辩论而辩论。这个提示词约束在实践中比硬性轮数限制更管用，因为它从源头减少了无效争论。

排查辩论循环问题时，日志里的消息流转时间戳是最好的排查线索。把每轮消息的时间戳拉出来看一眼，能快速判断是两个Agent在正常深度交流，还是陷入了同义反复的循环。

6.2 上下文越拉越长、效果越来越差

这是所有多Agent系统的通病。任务链路越长，中间产物越积越多，下游Agent一次性接收到的内容量越大，模型在长上下文中的检索和遵循能力会下降，反而容易遗漏关键信息。

我排查这类问题的流程通常是三步：先查看工作区各个中间产物体积，看哪一个环节产出膨胀得最厉害；然后检查编排器的策略配置，看是否在向某个Agent透传太多无关内容；最后针对膨胀环节做结构化压缩或分批处理。

举一个实际案例。某次跑周报系统，写稿Agent突然开始忽略分析师给的要点，自己编了一些行业趋势。查工作区发现，分析师输出的JSON要点有八十多条，写稿Agent收到的上下文里有大量重复和低质量条目。解决方案是在BatchAnalyzeStep里加了一层预处理：按事件影响程度排序，只保留权重最高的前30条给写稿Agent。问题立刻解决，报告质量也提升了。

6.3 任务分配不均与单点瓶颈

多Agent系统的瓶颈经常不在模型推理，而在某个特定Agent的输入负载。比如Router模式的入口Agent，所有任务都要经过它做分类，它一旦慢，全链路跟着慢。

我的经验是优先做Agent吞吐量监控：给每个Agent加耗时统计，连续跑几天后看哪个Agent的平均耗时最长、队列积压最多，再针对性优化。优化手段有两个方向：一是横向扩容，把这个Agent的负载拆给多个同质实例，比如三个采集员同时干活，每人处理三分之一；二是纵向瘦身，简化这个Agent的提示词或改用更快的模型。

领过几次教训之后，我再也不把所有处理逻辑塞进一个Agent里了。每个Agent只做一件事，做到极致，需要复杂逻辑时多做几个环节，也不要在单个环节里堆砌职责。

6.4 并发与队列选型：从内存队列到持久化队列

LocalClaw默认的进程内消息队列足够支持几十个Agent的简单场景，但一旦任务量上来，进程随时可能重启，内存队列里的任务就全丢了。

我的建议是分阶段选型。任务量每天几十条、可容忍少量失败时，默认内存队列完全够用。任务量每天上千条、需要保证不丢任务时，就要上持久化队列，比如用Redis做消息队列。切换成本也不高，改一行配置：

# 使用Redis持久化队列 from localclaw import RedisQueueConfig queue_config = RedisQueueConfig( host="127.0.0.1", port=6379, db=1, queue_name="multiagent-tasks", ) orchestrator = Orchestrator( strategy=chain_strategy, queue=queue_config, )

用持久化队列之后，编排器进程重启，任务可以从上次确认位置继续消费，不会丢。需要注意的一点是，使用外部队列后，任务负载必须可序列化（JSON/字符串），不能塞Python对象，否则反序列化时会报错。

7. 进阶扩展方向与个人实操体会

7.1 给Agent加工具：函数调用与外部系统打通

Agent不只能聊天，把工具挂上去之后才能解决实际问题。LocalClaw的工具机制比较简单清晰，Agent可以通过函数调用获取外部系统能力。

from localclaw.tools import FunctionTool def query_internal_database(keyword: str, limit: int = 10): """查询内部业务数据库""" # 实际查询逻辑省略 return [{"id": 1, "content": "示例结果"}] tool = FunctionTool( name="query_internal_database", description="查询内部业务数据库，传入关键词返回相关记录", func=query_internal_database, parameters={ "type": "object", "properties": { "keyword": {"type": "string", "description": "查询关键词"}, "limit": {"type": "integer", "description": "返回条数上限"} }, "required": ["keyword"] } ) analyst = Agent( name="分析师", system_prompt="...", llm_config={...}, tools=[tool], )

挂工具的Agent会自己判断什么时候该调用工具。工具描述信息写得越详细，Agent的判断越准确。尤其要注意parameters参数的描述，模型靠这些描述生成调用参数，描述模糊会直接导致调用失败。

7.2 人在回路（Human-in-the-Loop）设计

多Agent系统跑得再顺，有些关键节点还是需要人工确认。比如周报最终发布前、涉及大额资金操作前、面向外部客户的消息发送前，全部放开自动执行风险太大。

我在LocalClaw的编排器里嵌了人工审批节点：

from localclaw import HumanApprovalStep approval_step = HumanApprovalStep( name="发布审批", message="周报已生成，请确认是否发布。", timeout_seconds=3600, # 1小时没有确认则挂起 on_approve="publish", # 通过后进入发布节点 on_reject="revise", # 驳回后进入修订节点 ) orchestrator = Orchestrator( strategy=ChainStrategy(steps=[collector, batch_step, writer, reviewer, approval_step]), )

这个设计等于在自动化流程里保留了人工兜底。Agent流程负责提效，卡住风险环节的是人来把关。上线跑大流量任务之前，建议先把人工审批节点的超时策略想清楚：超时挂起还是超时默认拒绝？我倾向于默认拒绝，安全第一。

7.3 我踩过几次坑之后的几点心得

两周实测下来，有几条经验想特别分享给大家。

第一，多Agent系统的调试成本是单Agent的数倍，一定要从第一天就做好可观测性。消息日志、中间产物、耗时统计这三样是标配，缺一不可。很多问题在日志完备的情况下，定位只花五分钟；日志缺失的时候，排查一整天都找不到方向。

第二，不要把Agent之间的协作想象得太玄乎。本质上它还是一个数据加工管道，只是每个加工节点由大模型驱动。用工程思维去设计环节、定义接口、控制数据流，比追求复杂的"自主协商"机制靠谱得多。想让Agent协作，先把JSON格式定义清楚。

第三，模型不是越强越好，而是越匹配越好。全用最强模型，成本爆炸；全用小模型，效果撑不住。分级使用最灵活，把任务按性质分流到不同规模模型，既保质量又控制成本。

第四，开始搭建之前，先画任务依赖关系图，再画Agent分配图。很多项目失败不是因为框架不好用，而是任务拆解和Agent划分没想清楚。我第一版系统就是把六个职责塞进两个Agent里，效果还比不上现在的四Agent方案。职责边界清晰，系统表现反而更好。

LocalClaw这套框架帮我省掉了大量底层通信代码，让我能把时间花在真正重要的"工程问题"上。如果你正在考虑做多Agent系统，而且不想背着老重的框架起步，建议直接上手这套轻量方案。先把最小链路跑通，再逐步加Agent、加工具、加人工审批，边跑边调，很快就能搭出一套稳定可控的多Agent协作系统。