企业官网建设流程全解析

看到agency-agents这个名字，大部分人的第一反应是“这又是一个套壳的 AI 应用 Demo”。实际动过手之后我才发现，这个项目真正有意思的地方，是把一个复杂业务拆解成内部协作闭环的思路——多个专职智能体（Agent）像一家小型公司那样分工、汇报、质检和交付。它解决的并不是“单次对话”的问题，而是如何让一组 AI 代理稳定地完成端到端任务。

简单来说，agency-agents是一个面向任务编排的多智能体协作框架。你在配置文件里定义好不同的角色（研究员、数据分析师、内容审核员、最终报告撰写者），设置好各自的工具和权限，然后丢给它一个总目标，它就能自动规划子任务、分派给对应角色、收集结果、交叉验证，最后产出一份完整交付物。适合正在做智能体应用落地的开发者、技术团队负责人，以及被“单 Agent 做不了复杂事”卡住的朋友参考。这篇文章会从架构设计、角色拆解、实操步骤、问题排查四个维度，完整还原我基于这个项目搭建一套可用系统的全过程。

1. 整体设计与架构思路拆解

1.1 为什么“单兵作战”撑不起复杂任务

早期做智能体应用，最普遍的做法是“一个大模型 + 一堆工具函数”，把所有的业务逻辑都塞到一个系统提示词里。应付“查天气”“写周报”这类问题还能扛住，一旦任务变成“分析某个市场赛道并输出带数据配图的投资简报”，单个 Agent 马上暴露三个问题：上下文窗口被反复工具调用的结果塞满、角色立场来回摇摆、中间产物无人把关。我见过最典型的翻车现场：同一个 Agent 刚刚还在负责数据抓取，下一步就突然开始充当行业分析师，最后生成的报告数据之间互相打架，没有任何一个环节有纠错机会。

agency-agents的核心思路就是对这个痛点的直接回应：把“一个人”变成“一个机构”。机构里有老板（调度器/Supervisor），有干活的人（Worker Agents），有复核的人（Critic/Reviewer），有整理档案的（Memory/Vector Store）。每个角色只干自己那一亩三分地的事，输入输出都有确定性接口，谁出错就回溯到哪个环节重跑。

1.2 三层架构：调度层、执行层与协同层

我实际把这个项目跑起来之后，发现它的代码组织可以清晰分成三个层级，理解这个分层是二次开发和定制的前提：

• 调度层（Scheduler/Orchestrator）：负责任务分解、依赖关系梳理、执行顺序控制和结果状态管理。它不直接调用工具，只负责“派活”和“收账”。
• 执行层（Worker Agents）：包含多个独立角色，每个角色有专属的 System Prompt 和可用工具集，只负责完成调度层下发的单项任务，并返回结构化输出。
• 协同层（Shared Context & Memory）：负责存储任务过程数据、共享状态、最终交付物版本，让不同角色之间能够异步读写而不互相阻塞。

这三层最关键的物理隔离点在于：Agent A 的输出如何交给 Agent B，并不是简单把文本拼在一起塞给下一个模型，而是通过共享数据层（通常是结构化 JSON + Embedding 存储）转交。这样做的直接收益是：如果 Agent B 只需要 Agent A 结果的摘要字段，就不用把 Agent A 的全部中间过程都吃进上下文，token 消耗能下降至少一个量级。

2. 核心细节解析与实操要点

2.1 角色定义：不是“起个名字”，而是“划定边界”

我在配置第一个多智能体项目时（拿它写一份 AI 编程工具的竞品分析报告），参考了项目默认的agents.yaml结构，定义了四个角色：coordinator（协调者）、researcher（研究者）、analyst（分析师）、writer（写作者）。这里面的核心细节不是角色名称，而是每个角色的两个强制字段：description和allowed_tools。

description决定了该 Agent 在大模型视角里的立场与行为边界。一开始我写得太模糊，比如“分析师，擅长数据分析”，执行时经常出现分析师抢了研究员的活，或者自己臆造数据。后来改成具备明确约束的表述，效果立刻不一样。以某公司内部一个数据分析 Agent 的配置为例：

