如果你也想搭建一套属于自己的 AI 代理团队又不想被各种复杂框架按住头学习那么这篇文章就是为你准备的。我不会只介绍概念还会把一套可运行的多角色 AI 代理工程直接拆出来讲包含完整代码、配置方法、运行过程以及把团队做稳的细节设计。无论你是刚接触 AI Agent还是已经写过几个简单工具都能从这套思路里得到可直接落地的能力。很多人在接触 AI 代理时第一反应是去追最新框架、堆最贵的模型结果搭出来的系统往往只会在理想输入下跑通一两次。真正的差距不是谁用的模型更大而是谁能把“规划、执行、审查、重试、上下文管理”这些工程细节做成闭环。比 99% 的人更好听起来像口号但落到方法论上其实就是少数几件事。本文将围绕“AI 代理团队”的构建展开重点讲解如何用中等配置的模型和合理的工程结构搭建出一套具备多角色协作能力的 AI 代理解决方案。你会看到什么是 AI 代理团队为什么需要它以及如何通过规划器、执行器、审查器三个核心角色让代理系统稳定输出高质量结果。同时也会涉及本地模型与远程 API 的选型、成本控制、错误恢复、上下文维护等关键问题。文章面向三类读者刚开始学习 AI 代理的开发者、想在企业项目中引入多智能体协作的工程师以及正在探索本地模型落地的技术爱好者。读完你会收获一套可以修改和扩展的 Python 工程示例以及一套能直接迁移到生产项目的设计思路。1. AI 代理团队是什么为什么需要组队1.1 单 Agent 的局限先从一个最简单的问题说起一个 AI 代理能不能独立完成高质量任务如果任务是“帮我把这段英文翻译成中文”单个代理使用足够强的模型确实能做到。但如果是“调研某个技术方向输出一份调研报告并且确保每个结论都有来源”单个代理的表现就会变得很不稳定。原因在于这类任务包含多个不同性质的能力需求它需要检索信息、评估信息可信度、组织表达、检查逻辑漏洞还需要不断返工修订。让一个 Agent 同时承担所有角色它会在上下文窗口里混入大量不同目标的信息导致注意力分散、输出质量下降。另一个常见问题是“自我修正失效”。单个 Agent 生成内容后让它自己检查错误效果往往不理想。因为模型在同一个思维上下文里对刚刚生成的错误已经形成了路径依赖。它很难站在外部视角发现自己输出的盲点。就像一个人写代码写完很难看到自己明显的变量名错误。1.2 多角色 AI 代理团队的本质AI 代理团队的本质是把一个复杂任务拆成多个专业角色每个角色负责一个独立环节角色之间通过任务边界和消息进行协作。用人来类比更容易理解项目经理负责拆解任务确定目标和优先级。研究员负责收集资料筛选信息。工程师负责写代码或生成结构化内容。评审专家负责检查质量提出修改意见。这种设计最大的价值不只是“人多力量大”而是每个角色都能保持清晰的指令上下文。规划器只专注于目标拆解不会在中途去纠结代码细节执行器只专注于产出内容不需要反复切换思维模式审查器站在外部视角发现问题避免自我修正失效。在工程表现上多角色团队显著提升了三个指标第一是任务完成率因为复杂任务被拆成可管理的子任务第二是输出稳定性因为每个环节都有明确验收标准第三是可维护性因为错误定位从“整个 Agent 的问题”缩小到“某个角色的问题”。1.3 AI 代理团队适用的场景AI 代团队不是所有场景都需要但下面几类任务非常适合长文本研究报告生成。需要检索、筛选、提纲、写作、校对多个环节。代码生成与审查。需要设计模块、编写实现、检查边界条件、运行调试。复杂数据处理流程。需要解析、清洗、分析、可视化、结论总结。内容生产的质量工程。比如批量生成文章或营销文案需要统一审查标准。用户意图识别与任务路由。需要意图判断、参数提取、API 调用、结果复核。如果你的任务只是单轮问答或简单工具调用使用单 Agent 就够了。一旦任务需要多次推理、多步骤操作、反复修订就应该考虑代理团队模式。2. 构建 AI 代理团队的通用思维框架2.1 任务拆解能力“比 99% 的人更好”的第一个分水岭是任务拆解能力。同样要求 AI 代理团队“写一份竞品分析报告”普通做法是把这句话直接丢给一个 Agent让它自由发挥。更好的做法是先把任务拆解成阶段确定分析维度、收集竞品信息、整理功能对比、形成结论建议、审核输出格式。拆解后的任务可以进入不同的角色也可以在同一角色内串行执行多个步骤。关键是每一步都要有明确的输入、输出和验收标准。我在实际项目里发现把任务拆成 3 到 5 个可执行步骤模型的输出质量会明显高于一次性生成完整结果。在代码层面任务拆解对应的是一个结构化的任务数据对象。每个任务包含名称、目标、输入、输出约束。这样后续的规划器、执行器、审查器才能有统一的协作语言。2.2 角色设计与职责划分一个最小可用的 AI 代理团队至少需要三个角色规划器Planner负责分析输入目标拆解为任务序列决定任务顺序和依赖关系。执行器Executor负责执行具体子任务根据任务类型调用模型或工具。审查器Reviewer负责按质量标准审查执行结果返回修改意见或确认通过。角色不需要太多太多会带来通信开销和延迟。对于大部分业务场景三个角色已经能形成有效闭环。如果你做的是非常大型的系统可以在执行器内部再拆出代码代理、检索代理、写作代理但核心架构仍然是“规划-执行-审查”。2.3 工具层与模型层分离代理团队不能只靠模型“空想”。在真实场景中它还需要工具层支撑比如搜索引擎、数据库查询、文件读写、代码解释器等。好的设计会把工具层和模型层解耦。模型只负责判断“下一步调用哪个工具、传入什么参数”工具层负责真正执行操作并返回结果。这种解耦让代理团队可以轻松替换模型而不需要改动工具接口也可以新增工具而不需要修改模型逻辑。一个简单的接口约定可以是class Tool: name: str description: str def run(self, **kwargs) - str: ...每个工具都注册上名称和描述模型根据描述选择工具。这样代理团队就具备了一定的“工具使用能力”而不是只会生成文本。3. 中配环境下如何选择模型与本地模型3.1 算力与成本约束下的模型选型题目标题里提到的“中配”在实际工程里对应的是普通笔记本或单卡 GPU 服务器、预算有限的 API 调用额度、不愿意被大模型 API 完全锁定的团队。在这类约束下模型选择有两条路线第一条路线是使用远程 API。例如 DeepSeek、Qwen 系列、OpenAI 兼容接口等。优点是效果稳定、接入简单缺点是有网络依赖和 token 成本。对于探索期团队我建议优先走这条路线因为可以快速验证系统架构不用陷入模型部署的泥潭。第二条路线是部署本地模型。例如通过 Ollama、vLLM 等工具运行开源模型适合对数据隐私要求高、或需要离线运行的场景。缺点是显存占用大、推理速度受硬件限制需要做一些量化如 Q4、Q8和批处理优化。中配团队的策略通常是默认使用远程 API核心敏感环节使用本地模型。AI 代理助手加本地模型的组合核心价值在于让代理团队拥有一个“私有底座”避免所有上下文都暴露给外部 API。这在企业内部落地时是很现实的需求。3.2 本地模型部署的常见方案对比本地模型工具非常多这里只提三个主流方向工具特点适合场景Ollama安装简单命令友好支持一键拉取模型本地开发测试、笔记本体验vLLM高吞吐量支持 OpenAI 兼容接口生产环境、多用户并发LM Studio图形化界面支持本地推理非开发者快速体验简单来说Ollama 是最容易上手的选择。以最常见的部署方式为例启动本地模型服务后它会暴露一个与 OpenAI 兼容的接口地址例如http://localhost:11434/v1。这样你的代理团队代码只需要改一个base_url就能从远程 API 切换到本地模型不需要重构任何业务逻辑。这一点非常关键在架构设计时把所有模型调用统一封装到一个 ModelClient 中是整个代理团队后期可以自由切换模型的基础。下面的实战环节会具体演示。3.3 为什么代理团队需要“模型无关”很多代理项目写死了一家模型厂商的 SDK导致后期想换模型时四处改代码。更合理的做法是使用 OpenAI 兼容协议来统一访问远程模型和本地模型让模型层成为可替换的组件。你可以把模型看作代理团队的“员工”不同员工擅长不同工作。规划器可以用推理能力强的模型执行器可以用生成速度快的模型审查器可以用评判能力好的模型。这种“按角色配置模型”的能力才是真正的工程化思维。因此“AI 代理助手加本地模型”的实践路径不是简单地用本地模型替代远程 API而是要让代理团队有能力混用多种模型让每个角色用上最合适的模型。4. 完整实战构建一个“规划-执行-审查”AI 代理团队4.1 系统设计下面开始动手。我们构建一个 Python 项目实现一个最小的多角色 AI 代理团队。它的功能是接收一个用户任务由规划器拆解任务执行器逐个执行审查器检查结果并决定是大重写、小修改还是通过。为了演示通用性执行器提供的工具能力包括文本生成根据指令直接生成内容。文档摘要对一段文字进行摘要提取。代码审查对一段代码提出改进意见。这三类能力足以覆盖很多常见任务同时足够简单方便理解代理团队的协作机制。整体工作流程用户提交任务。规划器将任务拆成阶段化步骤。执行器按步骤调用模型与工具。审查器检查输出如果通过输出最终结果否则带着审查意见返回到规划器或执行器重做。推荐使用下面的项目结构agent_team/ ├── requirements.txt ├── .env.example ├── config │ └── config.yaml ├── src │ ├── __init__.py │ ├── model_client.py │ ├── tools.py │ ├── agents.py │ └── workflow.py └── main.py4.2 环境准备与依赖安装本文示例使用 Python 3.10核心依赖为 openai、pyyaml、python-dotenv。为了保持最小依赖我们不引入 LangChain 或 LangGraph而是用原生 Python 实现一套轻量多代理流程。这样做的好处是你能看到多代理协作的真正机制而不是被框架包装掩盖。创建虚拟环境并安装依赖python -m venv venv source venv/bin/activate pip install openai pyyaml python-dotenv如果项目中需要记录依赖可以生成 requirements.txtopenai1.30.0 pyyaml6.0 python-dotenv1.0.0注意不同版本的 openai SDK 接口可能有差异如果安装的是最新版调用方法与下面代码理论上兼容如果遇到不兼容报错以官方文档为准。4.3 模型客户端封装为了让代理团队能灵活切换远程模型和本地模型我们先封装 ModelClient 类。文件路径src/model_client.pyimport os from openai import OpenAI class ModelClient: 统一的模型调用客户端支持 OpenAI 兼容接口。 def __init__(self, model: str gpt-4o-mini, base_url: str None, api_key: str None, temperature: float 0.7): self.model model self.base_url base_url or os.getenv(LLM_BASE_URL, https://api.openai.com/v1) self.api_key api_key or os.getenv(LLM_API_KEY, sk-demo) self.temperature temperature self.client OpenAI(base_urlself.base_url, api_keyself.api_key) def chat(self, system_prompt: str, user_message: str, max_tokens: int 1024) - str: 发送对话请求返回模型生成的文本。 try: response self.client.chat.completions.create( modelself.model, temperatureself.temperature, max_tokensmax_tokens, messages[ {role: system, content: system_prompt}, {role: user, content: user_message}, ], ) return response.choices[0].message.content.strip() except Exception as e: return f[模型调用失败] {e}这段代码有几个关键设计统一使用 OpenAI 兼容协议所以切换模型时只需要调整环境变量。所有异常都被捕获并返回可读提示这样即使模型调用失败代理团队也能拿到结构化反馈而不是直接崩溃。system_prompt与user_message分离方便后续每个 Agent 注入自己的角色信息。对应的 .env.example 内容# 如果使用远程 API填对应的 base_url 和 api_key LLM_BASE_URLhttps://api.openai.com/v1 LLM_API_KEYsk-your-key # 如果使用本地模型例如 Ollama改成下面这样 # LLM_BASE_URLhttp://localhost:11434/v1 # LLM_API_KEYollama4.4 工具层实现工具层让执行器具备实际能力。本示例实现两个工具摘要工具和代码审查工具。文件路径src/tools.pyclass SummarizeTool: name summarize description 对一段文本生成简洁摘要 def run(self, text: str, max_length: int 100) - str: # 这里为了演示简单直接截断文本。 # 生产环境可以调用模型或使用更复杂的摘要算法。 if len(text) max_length: return text return text[:max_length] ... class CodeReviewTool: name code_review description 对代码片段提出改进建议 def run(self, code: str) - str: # 演示用规则式审查实际项目可替换为基于模型的审查。 suggestions [] if eval( in code: suggestions.append(避免使用 eval存在安全风险) if len(code.splitlines()) 50: suggestions.append(函数过长建议拆分为多个更小的函数) if TODO in code: suggestions.append(存在 TODO 待办事项需要补充实现) if not suggestions: suggestions.append(没有发现明显问题) return \n.join(suggestions) TOOL_MAP { SummarizeTool.name: SummarizeTool(), CodeReviewTool.name: CodeReviewTool(), } def run_tool(tool_name: str, **kwargs) - str: tool TOOL_MAP.get(tool_name) if tool is None: return f错误未找到名为 {tool_name} 的工具 try: return tool.run(**kwargs) except Exception as e: return f工具执行失败{e}在实际项目中工具层往往不只是规则代码而是会调用外部 API、执行数据库查询、读取本地文件等。但无论底层逻辑多复杂对上层代理来说工具只需要暴露“名称、描述、参数、返回值”这四样东西这样模型才能学会使用它。4.5 三个角色规划器、执行器、审查器文件路径src/agents.pyfrom .model_client import ModelClient from .tools import run_tool class Planner: 规划器把用户目标拆解成可执行任务列表。 def __init__(self, client: ModelClient): self.client client def plan(self, user_goal: str) - list[str]: system_prompt 你是一名资深项目经理负责把复杂目标拆解为可执行的独立步骤。 请只输出步骤列表不要输出解释性内容。格式要求 1. 步骤内容 2. 步骤内容 ... result self.client.chat(system_prompt, user_goal, max_tokens512) steps [line.strip().lstrip(0123456789.、 ) for line in result.splitlines() if line.strip() and not line.startswith(步骤)] return steps or [完成用户目标] class Executor: 执行器按规划结果执行子任务必要时调用工具。 def __init__(self, client: ModelClient): self.client client def execute(self, step: str, context: str ) - str: system_prompt 你是一名高效的执行者负责完成用户分配的具体子任务。 你可以调用工具但工具调用完成后你需要把工具结果整理成可读的文本输出。 当前可用工具 - summarize: 对文本生成摘要 - code_review: 对代码提供审查意见 如果不需要调用工具直接完成文本生成任务。 user_message f当前步骤{step}\n if context: user_message f上下文信息\n{context}\n user_message 请输出最终结果。 result self.client.chat(system_prompt, user_message, max_tokens1024) return result class Reviewer: 审查器检查执行结果是否合格返回通过或修改意见。 def __init__(self, client: ModelClient): self.client client def review(self, original_goal: str, steps: list[str], outputs: list[str]) - dict: system_prompt 你是一名质量审查专家负责检查执行结果是否完成了用户原始目标。 请输出以下格式 结论通过 或 结论需要修改 意见具体的修改意见 user_message f原始目标{original_goal}\n\n执行步骤和结果如下\n for idx, (step, output) in enumerate(zip(steps, outputs), 1): user_message f步骤{idx}{step}\n结果{output}\n user_message \n请给出审查结论。 result self.client.chat(system_prompt, user_message, max_tokens512) if 通过 in result: return {passed: True, feedback: result} return {passed: False, feedback: result}每个 Agent 的本质都是一个“带角色提示词 模型客户端”的组合。我们并没有发明复杂机制只是把不同角色的人设和系统提示词分开。这样每个模型调用都是干净的单一任务不会被无关上下文污染。这里需要注意规划器返回步骤列表时我们做了一个简单的文本清理去除开头的数字编号。这是为了把模型输出转成程序可用的结构化数据。在实际项目中更推荐让模型输出 JSON 格式再解析这样稳定性更高。4.6 主流程编排文件路径src/workflow.pyfrom .agents import Planner, Executor, Reviewer from .model_client import ModelClient class AgentTeam: AI 代理团队主流程。 def __init__(self, client: ModelClient): self.client client self.planner Planner(client) self.executor Executor(client) self.reviewer Reviewer(client) def run(self, user_goal: str, max_review_rounds: int 2) - dict: print( 规划器开始拆解任务) steps self.planner.plan(user_goal) print(f 规划结果{steps}) outputs [] context for idx, step in enumerate(steps, 1): print(f 执行器执行步骤 {idx}: {step}) output self.executor.execute(step, context) print(f 步骤 {idx} 输出\n{output}) outputs.append(output) context output round_num 0 while round_num max_review_rounds: print(f 审查器开始第 {round_num 1} 轮审查) review_result self.reviewer.review(user_goal, steps, outputs) print(f 审查结果{review_result}) if review_result[passed]: print( 审查通过流程结束) return { goal: user_goal, steps: steps, outputs: outputs, review: review_result, final_output: \n\n.join(outputs), } print( 审查未通过重新规划并执行) steps self.planner.plan(f{user_goal}\n同时考虑以下修改意见{review_result[feedback]}) outputs [] context for idx, step in enumerate(steps, 1): output self.executor.execute(step, context) outputs.append(output) context output round_num 1 return { goal: user_goal, steps: steps, outputs: outputs, review: review_result, final_output: \n\n.join(outputs), }这个流程的可贵之处在于它实现了一个“质量闭环”。当审查器认为结果不合格时代理团队不是简单地把步骤再执行一遍而是重新规划把修改意见带入新的任务拆解中。很多初版 AI 代理项目只做到“执行”没有“审查”导致输出质量完全依赖模型当天状态。加入审查环节后系统的鲁棒性会有质的提升。当然一个真实的团队里审查者可能会多次打回所以我们需要设置最大重试轮数防止因为模型反复不达标而陷入死循环。4.7 运行入口文件路径main.pyimport os import yaml from dotenv import load_dotenv from src.model_client import ModelClient from src.workflow import AgentTeam load_dotenv() # 读取配置 with open(config/config.yaml, r, encodingutf-8) as f: config yaml.safe_load(f) client ModelClient( modelconfig[models][default_model], base_urlos.getenv(LLM_BASE_URL, https://api.openai.com/v1), api_keyos.getenv(LLM_API_KEY, sk-demo), temperatureconfig[models][temperature], ) team AgentTeam(client) if __name__ __main__: goal input(请输入你的目标) result team.run(goal) print(\n\n 最终结果 ) print(result[final_output])配置文件 config/config.yamlmodels: default_model: gpt-4o-mini temperature: 0.74.8 运行验证假设我们输入一个目标帮我写一个 Python 函数用于统计列表中重复元素的次数并审查这个函数。运行后可能看到类似下面的流程日志 规划器开始拆解任务 规划结果[定义一个函数接收列表参数, 使用字典统计重复元素次数, 编写代码并审查] 执行器执行步骤 1: 定义一个函数接收列表参数 步骤 1 输出首先需要定义函数签名输入为 list输出为 dict 执行器执行步骤 2: 使用字典统计重复元素次数 步骤 2 输出遍历列表更新字典计数 执行器执行步骤 3: 编写代码并审查 步骤 3 输出def count_duplicates(lst): ... 审查器开始第 1 轮审查 审查结果结论通过 审查通过流程结束这就是一个最基本的 AI 代理团队工作过程。你会看到复杂任务被拆成步骤每个步骤单独执行最后还有质量检查。在真实使用中你输入的目标越具体规划器的拆解质量就越高。比如“帮我写一个 Python 函数”就比“写点代码”好得多。5. 让代理团队真正优于大多数人的 6 个细节5.1 上下文管理代理团队在执行多个步骤时最大的风险是上下文漂移。执行器在执行步骤 3 时可能已经忘记步骤 1 产生的关键信息。解决方法是显式维护一个 context 对象把历史关键信息持久化并在每一步执行时注入。上面的示例中我们把之前的输出拼接到当前步骤的上下文中这就是最简单的上下文管理。更精细的做法是只保留与当前步骤相关的信息避免上下文过长导致“注意力稀释”。你可以用一个简单的规则关键词匹配也可以用向量检索做相关性筛选。5.2 错误恢复与重试代理团队跑在真实环境里模型接口超时、限流、返回空内容都是家常便饭。不要把一次失败当作整个任务的终结。建议在 ModelClient 中加入简单的指数退避重试逻辑import time def chat_with_retry(self, system_prompt, user_message, max_tokens1024, retries3): for attempt in range(retries): result self.chat(system_prompt, user_message, max_tokens) if not result.startswith([模型调用失败]): return result time.sleep(2 ** attempt) return result这样即使模型服务短暂抖动代理团队也能自愈。5.3 成本控制多角色团队意味着多次模型调用。一次完整任务可能消耗 5 到 10 次 API 调用比单 Agent 更烧钱。成本控制的核心手段有三个精简步骤数量规划器不要拆出无意义步骤。为不同角色配置不同模型执行器用便宜的模型规划器与审查器用更强模型。对工具调用结果做缓存相同请求不重复调用模型。在 config.yaml 中可以为每个角色单独配置模型名称这是推荐的最佳实践models: planner_model: deepseek-chat executor_model: gpt-4o-mini reviewer_model: deepseek-chat temperature: 0.55.4 审查标准要可执行很多审查器的问题在于它只会说“内容不够好”但不会说“到底哪里不够好”。没有可执行的审查意见执行器重做时也会很迷茫。解决方法是把审查标准量化到提示词中。例如“检查报告是否包含数据来源如果缺失请明确指出缺失的是哪个部分”。审查意见越具体重写效果越好。5.5 记录运行轨迹代理团队比单 Agent 更复杂定位问题也更难。建议每次运行都保留完整的轨迹日志包括输入目标、规划步骤、每步输入输出、审查意见、最终结果。这样当输出不符合预期时你可以回溯到具体环节。可以使用 Python logging 模块或直接写入 JSON 文件。归档运行轨迹是代理团队从实验走向生产的必经之路。5.6 支持人工介入无论代理团队多强大在关键业务决策上人工审核都是必要的。这也是“AI 代理助手”的现实定位它是助手不是完全替代者。在设计时可以加入“敏感任务暂停点”当审查器判断某个步骤存在风险时输出到人工确认而不是自动继续。这不仅是安全需要也是企业合规需要。6. 本地模型与 AI 代理助手的结合实践6.1 为什么需要本地模型很多团队在试运行代理系统后会提出一个问题所有业务数据都要经过外部 API隐私能被保证吗答案往往是不能。本地模型的优势正好弥补这一点数据不出内网、调用无 token 成本、可以针对业务场景微调。缺点是需要显存资源、推理速度有限、模型能力可能不如顶级 API。对于中配团队最合理的路线是“混合部署”核心敏感操作使用本地模型复杂推理场景调用远程大模型两者共存于同一套代理团队中。6.2 通过 Ollama 接入本地模型如果你选择本地模型方案Ollama 是目前最友好的工具之一。以常见的开源模型为例安装并启动服务后可以用下面的命令确认服务状态ollama list本地服务默认地址一般是http://localhost:11434OpenAI 兼容接口路径为/v1。在 .env 中做如下配置代理团队代码几乎不用改动LLM_BASE_URLhttp://localhost:11434/v1 LLM_API_KEYollama LLM_MODELqwen2.5:7b这样前面封装的 ModelClient 会自动把请求转发到本地模型服务。需要注意的是本地模型对显存要求不低。7B 级别的模型经过量化后在 8GB 显存上通常可以勉强运行但并发能力很弱。真实的推理速度会因硬件环境差异非常大建议先用小模型验证流程再逐步升级到更大模型。6.3 本地模型适合代理团队里的哪个角色根据我的经验本地模型更适合执行器因为执行任务往往是重复性的内容生成而规划器和审查器对推理质量要求更高建议使用远程强模型。当然如果你的本地模型是 70B 级别的量化版本并且显存充足那么所有角色都可以交给本地模型。整体设计依然是“模型无关”的所以你可以随时调整。7. 常见问题与排查思路7.1 问题排查表问题现象常见原因解决思路模型调用一直失败base_url 配置错误或 API Key 无效检查 .env 配置或直接 curl 对应接口测试规划器返回空步骤模型输出格式不符合清理规则调整 prompts要求模型严格输出编号列表执行器输出过于简短温度过高或提示词约束不足降低 temperature要求“至少输出 300 字”审查器永远不通过审查标准过于模糊将审查标准改为可检查的具体清单整个流程运行太慢步骤过多、模型过重、重试多精简步骤数为不同角色分配不同模型上下文过长导致结果变差每步都拼接全部历史输出引入摘要缓存只传递关键上下文工具调用报错参数名不匹配或工具未注册检查工具映射表和调用参数7.2 实战故障复盘这里分享一个典型的失败场景有一个代理团队负责生成产品周报。最初设计是所有环节共用同一个模型温度设为 0.9。结果执行器生成的内容非常发散审查器几乎每次都要求重写导致成本飙升、效率极低。排查后发现问题不在模型能力而在于“没有给执行器足够清晰的格式约束”。修复方式是把执行器的 system prompt 中加入模板和字数要求。将 temperature 降到 0.3。审查器改为按固定清单逐项打分。调整后审查通过率从 30% 提升到 80%。这个案例说明代理团队的瓶颈往往不是模型不够强而是流程设计不够细。8. 工程最佳实践与落地建议8.1 配置与密钥管理不要把 API Key 硬编码在代码里。使用.env文件配合 python-dotenv 加载并且确保.env文件被加入.gitignore。对生产环境建议使用配置中心或机密管理服务例如环境变量注入、KMS 等。8.2 日志与监控代理团队需要记录每次调用的模型名称、token 使用量、耗时、是否重试。这些数据既能帮助排查问题也能帮助你评估成本。建议在 ModelClient 中埋点输出结构化日志而不是散落各种 print。日志字段建议如下timestamp, agent_role, model, prompt_type, tokens_used, latency_ms, status8.3 最小权限原则给代理团队的工具权限要遵循最小权限原则。比如代理团队需要访问数据库那就只给只读账号需要调用 API就不给它管理权限。这不仅防止误操作也保护整个系统不被 Agent 的异常行为带偏。8.4 渐进式落地路径如果你是在真实业务中引入 AI 代理团队建议走渐进式路线先选择一个非关键流程做试点比如自动生成会议纪要。把流程跑通并收集真实数据评估质量与成本。逐步增加角色和工具能力。最后才扩展到客户可见的业务场景。“比 99% 的人更好”不是一步到位而是通过持续收集反馈、优化 prompts、增加审查标准、沉淀工具链逐步形成自己的代理团队工程能力。8.5 与人协作的定位最后也是最重要的原则AI 代理团队永远是增强人的能力而不是替代人的判断。它能把繁琐、重复、需要多步骤处理的工作自动化但在关键决策、创新设计、合规审查等环节人的参与仍然不可替代。把代理团队当作一个“实习生小组”你需要给它清晰的指令、明确的标准、及时的反馈。这样你得到的不是一堆不可控的自动输出而是一个真正能交付结果的工程系统。9. 总结这篇文章从概念到代码完整演示了如何构建一个具备“规划-执行-审查”闭环的 AI 代理团队。你学会了任务拆解、角色设计、模型客户端封装、工具层实现、主流程编排以及运行验证。同时你还了解了本地模型与远程 API 的混合部署策略、成本控制、错误恢复、上下文管理等工程细节。下一步你可以按以下三个方向继续深入把规划器和审查器的输出改为 JSON 格式提高结构化程度。接入更多工具比如网页搜索、数据库查询、文件读取让代理团队能处理真实世界任务。引入专门的记忆模块让代理团队在跨天任务中保留上下文。如果你把本文示例代码跑通并加上了你自己的工具和角色设定那么你的 AI 代理团队就已经超过了绝大多数还停留在“单次对话”层面的开发者。剩下的就是用工程标准去打磨它。
中配环境构建AI代理团队：多角色协作与本地模型实战
如果你也想搭建一套属于自己的 AI 代理团队又不想被各种复杂框架按住头学习那么这篇文章就是为你准备的。我不会只介绍概念还会把一套可运行的多角色 AI 代理工程直接拆出来讲包含完整代码、配置方法、运行过程以及把团队做稳的细节设计。无论你是刚接触 AI Agent还是已经写过几个简单工具都能从这套思路里得到可直接落地的能力。很多人在接触 AI 代理时第一反应是去追最新框架、堆最贵的模型结果搭出来的系统往往只会在理想输入下跑通一两次。真正的差距不是谁用的模型更大而是谁能把“规划、执行、审查、重试、上下文管理”这些工程细节做成闭环。比 99% 的人更好听起来像口号但落到方法论上其实就是少数几件事。本文将围绕“AI 代理团队”的构建展开重点讲解如何用中等配置的模型和合理的工程结构搭建出一套具备多角色协作能力的 AI 代理解决方案。你会看到什么是 AI 代理团队为什么需要它以及如何通过规划器、执行器、审查器三个核心角色让代理系统稳定输出高质量结果。同时也会涉及本地模型与远程 API 的选型、成本控制、错误恢复、上下文维护等关键问题。文章面向三类读者刚开始学习 AI 代理的开发者、想在企业项目中引入多智能体协作的工程师以及正在探索本地模型落地的技术爱好者。读完你会收获一套可以修改和扩展的 Python 工程示例以及一套能直接迁移到生产项目的设计思路。1. AI 代理团队是什么为什么需要组队1.1 单 Agent 的局限先从一个最简单的问题说起一个 AI 代理能不能独立完成高质量任务如果任务是“帮我把这段英文翻译成中文”单个代理使用足够强的模型确实能做到。但如果是“调研某个技术方向输出一份调研报告并且确保每个结论都有来源”单个代理的表现就会变得很不稳定。原因在于这类任务包含多个不同性质的能力需求它需要检索信息、评估信息可信度、组织表达、检查逻辑漏洞还需要不断返工修订。让一个 Agent 同时承担所有角色它会在上下文窗口里混入大量不同目标的信息导致注意力分散、输出质量下降。另一个常见问题是“自我修正失效”。单个 Agent 生成内容后让它自己检查错误效果往往不理想。因为模型在同一个思维上下文里对刚刚生成的错误已经形成了路径依赖。它很难站在外部视角发现自己输出的盲点。就像一个人写代码写完很难看到自己明显的变量名错误。1.2 多角色 AI 代理团队的本质AI 代理团队的本质是把一个复杂任务拆成多个专业角色每个角色负责一个独立环节角色之间通过任务边界和消息进行协作。用人来类比更容易理解项目经理负责拆解任务确定目标和优先级。研究员负责收集资料筛选信息。工程师负责写代码或生成结构化内容。评审专家负责检查质量提出修改意见。这种设计最大的价值不只是“人多力量大”而是每个角色都能保持清晰的指令上下文。规划器只专注于目标拆解不会在中途去纠结代码细节执行器只专注于产出内容不需要反复切换思维模式审查器站在外部视角发现问题避免自我修正失效。在工程表现上多角色团队显著提升了三个指标第一是任务完成率因为复杂任务被拆成可管理的子任务第二是输出稳定性因为每个环节都有明确验收标准第三是可维护性因为错误定位从“整个 Agent 的问题”缩小到“某个角色的问题”。1.3 AI 代理团队适用的场景AI 代团队不是所有场景都需要但下面几类任务非常适合长文本研究报告生成。需要检索、筛选、提纲、写作、校对多个环节。代码生成与审查。需要设计模块、编写实现、检查边界条件、运行调试。复杂数据处理流程。需要解析、清洗、分析、可视化、结论总结。内容生产的质量工程。比如批量生成文章或营销文案需要统一审查标准。用户意图识别与任务路由。需要意图判断、参数提取、API 调用、结果复核。如果你的任务只是单轮问答或简单工具调用使用单 Agent 就够了。一旦任务需要多次推理、多步骤操作、反复修订就应该考虑代理团队模式。2. 构建 AI 代理团队的通用思维框架2.1 任务拆解能力“比 99% 的人更好”的第一个分水岭是任务拆解能力。同样要求 AI 代理团队“写一份竞品分析报告”普通做法是把这句话直接丢给一个 Agent让它自由发挥。更好的做法是先把任务拆解成阶段确定分析维度、收集竞品信息、整理功能对比、形成结论建议、审核输出格式。拆解后的任务可以进入不同的角色也可以在同一角色内串行执行多个步骤。关键是每一步都要有明确的输入、输出和验收标准。我在实际项目里发现把任务拆成 3 到 5 个可执行步骤模型的输出质量会明显高于一次性生成完整结果。在代码层面任务拆解对应的是一个结构化的任务数据对象。每个任务包含名称、目标、输入、输出约束。这样后续的规划器、执行器、审查器才能有统一的协作语言。2.2 角色设计与职责划分一个最小可用的 AI 代理团队至少需要三个角色规划器Planner负责分析输入目标拆解为任务序列决定任务顺序和依赖关系。执行器Executor负责执行具体子任务根据任务类型调用模型或工具。审查器Reviewer负责按质量标准审查执行结果返回修改意见或确认通过。角色不需要太多太多会带来通信开销和延迟。对于大部分业务场景三个角色已经能形成有效闭环。如果你做的是非常大型的系统可以在执行器内部再拆出代码代理、检索代理、写作代理但核心架构仍然是“规划-执行-审查”。2.3 工具层与模型层分离代理团队不能只靠模型“空想”。在真实场景中它还需要工具层支撑比如搜索引擎、数据库查询、文件读写、代码解释器等。好的设计会把工具层和模型层解耦。模型只负责判断“下一步调用哪个工具、传入什么参数”工具层负责真正执行操作并返回结果。这种解耦让代理团队可以轻松替换模型而不需要改动工具接口也可以新增工具而不需要修改模型逻辑。一个简单的接口约定可以是class Tool: name: str description: str def run(self, **kwargs) - str: ...每个工具都注册上名称和描述模型根据描述选择工具。这样代理团队就具备了一定的“工具使用能力”而不是只会生成文本。3. 中配环境下如何选择模型与本地模型3.1 算力与成本约束下的模型选型题目标题里提到的“中配”在实际工程里对应的是普通笔记本或单卡 GPU 服务器、预算有限的 API 调用额度、不愿意被大模型 API 完全锁定的团队。在这类约束下模型选择有两条路线第一条路线是使用远程 API。例如 DeepSeek、Qwen 系列、OpenAI 兼容接口等。优点是效果稳定、接入简单缺点是有网络依赖和 token 成本。对于探索期团队我建议优先走这条路线因为可以快速验证系统架构不用陷入模型部署的泥潭。第二条路线是部署本地模型。例如通过 Ollama、vLLM 等工具运行开源模型适合对数据隐私要求高、或需要离线运行的场景。缺点是显存占用大、推理速度受硬件限制需要做一些量化如 Q4、Q8和批处理优化。中配团队的策略通常是默认使用远程 API核心敏感环节使用本地模型。AI 代理助手加本地模型的组合核心价值在于让代理团队拥有一个“私有底座”避免所有上下文都暴露给外部 API。这在企业内部落地时是很现实的需求。3.2 本地模型部署的常见方案对比本地模型工具非常多这里只提三个主流方向工具特点适合场景Ollama安装简单命令友好支持一键拉取模型本地开发测试、笔记本体验vLLM高吞吐量支持 OpenAI 兼容接口生产环境、多用户并发LM Studio图形化界面支持本地推理非开发者快速体验简单来说Ollama 是最容易上手的选择。以最常见的部署方式为例启动本地模型服务后它会暴露一个与 OpenAI 兼容的接口地址例如http://localhost:11434/v1。这样你的代理团队代码只需要改一个base_url就能从远程 API 切换到本地模型不需要重构任何业务逻辑。这一点非常关键在架构设计时把所有模型调用统一封装到一个 ModelClient 中是整个代理团队后期可以自由切换模型的基础。下面的实战环节会具体演示。3.3 为什么代理团队需要“模型无关”很多代理项目写死了一家模型厂商的 SDK导致后期想换模型时四处改代码。更合理的做法是使用 OpenAI 兼容协议来统一访问远程模型和本地模型让模型层成为可替换的组件。你可以把模型看作代理团队的“员工”不同员工擅长不同工作。规划器可以用推理能力强的模型执行器可以用生成速度快的模型审查器可以用评判能力好的模型。这种“按角色配置模型”的能力才是真正的工程化思维。因此“AI 代理助手加本地模型”的实践路径不是简单地用本地模型替代远程 API而是要让代理团队有能力混用多种模型让每个角色用上最合适的模型。4. 完整实战构建一个“规划-执行-审查”AI 代理团队4.1 系统设计下面开始动手。我们构建一个 Python 项目实现一个最小的多角色 AI 代理团队。它的功能是接收一个用户任务由规划器拆解任务执行器逐个执行审查器检查结果并决定是大重写、小修改还是通过。为了演示通用性执行器提供的工具能力包括文本生成根据指令直接生成内容。文档摘要对一段文字进行摘要提取。代码审查对一段代码提出改进意见。这三类能力足以覆盖很多常见任务同时足够简单方便理解代理团队的协作机制。整体工作流程用户提交任务。规划器将任务拆成阶段化步骤。执行器按步骤调用模型与工具。审查器检查输出如果通过输出最终结果否则带着审查意见返回到规划器或执行器重做。推荐使用下面的项目结构agent_team/ ├── requirements.txt ├── .env.example ├── config │ └── config.yaml ├── src │ ├── __init__.py │ ├── model_client.py │ ├── tools.py │ ├── agents.py │ └── workflow.py └── main.py4.2 环境准备与依赖安装本文示例使用 Python 3.10核心依赖为 openai、pyyaml、python-dotenv。为了保持最小依赖我们不引入 LangChain 或 LangGraph而是用原生 Python 实现一套轻量多代理流程。这样做的好处是你能看到多代理协作的真正机制而不是被框架包装掩盖。创建虚拟环境并安装依赖python -m venv venv source venv/bin/activate pip install openai pyyaml python-dotenv如果项目中需要记录依赖可以生成 requirements.txtopenai1.30.0 pyyaml6.0 python-dotenv1.0.0注意不同版本的 openai SDK 接口可能有差异如果安装的是最新版调用方法与下面代码理论上兼容如果遇到不兼容报错以官方文档为准。4.3 模型客户端封装为了让代理团队能灵活切换远程模型和本地模型我们先封装 ModelClient 类。文件路径src/model_client.pyimport os from openai import OpenAI class ModelClient: 统一的模型调用客户端支持 OpenAI 兼容接口。 def __init__(self, model: str gpt-4o-mini, base_url: str None, api_key: str None, temperature: float 0.7): self.model model self.base_url base_url or os.getenv(LLM_BASE_URL, https://api.openai.com/v1) self.api_key api_key or os.getenv(LLM_API_KEY, sk-demo) self.temperature temperature self.client OpenAI(base_urlself.base_url, api_keyself.api_key) def chat(self, system_prompt: str, user_message: str, max_tokens: int 1024) - str: 发送对话请求返回模型生成的文本。 try: response self.client.chat.completions.create( modelself.model, temperatureself.temperature, max_tokensmax_tokens, messages[ {role: system, content: system_prompt}, {role: user, content: user_message}, ], ) return response.choices[0].message.content.strip() except Exception as e: return f[模型调用失败] {e}这段代码有几个关键设计统一使用 OpenAI 兼容协议所以切换模型时只需要调整环境变量。所有异常都被捕获并返回可读提示这样即使模型调用失败代理团队也能拿到结构化反馈而不是直接崩溃。system_prompt与user_message分离方便后续每个 Agent 注入自己的角色信息。对应的 .env.example 内容# 如果使用远程 API填对应的 base_url 和 api_key LLM_BASE_URLhttps://api.openai.com/v1 LLM_API_KEYsk-your-key # 如果使用本地模型例如 Ollama改成下面这样 # LLM_BASE_URLhttp://localhost:11434/v1 # LLM_API_KEYollama4.4 工具层实现工具层让执行器具备实际能力。本示例实现两个工具摘要工具和代码审查工具。文件路径src/tools.pyclass SummarizeTool: name summarize description 对一段文本生成简洁摘要 def run(self, text: str, max_length: int 100) - str: # 这里为了演示简单直接截断文本。 # 生产环境可以调用模型或使用更复杂的摘要算法。 if len(text) max_length: return text return text[:max_length] ... class CodeReviewTool: name code_review description 对代码片段提出改进建议 def run(self, code: str) - str: # 演示用规则式审查实际项目可替换为基于模型的审查。 suggestions [] if eval( in code: suggestions.append(避免使用 eval存在安全风险) if len(code.splitlines()) 50: suggestions.append(函数过长建议拆分为多个更小的函数) if TODO in code: suggestions.append(存在 TODO 待办事项需要补充实现) if not suggestions: suggestions.append(没有发现明显问题) return \n.join(suggestions) TOOL_MAP { SummarizeTool.name: SummarizeTool(), CodeReviewTool.name: CodeReviewTool(), } def run_tool(tool_name: str, **kwargs) - str: tool TOOL_MAP.get(tool_name) if tool is None: return f错误未找到名为 {tool_name} 的工具 try: return tool.run(**kwargs) except Exception as e: return f工具执行失败{e}在实际项目中工具层往往不只是规则代码而是会调用外部 API、执行数据库查询、读取本地文件等。但无论底层逻辑多复杂对上层代理来说工具只需要暴露“名称、描述、参数、返回值”这四样东西这样模型才能学会使用它。4.5 三个角色规划器、执行器、审查器文件路径src/agents.pyfrom .model_client import ModelClient from .tools import run_tool class Planner: 规划器把用户目标拆解成可执行任务列表。 def __init__(self, client: ModelClient): self.client client def plan(self, user_goal: str) - list[str]: system_prompt 你是一名资深项目经理负责把复杂目标拆解为可执行的独立步骤。 请只输出步骤列表不要输出解释性内容。格式要求 1. 步骤内容 2. 步骤内容 ... result self.client.chat(system_prompt, user_goal, max_tokens512) steps [line.strip().lstrip(0123456789.、 ) for line in result.splitlines() if line.strip() and not line.startswith(步骤)] return steps or [完成用户目标] class Executor: 执行器按规划结果执行子任务必要时调用工具。 def __init__(self, client: ModelClient): self.client client def execute(self, step: str, context: str ) - str: system_prompt 你是一名高效的执行者负责完成用户分配的具体子任务。 你可以调用工具但工具调用完成后你需要把工具结果整理成可读的文本输出。 当前可用工具 - summarize: 对文本生成摘要 - code_review: 对代码提供审查意见 如果不需要调用工具直接完成文本生成任务。 user_message f当前步骤{step}\n if context: user_message f上下文信息\n{context}\n user_message 请输出最终结果。 result self.client.chat(system_prompt, user_message, max_tokens1024) return result class Reviewer: 审查器检查执行结果是否合格返回通过或修改意见。 def __init__(self, client: ModelClient): self.client client def review(self, original_goal: str, steps: list[str], outputs: list[str]) - dict: system_prompt 你是一名质量审查专家负责检查执行结果是否完成了用户原始目标。 请输出以下格式 结论通过 或 结论需要修改 意见具体的修改意见 user_message f原始目标{original_goal}\n\n执行步骤和结果如下\n for idx, (step, output) in enumerate(zip(steps, outputs), 1): user_message f步骤{idx}{step}\n结果{output}\n user_message \n请给出审查结论。 result self.client.chat(system_prompt, user_message, max_tokens512) if 通过 in result: return {passed: True, feedback: result} return {passed: False, feedback: result}每个 Agent 的本质都是一个“带角色提示词 模型客户端”的组合。我们并没有发明复杂机制只是把不同角色的人设和系统提示词分开。这样每个模型调用都是干净的单一任务不会被无关上下文污染。这里需要注意规划器返回步骤列表时我们做了一个简单的文本清理去除开头的数字编号。这是为了把模型输出转成程序可用的结构化数据。在实际项目中更推荐让模型输出 JSON 格式再解析这样稳定性更高。4.6 主流程编排文件路径src/workflow.pyfrom .agents import Planner, Executor, Reviewer from .model_client import ModelClient class AgentTeam: AI 代理团队主流程。 def __init__(self, client: ModelClient): self.client client self.planner Planner(client) self.executor Executor(client) self.reviewer Reviewer(client) def run(self, user_goal: str, max_review_rounds: int 2) - dict: print( 规划器开始拆解任务) steps self.planner.plan(user_goal) print(f 规划结果{steps}) outputs [] context for idx, step in enumerate(steps, 1): print(f 执行器执行步骤 {idx}: {step}) output self.executor.execute(step, context) print(f 步骤 {idx} 输出\n{output}) outputs.append(output) context output round_num 0 while round_num max_review_rounds: print(f 审查器开始第 {round_num 1} 轮审查) review_result self.reviewer.review(user_goal, steps, outputs) print(f 审查结果{review_result}) if review_result[passed]: print( 审查通过流程结束) return { goal: user_goal, steps: steps, outputs: outputs, review: review_result, final_output: \n\n.join(outputs), } print( 审查未通过重新规划并执行) steps self.planner.plan(f{user_goal}\n同时考虑以下修改意见{review_result[feedback]}) outputs [] context for idx, step in enumerate(steps, 1): output self.executor.execute(step, context) outputs.append(output) context output round_num 1 return { goal: user_goal, steps: steps, outputs: outputs, review: review_result, final_output: \n\n.join(outputs), }这个流程的可贵之处在于它实现了一个“质量闭环”。当审查器认为结果不合格时代理团队不是简单地把步骤再执行一遍而是重新规划把修改意见带入新的任务拆解中。很多初版 AI 代理项目只做到“执行”没有“审查”导致输出质量完全依赖模型当天状态。加入审查环节后系统的鲁棒性会有质的提升。当然一个真实的团队里审查者可能会多次打回所以我们需要设置最大重试轮数防止因为模型反复不达标而陷入死循环。4.7 运行入口文件路径main.pyimport os import yaml from dotenv import load_dotenv from src.model_client import ModelClient from src.workflow import AgentTeam load_dotenv() # 读取配置 with open(config/config.yaml, r, encodingutf-8) as f: config yaml.safe_load(f) client ModelClient( modelconfig[models][default_model], base_urlos.getenv(LLM_BASE_URL, https://api.openai.com/v1), api_keyos.getenv(LLM_API_KEY, sk-demo), temperatureconfig[models][temperature], ) team AgentTeam(client) if __name__ __main__: goal input(请输入你的目标) result team.run(goal) print(\n\n 最终结果 ) print(result[final_output])配置文件 config/config.yamlmodels: default_model: gpt-4o-mini temperature: 0.74.8 运行验证假设我们输入一个目标帮我写一个 Python 函数用于统计列表中重复元素的次数并审查这个函数。运行后可能看到类似下面的流程日志 规划器开始拆解任务 规划结果[定义一个函数接收列表参数, 使用字典统计重复元素次数, 编写代码并审查] 执行器执行步骤 1: 定义一个函数接收列表参数 步骤 1 输出首先需要定义函数签名输入为 list输出为 dict 执行器执行步骤 2: 使用字典统计重复元素次数 步骤 2 输出遍历列表更新字典计数 执行器执行步骤 3: 编写代码并审查 步骤 3 输出def count_duplicates(lst): ... 审查器开始第 1 轮审查 审查结果结论通过 审查通过流程结束这就是一个最基本的 AI 代理团队工作过程。你会看到复杂任务被拆成步骤每个步骤单独执行最后还有质量检查。在真实使用中你输入的目标越具体规划器的拆解质量就越高。比如“帮我写一个 Python 函数”就比“写点代码”好得多。5. 让代理团队真正优于大多数人的 6 个细节5.1 上下文管理代理团队在执行多个步骤时最大的风险是上下文漂移。执行器在执行步骤 3 时可能已经忘记步骤 1 产生的关键信息。解决方法是显式维护一个 context 对象把历史关键信息持久化并在每一步执行时注入。上面的示例中我们把之前的输出拼接到当前步骤的上下文中这就是最简单的上下文管理。更精细的做法是只保留与当前步骤相关的信息避免上下文过长导致“注意力稀释”。你可以用一个简单的规则关键词匹配也可以用向量检索做相关性筛选。5.2 错误恢复与重试代理团队跑在真实环境里模型接口超时、限流、返回空内容都是家常便饭。不要把一次失败当作整个任务的终结。建议在 ModelClient 中加入简单的指数退避重试逻辑import time def chat_with_retry(self, system_prompt, user_message, max_tokens1024, retries3): for attempt in range(retries): result self.chat(system_prompt, user_message, max_tokens) if not result.startswith([模型调用失败]): return result time.sleep(2 ** attempt) return result这样即使模型服务短暂抖动代理团队也能自愈。5.3 成本控制多角色团队意味着多次模型调用。一次完整任务可能消耗 5 到 10 次 API 调用比单 Agent 更烧钱。成本控制的核心手段有三个精简步骤数量规划器不要拆出无意义步骤。为不同角色配置不同模型执行器用便宜的模型规划器与审查器用更强模型。对工具调用结果做缓存相同请求不重复调用模型。在 config.yaml 中可以为每个角色单独配置模型名称这是推荐的最佳实践models: planner_model: deepseek-chat executor_model: gpt-4o-mini reviewer_model: deepseek-chat temperature: 0.55.4 审查标准要可执行很多审查器的问题在于它只会说“内容不够好”但不会说“到底哪里不够好”。没有可执行的审查意见执行器重做时也会很迷茫。解决方法是把审查标准量化到提示词中。例如“检查报告是否包含数据来源如果缺失请明确指出缺失的是哪个部分”。审查意见越具体重写效果越好。5.5 记录运行轨迹代理团队比单 Agent 更复杂定位问题也更难。建议每次运行都保留完整的轨迹日志包括输入目标、规划步骤、每步输入输出、审查意见、最终结果。这样当输出不符合预期时你可以回溯到具体环节。可以使用 Python logging 模块或直接写入 JSON 文件。归档运行轨迹是代理团队从实验走向生产的必经之路。5.6 支持人工介入无论代理团队多强大在关键业务决策上人工审核都是必要的。这也是“AI 代理助手”的现实定位它是助手不是完全替代者。在设计时可以加入“敏感任务暂停点”当审查器判断某个步骤存在风险时输出到人工确认而不是自动继续。这不仅是安全需要也是企业合规需要。6. 本地模型与 AI 代理助手的结合实践6.1 为什么需要本地模型很多团队在试运行代理系统后会提出一个问题所有业务数据都要经过外部 API隐私能被保证吗答案往往是不能。本地模型的优势正好弥补这一点数据不出内网、调用无 token 成本、可以针对业务场景微调。缺点是需要显存资源、推理速度有限、模型能力可能不如顶级 API。对于中配团队最合理的路线是“混合部署”核心敏感操作使用本地模型复杂推理场景调用远程大模型两者共存于同一套代理团队中。6.2 通过 Ollama 接入本地模型如果你选择本地模型方案Ollama 是目前最友好的工具之一。以常见的开源模型为例安装并启动服务后可以用下面的命令确认服务状态ollama list本地服务默认地址一般是http://localhost:11434OpenAI 兼容接口路径为/v1。在 .env 中做如下配置代理团队代码几乎不用改动LLM_BASE_URLhttp://localhost:11434/v1 LLM_API_KEYollama LLM_MODELqwen2.5:7b这样前面封装的 ModelClient 会自动把请求转发到本地模型服务。需要注意的是本地模型对显存要求不低。7B 级别的模型经过量化后在 8GB 显存上通常可以勉强运行但并发能力很弱。真实的推理速度会因硬件环境差异非常大建议先用小模型验证流程再逐步升级到更大模型。6.3 本地模型适合代理团队里的哪个角色根据我的经验本地模型更适合执行器因为执行任务往往是重复性的内容生成而规划器和审查器对推理质量要求更高建议使用远程强模型。当然如果你的本地模型是 70B 级别的量化版本并且显存充足那么所有角色都可以交给本地模型。整体设计依然是“模型无关”的所以你可以随时调整。7. 常见问题与排查思路7.1 问题排查表问题现象常见原因解决思路模型调用一直失败base_url 配置错误或 API Key 无效检查 .env 配置或直接 curl 对应接口测试规划器返回空步骤模型输出格式不符合清理规则调整 prompts要求模型严格输出编号列表执行器输出过于简短温度过高或提示词约束不足降低 temperature要求“至少输出 300 字”审查器永远不通过审查标准过于模糊将审查标准改为可检查的具体清单整个流程运行太慢步骤过多、模型过重、重试多精简步骤数为不同角色分配不同模型上下文过长导致结果变差每步都拼接全部历史输出引入摘要缓存只传递关键上下文工具调用报错参数名不匹配或工具未注册检查工具映射表和调用参数7.2 实战故障复盘这里分享一个典型的失败场景有一个代理团队负责生成产品周报。最初设计是所有环节共用同一个模型温度设为 0.9。结果执行器生成的内容非常发散审查器几乎每次都要求重写导致成本飙升、效率极低。排查后发现问题不在模型能力而在于“没有给执行器足够清晰的格式约束”。修复方式是把执行器的 system prompt 中加入模板和字数要求。将 temperature 降到 0.3。审查器改为按固定清单逐项打分。调整后审查通过率从 30% 提升到 80%。这个案例说明代理团队的瓶颈往往不是模型不够强而是流程设计不够细。8. 工程最佳实践与落地建议8.1 配置与密钥管理不要把 API Key 硬编码在代码里。使用.env文件配合 python-dotenv 加载并且确保.env文件被加入.gitignore。对生产环境建议使用配置中心或机密管理服务例如环境变量注入、KMS 等。8.2 日志与监控代理团队需要记录每次调用的模型名称、token 使用量、耗时、是否重试。这些数据既能帮助排查问题也能帮助你评估成本。建议在 ModelClient 中埋点输出结构化日志而不是散落各种 print。日志字段建议如下timestamp, agent_role, model, prompt_type, tokens_used, latency_ms, status8.3 最小权限原则给代理团队的工具权限要遵循最小权限原则。比如代理团队需要访问数据库那就只给只读账号需要调用 API就不给它管理权限。这不仅防止误操作也保护整个系统不被 Agent 的异常行为带偏。8.4 渐进式落地路径如果你是在真实业务中引入 AI 代理团队建议走渐进式路线先选择一个非关键流程做试点比如自动生成会议纪要。把流程跑通并收集真实数据评估质量与成本。逐步增加角色和工具能力。最后才扩展到客户可见的业务场景。“比 99% 的人更好”不是一步到位而是通过持续收集反馈、优化 prompts、增加审查标准、沉淀工具链逐步形成自己的代理团队工程能力。8.5 与人协作的定位最后也是最重要的原则AI 代理团队永远是增强人的能力而不是替代人的判断。它能把繁琐、重复、需要多步骤处理的工作自动化但在关键决策、创新设计、合规审查等环节人的参与仍然不可替代。把代理团队当作一个“实习生小组”你需要给它清晰的指令、明确的标准、及时的反馈。这样你得到的不是一堆不可控的自动输出而是一个真正能交付结果的工程系统。9. 总结这篇文章从概念到代码完整演示了如何构建一个具备“规划-执行-审查”闭环的 AI 代理团队。你学会了任务拆解、角色设计、模型客户端封装、工具层实现、主流程编排以及运行验证。同时你还了解了本地模型与远程 API 的混合部署策略、成本控制、错误恢复、上下文管理等工程细节。下一步你可以按以下三个方向继续深入把规划器和审查器的输出改为 JSON 格式提高结构化程度。接入更多工具比如网页搜索、数据库查询、文件读取让代理团队能处理真实世界任务。引入专门的记忆模块让代理团队在跨天任务中保留上下文。如果你把本文示例代码跑通并加上了你自己的工具和角色设定那么你的 AI 代理团队就已经超过了绝大多数还停留在“单次对话”层面的开发者。剩下的就是用工程标准去打磨它。
