做 AI 代理AI Agent这件事眼下最大的误区不是“模型不够强”而是大多数个人开发者把精力都花在换更大的模型上却没有搭建起让多个代理协作的工程骨架。结果就是单看某个代理的回复能力还可以一旦让它独立完成一个多步骤任务就频繁卡在任务拆解、工具调用、状态流转和结果校验上最后只能用“单 Agent 硬跑”的方式凑合。这篇文章想讨论一个更现实的问题不靠顶级 GPU不算每个月大几千的 API 高配支出只用手头的中档配置比如一张消费级显卡甚至只有 CPU怎么搭出一支比大多数个人开发者做得更好的 AI 代理团队。先给一个明确结论决定一支 AI 代理团队上限的不是某一个模型聪明不聪明而是编排、记忆、工具、评测这四个工程环节。模型只解决“生成能力”代理团队解决的是“把复杂任务稳定地做完”。中配方案的核心思路就是“本地模型 API 模型混编”让便宜的本地模型承担结构化、分类、抽取等高频任务让云端模型承担复杂推理和最终生成既控制成本又保证质量。这里先做一点术语说明。本文说的“代理”是 AI Agent也就是 AI 智能体它指的不是网络代理而是能感知任务、调用工具、执行动作、根据结果迭代的自动化单元。一支 AI 代理团队就是让规划者、编码者、审查者等不同角色协作把单个大模型做不好的复杂任务拆碎、分工、验证、交付。全文按“概念 - 架构 - 环境 - 代码 - 验证 - 排错 - 最佳实践”的顺序展开所有代码和命令都给出完整可复制版本建议收藏备用。1. 先搞清楚什么才算一支“AI代理团队”1.1 从单 Agent 到多 Agent 的差别一个单独的 AI Agent本质上是一个“能循环调用大模型的进程”。它的标准执行链路是接收任务生成下一步计划调用工具观察结果再决定下一步。这套链路如果跑得顺单 Agent 已经能完成很多工作比如自动总结文档、生成代码片段、操作浏览器等。但单 Agent 的瓶颈很明显它必须在一个上下文里同时完成“理解任务、规划方案、编写代码、检查错误”四件事。一旦任务步骤变多上下文会被历史信息占满模型会忘记最初的目标或者在高频生成中累积错误。你可以想象一个开发团队只有一个人这个人同时做产品设计、写代码、测试和部署不是不可能但效率和质量都难以保证。多 Agent 团队则把不同职责拆给不同角色。每个 Agent 只负责一个小而清晰的环节上下文更短提示词更聚焦输出格式更容易控制。更重要的是不同角色之间可以互相校验规划者拆任务编码者写代码审查者找问题。这种结构天然减少了大模型“自说自话、错了也继续”的问题因为审查环节本身就是在制造一次交叉验证。1.2 代理团队能解决什么单 Agent 解决不了的问题最典型的场景是代码生成。单 Agent 让大模型直接写一个完整项目经常出现第一次生成时思路是对的但生成到第二十步时它已经把前面定义过的函数名忘记了。代理团队的处理方式则完全不一样。规划者先把“写一个带单元测试的 Python 命令行工具”拆成三个步骤设计接口、实现核心逻辑、编写测试用例。编码者根据每个步骤分别产出代码。审查者拿到代码后逐一检查语法、依赖和安全问题。如果审查发现问题编码者只针对问题修改而不是整个重写。这种“分而治之 交叉审查”的模式能让任务完成率显著提升尤其是在代码量超过 200 行的任务上。除了代码生成代理团队也适合研究报告整理、数据分析流水线、批量文档处理、自动化测试生成、多维度信息检索再汇总。共同特征是任务可以被拆解且拆解后的子任务之间有清晰的输入输出。1.3 不适合代理团队的场景也要说清楚边界。几十字的简单问答、只需要一次性调用模型翻译或总结的任务完全没必要上代理团队。代理团队有额外的编排开销每次多角色调用都会增加延迟和成本。如果一个单 Agent 一个提示词就能解决强行上多 Agent 只会让简单问题复杂化。更需要注意的是一类“伪协作”场景多个 Agent 之间没有明确分工也没有交叉校验只是轮流在大模型之间传话。这种设计并不会带来质量提升反而会让错误在对话链里不断放大最终输出比单 Agent 更差。2. 为什么 99% 的人搭不好代理团队2.1 差距不在模型在工程标题里的“99%”当然不是统计学数字更像是一种提醒多数个人开发者的代理系统目前还停留在“套一层提示词”的阶段。他们会写一个 System Prompt告诉模型“你是一个全能的助手”然后把所有任务都塞给一个模型。这种做法不是代理团队只是一个有提示词包装的单 Agent。真正拉开差距的是工程化能力。大模型本身擅长生成文本但不擅长保证格式稳定、不擅长记住跨轮次的状态、不擅长控制自己的调用次数。代理团队的搭建者本质上是在给模型配一套工程护栏让模型按 JSON 输出、让多轮循环有终止条件、让不同角色之间传递的数据结构固定、让每次调用都可以被记录和回放。这些工作不性感但决定了系统能不能稳定运行。2.2 四个关键短板多数代理团队做不好集中体现在四个环节环节失败表现影响编排没有明确的状态机角色之间靠“对话”传递信息流程不可控任务跑一半就散架记忆所有历史一股脑塞进上下文上下文爆炸模型忽略关键信息成本飙升工具只让模型“输出内容”没有真正接入可执行的工具代理无法完成“查数据、改文件、执行命令”等动作评测用肉眼判断输出好坏无法迭代改了提示词也不知道是好是坏如果做一次复盘你会发现大多数代理项目失败不是模型的生成能力差而是这四个环节里至少有一个没设计好。比如编排不清晰代理可能在同一个步骤上反复循环记忆不分层长任务跑到中段就开始“失忆”工具权限过大一轮对话就导致安全问题没有评测集则完全无法形成改进闭环。2.3 一个常见的失败案例假设你想做一个“自动写周报”的代理团队。初级做法是让一个 Agent 读取本周 Git 提交记录、对话记录和工作文档然后直接生成周报。听起来很合理实际跑起来会出现它读了大量无关的提交记录上下文被占满它分不清“本周完成事项”和“下周计划”应该用什么语气写它可能把某个临时分支的代码提交当成正式成果写进周报。改成代理团队之后流程会变成采集者只负责提取和过滤信息用结构化字段输出规划者把周报拆成“成果、问题、计划”三段写作者按模板生成审查者检查是否有夸大或遗漏。每个 Agent 的上下文都很短任务边界清晰输出的周报质量反而更稳定。这就是工程结构带来的差异。3. 中配方案的整体架构3.1 什么是“中配”“中配”指的是一个折中方案硬件上不一定需要高端多卡 GPU配置目标是让本地模型能跑起来同时把重活交给 API。具体硬件门槛本文后面会详细说。与“低配”相比中配会认真规划本地和云端的分工而不是完全依赖免费的在线小模型与“顶配”相比中配不会追求全流程用超大模型而是用路由策略让每一分钱都花在刀刃上。从材料看最近行业里“AI代理助手加本地模型”之所以热正是因为越来越多的开发者意识到完全依赖云端 API有成本、隐私和网络依赖问题完全依赖本地小模型又容易在复杂推理上质量不足。中配方案把两者结合让代理团队的底座既有本地模型的私有性又有云端模型的上限能力。3.2 整体架构本地模型 API 模型混编中配代理团队的整体架构可以分为四层接入层接收用户任务判断任务类型和复杂度。路由层根据任务复杂度决定调用本地模型还是云端 API。代理层多个角色分工协作包括规划者、编码者、审查者等。工具层库、文件、命令、搜索等外部能力供代理调用。路由层是“中配”的核心。一个简单的路由规则可以是信息抽取、格式整理、文本分类、简单问答等高频低难度任务走本地模型代码生成、冲突分析、多步推理、最终质量把关等低频率高难度任务走云端 API。通过这种路由大部分调用量沉淀在本地模型上API 只承担关键节点的生成任务成本能大幅下降。3.3 代理团队的角色设计角色设计不需要模仿大型团队最少三个角色就能成型角色职责输入输出Planner 规划者把任务拆成可执行步骤用户任务步骤列表Coder 编码者根据步骤生成代码或命令用户任务 规划结果代码块Reviewer 审查者检查生成的代码和结果任务 代码块通过或修改建议对于更复杂的需求可以增加 Executor 执行者角色负责运行代码并返回执行结果增加 Search 搜索者角色负责检索外部资料。但在最小可运行版本里三个角色已经足够跑通流程。4. 环境准备与基础配置4.1 硬件要求中配方案对硬件的要求并不高。如果你有 16GB 内存的电脑就可以用 Ollama 跑 7B 量级量化模型做文本分类、抽取、格式整理等任务如果有 32GB 内存还可以选择更大的模型应对更复杂的生成任务。如果你有一张 8GB 以上显存的消费级显卡本地模型的推理速度和上下文长度都会明显改善。注意这里的配置只是参考实际以你的机器性能和模型要求为准。即使机器上完全不能跑本地大模型也可以退化为“纯 API 调用”模式架构和代码逻辑不变只是路由层会默认走云端。4.2 安装 Python 与依赖代码示例基于 Python 3。建议使用虚拟环境隔离依赖避免污染系统 Pythonmkdir -p agent-team cd agent-team python3 -m venv venv source venv/bin/activate # Windows 下使用 venv\Scripts\activate pip install requests本项目只需要 requests 库因为 Ollama 和主流 API 服务都提供 OpenAI 兼容协议我们可以直接用 HTTP 调用不需要额外引入大型框架。这保证了示例的最小可运行性。4.3 用 Ollama 启动本地模型Ollama 是目前最方便本地跑大模型的工具之一。官方提供了一个安装脚本curl -fsSL https://ollama.com/install.sh | sh安装完成后拉取一个本地模型。模型选择请以你的硬件条件为准这里以 7B 量级模型为例ollama pull qwen2.5:7b然后启动服务ollama serve验证服务是否启动在浏览器访问http://localhost:11434或者用命令检查curl http://localhost:11434/v1/models如果返回 JSON 列表说明本地模型服务已经正常启动。Ollama 同时提供 OpenAI 兼容接口base_url 一般就是http://localhost:11434/v1这为后面的统一调用层提供了便利。4.4 配置云端 API 和模型路由如果你的任务需要更高的推理质量可以让审查者角色走云端 API。设置环境变量即可export CLOUD_API_KEY你的APIKey export CLOUD_BASEhttps://api.openai.com/v1 export CLOUD_MODELgpt-4o-mini如果没有云端 API Key代码中的云端角色会自动回退到本地模型所以纯本地环境也能运行。关于路由逻辑后面的完整代码会具体演示。5. 从零实现一个最小可运行的代理团队接下来的代码是一个完整可运行的示例规划者先拆步骤编码者按步骤生成代码审查者检查并决定是否需要迭代。为了让新手能直接跑通我们把所有代码放在一个文件里实际项目可以再拆分成多个模块。5.1 创建主脚本 agent_team.py# 文件路径agent_team.py 最小可运行的 AI 代理团队示例 角色Planner(规划者) - Coder(编码者) - Reviewer(审查者) 模型路由本地模型 云端 API 混编 import json import os import requests # ---------- 模型配置 ---------- OLLAMA_BASE os.environ.get(OLLAMA_BASE, http://localhost:11434/v1) LOCAL_MODEL os.environ.get(LOCAL_MODEL, qwen2.5:7b) CLOUD_BASE os.environ.get(CLOUD_BASE, https://api.openai.com/v1) CLOUD_MODEL os.environ.get(CLOUD_MODEL, gpt-4o-mini) CLOUD_API_KEY os.environ.get(CLOUD_API_KEY, ) ROLE_ROUTING { planner: {base_url: OLLAMA_BASE, model: LOCAL_MODEL, api_key: None}, coder: {base_url: OLLAMA_BASE, model: LOCAL_MODEL, api_key: None}, reviewer: {base_url: CLOUD_BASE, model: CLOUD_MODEL, api_key: CLOUD_API_KEY}, } # ---------- 角色提示词 ---------- PROMPTS { planner: ( 你是团队规划者。把用户任务拆解为1-3个可执行步骤每个步骤用一句话描述。 只输出JSON数组不要输出任何解释。例如[\步骤1\, \步骤2\] ), coder: ( 你是编码者。根据规划者的步骤编写可以运行的 Python 代码或 Shell 命令。 只输出代码块不要输出多余解释。 ), reviewer: ( 你是代码审查者。检查代码是否有语法错误、安全隐患、缺少依赖。 如果发现问题给出具体修改建议如果没有问题只输出通过。 ), } # ---------- 统一调用层 ---------- def get_route(role): 获取角色对应的模型路由云端不可用时回退本地模型。 route ROLE_ROUTING[role] if not route.get(api_key): return { base_url: OLLAMA_BASE, model: LOCAL_MODEL, api_key: None, } return route def call_llm(role, system_prompt, user_prompt, temperature0.2): 统一调用不同来源的 LLM兼容 Ollama 和 OpenAI 协议。 route get_route(role) url route[base_url].rstrip(/) /chat/completions headers {Content-Type: application/json} if route[api_key]: headers[Authorization] fBearer {route[api_key]} payload { model: route[model], messages: [ {role: system, content: system_prompt}, {role: user, content: user_prompt}, ], temperature: temperature, } resp requests.post(url, headersheaders, jsonpayload, timeout600) resp.raise_for_status() return resp.json()[choices][0][message][content] # ---------- 编排器 ---------- def run_agent_team(task, max_iterations3): Planner - Coder - Reviewer最多迭代 max_iterations 轮。 # 1. 规划 plan_raw call_llm(planner, PROMPTS[planner], task) try: plan json.loads(plan_raw) except json.JSONDecodeError: # 本地模型偶尔会输出多余文字做一次兜底清洗 start plan_raw.find([) end plan_raw.rfind(]) 1 plan json.loads(plan_raw[start:end]) print( 规划结果 ) for i, step in enumerate(plan, 1): print(f{i}. {step}) # 2. 编码 审查迭代 code_output review for iteration in range(max_iterations): code_output call_llm( coder, PROMPTS[coder], f任务{task}\n规划{json.dumps(plan, ensure_asciiFalse)}\n, ) print(f\n 第 {iteration 1} 轮编码输出 ) print(code_output[:800]) review call_llm( reviewer, PROMPTS[reviewer], f任务{task}\n{code_output}, ) print(f 第 {iteration 1} 轮审查结果 ) print(review[:300]) if 通过 in review: break return {plan: plan, code: code_output, review: review} if __name__ __main__: user_task 用 Python 写一个快速排序算法并附带调用示例。 result run_agent_team(user_task)代码里的几个设计点值得说明。ROLE_ROUTING是混编的关键默认情况下规划者和编码者走本地模型审查者走云端 API如果云端 API 没配置get_route函数会把审查者也回退到本地模型。planner的提示词明确要求 JSON 输出但由于本地小模型可能输出不规范代码里加了 JSON 兜底解析逻辑。max_iterations限制了审查-修改循环的最大轮数这是防止代理团队死循环的必要设计。5.2 运行示例把当前目录切到脚本所在位置直接运行python agent_team.py如果你给 CLOUD_API_KEY 设置了值审查者会走云端否则全部走本地模型。第一次运行本地模型时加载速度会相对较慢这是正常现象。示例任务的输出是一个“规划 - 编码 - 审查”的完整流程记录。5.3 如何接入真实工具上面的代码只展示了“生成内容”还没有让代理真正“执行动作”。实际使用时最需要接的工具包括执行 Python 代码、读写文件、查询数据库、调用搜索接口。一个稳妥的扩展方式是新增 Executor 执行者角色。# 伪代码示例在审查通过后增加执行环节 def execute_code(code: str): # 重要生产环境必须使用沙箱不要直接执行任意代码 # 这里只演示最小执行逻辑 import subprocess result subprocess.run( [python, -c, code], capture_outputTrue, textTrue, timeout60, ) return result.stdout, result.stderr这条路径有明确的安全要求执行大模型生成代码必须在隔离沙箱里进行设置资源限制和超时机制。即使只是本地个人使用也要防止模型输出恶意或异常代码。生产环境建议用 Docker 容器或专业沙箱服务不要直接在主机的 shell 上执行。6. 运行效果验证与评测6.1 怎么判断跑通了运行python agent_team.py后预期输出会依次出现规划结果、编码输出和审查结果。一个成功的运行标志是规划结果是一个可解析的步骤列表编码输出是完整代码块审查结果最终出现“通过”或者在不通过时给出具体修改建议。如果第一次审查没有通过说明代码确实存在问题代理团队进入了修改迭代这是正常且符合预期的。真正判断“跑通”的标准不是看脚本是否不报错而是看代理团队是否形成了一条“规划 - 生成 - 校验 - 修改”的闭环。6.2 建立评测集只跑一个示例不算完。要真正验证代理团队的能力应该准备一个固定评测集包含 10 到 20 个有代表性的任务比如任务类型示例简单代码生成写一个统计词频的函数带依赖的代码项目生成一个含两个模块的小项目文档整理从一段会议记录中提取待办事项多步推理根据数据文件生成分析报告每次修改提示词或模型路由后跑一遍同样的评测集记录每个任务的成功率、平均延迟、平均成本。没有这个评测集你根本无法判断自己的改动是提高了还是降低了代理团队的稳定性。6.3 观察成本与延迟中配方案的一个重要收益是成本。你可以观察同一个任务在“全部云端”和“本地 云端混编”两种模式下的 token 消耗差异。简单任务切到本地模型后云端 token 消耗通常能明显下降而体验上的变化并不会有那么大因为规划者和编码者的任务相对简单。延迟方面本地模型的首 token 速度取决于硬件。如果任务不要求低延迟纯本地模式可以接受如果用户体验敏感可以把关键路径上的重任务切到云端把批处理和离线任务放在本地。7. 常见问题与排查方法代理团队是典型的“表面简单、实际容易翻车”的工程这里整理几个高频问题问题现象可能原因排查方式解决方案JSON 解析报错规划结果不稳定本地小模型指令跟随能力弱打印 plan_raw 原始内容降低 temperature 到 0.1增加兜底解析换更大的本地模型连接 localhost:11434 失败Ollama 服务未启动curl http://localhost:11434/v1/models执行 ollama serve确保服务正常云端接口返回 401API Key 未设置或失效echo $CLOUD_API_KEY 查看环境变量重新配置环境变量确认密钥有效审查环节一直不通过进入死循环审查提示词过严或模型误解打印审查输出查看具体原因调整提示词提高迭代上限允许人类手动判断任务跑到中段开始失忆上下文逐步累积关键信息被淹没记录每轮请求的 messages 长度做上下文裁剪只保留规划结果和最近一轮输出成本超过预期云端模型调用次数过多查看每轮的模型路由日志把更多角色切到本地模型增加缓存运行时间过长本地模型推理慢多轮迭代叠加记录每轮耗时拆小任务减少 max_iterations必要时换更快的模型排错时的通用做法是先打开日志打印每个角色的原始输入输出。因为代理团队的错误往往不是代码逻辑问题而是模型输出不符合预期。看到原始输出后通常就明白卡点在哪里。不要一上来就改模型、改提示词先还原现场。8. AI代理团队工程化最佳实践如果上面这些已经跑通下一步就是把它从“示例脚本”推进到“能长期使用的工程系统”。这里几条建议最重要。8.1 可观测性优先代理团队是多步骤、多角色系统排查问题的难度比单次 API 调用大得多。上线前必须给每个角色调用加上 trace_id记录角色名、模型名、输入摘要、输出摘要、耗时和消耗 token。所有记录落到结构化日志里既方便回放问题也方便统计成本。没有可观测性的代理团队就像没有日志的微服务一旦出错只能重新跑一遍。8.2 成本控制与路由优化中配方案的优势在于成本可控。落地时建议把路由规则做成显式的配置而不是写死在代码里。比如用简单的规则引擎判断任务类型再决定调用本地还是云端。定期查看日志里的 token 消耗分布找出哪些调用实际收益很低把它降级到本地模型识别哪些任务经常需要多轮修改考虑直接让云端模型处理。8.3 安全边界与最小权限大模型生成的内容不可信尤其是它生成的代码和命令。工具层必须遵循最小权限原则沙箱执行代码、限制文件路径、限制网络请求、对危险操作增加人工审批。不要为了演示方便让代理直接操作生产数据库或删除文件。记住一个原则模型可以提出方案但关键动作必须经过校验。8.4 人在回路不要追求“全自动无人值守”。在代理团队的规划阶段可以让用户确认任务拆解是否符合预期在审查不通过达到一定次数时把问题交给人工判断在涉及敏感操作时强制人工确认。人机协同不是退步而是让代理团队在可控边界内发挥价值。完全放任大模型自主执行是很多项目翻车的最常见原因。8.5 提示词和配置版本化代理团队的提示词、路由规则、评测集都应该纳入版本管理和代码一起提交。很多人在迭代提示词时习惯直接在脚本里改改完不记录等发现效果回退时已经找不回原来的版本。把提示词提出来放到单独配置文件里每次改动都有 diff评测结果也能和历史版本对比这样团队的质量曲线才清晰。9. 总结与下一步这篇文章的核心观点是构建一支更好的 AI 代理团队重点不在模型规模而在工程化能力。你可以用中配硬件和“本地模型 API 模型混编”的架构通过合理的角色设计、路由策略和评测机制搭出一套比多数个人开发者更稳定、更可控的代理团队系统。文中给出的最小示例已经可以跑通“规划 - 编码 - 审查”的流程。下一步建议你按自己的场景做三件事准备一份固定评测集开始记录每次改动的效果给你的代理团队加上一个真实工具比如文件读写或代码执行再逐步补充可观测性和成本统计。然后把这个问题想清楚你希望代理团队帮你解决哪一类固定任务把这个任务打磨到可用比搭建一个“看起来全能但什么都做不稳”的系统更重要。如果这篇文章对你有帮助建议收藏备用。你可以在评论区聊聊你正在用 AI 代理团队解决什么问题或者踩过哪些坑后续我可以围绕本地模型部署、工具接入和评测体系做更深入的拆解。
做 AI 代理AI Agent这件事眼下最大的误区不是“模型不够强”而是大多数个人开发者把精力都花在换更大的模型上却没有搭建起让多个代理协作的工程骨架。结果就是单看某个代理的回复能力还可以一旦让它独立完成一个多步骤任务就频繁卡在任务拆解、工具调用、状态流转和结果校验上最后只能用“单 Agent 硬跑”的方式凑合。这篇文章想讨论一个更现实的问题不靠顶级 GPU不算每个月大几千的 API 高配支出只用手头的中档配置比如一张消费级显卡甚至只有 CPU怎么搭出一支比大多数个人开发者做得更好的 AI 代理团队。先给一个明确结论决定一支 AI 代理团队上限的不是某一个模型聪明不聪明而是编排、记忆、工具、评测这四个工程环节。模型只解决“生成能力”代理团队解决的是“把复杂任务稳定地做完”。中配方案的核心思路就是“本地模型 API 模型混编”让便宜的本地模型承担结构化、分类、抽取等高频任务让云端模型承担复杂推理和最终生成既控制成本又保证质量。这里先做一点术语说明。本文说的“代理”是 AI Agent也就是 AI 智能体它指的不是网络代理而是能感知任务、调用工具、执行动作、根据结果迭代的自动化单元。一支 AI 代理团队就是让规划者、编码者、审查者等不同角色协作把单个大模型做不好的复杂任务拆碎、分工、验证、交付。全文按“概念 - 架构 - 环境 - 代码 - 验证 - 排错 - 最佳实践”的顺序展开所有代码和命令都给出完整可复制版本建议收藏备用。1. 先搞清楚什么才算一支“AI代理团队”1.1 从单 Agent 到多 Agent 的差别一个单独的 AI Agent本质上是一个“能循环调用大模型的进程”。它的标准执行链路是接收任务生成下一步计划调用工具观察结果再决定下一步。这套链路如果跑得顺单 Agent 已经能完成很多工作比如自动总结文档、生成代码片段、操作浏览器等。但单 Agent 的瓶颈很明显它必须在一个上下文里同时完成“理解任务、规划方案、编写代码、检查错误”四件事。一旦任务步骤变多上下文会被历史信息占满模型会忘记最初的目标或者在高频生成中累积错误。你可以想象一个开发团队只有一个人这个人同时做产品设计、写代码、测试和部署不是不可能但效率和质量都难以保证。多 Agent 团队则把不同职责拆给不同角色。每个 Agent 只负责一个小而清晰的环节上下文更短提示词更聚焦输出格式更容易控制。更重要的是不同角色之间可以互相校验规划者拆任务编码者写代码审查者找问题。这种结构天然减少了大模型“自说自话、错了也继续”的问题因为审查环节本身就是在制造一次交叉验证。1.2 代理团队能解决什么单 Agent 解决不了的问题最典型的场景是代码生成。单 Agent 让大模型直接写一个完整项目经常出现第一次生成时思路是对的但生成到第二十步时它已经把前面定义过的函数名忘记了。代理团队的处理方式则完全不一样。规划者先把“写一个带单元测试的 Python 命令行工具”拆成三个步骤设计接口、实现核心逻辑、编写测试用例。编码者根据每个步骤分别产出代码。审查者拿到代码后逐一检查语法、依赖和安全问题。如果审查发现问题编码者只针对问题修改而不是整个重写。这种“分而治之 交叉审查”的模式能让任务完成率显著提升尤其是在代码量超过 200 行的任务上。除了代码生成代理团队也适合研究报告整理、数据分析流水线、批量文档处理、自动化测试生成、多维度信息检索再汇总。共同特征是任务可以被拆解且拆解后的子任务之间有清晰的输入输出。1.3 不适合代理团队的场景也要说清楚边界。几十字的简单问答、只需要一次性调用模型翻译或总结的任务完全没必要上代理团队。代理团队有额外的编排开销每次多角色调用都会增加延迟和成本。如果一个单 Agent 一个提示词就能解决强行上多 Agent 只会让简单问题复杂化。更需要注意的是一类“伪协作”场景多个 Agent 之间没有明确分工也没有交叉校验只是轮流在大模型之间传话。这种设计并不会带来质量提升反而会让错误在对话链里不断放大最终输出比单 Agent 更差。2. 为什么 99% 的人搭不好代理团队2.1 差距不在模型在工程标题里的“99%”当然不是统计学数字更像是一种提醒多数个人开发者的代理系统目前还停留在“套一层提示词”的阶段。他们会写一个 System Prompt告诉模型“你是一个全能的助手”然后把所有任务都塞给一个模型。这种做法不是代理团队只是一个有提示词包装的单 Agent。真正拉开差距的是工程化能力。大模型本身擅长生成文本但不擅长保证格式稳定、不擅长记住跨轮次的状态、不擅长控制自己的调用次数。代理团队的搭建者本质上是在给模型配一套工程护栏让模型按 JSON 输出、让多轮循环有终止条件、让不同角色之间传递的数据结构固定、让每次调用都可以被记录和回放。这些工作不性感但决定了系统能不能稳定运行。2.2 四个关键短板多数代理团队做不好集中体现在四个环节环节失败表现影响编排没有明确的状态机角色之间靠“对话”传递信息流程不可控任务跑一半就散架记忆所有历史一股脑塞进上下文上下文爆炸模型忽略关键信息成本飙升工具只让模型“输出内容”没有真正接入可执行的工具代理无法完成“查数据、改文件、执行命令”等动作评测用肉眼判断输出好坏无法迭代改了提示词也不知道是好是坏如果做一次复盘你会发现大多数代理项目失败不是模型的生成能力差而是这四个环节里至少有一个没设计好。比如编排不清晰代理可能在同一个步骤上反复循环记忆不分层长任务跑到中段就开始“失忆”工具权限过大一轮对话就导致安全问题没有评测集则完全无法形成改进闭环。2.3 一个常见的失败案例假设你想做一个“自动写周报”的代理团队。初级做法是让一个 Agent 读取本周 Git 提交记录、对话记录和工作文档然后直接生成周报。听起来很合理实际跑起来会出现它读了大量无关的提交记录上下文被占满它分不清“本周完成事项”和“下周计划”应该用什么语气写它可能把某个临时分支的代码提交当成正式成果写进周报。改成代理团队之后流程会变成采集者只负责提取和过滤信息用结构化字段输出规划者把周报拆成“成果、问题、计划”三段写作者按模板生成审查者检查是否有夸大或遗漏。每个 Agent 的上下文都很短任务边界清晰输出的周报质量反而更稳定。这就是工程结构带来的差异。3. 中配方案的整体架构3.1 什么是“中配”“中配”指的是一个折中方案硬件上不一定需要高端多卡 GPU配置目标是让本地模型能跑起来同时把重活交给 API。具体硬件门槛本文后面会详细说。与“低配”相比中配会认真规划本地和云端的分工而不是完全依赖免费的在线小模型与“顶配”相比中配不会追求全流程用超大模型而是用路由策略让每一分钱都花在刀刃上。从材料看最近行业里“AI代理助手加本地模型”之所以热正是因为越来越多的开发者意识到完全依赖云端 API有成本、隐私和网络依赖问题完全依赖本地小模型又容易在复杂推理上质量不足。中配方案把两者结合让代理团队的底座既有本地模型的私有性又有云端模型的上限能力。3.2 整体架构本地模型 API 模型混编中配代理团队的整体架构可以分为四层接入层接收用户任务判断任务类型和复杂度。路由层根据任务复杂度决定调用本地模型还是云端 API。代理层多个角色分工协作包括规划者、编码者、审查者等。工具层库、文件、命令、搜索等外部能力供代理调用。路由层是“中配”的核心。一个简单的路由规则可以是信息抽取、格式整理、文本分类、简单问答等高频低难度任务走本地模型代码生成、冲突分析、多步推理、最终质量把关等低频率高难度任务走云端 API。通过这种路由大部分调用量沉淀在本地模型上API 只承担关键节点的生成任务成本能大幅下降。3.3 代理团队的角色设计角色设计不需要模仿大型团队最少三个角色就能成型角色职责输入输出Planner 规划者把任务拆成可执行步骤用户任务步骤列表Coder 编码者根据步骤生成代码或命令用户任务 规划结果代码块Reviewer 审查者检查生成的代码和结果任务 代码块通过或修改建议对于更复杂的需求可以增加 Executor 执行者角色负责运行代码并返回执行结果增加 Search 搜索者角色负责检索外部资料。但在最小可运行版本里三个角色已经足够跑通流程。4. 环境准备与基础配置4.1 硬件要求中配方案对硬件的要求并不高。如果你有 16GB 内存的电脑就可以用 Ollama 跑 7B 量级量化模型做文本分类、抽取、格式整理等任务如果有 32GB 内存还可以选择更大的模型应对更复杂的生成任务。如果你有一张 8GB 以上显存的消费级显卡本地模型的推理速度和上下文长度都会明显改善。注意这里的配置只是参考实际以你的机器性能和模型要求为准。即使机器上完全不能跑本地大模型也可以退化为“纯 API 调用”模式架构和代码逻辑不变只是路由层会默认走云端。4.2 安装 Python 与依赖代码示例基于 Python 3。建议使用虚拟环境隔离依赖避免污染系统 Pythonmkdir -p agent-team cd agent-team python3 -m venv venv source venv/bin/activate # Windows 下使用 venv\Scripts\activate pip install requests本项目只需要 requests 库因为 Ollama 和主流 API 服务都提供 OpenAI 兼容协议我们可以直接用 HTTP 调用不需要额外引入大型框架。这保证了示例的最小可运行性。4.3 用 Ollama 启动本地模型Ollama 是目前最方便本地跑大模型的工具之一。官方提供了一个安装脚本curl -fsSL https://ollama.com/install.sh | sh安装完成后拉取一个本地模型。模型选择请以你的硬件条件为准这里以 7B 量级模型为例ollama pull qwen2.5:7b然后启动服务ollama serve验证服务是否启动在浏览器访问http://localhost:11434或者用命令检查curl http://localhost:11434/v1/models如果返回 JSON 列表说明本地模型服务已经正常启动。Ollama 同时提供 OpenAI 兼容接口base_url 一般就是http://localhost:11434/v1这为后面的统一调用层提供了便利。4.4 配置云端 API 和模型路由如果你的任务需要更高的推理质量可以让审查者角色走云端 API。设置环境变量即可export CLOUD_API_KEY你的APIKey export CLOUD_BASEhttps://api.openai.com/v1 export CLOUD_MODELgpt-4o-mini如果没有云端 API Key代码中的云端角色会自动回退到本地模型所以纯本地环境也能运行。关于路由逻辑后面的完整代码会具体演示。5. 从零实现一个最小可运行的代理团队接下来的代码是一个完整可运行的示例规划者先拆步骤编码者按步骤生成代码审查者检查并决定是否需要迭代。为了让新手能直接跑通我们把所有代码放在一个文件里实际项目可以再拆分成多个模块。5.1 创建主脚本 agent_team.py# 文件路径agent_team.py 最小可运行的 AI 代理团队示例 角色Planner(规划者) - Coder(编码者) - Reviewer(审查者) 模型路由本地模型 云端 API 混编 import json import os import requests # ---------- 模型配置 ---------- OLLAMA_BASE os.environ.get(OLLAMA_BASE, http://localhost:11434/v1) LOCAL_MODEL os.environ.get(LOCAL_MODEL, qwen2.5:7b) CLOUD_BASE os.environ.get(CLOUD_BASE, https://api.openai.com/v1) CLOUD_MODEL os.environ.get(CLOUD_MODEL, gpt-4o-mini) CLOUD_API_KEY os.environ.get(CLOUD_API_KEY, ) ROLE_ROUTING { planner: {base_url: OLLAMA_BASE, model: LOCAL_MODEL, api_key: None}, coder: {base_url: OLLAMA_BASE, model: LOCAL_MODEL, api_key: None}, reviewer: {base_url: CLOUD_BASE, model: CLOUD_MODEL, api_key: CLOUD_API_KEY}, } # ---------- 角色提示词 ---------- PROMPTS { planner: ( 你是团队规划者。把用户任务拆解为1-3个可执行步骤每个步骤用一句话描述。 只输出JSON数组不要输出任何解释。例如[\步骤1\, \步骤2\] ), coder: ( 你是编码者。根据规划者的步骤编写可以运行的 Python 代码或 Shell 命令。 只输出代码块不要输出多余解释。 ), reviewer: ( 你是代码审查者。检查代码是否有语法错误、安全隐患、缺少依赖。 如果发现问题给出具体修改建议如果没有问题只输出通过。 ), } # ---------- 统一调用层 ---------- def get_route(role): 获取角色对应的模型路由云端不可用时回退本地模型。 route ROLE_ROUTING[role] if not route.get(api_key): return { base_url: OLLAMA_BASE, model: LOCAL_MODEL, api_key: None, } return route def call_llm(role, system_prompt, user_prompt, temperature0.2): 统一调用不同来源的 LLM兼容 Ollama 和 OpenAI 协议。 route get_route(role) url route[base_url].rstrip(/) /chat/completions headers {Content-Type: application/json} if route[api_key]: headers[Authorization] fBearer {route[api_key]} payload { model: route[model], messages: [ {role: system, content: system_prompt}, {role: user, content: user_prompt}, ], temperature: temperature, } resp requests.post(url, headersheaders, jsonpayload, timeout600) resp.raise_for_status() return resp.json()[choices][0][message][content] # ---------- 编排器 ---------- def run_agent_team(task, max_iterations3): Planner - Coder - Reviewer最多迭代 max_iterations 轮。 # 1. 规划 plan_raw call_llm(planner, PROMPTS[planner], task) try: plan json.loads(plan_raw) except json.JSONDecodeError: # 本地模型偶尔会输出多余文字做一次兜底清洗 start plan_raw.find([) end plan_raw.rfind(]) 1 plan json.loads(plan_raw[start:end]) print( 规划结果 ) for i, step in enumerate(plan, 1): print(f{i}. {step}) # 2. 编码 审查迭代 code_output review for iteration in range(max_iterations): code_output call_llm( coder, PROMPTS[coder], f任务{task}\n规划{json.dumps(plan, ensure_asciiFalse)}\n, ) print(f\n 第 {iteration 1} 轮编码输出 ) print(code_output[:800]) review call_llm( reviewer, PROMPTS[reviewer], f任务{task}\n{code_output}, ) print(f 第 {iteration 1} 轮审查结果 ) print(review[:300]) if 通过 in review: break return {plan: plan, code: code_output, review: review} if __name__ __main__: user_task 用 Python 写一个快速排序算法并附带调用示例。 result run_agent_team(user_task)代码里的几个设计点值得说明。ROLE_ROUTING是混编的关键默认情况下规划者和编码者走本地模型审查者走云端 API如果云端 API 没配置get_route函数会把审查者也回退到本地模型。planner的提示词明确要求 JSON 输出但由于本地小模型可能输出不规范代码里加了 JSON 兜底解析逻辑。max_iterations限制了审查-修改循环的最大轮数这是防止代理团队死循环的必要设计。5.2 运行示例把当前目录切到脚本所在位置直接运行python agent_team.py如果你给 CLOUD_API_KEY 设置了值审查者会走云端否则全部走本地模型。第一次运行本地模型时加载速度会相对较慢这是正常现象。示例任务的输出是一个“规划 - 编码 - 审查”的完整流程记录。5.3 如何接入真实工具上面的代码只展示了“生成内容”还没有让代理真正“执行动作”。实际使用时最需要接的工具包括执行 Python 代码、读写文件、查询数据库、调用搜索接口。一个稳妥的扩展方式是新增 Executor 执行者角色。# 伪代码示例在审查通过后增加执行环节 def execute_code(code: str): # 重要生产环境必须使用沙箱不要直接执行任意代码 # 这里只演示最小执行逻辑 import subprocess result subprocess.run( [python, -c, code], capture_outputTrue, textTrue, timeout60, ) return result.stdout, result.stderr这条路径有明确的安全要求执行大模型生成代码必须在隔离沙箱里进行设置资源限制和超时机制。即使只是本地个人使用也要防止模型输出恶意或异常代码。生产环境建议用 Docker 容器或专业沙箱服务不要直接在主机的 shell 上执行。6. 运行效果验证与评测6.1 怎么判断跑通了运行python agent_team.py后预期输出会依次出现规划结果、编码输出和审查结果。一个成功的运行标志是规划结果是一个可解析的步骤列表编码输出是完整代码块审查结果最终出现“通过”或者在不通过时给出具体修改建议。如果第一次审查没有通过说明代码确实存在问题代理团队进入了修改迭代这是正常且符合预期的。真正判断“跑通”的标准不是看脚本是否不报错而是看代理团队是否形成了一条“规划 - 生成 - 校验 - 修改”的闭环。6.2 建立评测集只跑一个示例不算完。要真正验证代理团队的能力应该准备一个固定评测集包含 10 到 20 个有代表性的任务比如任务类型示例简单代码生成写一个统计词频的函数带依赖的代码项目生成一个含两个模块的小项目文档整理从一段会议记录中提取待办事项多步推理根据数据文件生成分析报告每次修改提示词或模型路由后跑一遍同样的评测集记录每个任务的成功率、平均延迟、平均成本。没有这个评测集你根本无法判断自己的改动是提高了还是降低了代理团队的稳定性。6.3 观察成本与延迟中配方案的一个重要收益是成本。你可以观察同一个任务在“全部云端”和“本地 云端混编”两种模式下的 token 消耗差异。简单任务切到本地模型后云端 token 消耗通常能明显下降而体验上的变化并不会有那么大因为规划者和编码者的任务相对简单。延迟方面本地模型的首 token 速度取决于硬件。如果任务不要求低延迟纯本地模式可以接受如果用户体验敏感可以把关键路径上的重任务切到云端把批处理和离线任务放在本地。7. 常见问题与排查方法代理团队是典型的“表面简单、实际容易翻车”的工程这里整理几个高频问题问题现象可能原因排查方式解决方案JSON 解析报错规划结果不稳定本地小模型指令跟随能力弱打印 plan_raw 原始内容降低 temperature 到 0.1增加兜底解析换更大的本地模型连接 localhost:11434 失败Ollama 服务未启动curl http://localhost:11434/v1/models执行 ollama serve确保服务正常云端接口返回 401API Key 未设置或失效echo $CLOUD_API_KEY 查看环境变量重新配置环境变量确认密钥有效审查环节一直不通过进入死循环审查提示词过严或模型误解打印审查输出查看具体原因调整提示词提高迭代上限允许人类手动判断任务跑到中段开始失忆上下文逐步累积关键信息被淹没记录每轮请求的 messages 长度做上下文裁剪只保留规划结果和最近一轮输出成本超过预期云端模型调用次数过多查看每轮的模型路由日志把更多角色切到本地模型增加缓存运行时间过长本地模型推理慢多轮迭代叠加记录每轮耗时拆小任务减少 max_iterations必要时换更快的模型排错时的通用做法是先打开日志打印每个角色的原始输入输出。因为代理团队的错误往往不是代码逻辑问题而是模型输出不符合预期。看到原始输出后通常就明白卡点在哪里。不要一上来就改模型、改提示词先还原现场。8. AI代理团队工程化最佳实践如果上面这些已经跑通下一步就是把它从“示例脚本”推进到“能长期使用的工程系统”。这里几条建议最重要。8.1 可观测性优先代理团队是多步骤、多角色系统排查问题的难度比单次 API 调用大得多。上线前必须给每个角色调用加上 trace_id记录角色名、模型名、输入摘要、输出摘要、耗时和消耗 token。所有记录落到结构化日志里既方便回放问题也方便统计成本。没有可观测性的代理团队就像没有日志的微服务一旦出错只能重新跑一遍。8.2 成本控制与路由优化中配方案的优势在于成本可控。落地时建议把路由规则做成显式的配置而不是写死在代码里。比如用简单的规则引擎判断任务类型再决定调用本地还是云端。定期查看日志里的 token 消耗分布找出哪些调用实际收益很低把它降级到本地模型识别哪些任务经常需要多轮修改考虑直接让云端模型处理。8.3 安全边界与最小权限大模型生成的内容不可信尤其是它生成的代码和命令。工具层必须遵循最小权限原则沙箱执行代码、限制文件路径、限制网络请求、对危险操作增加人工审批。不要为了演示方便让代理直接操作生产数据库或删除文件。记住一个原则模型可以提出方案但关键动作必须经过校验。8.4 人在回路不要追求“全自动无人值守”。在代理团队的规划阶段可以让用户确认任务拆解是否符合预期在审查不通过达到一定次数时把问题交给人工判断在涉及敏感操作时强制人工确认。人机协同不是退步而是让代理团队在可控边界内发挥价值。完全放任大模型自主执行是很多项目翻车的最常见原因。8.5 提示词和配置版本化代理团队的提示词、路由规则、评测集都应该纳入版本管理和代码一起提交。很多人在迭代提示词时习惯直接在脚本里改改完不记录等发现效果回退时已经找不回原来的版本。把提示词提出来放到单独配置文件里每次改动都有 diff评测结果也能和历史版本对比这样团队的质量曲线才清晰。9. 总结与下一步这篇文章的核心观点是构建一支更好的 AI 代理团队重点不在模型规模而在工程化能力。你可以用中配硬件和“本地模型 API 模型混编”的架构通过合理的角色设计、路由策略和评测机制搭出一套比多数个人开发者更稳定、更可控的代理团队系统。文中给出的最小示例已经可以跑通“规划 - 编码 - 审查”的流程。下一步建议你按自己的场景做三件事准备一份固定评测集开始记录每次改动的效果给你的代理团队加上一个真实工具比如文件读写或代码执行再逐步补充可观测性和成本统计。然后把这个问题想清楚你希望代理团队帮你解决哪一类固定任务把这个任务打磨到可用比搭建一个“看起来全能但什么都做不稳”的系统更重要。如果这篇文章对你有帮助建议收藏备用。你可以在评论区聊聊你正在用 AI 代理团队解决什么问题或者踩过哪些坑后续我可以围绕本地模型部署、工具接入和评测体系做更深入的拆解。