agents: - role: analyst description: > 你是一名严谨的数据分析师。你的唯一输入来源是 researcher 提供的结构化数据快照。 禁止自行检索外部信息，禁止对缺失数据做猜测。如果数据不足，必须返回明确的 insufficient_data 错误码，不得尝试编造结论。 allowed_tools: - pandas_query - chart_generator - data_snapshot_reader

allowed_tools才是真正的紧箍咒。某项目里我给了 researcher 网页抓取工具，却忘了从 analyst 的可用列表里把它删掉，结果 analyst 在一次执行中自己抓了竞品官网的数据，和 researcher 给的调研样本口径不一致，整个报告的数据链条直接断裂。教训很直接：工具的开放范围就是职责的物理边界，少给一个工具，远比多给一个安全。

2.2 任务编排机制：工作流图与有限状态机

这个项目在任务编排上默认采用了基于依赖图（DAG）的方式，而不是简单的流水线硬编码。我一开始觉得 DAG 是过度设计，任务不就是按顺序跑吗？实际跑了带分支的任务才明白硬编码的局限：某个调研任务根据“竞品是否有公开定价”分为两条路径，有公开定价走“价格分析”，没有就走“估值推算”，流水线不得不写大量 if-else，而 DAG 只需要每个任务声明依赖项，调度层自动决定谁先跑、谁能并行。

实际配置片段长这样：

workflow: entrypoint: kickoff_task tasks: kickoff_task: next: [market_scan, competitor_discovery] market_scan: next: [data_normalization] competitor_discovery: next: [data_normalization] data_normalization: next: [report_drafting] report_drafting: next: [final_review]

这里market_scan和competitor_discovery是并行执行的，都完成之后才进入data_normalization。实操时我最推荐的调试方法是：先在小规模数据上把每个节点单独执行一次，确认输入输出格式匹配，再放进整个工作流里跑。节点之间的数据契约问题，是这类系统里最容易返工的地方。

2.3 记忆与上下文管理策略

多智能体系统的另一个致命细节是“上下文污染”。单个 Agent 对话还能靠遗忘机制兜底，多智能体里每一个中间结果都会写入共享上下文。如果所有内容都全量保存，到第三个 Agent 执行的时候，token 就已经见顶了。

agency-agents的默认策略是“分层记忆”：短期记忆存当前任务链的原始结果，长期记忆只存经过摘要化处理的结论与关键数据点。实操时我给 researcher 的每条输出增加了一个summary字段，分析师只读取摘要和结构化数据表，不读原始抓取 HTML。这样做的效果非常直接，整条链路跑完，总 token 消耗比最初的全量传递方案减少了大约 55%，而且最终报告质量没任何下降。

3. 实操过程：从零搭建一套多智能体任务系统

3.1 准备工作与环境搭建

项目本身基于 Python 3.10+，核心依赖是pydantic、langchain-core、openai或任意兼容接口的网关。安装时有一个容易踩坑的地方：不要直接pip install最新版全部依赖，不同版本的langchain-core对工具 Schema 的处理有差异，建议用项目仓库里的requirements.txt锁定版本。

# 建议使用虚拟环境 python -m venv .venv source .venv/bin/activate # 安装核心依赖（不用额外装 torch/tensorflow，这个项目不涉及本地模型推理） pip install -r requirements.txt

我在某台 4c8g 的服务器上跑通了整套流程，CPU 资源完全够用，真正耗时的是大模型接口的往返延迟。所以如果你的执行链路里包含大量串行请求，建议准备 API 负载均衡网关或者支持并发调用的接口配置。

3.2 定义工具注册表

工具注册是这个框架里最灵活也最容易出错的部分。每个工具必须是“输入 JSON Schema + 输出 JSON Schema + 可调用函数”的三元组结构。我封装了一个最常用的工具：网页内容提取与正文清洗。

