先说我自己的现状每天要面对需求梳理、接口设计、代码实现、走查测试这一整套流程时间永远不够用。于是我做了一个大胆决定不招人雇一个 AI 团队。这个团队没有工位没有工资单只有一个代号叫 AgentTeams。所谓 AgentTeams其实就是一套跑在我本地的多智能体协作流水线它会根据输入需求自动拆分任务让不同角色的 Agent 依次介入产出设计文档、代码、评审意见和测试结果。这篇文章我会把整套实战过程复盘出来包括角色如何配置、流程如何编排、实际效果如何以及踩过的坑。这套东西不是某个商业平台的付费功能而是我自己用模型 API 加 Python 脚本搭出来的编排体系。核心思路一句话就能说清把一个复杂目标拆成若干子目标每个子目标交给一个“专业性极强”的 AI 角色去处理再让角色之间进行交接和交叉验证。听起来很像公司里的敏捷团队只不过我的员工全是逻辑权重。这篇文章适合两类人看一类是不满足于“跟 AI 对话写代码”想构建稳定工作流的开发者另一类是刚接触多智能体想了解 AI Agent 搭建是不是真的能落地的人。1. 整体设计AgentTeams 到底怎么运转1.1 AgentTeams 到底解决什么问题先说我在没有 AgentTeams 之前的痛点。直接打开一个聊天窗口丢给大模型一句“帮我做一个待办事项系统”它确实能回一段能跑的代码但往往只有代码没有需求分析没有异常处理说明没有测试用例更没有对边界条件的讨论。等我让它补测试它会基于自己刚生成的代码继续写完全无视我原本想约束的验收条件。你问它为什么这么写它的解释往往前后矛盾。这个现象业内说得很形象上下文漂移。单个对话窗口能承载的上下文有限任务一旦复杂前面的约束条件就会被后续生成内容挤占。我试着把所有要求写进一个超大 System Prompt比如把角色设定、技术选型、代码规范、测试要求一次性塞进去结果更糟。模型被大量指令压住反而开始在关键输出上“偷懒”生成一些看着齐全、实际经不起推敲的模板代码。AgentTeams 解决的就是这个问题。它把任务拆成多个阶段每个阶段由独立角色负责。产品 Agent 只写需求不写代码开发 Agent 只做实现不做整体评审测试 Agent 专门挑毛病。每个角色在一个较小的上下文窗口内工作状态被人工限定角色切换时我通过编排器做信息交接而不是让模型自己背住全部约束。这样一来每个人的“视野”虽然变窄但聚焦度和稳定性都上来了。1.2 多智能体协作相比“单条大提示词”的优势很多人第一反应是我写一个巨大提示词不也能模拟多个角色吗确实能但实际跑一次就有差异。单条大提示词把五个角色的设定塞进同一个上下文中模型在同一轮生成里要同时扮演产品、架构、开发、评审、测试思考路径处处打架。更麻烦的是它缺少真正的“评审反馈闭环”。一个模型写的代码让同一个模型自己评审等于让运动员兼任裁判它大概率会觉得自己写得没毛病。多智能体协作的真正价值在于“职责分离”和“交叉验证”。每个角色是独立请求拥有独立上下文和独立的系统提示词上一个角色的输出作为下一个角色的输入下一个角色可以对前文提出修改意见。这种结构天然形成一条质量流水线。我自己的实测中只要评审 Agent 给了明确的“未通过”理由开发 Agent 重写后的代码质量往往能立刻提高一个档次因为二次生成时多了一个具体的纠错方向。另外从工程角度看多智能体架构更容易加监控和熔断。比如我在编排层统计每个环节耗时发现某轮测试 Agent 反复触发重试就可以手动介入中断而不是让一个大模型 Prompt 在那儿空转到超时。后面我会讲到这种可观察、可中断、可重放的能力对真实项目落地来说比“生成得多漂亮”更重要。2. 核心配置把我的数字员工逐个立起来2.1 环境依赖与基础参数搭建 AgentTeams 的技术栈很简单我没有用太重的东西。Python 3.10 作为主语言openai 客户端库作为模型接入层pydantic 做输出校验yaml 做配置文件Redis 选装用于并发任务状态存储。整个原型不到一千行代码但架构上给日后扩展留了空间。pip install openai pydantic pyyaml redis模型我选了支持长上下文的 instruct 系列温度统一设置成 0.3。这个温度值是有讲究的真实团队干活追求的是稳定交付不是天马行空。温度调太低会显得机械有时候本来该随机想到的边界情况反而想不出来调太高又容易偏题。0.3 基本能在稳定性和发散性之间找到平衡。配置我全放一个 yaml 文件里方便随时调整角色参数model: qwen2.5-72b-instruct temperature: 0.3 max_iteration: 8 timeout_second: 120 roles: product: description: 需求分析输出结构化PRD architect: description: 系统设计拆分子任务 developer: description: 编码实现输出可运行代码 reviewer: description: 代码走查给出修改意见 tester: description: 测试设计执行验证并输出结果一个容易被忽略的参数是 max_iteration。这个值控制整个团队最多迭代几轮。最初我把它设成 50有一次因为评审 Agent 反复挑格式问题整个流程重跑了一个小时。后来我统一设成 8宁可中途失败让我手动介入也不能让流程陷入失控。2.2 五位核心角色的 System Prompt 设计角色能不能立住九成靠 System Prompt。我的写法遵循一个原则每个角色只描述“你是谁、要做什么、输出长什么样、绝对不做什么”禁止在一份提示词里塞多个目标的杂糅描述。以产品 Agent 为例它的 Prompt 模板大致是这样你是一名有15年经验的B端产品经理。 你的职责是根据用户输入的需求输出一份结构化需求文档。 需求文档必须包含 1. 用户故事 2. 功能列表按优先级排序 3. 验收标准 4. 不涉及或延期处理的内容 禁止讨论具体技术实现禁止直接输出代码。 输出必须使用JSON格式key包括title, stories, features, acceptance_criteria, out_of_scope这份 Prompt 的关键不是“15年经验”这种废话而是最后的约束禁止讨论技术实现、输出必须是 JSON。很多 AI 协作项目翻车就翻在角色串台产品 Agent 写着写着开始报 API 路径开发 Agent 写着写着开始改需求。用明确的“禁止项”可以大幅减少串台概率。开发 Agent 的 Prompt 我这样设计你是一名高级后端工程师精通Python和FastAPI。 你的任务是根据PRD和任务描述生成可直接运行的代码。 输出必须包含 1. 完整的文件路径列表 2. 每个文件的代码内容使用代码块标注语言 3. 运行依赖和启动命令 你已经收到评审Agent的反馈如果反馈存在“拒绝”意见必须针对反馈逐条修改。 不要输出任何解释性废话不要自己增加功能。注意最后两条。评审 Agent 的反馈会被追加到开发 Agent 的消息序列中开发 Agent 的重写不是凭空发挥而是带着“逐条修改”的硬指令。我还特意加了“不要自己增加功能”否则开发 Agent 很容易在修复 bug 时顺手造一个新接口评审再次拒绝流程进入死循环。2.3 编排循环与上下文管理有了角色还要有流程。AgentTeams 使用一个非常简单的主循环需求进入队列后依次经过产品、架构、开发、评审测试环节放在评审通过之后如果测试失败则回到开发阶段重写。我把这个循环叫做“带门禁的流水线”。核心代码如下class TeamOrchestrator: def __init__(self, config): self.roles load_roles(config[roles]) self.max_iteration config[max_iteration] self.iteration 0 def run(self, user_requirement: str): prd self.roles[product].execute(user_requirement) tasks self.roles[architect].split(prd) approved_tasks [] for task in tasks: while self.iteration self.max_iteration: code self.roles[developer].execute(prd, task) review self.roles[reviewer].audit(code, task) if review[verdict] approve: test_result self.roles[tester].execute(code, task) if test_result[passed]: approved_tasks.append(code) break else: task[feedback] test_result[report] else: task[feedback] review[comments] self.iteration 1 return approved_tasks这个循环的模样子很粗糙但跑起来意外地稳。核心思想是每个环节的输出都被结构化评审环节必须有明确“approve/reject”的裁决测试环节必须有 pass/fail 的布尔结论。如果没有裁决标准Agent 之间的协作会陷入“你给我改我改了给你”的无限对话。上下文管理是另一个关键。我的做法是“窄通道交接”产品 Agent 的输出只保留需求文档架构 Agent 的输出只保留拆解后的任务清单任务清单加上评审反馈再喂给开发 Agent。上一轮角色的完整思考过程不会全部传给下一轮。这个设计很反直觉一开始我也担心信息丢失但实际测试后发现丢弃“思考过程”恰恰能避免模型被前面角色的思路带偏它只需要对结论负责。3. 实战复盘让 AI 团队从零做一个待办事项后端3.1 从需求输入到团队分工理论说多了直接看实战。我给 AgentTeams 输入的需求是开发一个轻量待办事项后端使用 FastAPI要求支持增删改查、状态流转数据持久化到 SQLite并提供 OpenAPI 文档。首先出场的是产品 Agent。它输出的需求文档里写了一条很有趣的验收标准“当用户创建一个待办事项时响应时间应小于500ms且能返回唯一ID。” 这条标准不是我给的是它自己补充的说明在明确的角色约束下模型确实会自动提升专业度。唯一的插曲是它在 out_of_scope 里把“用户注册登录”排除掉了这符合我的预期登录鉴权确实不该在一个演示项目里展开。接下来架构 Agent 把整体拆成三个任务数据库模型与初始化、CRUD 路由、状态流转逻辑。它没有拆得更细我手动补充了“异常处理”和“入参校验”两个任务然后把这些任务重新塞回开发 Agent。这一步进入实操阶段后会发现架构 Agent 虽然能抽象思路但实际编码的子任务边界仍然需要人工过滤尤其是涉及异常路径时机器默认会优先考虑 happy path。开发 Agent 收到任务清单和 PRD 后生成了完整代码。让我惊艳的部分是它自动生成了 SQLite 初始化脚本并且考虑到了表结构变更的情况。几十秒后评审 Agent 输出裁决结果拒绝。理由是“代码中没有对状态字段做枚举约束存在脏数据风险且 API 层缺少统一的异常响应结构”。这两个问题非常准确实是我在人工审查时也会提的点。3.2 生成结果的质检与人工介入点拒绝之后开发 Agent 带着评审意见重写了一版。这一次代码质量肉眼可见地提升。下面这段是其中一次生成的模型层代码from sqlalchemy import Column, Integer, String, Boolean, Enum, DateTime from sqlalchemy.orm import declarative_base from datetime import datetime import enum Base declarative_base() class TodoStatus(str, enum.Enum): PENDING pending IN_PROGRESS in_progress DONE done ARCHIVED archived class Todo(Base): __tablename__ todos id Column(Integer, primary_keyTrue, autoincrementTrue) title Column(String(200), nullableFalse) description Column(String(1000), nullableTrue) status Column(Enum(TodoStatus), defaultTodoStatus.PENDING) created_at Column(DateTime, defaultdatetime.utcnow) completed_at Column(DateTime, nullableTrue)代码使用了 SQLAlchemy 而不是裸写 SQLite这是开发 Agent 自己的选择。我在这个环节做了三次人工介入第一次是发现模型没有创建数据库索引我在 Todo 表的 status 字段上主动加了一个索引因为实际业务中“按状态筛选待办”是最常见查询路径。第二次是模型把 Completed_at 设计成可空字段但没有给出状态流转到 DONE 时的自动赋值逻辑我补了一个更新时间的方法。第三次是测试 Agent 生成的测试用例只覆盖了正常分支我额外补了一个删除不存在资源的 404 用例。整个实战跑完流程耗时约 5 分钟API 调用成本折算下来不到一元人民币。如果换我人工从零写这些加上吃饭开小差的时问至少两小时起步。但这不是说 AI 团队可以完全替代人工我的主要时间花在质量把关和边界补全上比例的偏移从“写代码”变成了“做审查”。4. 高频问题和排查技巧实录4.1 我遇到的六个典型故障跑 AgentTeams 这段时间踩过的坑比收获还多。这里直接整理成一张速查表方便大家按图索骥。故障现象根本原因排查方向解决方案Agent 在评审环节反复拒绝且理由不具体评审 Prompt 缺少“通过标准”定义模型只能用模糊措辞否定查看评审输出的拒绝原因是否有 action item在评审 Prompt 中追加“必须列出具体修改文件和行号”开发 Agent 越写偏得越远评审反馈直接拼在原始 Prompt 后面上下文被拉长监测开发 Agent 输入消息序列只保留最近一次评审反馈不叠加历史评审记录测试 Agent 永远报“通过”形同虚设测试 Prompt 未要求先写用例再执行模型直接看代码写结果检查测试 Agent 的输出顺序强制要求测试 Agent 先输出 test cases 再输出 run result输出 JSON 偶尔被 Markdown 代码块包裹模型自身行为不稳定查看原始返回文本开启 response_format 的 json_object 模式做一个预清洗函数流程进入死循环迭代次数耗尽开发修复 bug 引入了新问题评审再次拒绝打印每次评审的拒绝原因看趋势是否收敛降低 max_iteration在第二次拒绝时让人工介入多个 Agent 并发调用 API 触发限流编排器没有做并发控制看调用日志的 429 状态码增加 Python asyncio 信号量限制同一时间最大请求数第一个故障最隐蔽。我给评审 Agent 的 Prompt 原本写了“输出审核结论”但它输出的结论是“代码整体可读性良好但存在一些细节问题需要优化”。这种话在真实评审会上等于没说。后来我强制要求评审 Agent 必须输出“通过”或“不通过”二值结论并且不通过时必须附带具体到文件名的修改建议。这个改动立竿见影评审环节的稳定性迅速提升。4.2 稳定运行的“三条铁律”综合这些踩坑记录我总结出三条经验后来所有团队成员都遵守这三条项目才真正稳定下来。第一状态显式化。不要让 Agent 自己判断当前处于流程哪一步所有中间结果统一用 JSON 结构传递并且每个字段有严格定义。说白了就是给 Agent 们建立了一套“交接单据”单据上没有的东西一律视为不存在。第二输出格式硬校验。在大模型 API 入口处做响应拦截返回结果不符合 JSON Schema 时直接置为失败并重发一次请求。别信模型嘴里说的“我输出了合法 JSON”实测处理 Markdown 代码块包裹的伪 JSON 是 AI 工程师最常做的事。第三流程必须可熔断。任何环节连续失败两次以上编排器就要暂停并通知我。我最初完全信任自动化循环结果一次测试 Agent 陷入重复修改死循环我直到第六分钟才发现。现在用 max_iteration 配合失败次数触发器流程最长运行时间被限制在 10 分钟以内。5. 进阶扩展让 AI 团队长出手脚5.1 让 Agent 调用工具基本流程能跑通之后我开始考虑让 Agent 不只在对话里输出代码而是真的去执行代码。这一步至关重要因为 AI Agent 搭建的最终目标应该从“生成内容”进化到“完成操作”。AgentTeams 的第二版引入了 function calling。我给测试 Agent 挂了一个本地工具允许它在输出测试脚本后调用run_pytest命令直接执行测试并获得真实返回结果。工具定义如下[ { type: function, function: { name: run_pytest, description: Run pytest tests in current project directory and return test report, parameters: { type: object, properties: { path: { type: string, description: test file or directory path } }, required: [path] } } } ]挂上这个工具后测试环节不再是模型“假装跑测试”而是 shell 真正执行 pytest 并捕获返回码。所有失败用例会被解析成文本反馈重新丢回开发 Agent 的输入。效果是立竿见影的因为一个本来靠模型“想象”出来的通过结果变成了真实环境下的“硬通过”。我给开发 Agent 也挂了 git 工具它可以在完成实现后自动创建分支提交每次迭代形成独立 commit方便我回溯任意版本。5.2 按业务场景自定义新角色AgentTeams 的角色列表不是写死的代码里我维护了一个角色注册表新增角色只需要两步写一份 System Prompt注册到 yaml 配置里。你自己做项目时可以按业务场景灵活组合。举个例子给团队加一个数据分析 Agent。它的 Prompt 里多了一项“必须使用 pandas 库分析输入数据输出为可复现的 Python 脚本”同时给它绑定了读取本地 CSV 文件的工具。队伍里有了这个角色之后业务人员直接丢一个报表需求给编排器它就能自动完成数据清洗、指标计算、图表生成的整个流程。另一个值得尝试的角色是文档 Agent。开发 Agent 产出代码后文档 Agent 自动根据源码生成 API 文档和 README避免了我总是要花半小时补文档的老大难问题。文档 Agent 不需要理解全部业务逻辑它只需从代码注释和类型签名抽取信息输出 markdown 格式的项目文档并写入指定文件。用下来最深的感受是角色一旦具备“单一职责”模型的表现会远比全能型角色稳定这个规律在自定义角色时同样成立。最后讲一个我最推荐的落地方案如果你的项目刚起步先不要在整套流程里塞满角色。我自己是先从 Product Developer Reviewer 三个角色跑通的加上 Tester 是在第二个项目阶段Architect 则是在需求变得足够复杂后才加入。角色越细编排复杂度会指数级上升你可能很快被接口超时、上下文同步和权限配置问题淹没。更稳妥的做法是先让团队小步跑起来再根据实际痛点逐步扩大编制。AI 团队再能干动手之前也总得有个清醒的分工规划。