Agency Agents：多智能体协作的跨平台AI编程架构实践-北京尧图网络

凌晨两点半我盯着一条失败的CI日志发现问题的根源竟然是上一次对话里模型理解错了某个配置项的口径。那一刻我就意识到靠单个对话框一次性代码生成的方式根本撑不起真正的软件工程。于是有了Agency Agents这个项目——我们打算把若干个职责明确的AI智能体像一家虚拟研发外包公司那样组织起来统一接入不同的开发平台让它们在不同IDE、命令行、Web环境和移动端上协同工作真正介入从需求拆解到代码提交的完整链条。这篇内容适合正在构建AI编程工具、想把对话式助手升级成多智能体体系的开发团队也适合想了解跨平台智能体架构怎么分层、怎么处理状态同步、怎么做工具调用安全隔离的同学。我不会只给一张架构图然后说很美而是把我们在真实工程落地里踩过的坑、做过的取舍、验证过的方案尽量完整地摊开。如果你也在做一个类似的Agent系统这篇应该能帮你节省至少两周的试错时间。1. 从单体代码生成到多智能体协作项目缘起与目标定位1.1 旧的开发辅助流程痛点在Agency Agents之前我们的开发辅助工具本质上是带着上下文的代码补全器。模型可以基于仓库内容生成函数、解释报错、补测试但你跟它的交互是单线程的你提问它回答再提问再回答。一旦任务涉及跨模块改造、构建修复、回归验证这种单线程模式就开始四处漏风——生成完A模块的代码B模块的测试崩了模型完全不知道CI上暴露的兼容性问题对话里根本没出现过。更麻烦的是不同平台上的交互形态各说各话。IDE插件里是长文本对话命令行里是极简输出Web端又有自己的异步任务模型。我们早期在每个端各自接了一遍底层模型API结果当底层提示词模板或者工具调用协议一改五个客户端要同步改五遍维护成本直线上升。1.2 Agency Agents要解决的核心问题这个项目的核心目标可以归纳成三句话把对话升级为任务流程把单模型调用升级为多角色协作把一个端一个实现升级为一套内核多端接入。第一点意味着系统要能理解目标任务而非单条指令。你告诉它把这个服务从单体拆出来并写迁移测试它会自动拆解成若干子任务而不是一次性吐一堆代码让你自己去缝缝补补。第二点意味着在任务流程里必须有不同角色分工——有人负责规划有人负责写代码有人负责审查有人负责执行构建验证。第三点则体现在架构上底层核心引擎是平台无关的各端只是不同的皮肤和交互外壳。1.3 为什么叫Agency AgentsAgency这个词在英文里有代理和机构双重含义。我们想表达的正是一组共同协作的智能体机构项目初始化时它会自动拉起一个临时的虚拟项目组里面有架构师、编码员、审查员、测试员这几个角色围绕一个任务各司其职。这比单智能体系统更接近真实的软件开发方式。命名本身看起来像循环废话Agency里的Agents但它其实点出了我们整个架构设计的出发点智能体不是在帮用户做二次对话而是在作为一个机构式整体为用户交付结果。后面所有的架构决策包括角色通信、消息总线、任务编排都是围绕这个出发点展开的。2. 整体架构的分层设计与技术选型2.1 六层架构总览Agency Agents的整体架构可以按照调用方向拆成六层每一层只依赖其相邻下层禁止跨层调用。这个约束一开始看起来很教条但后来证明是我们能持续迭代的前提。从上到下分别是接入层IDE插件、CLI、Web端、移动端等不同平台上的客户端外壳。会话层统一维护会话上下文、用户偏好、项目维度信息为上层客户端提供一致的会话模型。编排层负责任务拆解、Agent角色调度、任务依赖管理和结果汇聚。这是多智能体协同的核心。引擎层封装大模型调用、提示词组装、流式解析、函数调用工具调用执行。引擎层不关心任务怎么拆只负责一次完整推理。工具层提供代码执行沙箱、Git操作、Shell执行、文件读写、HTTP请求等实际能力。基础设施层缓存、任务队列、日志链路追踪、鉴权与限流、数据持久化。2.2 通信协议与不同平台的适配跨平台最怕的是各端各自为政。我们在协议上定了两条硬约束客户端与服务器之间统一走JSON-RPC 2.0 over WebSocket同时支持流式响应的增强字段客户端与客户端之间不允许直接通信所有状态变更必须通过服务端会话层广播。为什么是JSON-RPC而不是REST因为在智能体交互里双向通信和服务器主动推送太重要了。任务执行过程中编排层需要持续向客户端推送状态变化、子任务进度、代码输出片段用WebSocket长连接比轮询REST接口要自然得多也省掉了大量拉取不到增量的尴尬。JSON-RPC本身有规范成熟的请求/响应/错误语义比自定义一套JSON协议省心各端语言都有现成库接入成本低。2.3 后端技术栈与部署形态技术选型里我们纠结最久的是核心引擎到底用TypeScript还是Python。最终落地是一主一辅编排层、会话层和接入网关用TypeScriptNode.js运行时因为IDE插件、CLI这些生态天然跟JS/TS亲近共享类型定义可以减少一大截跨语言接口成本引擎层的模型调度和提示词模板管理也放在TS侧方便直接复用上下文组装逻辑。工具层里的代码执行沙箱则单独拆成Python侧的一个异步服务因为沙箱隔离、子进程管理和更多底层系统API在Python里做起来更顺手。部署形态不是一刀切而是三种并存本地开发场景下后端以单进程方式跑在开发者机器上SQLite做持久化团队使用场景下部署为内网服务Redis管任务队列和分布式锁面向更大规模外部访问时再套上Kubernetes做横向伸缩。同一套代码在不同部署形态下要平滑切换因此所有存储访问都走一层薄薄的Store适配层。3. 跨平台接入层一个Adapter处处运行3.1 平台适配器的抽象规则接入层的核心抽象是PlatformAdapter。每个平台VS Code插件、JetBrains插件、CLI、Web IDE、浏览器侧边栏只需要实现一个适配器负责把该平台的UI事件翻译成统一的内部命令start_task、send_message、accept_edit、reject_edit同时把内部事件task_progress、agent_output、file_change渲染回平台的UI形态。规则有三条第一适配器内不允许有任何业务逻辑它只做协议转换和UI渲染第二所有适配器必须实现同样的最小能力集——会话建立、任务提交、流式接收、文件操作申请、工具执行结果呈现第三平台特有的能力比如编辑器里的inline diff、终端的交互式确认通过能力标签声明服务端再根据能力决定下发什么形式的结果。3.2 IDE插件、CLI与Web端的实现细节以IDE插件为例我们基于扩展点机制实现了一个约等于会话内置的视图左侧是任务列表右侧是代码变更流以逐块diff呈现底部是对话面板。每个Agent的产出都作为待审查变更出现用户可以直接接受或拒绝单个文件变更而不必全盘接受整个任务的输出。CLI端则完全不同。没有GUI的情况下任务的输出必须以紧凑的文本流呈现。我们为此定义了类似结构化Markdown的输出协议##[agent_name]表示当前产出Agent[file_path]表示之后是文件操作![tool_call]表示工具调用事件。这样CLI用户可以用管道把输出接到其他工具里也可以直接给人阅读。Web端的长任务体验反而是最让团队头痛的。浏览器里一直开着WebSocket长任务跑了几分钟网络抖动断连前端如果没做状态重建用户界面就会滞留在一个死掉的会话上。我们的解法是Web端在连接恢复时主动拉取一次完整会话快照将散落的增量事件对齐到快照时间线之后。3.3 会话状态同步与断线恢复会话状态同步是所有平台里最容易被低估的问题。智能体任务不是一秒两秒就结束的有的构建验证任务能跑十分钟以上。这中间如果用户切了设备——从IDE切到Web端继续看——会话状态必须无缝迁移。我们把会话状态分成三层基础会话用户消息、Agent消息、任务元数据按时间序追加、上下文状态当前任务拆分树、各Agent已消费的上下文片段、工具调用的结果引用、视图状态watched files、当前diff位置只存在于客户端本地不上服务器。断线恢复的具体流程是客户端重连后向会话层发session.resume请求带上最后一次看到的event_sequence。会话层把增量事件重放给客户端同时把上下文状态的最新哈希一并返回。若状态哈希不一致客户端会触发一次全量快照拉取保证UI和服务端的逻辑状态不脱节。4. 智能体引擎规划、上下文与工具调用4.1 任务规划器的三种策略任务规划器是引擎层的大脑。我们实现了三种规划策略对应不同复杂度的任务线性策略任务按先后顺序拆成子任务适合构建流程、代码迁移这类强依赖场景。前一个子任务的输出作为后一个子任务的附加上下文。扇出策略一个任务拆成多个互不依赖的并行子任务分别交给不同Agent执行最后统一汇聚。适合为三个模块各写一套单测这类任务。自适应策略先让规划Agent拆出一版任务树然后在执行过程中任何一个子任务完成时都触发是否需要重规划的判断。如果偏差过大则暂停并询问用户确认。这三种策略是运行时动态决定的不强绑定。用户只说帮我重构这个模块规划器会先扫描模块结构根据耦合度推断是线性还是扇出再决定要不要启动自适应。4.2 上下文窗口管理与压缩策略上下文窗口是所有AI编程工具都会撞上的那堵墙。我们的管理思路是按需分层加载而非一把梭全塞进模型。任务启动时规划器会生成一份上下文清单仓库根信息、涉及的文件路径级、依赖声明、相关测试文件。引擎层按这份清单做文件内容懒加载——Agent实际需要某一文件时才读入而不是启动时全量读入。当某个子任务完成后它的过程性输出中间版本代码、中间调试日志会被压缩成一段摘要作为后续子任务的附加上下文。这个压缩动作不是简单的截断而是调用一次模型做信息蒸馏把关键决策和结果浓缩成200~500字的结构化摘要。压缩之后我们还会做一步上下文准入校验在把摘要追加进下一子任务之前过滤掉涉及绝对路径、临时文件名和时间戳等易引起模型混淆的信息。这一步帮我们显著降低了模型张冠李戴的概率。4.3 工具调用安全沙箱的设计工具调用是把双刃剑——Agent能跑Shell、改文件、执行测试但这里的风险和收益一样大。我们的安全设计经历了三代迭代最终定为四层隔离第一层是权限声明。每个Agent在执行前必须声明要用到的工具列表和目标文件范围编排层校验声明和实际行为是否一致。第二层是执行沙箱。所有Shell命令、代码执行统一走Python侧沙箱服务沙箱内部以seccomp限制系统调用、以资源配额限制CPU/内存/磁盘再以只读挂载保护系统目录。第三层是操作审计。每次工具调用生成一条审计日志记录参数、返回值摘要和执行耗时。第四层是人工确认闸门。高危操作删除文件、安装依赖、修改Git配置、推送代码默认会暂停任务并向用户端推送确认请求用户确认前Agent不能继续下一步。这四层由编排层的一个ToolPolicy组件统一管理每个工具都在策略表里注册了风险等级和是否需要确认。前两版我们只做了后两层结果就是一遇到误操作就只能靠日志回滚又慢又丑。5. 多Agent协作机制从单点对话到团队工作流5.1 角色划分与任务描述规范Agency Agents里不是一个万能的Agent而是固定角色加上可扩展角色。核心角色有四个架构师Architect负责任务分解、技术方案设计、依赖关系定义。编码员Coder接收明确任务描述产出具体代码变更。审查员Reviewer对代码变更做静态检查、设计评审、潜在缺陷分析。验证员Verifier执行构建、测试、静态分析返回真实执行结果。每个角色接收任务描述时必须包含四个字段目标一句话、范围涉及文件或模块、约束不能改什么、必须遵守什么规范、可用的工具列表。缺少任何一个字段角色可以拒绝接受任务防止话没说清就瞎干活。5.2 消息总线与任务编排逻辑多Agent协作的基础设施是一条轻量级任务消息总线。所有Agent之间的通信都不是直接调用而是通过总线发布消息。消息类型包括task_assigned、task_completed、review_comment、request_clarification、policy_violation。控制面在编排层每个任务有自己的当前状态机。编排层的调度逻辑是事件驱动的当某个子任务完成事件携带产出产物的元信息文件路径、diff哈希、测试结果摘要进入总线对应的下游子任务如果依赖它且依赖条件满足调度器就把新任务投递到相应的Agent执行队列里。队列是带优先级的审查员的反馈消息优先级高于新任务的派发这能避免审查完了Coder还在等任务的空置。5.3 冲突处理与结果一致性多Agent协作的经典问题是两个人同时改同一个文件。我们的处理分成预防和消解两个阶段。预防阶段靠编排层的仓库锁每个Agent在动手前申请目标文件的写锁锁粒度是文件级同一时刻同一文件只有一个Agent能持有写锁。持锁时间超过30秒的会触发锁升级——由编排层询问是延长还是让渡。消解阶段靠差异合并如果出现了不可避免的冲突比如两个Agent先后修改同一文件的不同区域我们会在文件级做一次三方合并把当前工作区版本作为基准后续Agent的修改作为一条变更流前一个Agent的修改作为另一条变更流。能够自动合并的则自动合并合并不了的则生成冲突标记并交给用户决定。在实测里自动合并的成功率在七成以上剩下的三成基本集中在配置文件这种小而关键的文件上。6. 工程实践中的性能优化与稳定性建设6.1 流式输出的端到端链路模型输出如果不做流式用户会在长任务里等得崩溃。我们的流式链路是引擎层的模型Provider按token增量推送 → 消息总线的流式事件通道转发 → 会话层按event_sequence标记追加 → 客户端按平台能力渲染。这里最容易出问题的是流式事件的完整性。某次线上异常就是客户端收到的代码片段不完整错误地渲染了半个函数用户点击接受后直接把残文件写进了仓库。我们的修复方案是为每个流式输出片段增加一个end_of_stream标记客户端只有收到标记后才把最终结果写入UI如果连接断开而标记未到达客户端丢弃该片段并在重连后请求服务端重放。这个宁可丢勿要残的原则靠一次惨痛教训换来的。6.2 缓存与命中策略智能体系统天然适合做缓存因为同一仓库里很多上下文片段是重复的。我们做了三级缓存第一级是文件级缓存文件内容的hash到文件token化的映射只要文件没变就不需要重新读取和重新分块。第二级是检索级缓存用户请求找到入口函数这类语义检索命中后缓存向量和上下文摘要key是仓库路径加检索语句的哈希。第三级是模型输出缓存对于完全相同的工具调用序列和输入上下文直接返回上一次的输出。这一级缓存我们只开了很小的范围因为模型输出有随机性除非是纯测试场景否则默认关闭。这套缓存组合下来一个中等规模的仓库比如1万行代码左右常规任务的上下文准备时间能压到1秒以内。6.3 降级与熔断的实践外部模型服务总会有不稳定的时候。我们早期的做法是单调重试结果一次服务商大范围降级时我们整个任务队列被重试请求塞满把还能用的备用通道也挤垮了。现在我们的降级策略分四段第一段接口超时快速失败并重试一次第二段同一个任务在请求模型前先做缓存检查、上下文轻量化比如暂时压缩掉超大文件内容试试能不能减小输入体积来降低失败率第三段自动切换备用模型通道此时模型的推理能力和可用工具范围会降级编排层会主动提醒用户当前处于降级模式部分能力不可用第四段如果全部通道都失败任务挂起而不是失败保存现场等通道恢复后从挂起点续跑。熔断器按服务商维度独立配置连续失败超过阈值就快速熔断不再无脑尝试五分钟后再半开试探。这套机制上线半年帮我们在外部服务商出问题的时候至少保住了团队内部的开发流程不被整体中断。7. 遇到的那些坑与解决方式7.1 平台差异导致的适配陷阱IE6悲剧在AI编程工具里也会重演。我们的Web端和小程序端早期共享了不少逻辑结果发现同一个任务在Web端展示正常在移动端却因为渲染引擎不支持某些内联样式而直接白屏。这不是业务问题而是适配问题。我们的统一解法是能力声明机制加逐端渲染回退。一个组件在注册时声明它需要的最低渲染能力客户端在渲染前做一次能力探测能力不足就用简化模板。比如编辑器diff视图在普通Web里是内联高亮在小屏端则降级成上一版/下一版的叠加卡片。核心逻辑完全没变变的只是表现层。7.2 长任务的中断恢复智能体跑长任务是常态但进程被杀就一切归零是不能接受的。我们引入了基于事件溯源的任务记录每一个已发布的子任务事件分配、执行中、执行成功、执行失败都追加写入本地事件日志。系统重启时编排层扫描事件日志重建任务树状态把中断时正在执行的子任务标记为需重跑并让Agent从最近的检查点续跑。检查点不是拍脑袋定的而是每个工具调用结束之后、每个代码变更写盘之后各落一次。这样最多损失一个工具调用的进度不至于整个任务从头来过。7.3 代码执行的隔离风险这个话题必须严肃对待。我们早期用直接exec跑Agent生成的代码差点酿成大祸——某个Agent在测试某个合法的列出目录结构命令时因为路径拼接疏漏读到了沙箱外的系统目录列表。从那以后我们彻底放弃了非严格隔离的想法。沙箱服务强制开启网络白名单只有内网特定域名可访问、文件系统视图基于OverlayFS重构Agent看到的整个文件系统是一个虚拟镜像写操作落在临时层任务结束后自动遗弃并关闭了一切涉及ptrace、mount、reboot等危险系统调用。每次任务执行前沙箱重新创建一个干净的镜像确保Agent之间的执行环境互不可见。内存配额默认1GBCPU配额默认一个核防跑飞。8. 生态扩展方向与我的实践体会8.1 生态扩展的下一步Agency Agents的平台适配器体系天然适合向更多端扩展。我们正在做的是浏览器DevTools集成和聊天软件机器人集成前者让前端调试时的代码修复直接在调试面板里内联呈现后者让人在聊天软件里就能把任务派给智能体收到结果再回来审核。这两块的接入成本确实比当初设计第一版适配器协议时低得多说明基础抽象没白做。8.2 项目落地过程中的几点经验如果让我提炼几条对这个项目的实操体会我会说架构上六层各管各的这种笨规矩真的要守。跨层调用一开始又爽又方便三个月后就是技术债高利贷。编排层的任务树状态要显式建模不要用聊天记录里的上下文隐式表示任务。多Agent协作的消息总线必须从一开始就支持消息重放和订阅否则排查问题会非常痛苦。工具的权限管理宁可过度设计也别先裸奔一次安全事故的代价远超你提前做安全设计付出的成本。再分享一个具体的写码习惯在规划器的输出里永远保留一段为什么这么拆的说明把它作为上下文传给执行Agent。执行Agent知道你让它做这件事背后的理由产出质量比盲目照做明显高一个档次。这是我们在几百次实测里反复验证过的——任务的上下文不仅仅是代码还包括决策意图。如果你也准备做一个跨平台的AI智能体系统我希望这篇架构实践的记录能帮你绕开一些我们踩过的坑。这套架构远不算完美但它在真实工程里的表现已经验证了多角色协作跨平台接入强隔离工具调用这几个核心思路的方向是对的。接下来的迭代里我们会继续在上下文蒸馏效率和多Agent冲突消解上打磨到时候再回来填坑。

Agency Agents：多智能体协作的跨平台AI编程架构实践

相关推荐

逆向分析实战：从静态到动态的App逆向工程方法论

浏览器内置大模型实战：零成本实现网页文案优化建议

UE5渲染管线源码深度解析：Lumen与虚拟阴影贴图实现

更多资讯

从符文到数学：教育游戏如何用规则设计点燃孩子的学习内驱力

LiteLLM统一接入多模型：从SDK到代理网关的工程实践

AI辅助App开发全流程：从想法到上架的实战指南

iOS 17游客内购失败原因与StoreKit 2账户声明方案

PDF分布式处理实战：轻量级架构与工程落地

栈与表达式求值：双栈法及中缀转后缀的机试实战

今日更新

小波包能量谱原理与MATLAB实现：从频带分解到故障特征提取

基于LSTM的网易云音乐评论情感分析：数据清洗与模型调优实战

Alpha-Beta剪枝与极大极小值算法：博弈树搜索原理与实战优化

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？