from agency_agents.tool import register_tool from agency_agents.schema import ToolIO import requests from bs4 import BeautifulSoup @register_tool( name="web_extract", description="从指定 URL 提取主正文内容，去除导航、页脚和脚本代码；返回纯文本和页面标题。", input_schema={ "type": "object", "properties": { "url": {"type": "string", "format": "uri"} }, "required": ["url"] }, output_schema={ "type": "object", "properties": { "title": {"type": "string"}, "content": {"type": "string"}, "charset": {"type": "string"} } } ) def web_extract(url: str) -> dict: # 实际调用逻辑... resp = requests.get(url, timeout=20, headers={"User-Agent": "Mozilla/5.0"}) soup = BeautifulSoup(resp.text, "html.parser") for tag in soup(["script", "style", "nav", "footer"]): tag.decompose() return { "title": soup.title.string.strip() if soup.title else "", "content": soup.get_text("\n", strip=True)[:8000], "charset": resp.encoding }

这里最值得注意的细节是input_schema的严格程度。大模型调用工具时经常漏参数，如果不做强校验，后面的流程会一路脏数据跑到底。建议在 Schema 里把非必需字段全部标注成 optional，并且工具函数内部再做一遍容错。

3.3 配置你的第一个多智能体协作场景

我拿一个实际业务需求来演示：编写一份“社区团购行业 2025 年发展趋势简报”。完整配置两个角色加一个协调者就够了。

coordinator: model: "your-model-endpoint" max_plans: 3 system_prompt: | 你负责将一个复杂分析任务分解为最多3个可并行执行的调研子任务。 每次只输出 JSON 数组，每个元素包含 agent_role、task_brief、depends_on 三个字段。 严禁添加解释。 agents: researcher: model: "your-model-endpoint" system_prompt: | 你是一名行业信息调研员。你可以调用 web_search 和 web_extract 工具。 围绕给定课题检索公开信息，整理出包含数据来源、时间戳、结论要点的事实清单。 禁止输出没有来源支撑的判断。 tools: [web_search, web_extract] analyst: model: "your-model-endpoint" system_prompt: | 你是一名商业分析师。你只基于提供的结构化事实清单进行分析， 推断行业趋势与潜在风险。分析结果必须包含：key_trends、risk_points、data_gaps。 data_gaps 用于记录缺失且无法推测的信息。 tools: []

这套配置跑下来的效果是：coordinator 先生成两个子任务（行业规模信息收集、主要玩家动态收集），两个任务并行交给各自 researcher，完成后再汇总给 analyst 做趋势交叉，整个过程无需人工干预。需要提一句，analyst我给了空工具列表，这种“权限最小化”设计刻意为之，逼它只做推理，不做检索，保证了交付物风格的统一。

3.4 启动任务流与监控状态

命令行启动很简单，项目提供了run入口。实际操作中我最关心的不是启动，而是运行过程中的状态可视化。默认配置在终端打印的是纯文本日志，看长了很累。建议你在项目配置文件里打开enable_state_trace: true，会生成一份结构化 JSONL 运行轨迹文件，用表格或者任意日志分析工具都能直观看到每个 Agent 的耗时、token 消耗和上下游数据流转情况。

python -m agency_agents run --config configs/demo_team.yaml --task "撰写一份社区团购行业2025年发展趋势简报"

任务跑完后，会在输出目录生成final_report.md以及全部中间产物的归档文件。中间产物归档简直是调试救星，某次报告里出现了一个奇怪的数据引用，靠回溯 researcher 的原始搜索快照才发现是网页编码识别错误导致的乱码被当成了数据。

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

4.1 Agent 连环递归导致死循环

这是多智能体系统最常见的事故，没有之一。表现：任务调度层不断生成新的子任务，永远停不下来。根因通常是 coordinator 的max_plans设置过大或者系统提示词里没有“穷尽”的概念。

排查方法：第一，看运行轨迹的task_count，远超预期基本就是失控；第二，检查 coordinator 的 system prompt 是否明确了“禁止反复拆解同一子任务”。解决时就一个参数一个参数调，我最终固定为max_plans: 3，并且在 coordinator 提示词里加上一句“如果子任务与历史任务同质化，直接标记 completed 并返回现有结果”。

