做AI编程智能体这件事我断断续续折腾了快两年。一开始只是用单个模型写点小脚本后来发现只要任务一复杂——比如“帮我重构这个模块再补上测试然后顺手把接口文档更新了”——单个Agent就开始顾此失彼。Agency Agents这个项目就是在那个背景下冒出来的它本质上是一套跨平台的AI编程智能体生态框架把模型、工具、会话、权限这些乱七八糟的东西统一到一起让我能同时指挥多个Agent干活还能在不同操作系统、不同模型服务和不同IDE之间自由切换。这篇文章不打算讲太多花哨的架构图就说说我在实际搭建和运行这套东西时踩过的坑、做过的取舍以及那些可以直接抄走的工程实践。先给一句总括Agency Agents不是某个特定产品而是一套由我自己维护的、面向AI编程场景的智能体编排框架。它的核心思路是“模型无关、工具可插拔、任务可编排”。你可以在macOS上调通一套Agent流程然后原样部署到Linux服务器上你在本地用开源模型测试完的逻辑切到云端商业模型API时不用改一行调用代码。这个“跨平台”对我们做研发的人来说太重要了因为AI编程环境本身就够杂了谁也不想被某一个模型服务或某个代码工具锁死。1. 为什么做Agency Agents单Agent的天花板与跨平台之痛1.1 单Agent的三大瓶颈我最早接触AI编程智能体是用聊天式助手改代码。模型确实能理解需求但顶多算个“升级版自动补全”。一旦涉及多个文件的改动它就像个记性不太好的人——你说完前面转头它就忘了后面。单Agent的第一个瓶颈是上下文窗口有限你不可能把一个中型仓库的所有代码塞进去就算塞进去token费用也扛不住。第二个瓶颈是工具调用混乱模型一会儿要读文件一会儿要执行命令如果工具没有一个统一的鉴权和管理机制很快就会出现权限混乱甚至误操作。第三个瓶颈是无法并行单Agent处理多个任务只能串行改完A才能改B这对稍微复杂一点的工程来说效率太低。我做过一次实验用同一个模型分别用单Agent和双Agent跑同一个“给某个Python模块增加异常捕获并补充测试用例”的任务。单Agent的方案是先读文件再改代码再写测试最后跑测试。听起来很顺但实际操作里模型在读完文件后经常把原始代码结构理解偏改出来的代码和原有风格不一致测试跑了三次才过。而让两个Agent协作——一个负责代码改造一个负责测试编写——反而效率高不少因为它们各管一段上下文更聚焦分工也明确。1.2 “跨平台”到底跨什么很多人一听到跨平台就只想到操作系统但AI编程智能体生态里的“跨平台”至少包含三层模型平台不同厂商的模型API包括云端商业模型、开源模型本地部署甚至公司内部自研的模型服务。它们的数据格式、认证方式、响应结构都不一样。运行环境开发者的笔记本可能是macOSCI服务器是Linux而有些遗留项目还得跑在Windows上。文件路径、命令执行、环境变量设置这些差异很磨人。开发工具链有人用VS Code有人用JetBrains系列还有人直接在命令行里操作。Agent需要能输出补丁、执行测试、调用linter这些操作在不同工具链下的表现也不一样。在Agency Agents里这三层都被抽象成了可替换的“适配器”。模型适配层解决第一个问题运行时抽象解决第二个问题工具注册体系解决第三个问题。这样做的直接好处是我可以在任何平台上沉淀一套Agent工作流换环境时只需要改一份配置不需要重写Agent逻辑。1.3 设计目标与边界项目开始前我给自己定了几个目标到现在都在沿用最小可跑一个Agent能跑起来的最少代码量要尽量低不能为了“生态”先写一堆基础设施。外部服务可替换所有第三方依赖包括模型API、数据库、消息队列都要有接口隔离。任务可观测每个Agent在做什么、用了哪些工具、消耗了多少token都必须能追踪到。权限默认拒绝Agent发起的任何外部操作默认都是拒绝的必须显式放行。也有明确不做的事不做自己的模型训练不做专门的IDE插件不做编程语言编译器。专注做好“智能体编排”这一件事。这个边界很重要否则项目很容易失控。2. 整体架构拆解一个可插拔的智能体生态2.1 核心模块总览Agency Agents的架构可以拆成五个互相独立的部分Brain大脑、Hands手、Memory记忆、Channel通信和Registry注册中心。Brain是Agent的决策核心负责理解任务、拆分步骤、选择工具。它本身不直接访问外部资源只通过结构化指令和工具交互。Hands是工具的具体实现比如执行Shell命令、读写文件、调用Git、发送HTTP请求。每个工具都要遵循统一的输入输出协议。Memory负责存储和检索上下文包括短期记忆当前任务相关的临时信息和长期记忆历史项目经验、用户偏好等。Channel是Agent之间以及Agent与用户之间的消息通道。它可以是简单的函数调用也可以是基于消息队列的异步通信。Registry是所有可用工具和Agent能力的元数据中心用一份统一描述文件登记它们的能力和参数。这五个模块之间有一条铁律Brain不能直接碰任何外部系统必须通过Hands。这样一来审计和权限控制就有了单一入口。哪怕某个模型突然“发疯”想执行rm -rf只要Hands里没有授权这个操作它就什么也做不了。2.2 模型适配层把不同模型统一成一个接口模型适配层是整个项目里最早稳定下来的模块。我的做法很简单定义一个统一的ModelProvider接口把模型之间的差异封装到各自的适配器里。下面是接口的简化版本class ModelProvider(ABC): abstractmethod def chat(self, messages: list[dict], tools: list[dict] | None None, **kwargs) - ModelResponse: 发送对话请求返回标准化的响应对象 ...然后为每一个模型服务写一个实现OpenAIProvider封装OpenAI风格API包括base_url、模型名、密钥等。AnthropicProvider封装Claude风格API处理其特有的系统提示词和工具调用格式。OllamaProvider封装本地Ollama服务用于测试和离线环境。CustomProvider接公司内部模型网关按内部规范处理。不同模型的返回格式差异很大尤其工具调用字段有的在tool_calls里有的在content里带特定标记。我这里把所有情况统一成自己的ModelResponse结构content字段是纯文本回复tool_calls字段是标准化的工具调用列表每个包含tool_name和arguments。下游所有代码只认这个结构不关心上游是哪个模型。这种做法还有个额外好处切换模型时可以直接做A/B对比。同一个任务用不同模型跑一遍把结果和token消耗记下来就能数据化地评估哪个模型适合哪种任务。2.3 工具注册与权限模型工具管理是我在这类项目里最看重的一环。Agent的能力完全由注册进来的工具决定而每个工具必须有三个东西描述description、参数模式parameter schema和执行函数executor。描述是给模型看的参数模式是给模型调用时用的执行函数是实际干活的部分。每注册一个工具必须声明它的危险等级tools: - name: shell_run description: 在本地环境执行任意Shell命令用于编译、测试、安装依赖。 parameters: command: string timeout: integer danger_level: high requires_approval: true - name: file_read description: 读取指定文件的内容支持相对路径和绝对路径。 parameters: path: string danger_level: low requires_approval: falserequires_approval是权限模型的开关。执行工具前Runtime会检查这个字段如果为true则把调用请求挂起等人工确认后再放行如果为false则直接执行。这个设计在初期帮我挡掉了不少灾难——模型没事就喜欢给你执行个git push --force没有这个保险机制仓库早被推没了。2.4 任务编排与消息总线多Agent协作的核心是任务编排。Agency Agents没有选择像某些框架那样搞一个中心化的“超级Agent”来控制所有子Agent而是采用了一个轻量级的消息总线。每个Agent都是独立的节点订阅自己感兴趣的任务类型发布自己完成的结果。举个例子一次代码重构任务可以被拆成三类子任务RefactorTask修改代码结构。TestTask生成或更新测试。ReviewTask审查代码变更检查风格和潜在bug。任务之间通过消息总线相连。RefactorTask完成的消息会触发TestTask测试不过的话又会回到RefactorTask手里重新处理形成一个人工智能参与的闭环。这个编排逻辑我用了一个很简单的JSON Schema来定义workflow: name: refactor_with_tests tasks: - id: refactor agent: code_agent next: [test] - id: test agent: test_agent next: [review] on_failed: [refactor] - id: review agent: review_agent next: []这个消息总线的好处是不需要维护复杂的全局状态每个Agent只需要关心自己收到的消息。坏处是任务流转的每一步都需要有明确的超时和重试策略否则某个消息丢了整个流程就会卡住。这个问题后面会专门讲。3. 从零到一的工程实现3.1 最小可运行骨架我不喜欢那种“先搭一个十天才能跑起来的框架”的工程方式。Agency Agents的最小骨架我只写了三个文件agent.pyAgent主体、tool.py工具基类、runtime.py运行时。整个框架在几百行内可以跑通“模型读文件、分析代码、执行测试”这条链路。先看工具基类# tool.py from dataclasses import dataclass, field from typing import Any, Callable dataclass class Tool: name: str description: str parameters: dict danger_level: str low requires_approval: bool False handler: Callable[..., Any] None def execute(self, **kwargs): if self.handler is None: raise NotImplementedError(fTool {self.name} has no handler) return self.handler(**kwargs)Agent主体需要接收模型提供者、工具列表和任务描述然后循环调用模型直到拿到最终结果# agent.py class Agent: def __init__(self, name: str, provider: ModelProvider, tools: list[Tool]): self.name name self.provider provider self.tools {t.name: t for t in tools} def run(self, task: str): messages [{role: system, content: 你是一个严谨的编程助手。}, {role: user, content: task}] max_steps int(os.getenv(AGENT_MAX_STEPS, 15)) for step in range(max_steps): response self.provider.chat( messagesmessages, tools[self._tool_specs()] ) messages.append(response.message) if not response.tool_calls: return response.content for call in response.tool_calls: tool self.tools.get(call.tool_name) if tool is None: messages.append({role: tool, tool_call_id: call.id, content: f错误未知工具 {call.tool_name}}) continue if tool.requires_approval: approve input(f确认执行 {call.tool_name} 参数: {call.arguments}? [y/N] ) if approve.lower() ! y: messages.append({role: tool, tool_call_id: call.id, content: 用户拒绝执行此工具调用}) continue result tool.execute(**call.arguments) messages.append({role: tool, tool_call_id: call.id, content: json.dumps(result, ensure_asciiFalse)}) raise RuntimeError(达到最大步骤数任务未完成)这个骨架虽然简陋但它把Agent循环的四个基本环节都体现出来了接收反馈、决策、执行工具、继续反馈。后面所有复杂功能包括记忆、多Agent协作、重试策略都是在这个循环上扩展的。3.2 跨平台配置文件怎么写跨平台这件事我采用的方式是“环境归一化”。也就是说在进入Agent逻辑之前先通过一层配置把所有平台差异抹平。每个平台有一套配置文件描述路径分隔符、Shell类型、Python解释器位置、Git可用性等。一份环境配置长这样# config/windows.yaml platform: windows shell: cmd temp_dir: %TEMP%/agency path_separator: \\ git_available: true python_interpreter: py -3 env: AGENT_WORKSPACE: C:\\workspace\\agency # config/linux.yaml platform: linux shell: /bin/bash temp_dir: /tmp/agency path_separator: / git_available: true python_interpreter: python3 env: AGENT_WORKSPACE: /home/user/workspace/agency这个配置的主要使用者是shell_run这类工具。比如执行测试时工具读取python_interpreter字段按不同平台逐步构造命令。这样Agent里写的任务逻辑不需要关心自己是在Windows还是Linux上。为了让配置切换更自动化我还写了一个小的自动探测脚本启动时检测sys.platform和关键命令是否存在自动加载对应的配置文件。如果platform没有匹配项就抛出一个明确错误提示“当前平台没有配置请参考config/windows.yaml补充”。3.3 上下文管理与记忆持久化模型上下文窗口再大也扛不住多轮工具调用的日志堆积。我最早天真地把所有历史消息都塞回给模型结果跑了十轮工具调用后token消耗直接翻倍而且模型开始“忘记”最初的指令。后来我采用了三层上下文管理策略关键信息摘要每轮对话完成后用一个独立的摘要Agent把长期不变的信息压缩成简短笔记替换掉冗长的原始历史。工具结果截断file_read和shell_run这类工具返回的内容会设置一个最大长度阈值超出部分用“已截断仅展示前2000字符”代替。需要完整内容时模型可以显式调用一个新的读取范围。会话生命周期分离短对话用内存缓存项目级长期记忆存本地SQLite。只有跨会话需要的信息才写入长期记忆。关于长期记忆我用的表结构非常简单CREATE TABLE memory ( id INTEGER PRIMARY KEY AUTOINCREMENT, project_id TEXT, key TEXT, content TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); CREATE INDEX idx_memory_project_key ON memory(project_id, key);新的Agent会话开始时可以先按project_id把相关记忆查出来注入系统提示词里。比如之前遇到过某个项目里测试命令需要额外加--no-cov参数这个信息被保存后下次会话调测试工具时就不会再踩同样的坑了。3.4 多Agent协作实例一个代码审查任务前面说的都是单Agent能力真正强大的还是多Agent协作。我拿一个具体的代码审查任务来展示整个流程。任务背景是仓库里有一个函数写得特别长需要拆成几个小函数并保证行为不变。我定义了三个Agentplanner负责分解步骤输出一份简洁的改造计划。coder按计划实际修改代码运行测试直到通过。reviewer审查diff检查变量命名、边界条件和潜在的回归风险。它们之间没有硬编码的顺序而是通过一个“任务状态机”来控制planner完成后把计划发到plan_completed频道。coder订阅了这个频道收到计划后开始工作工作完成后发code_ready消息。reviewer订阅code_ready审查后发review_completed如果发现问题可以附带fix_suggestions发回plan_completed频道让coder继续改。这个流程在落地时遇到了不少问题最典型的是“鸡同鸭讲”。planner输出的计划是自然语言长段落coder理解不到位经常抓不到重点。后来我规定planner的输出必须是一个固定格式的JSON数组每个元素包含file、actions、notes。coder只解析这个JSON不再读长篇大论。格式化的结构化消息极大减少了多Agent之间的理解偏差。下面是这个流程的一个简化代码片段# workflow.py from collections import defaultdict class TaskBus: def __init__(self): self.subscribers defaultdict(list) def subscribe(self, channel, handler): self.subscribers[channel].append(handler) def publish(self, channel, payload): for handler in self.subscribers.get(channel, []): handler(payload) bus TaskBus() def on_plan_completed(plan): # coder 拿到计划开始实现 bus.publish(plan_completed, plan) bus.subscribe(plan_completed, coder.implement) bus.subscribe(code_ready, reviewer.review)任务总线是异步的吗最开始不是后来生产环境里任务多了我把它换成了Redis Stream做底层但上层接口不变还是publish/subscribe。这样在单机调试时可以跑内存队列部署到服务器时切换Redis整个过程对业务代码透明。4. 生产环境踩坑实录4.1 网络与模型超时模型API不是永远可靠的尤其在调用大模型时动辄几十秒的响应延迟很常见。最初我的代码里没有设置超时一个Agent卡在网络请求上能卡半小时整个任务队列全被堵住。后来我做了两件事给每个模型调用设置合理的超时上限默认60秒可以按模型类型调整。增加“指数退避重试”机制。第一次超时后等2秒重试第二次等4秒第三次等8秒最多重试5次。如果还是失败就把任务标记为失败并通知周围的协作Agent。重试时要注意幂等性。模型请求本身是幂等的但工具执行不一定是。比如git commit这种操作重试两次就会产生两个重复提交。所以我给每次工具执行生成了一个全局唯一的execution_id在工具内部判断同样参数的执行是否已经发生过如果发生过就返回上次的结果缓存。4.2 工具调用的幂等性与回滚提到幂等性这里展开说说。AI编程智能体最危险的地方在于它会在你眼皮底下执行有副作用的命令。一次代码重构Agent可能连续执行了十几次sleep 10 git commit -m refactor哪怕它是按正常逻辑跑的最后也会产生一堆重复提交。我的解决方案是给关键工具增加一个“计划-确认-执行-回滚”四阶段机制。以git_commit为例计划阶段Agent生成想要提交的commit message和变更范围工具返回一个计划ID。确认阶段需要人工确认或者通过配置的自动审批规则确认。执行阶段执行实际命令。回滚阶段如果执行后的验证失败比如测试挂了可以根据计划ID执行git reset --hard HEAD~1回到之前的状态。这个机制不是所有工具都需要但凡是会修改状态的高危工具我都强制要求实现。还有一点文件修改类的工具尽量做成“先写临时文件再替换原文件”。这样如果Agent中途写乱了原文件还在可以直接恢复。我见过不止一次模型把整个源文件用一段不完整的内容覆盖掉的场面没有备份的话那个上午就全废了。4.3 上下文溢出与压缩策略上下文溢出是每天都会遇到的事。一个Agent改完一个文件后为了继续改下一个文件需要把前面的文件内容全部记在脑子里这很快就把窗口塞满了。我踩过一个很蠢的坑把所有文件都塞进一个系统提示词里想着“模型看得越多越全面”结果模型输出质量反而下降因为它没法在几千行代码里精准找到要改的那一小块。后来我换成了“局部感知”策略先让Agent读取项目的目录树和关键入口文件形成“地图”。真正要改某个文件时只读取该文件并读取和它直接相关的几个依赖文件。文件内容进入上下文前先用一个预处理Agent做精简去掉注释和无关代码保留函数签名和主干逻辑。这个策略让同样规模的代码任务token消耗大约少了60%而完成质量没有下降。代价是预处理Agent也需要算力和时间但总体还是划算的。4.4 权限失控Agent闯祸的三次教训权限失控是最严重的问题。我记得有三件印象很深的事第一次是Agent执行了pip install --upgrade把环境里所有包升级了一遍导致另一个项目跑不了了。从那以后pip install类命令被默认禁用除非在配置里显式放行。第二次是Agent为了“测试”某个接口对生产环境的数据库执行了删除操作。好在有权限拦截它执行前弹出了确认框我及时拦住了。从那次开始数据库写操作类工具都设置了requires_approval: true甚至某些高危操作直接不进工具注册表。第三次是Agent在格式化代码时把整个目录下的所有文件都按同一风格改写了一遍结果git diff巨大无比根本没法review。教训是给Agent的工具必须带范围参数比如format_path必须限定在某个子目录内。在我的经验里权限控制宁可“过度安全”也不要“宽松”。每次误操作的恢复成本都远高于确认一下的麻烦成本。4.5 问题排查速查表这里整理一个我在实际运维里反复用到的排查速查表症状可能原因检查方法解决方案Agent一直不执行工具模型响应中没有工具调用字段查看模型返回原始日志检查模型是否支持function calling或工具描述是否清晰工具执行成功但Agent仍报错工具输出格式不符合预期打印工具返回的JSON结构统一工具返回格式让模型清楚如何解析任务卡在等待确认权限配置为需要人工确认但无人值守检查任务状态和管理界面区分交互模式和非交互模式非交互模式自动跳过需确认工具多Agent循环互相覆盖修改共享文件被多个Agent同时写查看文件修改时间线和git log给文件加锁同一时间只允许一个Agent写上下文突然爆掉工具返回了超大文件内容查看token统计启用工具结果截断启用局部感知策略模型输出乱码不同模型编码处理不同打印原始字节统一使用UTF-8并在适配层做编码检测5. 实测效果与可复用的经验5.1 对比单Agent的提升数据在几轮真实代码任务上我记录了一些数据不严谨但能反映趋势。同样一个“为某模块增加单元测试并修改两处边界bug”的任务指标单Agent双Agent协作编码测试完成时间约28分钟19分钟工具调用次数4652失败重试次数73最终测试通过第3次通过第2次通过人工介入次数2次1次从数据看多Agent协作并没有减少工具调用总量甚至更多但因为分工清晰、上下文专注反而减少了无效重试最终效率更高。当然如果任务很简单比如“修复一个变量名拼写错误”单Agent反而更省多Agent反而引入调度开销。所以我最终的判断是任务的复杂度和并行度达到一定阈值时多Agent才有价值。5.2 迁移到新平台的实测我专门做过一次“平台迁移”测试把一套在Linux上跑通的Agent工作流迁移到Windows环境全程不修改Agent业务代码只改配置和环境脚本。迁移过程中遇到的主要问题集中在三处路径分隔符/和\混用统一走配置里的path_separator解决。Shell差异Linux用bashWindows用cmd或者PowerShell工具实现里加一个shell参数选择器。Python环境不同平台解释器名称不同配置里指定后无需修改代码。实际迁移耗时不到半天其中大部分时间花在手动测试工具链上。这个结果让我对“跨平台”这件事更有信心了。5.3 一点个人的实操心得最后说一点我在反复调这套框架时攒下的感悟。最能提升AI编程智能体成功率的往往不是模型本身多强而是你给它的工具和约束是否清晰。模型就像一个能力很强但不熟悉你项目的新同事它需要一份明确的使用手册哪些命令能用、哪些不能、文件往哪里写、测试怎么跑。把这些约束写进工具描述和权限配置里比你在提示词里反复强调“要小心”有效得多。另外任何一个Agent任务都应该设计成“可重跑”的。它跑挂了你要能一键恢复到上一个稳定状态然后调整提示词或工具参数重来。我一般每个任务都会配一个run.sh脚本里面包含清空临时目录、重新生成Agent会话、设置环境变量。这样调试起来效率极高。Agency Agents这套东西我没有刻意做成一个“产品”它更像是我日常开发工具箱里的一件趁手家伙。但它反映出来的思路是可以复用的模型无关、权限隔离、局部感知、可重跑、可观测。如果你也在做AI编程智能体相关的东西希望能从这篇文章里找到一两个可以直接落地的点。拿一个小小的建议收尾吧不要一开始就追求复杂的大模型编排先写好一个最小闭环跑通一次“读文件-改代码-执行测试”的循环再往里面加更多Agent和工具。你会发现基础稳定了上层怎么长都顺。