最近一年多智能体系统这个词几乎被各种框架和社区项目反复包装但真正能落地解决问题的编排方案并没有想象中那么多。我最近在做的 Antigravity 多智能体系统就是一套把代码生成能力和通用对话能力拆开分别交给 Copilot 与 Claude 负责的编排系统。简单说系统里有三个角色一个编排器一个代码代理一个分析代理。代码代理专门接生成和修改代码的任务分析代理负责代码审查、技术问题答疑、方案对比。整套系统不是简单把两个 API 串成一个 API而是让每个代理拥有自己的上下文和工具再由编排器统一调度。这篇文章会把完整搭建过程里的架构决策、代码实现、踩坑记录全部展开适合正在做多智能体编排、或者想把自己手上的 AI 工具从“单点调用”升级成“多角色协作”的人参考。1. Antigravity 系统的设计初衷1.1 为什么把 Copilot 和 Claude 放在同一个系统里过去两年我试过很多种用法拿一个模型既写代码又做分析往往都会出现“偏科”的问题。代码生成场景里Copilot 这类模型对于补全节奏、语法结构、常见框架的惯用法响应更直接生成结果更像一个熟悉代码库的结对程序员。而 Claude 这边优势在长上下文理解和推理让它去读一段复杂业务逻辑然后给出漏洞分析比单纯让它生成代码更可靠。把两者集成到一个系统后最直观的好处是任务能按能力分工。生成任务分发到 Copilot 代理分析任务分发到 Claude 代理各自不用做自己不擅长的事。这样做不是为了提高某一个环节的“刷分效果”而是为了在实际工程里得到更稳定的结果。另一个原因是成本结构。日常开发请求里有大量简单补全也有少量复杂方案评审。如果所有请求都丢给同一个高能力模型成本会一直保持高位。拆开以后简单任务走轻量链路复杂任务走深度链路整体预算更可控。Antigravity 的底层设计说白了就是“路由逻辑 双代理 共享上下文”这三个东西组合起来才叫多智能体系统而不是简单地同时调用两个模型。1.2 核心使用场景与边界Antigravity 不是又一个大而全的 AI 助手它解决的是几个非常具体的工程问题。第一个场景是代码补全与片段生成。Copilot 代理维护当前代码库上下文收到任务后返回 diff 或完整函数实现。第二个场景是代码审查。Claude 代理读取代码变更内容对照用户给出的检查清单输出问题列表和修改建议。第三个场景是技术方案答疑。用户在项目里提出一个“怎么设计任务队列”的问题编排器会把问题整理成带项目上下文的 prompt交给 Claude 代理回答。边界也很清晰不做自主写长期任务计划不自动改动外部系统不在没有用户确认的情况下部署代码。系统里所有代理的行为都是“建议生成”最终决策权在人类手里。明确了边界之后后续的接口设计和安全控制才有据可依。1.3 为什么选择自研编排层一开始我也考虑过直接套现成的多智能体框架但用了几个之后发现框架最大的问题是把抽象定得太高遇到需要同时对接两家不同风格服务商的接口时反而要写大量适配层。后来决定自己写一个轻量编排器只保留三个核心能力消息路由、任务状态跟踪、上下文汇总。代码量不多但每个环节都可控。这个决策背后有个很实际的考虑Antigravity 以后一定还要接入新的智能体比如本地小模型、专门的 SQL 生成器如果底层被某个框架锁死扩展起来会非常痛苦。自己维护一个只有几百行核心逻辑的编排器所有事情都能看得见摸得着。2. 架构设计与通信机制2.1 中心化编排模式Antigravity 采用“中心编排器 工作节点”的组织方式。编排器是整个系统的中枢负责接收外部请求识别意图拆分任务调用对应的代理再汇总结果。工作节点只有两类Copilot 代理和 Claude 代理它们不直接通信所有消息都经过编排器中转。我为什么不采用完全去中心化的“代理之间相互聊天”模式因为那在工程上很难收敛。几个代理自由协商时经常会出现绕圈、重复消息、上下文相互污染的问题。中心化模式是牺牲了一点灵活性换来每个人都能看清楚“当前系统到底在干什么”。对于生产环境这个取舍非常重要。2.2 统一消息协议为了让多个代理能协作必须统一消息格式。我用 Pydantic 定义了一个基础消息模型核心字段包括消息 ID、发送者、接收者、消息类型、内容、关联任务 ID、时间戳。消息类型分三类request、response、tool_call。其中tool_call用在需要调用外部工具的场景比如 Copilot 代理需要读取某个文件内容后才能补全代码。统一协议最大好处是后续任何一个新代理只要遵循同样的消息模型就能接入编排器实现真正的可插拔。2.3 上下文管理私有记忆与公共黑板多智能体系统最容易翻车的地方是上下文混乱。我在 Antigravity 里采用了双层上下文机制。每个代理有私有记忆区保存和自己工作最相关的信息。代码代理会记住它最近生成的几个文件路径和风格偏好分析代理会记住它最近审查过的代码模式。公共黑板区域保存所有代理都能读到的全局信息比如当前任务的目标、代码仓目录结构、用户最近的几条指令。请求进来时编排器先向公共黑板写入摘要再把任务分发给代理代理返回结果后编排器把关键结果同步回黑板。这样设计的好处是上下文不会无限膨胀。私有记忆保证了专业性公共黑板保证了协作信息同步。3. Copilot 与 Claude 代理的集成实现3.1 抽象通用 Agent 接口在写具体接入代码之前先定义所有代理共用的抽象类。每个代理只需要实现两个方法handle_request和build_prompt。from abc import ABC, abstractmethod from dataclasses import dataclass, field from typing import Any dataclass class AgentContext: task_id: str user_query: str code_snippets: dict field(default_factorydict) other_agents_output: list field(default_factorylist) class BaseAgent(ABC): def __init__(self, name: str, config: dict): self.name name self.config config self.memory: list[dict] [] abstractmethod def build_prompt(self, context: AgentContext) - str: ... abstractmethod def handle_request(self, context: AgentContext) - str: ...这个抽象层是整个系统稳定运行的基础。一旦接口统一了后面的编排器就不需要关心每个代理内部用的是谁的模型、什么参数只要拿到一个字符串结果就行。3.2 Copilot 代码代理实现Copilot 代理的工作主要是代码补全和代码修改。实现时需要注意不能把整份代码库塞进 prompt那样既不经济也会超出上下文窗口。合理做法是让编排器提前做好代码定位代理只接收“文件路径 相关片段 任务说明”。import os import requests class CopilotAgent(BaseAgent): def __init__(self, config: dict): super().__init__(copilot, config) self.endpoint config.get(endpoint) self.api_key config.get(api_key) def build_prompt(self, context: AgentContext) - str: code context.code_snippets.get(target_file, ) return f你是一个严格的代码实现助手。 请根据下面的代码片段和用户需求生成修改后的代码。 需求 {context.user_query} 当前代码 python {code}要求只输出修改后的代码块不要输出额外解释。保持原有代码风格。如果需求描述不清晰请用 # TODO 标注。 def handle_request(self, context: AgentContext) - str: prompt self.build_prompt(context) resp requests.post( f{self.endpoint}/completions, headers{Authorization: fBearer {self.api_key}}, json{ prompt: prompt, max_tokens: 2000, temperature: 0.2, }, timeoutint(self.config.get(timeout, 60)), ) resp.raise_for_status() result resp.json()[choices][0][text] self.memory.append({task_id: context.task_id, result: result}) return result这里把 temperature 设成 0.2是为了让代码生成更稳定。代码生成任务和发散型写作不一样温度太高会让输出出现各种不必要的“创意”低温度配合清晰的 prompt 结构实测下来补全质量最可靠。 ### 3.3 Claude 分析代理实现 Claude 代理负责代码审查、技术方案分析。它的 prompt 更强调推理过程需要用户能看到“为什么会发现问题”。 python class ClaudeAgent(BaseAgent): def __init__(self, config: dict): super().__init__(claude, config) self.endpoint config.get(endpoint) self.api_key config.get(api_key) self.model config.get(model, claude-3-5-sonnet) def build_prompt(self, context: AgentContext) - str: code context.code_snippets.get(target_file, ) return f你是一个资深代码审查专家。 请审查下面的代码输出必须包含三部分 1. 问题概述 2. 具体问题和严重程度高/中/低 3. 修改建议 用户额外关注点 {context.user_query} 代码内容 python {code}请注意输出要保持客观不要重复代码中已有的注释。 def handle_request(self, context: AgentContext) - str: prompt self.build_prompt(context) resp requests.post( f{self.endpoint}/messages, headers{ Authorization: fBearer {self.api_key}, Content-Type: application/json, }, json{ model: self.model, messages: [{role: user, content: prompt}], max_tokens: 3000, temperature: 0.3, }, timeoutint(self.config.get(timeout, 90)), ) resp.raise_for_status() result resp.json()[content][0][text] self.memory.append({task_id: context.task_id, result: result}) return result审查类任务不适合频繁重试所以我一般把 timeout 设置得比生成任务更长。代码审查往往需要模型上下文一旦超时编排器要决定是重试还是降级处理。 ### 3.4 编排器调度逻辑 编排器是整个系统的核心决策单元。它要先判断当前任务应该给哪个代理然后再决定是否需要两个代理协作完成。 代码实现如下 python import uuid class Orchestrator: def __init__(self, agents: dict): self.agents agents self.board: dict[str, dict] {} def _route(self, query: str) - list[str]: if any(word in query for word in [生成, 补全, 写一个, 实现, 修改函数]): return [copilot] if any(word in query for word in [审查, 分析, 方案, 对比, 优化建议]): return [claude] return [copilot, claude] def run(self, user_query: str, code_snippets: dict): task_id uuid.uuid4().hex[:8] context AgentContext( task_idtask_id, user_queryuser_query, code_snippetscode_snippets, ) chain self._route(user_query) results [] for agent_name in chain: agent self.agents[agent_name] result agent.handle_request(context) context.other_agents_output.append(result) results.append({agent_name: result}) # 写入公共黑板 self.board[task_id] { query: user_query, agent_output: results, } return self.board[task_id]这个编排器虽然是极简版但已经支持“单代理任务”和“双代理接力”两种模式。当用户提出“生成一段同步代码然后审查一下”这种复合需求时用关键词匹配确实不够全面却已经能覆盖大部分开发场景。如果后续要支持更复杂的意图可以在这里接入另一个分类模型。4. 实操过程与关键环节记录4.1 从零配置项目环境搭建 Antigravity 时我按下面这几步操作。创建 Python 虚拟环境使用 Python 3.11 版本保证asyncio和pydantic都能正常工作。安装依赖库只用了requests、pydantic、python-dotenv三个核心库尽量精简。配置环境变量文件.env保存两套密钥和服务地址。建立agents/目录分别放base.py、copilot_agent.py、claude_agent.py再加一个orchestrator.py。在本地开发阶段我建议不要直接把密钥写入代码而是全部通过环境变量读取。万一代码不小心提交到仓库也不会把密钥泄露出去。python -m venv .venv source .venv/bin/activate pip install requests pydantic python-dotenv # 配置环境变量 cat EOF .env COPILOT_ENDPOINThttp://your-gateway/v1 COPILOT_API_KEYyour_copilot_key CLAUDE_ENDPOINThttp://your-gateway/v1 CLAUDE_API_KEYyour_claude_key CLAUDE_MODELyour-claude-model-id EOF4.2 用一段真实请求跑通整个链路我拿一个非常常见的开发请求做测试“生成一个读取 CSV 文件并返回统计信息的函数然后审查这段代码是否存在异常处理问题。”第一步编排器收到请求后因为关键词“生成”和“审查”同时出现路由结果为[copilot, claude]。Copilot 代理先执行生成代码如下import csv from pathlib import Path def load_csv_stats(filepath: str) - dict: rows [] with open(filepath, r, encodingutf-8) as f: reader csv.DictReader(f) for row in reader: rows.append(row) return { total_rows: len(rows), columns: list(rows[0].keys()) if rows else [], preview: rows[:5], }第二步编排器把这段代码交给 Claude 代理审查。Claude 代理输出了一份问题列表指出代码没有处理文件不存在、CSV 文件为空、编码不规范等情况并给出了修改版建议。最后编排器把 “生成结果 审查结果” 合并返回给用户。这个测试说明了一个关键点多智能体协作不是把多个模型的结果简单拼接而是前一个代理的输出会变成后一个代理的输入形成一条完整的处理链。4.3 成本控制和并发设计在生产环境里我强烈建议给每个代理设置独立的超时时间和最大并发数。Copilot 的补全请求通常比较快并发可以调高Claude 的审查请求耗时较长并发需要压低否则很容触发上游限流。可以在编排器外面加一个简单的信号量import asyncio class RateLimiter: def __init__(self, max_concurrent: int): self.sem asyncio.Semaphore(max_concurrent) async def run_agent(self, agent, context): async with self.sem: loop asyncio.get_event_loop() return await loop.run_in_executor(None, agent.handle_request, context)这样能防止同时发出太多请求把服务商打爆。成本上我也建议加一层缓存同一个任务如果 hash 相同可以直接返回上一次的结果省掉很大一笔重复调用费用。5. 常见问题与排查技巧实录5.1 多智能体系统最容易遇到的四个问题我整理了一张排查表都是这套 Antigravity 系统实际运行中遇到的问题。现象可能原因处理方法两个代理结果互相矛盾上下文没有同步检查公共黑板确认任务上下文是否包含其他代理输出Copilot 补全结果明显偏离需求prompt 里代码定位不准确提升代码片段定位精度给代理提供更多相关代码Claude 审查结果空洞没有具体问题prompt 缺少项目背景在审查 prompt 中加入项目技术栈和业务背景请求超时频繁并发设置过高或单次响应过长降低并发数延长超时时间增加重试策略API 返回格式不匹配不同服务商字段命名不一致在代理层做统一解析不要直接透传原始响应其中上下文不同步是最隐蔽的问题。如果两个代理各自持有自己的记忆但它们的记忆容量不同就会出现“A 代理知道文件结构但 B 代理不知道”。我用公共黑板机制解决之后这类问题少了很多。5.2 踩过几次坑之后的硬经验第一个硬经验多智能体系统的调试难度会随着代理数量增加剧烈上升。只要能把任务分成两个代理干就不要拆成四个。Antigravity 目前只有两个工作代理在实际运行时都非常容易出现“一个代理的错误输出误导另一个代理”的情况。以后每加一个代理都要重新设计一轮上下文流转绝不是简单注册一个类就行。第二个硬经验prompt 模板必须带版本号。每次修改 Copilot 或 Claude 的 prompt都要在代码里留下版本记录。否则当结果质量突然变化时你根本不知道是哪次改动引起的。我现在的做法是每个代理的build_prompt返回开头都会携带# prompt-v2.1这样的注释日志一对比就能定位。第三个硬经验不要盲目信任入口路由。关键词匹配在 70% 的情况下够用但遇到“帮我优化这个函数并对比两种写法”这种请求关键词路由很容易走错分支。我现在的方法是给路由结果加一个置信度评分当置信度不高时默认走[copilot, claude]双代理链路让两个模型各自发挥然后由编排器做汇总。宁可多花一点调用成本也不要让用户拿到明显错误的结果。第四个硬经验日志信息必须包含每个代理的 tokens 消耗。多智能体系统的成本是一个累加过程如果不在每一层记录用量月底账单会非常难看。我用一个非常简单的装饰器每次代理返回结果时把模型、输入 tokens、输出 tokens、任务 ID 记入日志文件。6. 扩展方向与最后的个人体会Antigravity 这套架构后面还有几个明显可扩展的空间。一个是接入第三个专用代理比如本地小模型专门做代码格式化或 lint 检查因为这类任务要求低延迟且敏感数据不出内网。另一个是在编排器里加入“评估员”代理让每次生成和审查的结果都自动打分形成反馈数据再反哺优化每个代理的 prompt。我自己的实际感受是多智能体系统真正难的从来不是调 API而是把系统架构里的每个环节都变得可解释、可观测、可控制。Copilot 和 Claude 的集成只是第一步Antigravity 更重要的价值是把原本分散的模型能力变成一条稳定的工程流水线。搭建的过程中如果发现两个代理开始相互推诿、来回横跳先别急着责怪模型回到编排器看看上下文到底传了什么绝大部分问题都会一目了然。