4.2 工具调用参数幻觉与格式崩坏

大模型在调用工具时生成 JSON 参数出错属于常态。我把 OpenAI 兼容接口的temperature在工具调用链路上调到0.1，情况能缓解大半，仍然无法根治。更可靠的手段是“工具调用结果校验 + 错误代码反馈重试”的闭环。工具执行失败后，不要直接让链路崩溃，而是返回标准错误 JSON，反馈给 Agent 让它重试或者换一种调用姿势。

4.3 上下文与输出长度失控

当某个 Agent 一次性输出 8000 字原始材料和 20 个网页摘要时，下一环必然 token 爆炸。我的对策是严格执行前面说的“输出摘要化”。在工具层就做截断与摘要，不让大量原始文本进入共享上下文。具体做法是给每个工具的输出 Schema 加一个compressed_content字段，由本地逻辑负责压缩，而不是依赖大模型二次总结，省时省 token。

4.4 多 Agent 结果互相矛盾

不同 Agent 基于不同来源得出结论冲突，在业务分析场景尤其明显。例如 Researcher A 找到市场规模 1000 亿，Researcher B 找到另一份报告说 800 亿，Analyst 最后混在一起算出了 1200 亿。

这部分的处理策略不是“一刀切”，而是引入第三方的仲裁 Agent，或者在任务编排里增加一个 “cross_check” 节点。配置思路是让 analyst 生成报告的同时，输出contradiction_list字段，再由一个reviewer角色专门针对矛盾点进行核验并给出最终采纳版本。

4.5 成本控制与效率调优心得

跑了一周这个框架，每天处理上百个任务链，我在成本控制层面有两点切身体会。第一点是“并发度不是越大越好”。当多个子任务调用同一个 API 网关时，盲目增加并发会触发限流，重试反而拖慢整体速度。我最终把并行度设定在 4，综合吞吐和稳定性最佳。第二点是“不要把所有环节都交给大模型”。像 URL 清洗、HTML 正文抽取、日期格式化这种规则明确的活，全部用本地函数实现，框架只负责在工具层调用它们，一个环节能省好几百毫秒的延迟。

5. 适合扩展的方向与后续演进

5.1 从“报告生成”到“业务闭环”

演示场景写的是报告，实际上这套框架完全可以扩展到更硬的业务链路。比如客服工单自动分拣、运维故障初步诊断、电商评论情感聚类分析。框架的价值在于它已经帮你解决了“多角色协作”的底层问题，你只需要替换掉角色配置和工具集。

5.2 引入人机协同与人工审批节点

当前项目默认是全自动执行，但真实业务里很多环节需要人工拍板。我在二次开发时加了一个human_intervention标志位，放到工作流节点的next逻辑里。当任务链走到final_review节点时，如果检测到结果置信度低于阈值（比如data_gaps超过两个），自动发送通知给人工专家进行审核，审核通过才继续往下走。这个改动对系统可靠性提升非常明显，也更容易说服业务团队接入。

5.3 模型网关替换与私有化部署

有些团队对数据外发有严格要求，这套框架因为模型调用层做了接口抽象，替换成私有化模型网关并不难。只需要改model_provider配置和认证方式即可。我的建议是先跑通一个最小任务链，再逐步扩展到真实负载，避免一上来就迁移所有任务导致问题难定位。

最后再分享一个实用技巧

执行多智能体任务链时，如果你发现最终交付物的质量忽高忽低，最值得怀疑的不是单个 Agent 的能力，而是任务边界的切分方式。同样的调研任务，如果 coordinator 把“收集信息”和“整理信息”拆成两个串行子任务，虽然逻辑上顺理成章，却容易丢失中间信息；而把两者合并成一个节点，让同一个 Agent 在最短上下文窗口内完成，反而更稳定。这种“任务不要切得过碎”的经验，是我在多次实验中对比出来的，写在这里供大家参考。