1. 从单轮到多 Agent为什么这个话题值得认真聊Agent 这个词在过去一年里被反复提及但真正落到工程实现层面很多人的认知还停留在“调一次大模型 API返回一段文本”的阶段。如果你也是从这个起点出发那这篇文章就是写给你的。我会把 Agent 的实现方式从最简单的单轮调用一路拆到多 Agent 协作讲清楚每一层架构背后的设计动机、核心机制、实操要点以及我在实际项目中踩过的坑。先说清楚这篇文章的定位它不是某个框架的官方文档翻译也不是概念科普。它更像是一个做过几个 Agent 项目的人坐下来跟你复盘“我当时为什么这么选、这么写、这么调”。涉及到的框架会提到但重点在架构思路和实现原理因为框架会变思路不会。单轮调用是最基础的形态用户输入一段话模型返回一段话结束。多 Agent 协作则是多个具备独立角色、独立工具、独立记忆的智能体通过某种编排机制协同完成一个复杂任务。从前者到后者中间隔着工具调用、记忆管理、任务规划、通信协议、并发控制、安全沙箱等一大堆工程问题。这篇文章会沿着这条演进路线逐层拆解。适合谁看如果你正在做 Agent 应用开发或者准备从“调 API”进阶到“搭系统”又或者你在面试中被问到 Agent 架构设计这篇文章里的思路和细节应该能帮到你。我会尽量用生活化的类比解释复杂概念同时保证技术细节足够扎实让你看完能直接上手改自己的项目。2. 单轮调用Agent 的最小可行形态2.1 单轮调用的本质与边界单轮调用说白了就是“一问一答”。你给模型一个 prompt模型给你一个 completion整个交互在一次请求内完成。这是所有 Agent 系统的原子操作也是理解后续所有复杂架构的基础。但这里有个容易被忽略的点单轮调用并不等于“没有 Agent 能力”。一个设计良好的单轮调用可以通过精心构造的 prompt 实现意图识别、信息抽取、格式化输出等功能。很多所谓的“Agent 应用”拆开看其实就是一串单轮调用的串联。问题在于当任务需要多步推理、需要调用外部工具、需要根据中间结果调整策略时单轮调用的天花板就出现了。我试过用一个单轮 prompt 让模型完成“查天气并推荐穿搭”的任务结果是模型要么编造天气数据要么给出与天气无关的穿搭建议。原因很简单模型没有获取实时信息的能力也没有“先查再推”的分步执行机制。这就是单轮调用的核心边界——它只能基于已有上下文做一次性生成无法与外部世界交互也无法自我修正。2.2 单轮调用的工程实现要点虽然简单但单轮调用在生产环境里也有不少讲究。首先是超时控制。大模型 API 的响应时间波动很大短则几百毫秒长则几十秒。如果不设超时一个慢请求可能拖垮整个服务。我的做法是设置两级超时连接超时 5 秒读取超时根据任务复杂度动态调整一般 30 到 60 秒。其次是重试策略。网络抖动、服务端限流都会导致请求失败。但不是所有失败都值得重试——参数错误重试多少次都没用而 429 限流则需要退避重试。我通常用指数退避加随机抖动初始间隔 1 秒最大重试 3 次。import time import random import requests def call_llm_with_retry(prompt, max_retries3): base_delay 1.0 for attempt in range(max_retries): try: resp requests.post( LLM_ENDPOINT, json{prompt: prompt}, timeout(5, 60) ) if resp.status_code 429: delay base_delay * (2 ** attempt) random.uniform(0, 0.5) time.sleep(delay) continue resp.raise_for_status() return resp.json() except requests.exceptions.Timeout: if attempt max_retries - 1: raise time.sleep(base_delay * (2 ** attempt)) raise RuntimeError(LLM call failed after retries)还有一个常被忽视的点是输出解析的健壮性。如果你要求模型返回 JSON就必须处理它返回非 JSON 的情况。我的经验是在 prompt 里明确给出 JSON schema同时在代码里做容错解析比如用正则提取第一个完整的 JSON 对象或者用 json_repair 这类库兜底。别指望模型 100% 听话工程代码要假设它会犯错。提示单轮调用阶段就要建立可观测性。记录每次请求的 prompt、响应、耗时、token 消耗这些数据在后续排查问题和优化成本时非常关键。3. 工具调用让 Agent 真正“能做事”3.1 工具调用的核心机制单轮调用只能“说”工具调用才能“做”。工具调用的本质是模型不再直接生成最终答案而是生成一个结构化的工具调用请求由外部系统执行后把结果返回给模型模型再基于结果生成最终回答。这个机制在不同模型上的实现细节不同但核心流程一致。以常见的 function calling 为例你需要向模型描述可用的工具工具名称、功能说明、参数 schema。模型根据用户输入判断是否需要调用工具如果需要就输出一个包含工具名和参数的 JSON。你的代码解析这个 JSON执行对应的函数把返回值作为新的消息追加到对话历史中再次调用模型。这里的关键设计点是工具描述的粒度。工具太粗模型不知道怎么用工具太细模型会在多个工具间反复横跳。我的经验是一个工具只做一件事但这件事要有明确的输入输出边界。比如“查询订单状态”是一个好工具“处理订单”就太宽泛了应该拆成“查询订单”“取消订单”“修改订单地址”等。3.2 工具调用的实操细节与避坑实现工具调用时有几个坑我踩过不止一次。第一个是参数类型不匹配。模型可能把数字类型的参数输出成字符串或者把数组输出成逗号分隔的字符串。解决办法是在工具执行层做类型转换和校验别直接信任模型的输出。第二个是工具调用循环。模型可能反复调用同一个工具或者在不同工具之间无限循环。我通常设置一个最大迭代次数比如 10 次超过就强制终止并返回当前结果。同时在 prompt 里明确告诉模型“如果已经获得足够信息请直接给出最终答案不要继续调用工具”。第三个是错误处理。工具执行失败时不要把异常直接抛给模型而是返回一个结构化的错误信息让模型有机会调整策略。比如查询天气失败返回{error: 城市名称无法识别请确认城市名是否正确}模型可能会尝试用另一个城市名重新查询。def execute_tool(tool_name, arguments): tool_map { get_weather: get_weather, search_web: search_web, query_order: query_order, } if tool_name not in tool_map: return {error: f未知工具: {tool_name}} try: result tool_map[tool_name](**arguments) return {result: result} except TypeError as e: return {error: f参数错误: {str(e)}} except Exception as e: return {error: f执行失败: {str(e)}}注意工具的执行结果要控制长度。如果工具返回了大量数据不要全部塞回给模型而是做摘要或截断。否则 token 消耗会爆炸而且模型可能被无关信息干扰。3.3 工具调用与单轮调用的本质区别从架构角度看工具调用把“一次请求”变成了“一个循环”。这个循环的终止条件是模型不再请求调用工具而是直接输出最终答案。这个变化看似简单但它意味着 Agent 开始具备了“感知-决策-行动”的闭环能力。我习惯把这个循环叫做Agent Loop。它是后续所有复杂 Agent 架构的基础单元。理解了 Agent Loop你就能理解为什么需要记忆管理循环中要保存历史、为什么需要任务规划循环中要决定下一步、为什么需要多 Agent单个循环搞不定复杂任务。4. 记忆与规划Agent 的“大脑”升级4.1 短期记忆与长期记忆的分层设计Agent 的记忆问题本质上是上下文窗口有限与任务信息无限之间的矛盾。短期记忆就是当前对话的消息列表它随着 Agent Loop 的进行不断增长。长期记忆则是跨会话、跨任务持久化的信息通常存在外部数据库或向量库中。短期记忆的管理策略直接影响 Agent 的表现。最简单的做法是全量保留但很快会遇到上下文超限的问题。我的做法是分层处理最近 N 轮对话完整保留更早的对话做摘要压缩关键信息如用户偏好、任务目标提取成结构化字段单独存储。长期记忆的实现通常用向量数据库。把历史对话、文档、知识库切片后做 embedding查询时用相似度检索。但这里有个常见误区不是所有信息都值得存入长期记忆。我的筛选标准是用户明确表达的偏好、任务执行中的关键决策、可复用的知识片段。闲聊内容、临时状态不需要长期保存。4.2 任务规划的实现方式任务规划是 Agent 从“被动响应”到“主动执行”的关键。没有规划的 Agent每一步都依赖模型的即时判断容易迷失在复杂任务中。有了规划Agent 可以先拆解任务再逐步执行。常见的规划方式有三种。第一种是ReAct 模式推理和行动交替进行模型先思考下一步做什么然后执行观察结果后再思考。这种方式灵活但效率不高适合探索性任务。第二种是Plan-and-Execute 模式先让模型生成完整的任务计划然后按计划逐步执行。这种方式效率高但缺乏灵活性适合流程明确的任务。第三种是混合模式先做粗粒度规划执行过程中根据实际情况动态调整。我在实际项目中用得最多的是混合模式。具体做法是第一轮让模型输出一个高层级的步骤列表然后每一步执行时再让模型决定具体用什么工具、传什么参数。这样既保证了方向不跑偏又保留了应对意外的灵活性。def plan_and_execute(task, max_steps10): plan llm_generate_plan(task) results [] for step in plan[steps]: step_result execute_step(step, contextresults) results.append(step_result) if step_result.get(need_replan): plan llm_replan(task, results) return llm_summarize(task, results)提示规划的质量高度依赖 prompt 的设计。我通常会在 prompt 里给出规划的输出格式示例并明确要求“步骤要具体、可执行、有明确的完成标准”。5. 多 Agent 协作从单兵作战到团队配合5.1 多 Agent 架构的核心模式当任务复杂到单个 Agent 搞不定时就需要多个 Agent 协作。多 Agent 架构的核心问题是如何划分角色、如何通信、如何协调。目前主流的模式有三种。第一种是主从模式一个 Orchestrator Agent 负责拆解任务和分配工作多个 Worker Agent 负责执行具体子任务。这种模式结构清晰适合任务可分解的场景。第二种是对等模式多个 Agent 地位平等通过消息传递协商完成任务。这种模式灵活但协调成本高。第三种是流水线模式多个 Agent 按固定顺序处理任务每个 Agent 负责一个阶段。这种模式效率高但适应性差。我做过的一个项目是自动生成行业分析报告用的就是主从模式。Orchestrator 负责把报告拆成“数据收集”“数据分析”“趋势判断”“报告撰写”四个子任务分别交给四个专门的 Agent。每个 Worker Agent 有自己的工具集和 prompt 模板完成后把结果返回给 Orchestrator由它整合成最终报告。5.2 Agent 间通信与状态共享多 Agent 协作的难点不在单个 Agent 的实现而在 Agent 之间的通信和状态共享。通信方式主要有两种消息传递和共享内存。消息传递就是 Agent 之间直接发送结构化消息优点是解耦彻底缺点是调试困难消息丢失或格式错误时很难定位。共享内存则是所有 Agent 读写同一个状态存储优点是状态一致性好缺点是并发控制复杂。我的经验是小规模协作3 个 Agent 以内用消息传递大规模协作用共享内存加锁。共享内存的实现可以用 Redis 或数据库关键是要定义好状态 schema并且对写操作加锁。import redis import json class SharedState: def __init__(self, redis_client): self.redis redis_client def update(self, key, value, agent_id): lock_key flock:{key} with self.redis.lock(lock_key, timeout10): current self.redis.get(key) data json.loads(current) if current else {} data[agent_id] value self.redis.set(key, json.dumps(data)) def read(self, key): data self.redis.get(key) return json.loads(data) if data else {}注意多 Agent 系统一定要有超时和熔断机制。某个 Agent 卡住不返回整个系统不能跟着卡死。我通常给每个 Agent 设置独立的超时时间超时后由 Orchestrator 决定是重试、跳过还是终止整个任务。5.3 多 Agent 协作的并发与安全考量多 Agent 系统天然涉及并发。多个 Agent 同时读写共享状态、同时调用外部工具、同时消耗 token 配额这些都需要工程上的处理。并发控制方面我用过两种方案。一种是信号量限流限制同时运行的 Agent 数量避免资源耗尽。另一种是任务队列把子任务放入队列由 Worker 池消费。前者实现简单后者扩展性好。具体选哪种取决于任务的实时性要求和资源预算。安全方面多 Agent 系统面临的风险比单 Agent 更大。一个 Agent 被恶意输入操控可能影响整个系统。我的做法是每个 Agent 的输入输出都做校验敏感操作如删除数据、发送消息需要额外的确认机制Agent 之间的通信内容也要做过滤。还有一个容易被忽视的点是成本控制。多 Agent 意味着多倍的 token 消耗。我在项目里会设置全局 token 预算每个 Agent 有独立的配额超预算就降级处理或终止。这个机制在演示环境可能用不上但生产环境是必须的。6. 常见问题与排查技巧实录6.1 Agent 开发中的典型问题速查问题现象可能原因排查思路解决方案Agent 反复调用同一工具prompt 未明确终止条件检查工具调用历史设置最大迭代次数prompt 中明确“信息足够时直接回答”工具参数格式错误模型输出不稳定打印模型原始输出在工具执行层做类型转换和校验多 Agent 结果冲突共享状态未加锁检查并发写入日志对共享状态加分布式锁上下文超限记忆未压缩统计每轮 token 数分层记忆管理早期对话做摘要Agent 响应慢工具调用串行分析各步骤耗时无依赖的工具调用并行化输出格式不符合预期prompt 约束不够对比 prompt 和实际输出给出明确的输出示例和格式说明6.2 几个我踩过的坑和独家技巧第一个坑是过度设计。刚开始做 Agent 时我总想一步到位搞多 Agent 协作结果系统复杂度爆炸调试成本极高。后来我学乖了能用单轮调用解决的不用工具调用能用单 Agent 解决的不用多 Agent。架构演进应该是被需求驱动的不是被技术好奇心驱动的。第二个坑是忽视日志。Agent 系统的执行路径是不确定的没有详细的日志出了问题根本不知道哪一步错了。我现在会在每个关键节点打日志模型输入、模型输出、工具调用参数、工具返回结果、状态变更。日志格式用结构化 JSON方便后续检索和分析。第三个技巧是用评测集驱动开发。Agent 的行为很难用单元测试覆盖但可以构建评测集准备一批典型任务定义期望的输出标准每次修改后跑一遍评测集看通过率变化。这个做法能有效防止“改了一个地方坏了另一个地方”。提示评测集的构建要从真实场景出发覆盖正常流程、边界情况和异常输入。我通常从线上日志里采样脱敏后作为评测用例。6.3 Agent 安全与沙箱实践Agent 安全是个容易被忽视但极其重要的话题。Agent 能调用工具、能读写数据、能发消息一旦被恶意操控后果可能很严重。我的安全实践包括三层。第一层是输入过滤对用户输入做敏感词检测和注入攻击防护防止 prompt 注入。第二层是权限控制每个 Agent 只能访问它需要的工具和数据遵循最小权限原则。第三层是沙箱隔离工具执行在沙箱环境中进行限制网络访问和文件系统访问。ALLOWED_TOOLS { report_agent: [search_web, read_database], write_agent: [write_file, send_email], } def check_permission(agent_id, tool_name): allowed ALLOWED_TOOLS.get(agent_id, []) if tool_name not in allowed: raise PermissionError(fAgent {agent_id} 无权调用 {tool_name})沙箱的实现可以用容器或轻量级虚拟机。关键是要确保 Agent 的工具调用不会影响宿主系统同时保留必要的功能。这个平衡点需要根据具体场景调整。7. 从理论到落地我的 Agent 学习路线建议如果你刚接触 Agent 开发我建议按这个顺序推进。先吃透单轮调用和 prompt 工程这是所有后续能力的基础。然后实现一个带工具调用的 Agent Loop理解“感知-决策-行动”的闭环。接着加入记忆管理和任务规划让 Agent 能处理多步任务。最后再尝试多 Agent 协作从两个 Agent 的主从模式开始逐步增加复杂度。框架方面LangChain、AutoGen、CrewAI 这些都可以了解但不要被框架绑架。我见过太多人花大量时间学框架 API却说不清楚 Agent Loop 的原理。框架是工具原理才是根本。理解了原理换任何框架都能快速上手。最后分享一个我在实际项目中的体会Agent 系统的质量80% 取决于 prompt 设计和工具设计20% 取决于编排逻辑。很多人把精力花在编排上却忽视了最基础的 prompt 和工具。我的建议是先把单个 Agent 的 prompt 调到满意把工具设计得清晰易用再去考虑多 Agent 协作。基础不牢地动山摇这句话在 Agent 开发里同样适用。
