企业官网建设流程全解析

在AI Agent从单打独斗走向团队协作的过程中，Handoffs和动态路由是两个绕不开的关键词。很多开发者在构建智能体应用时，一开始只用一个Agent去处理所有请求，用不了多久就会发现，这个Agent变成了什么都懂又什么都不精的“万金油”——上下文字符数迅速告急，工具清单混乱，某个领域内的失误还会污染其他任务的结果。于是大家开始尝试把一个大Agent拆成多个专注的小Agent，用某种机制让它们互相配合。而配合的核心，就是如何在恰当的时机把任务从当前Agent无缝转交给另一个Agent，以及如何决定该交给谁。

这两个机制就是我们常说的Handoffs（交接）和动态路由。简单来说，Handoffs解决的是“如何交接”的问题，动态路由解决的是“交给谁”的问题。两者配合得好，多个Agent就能像一个高效团队一样协作；配合不好，就会出现踢皮球、掉链子、上下文错乱等一连串问题。这篇文章我会从实战角度拆解这两个机制，把底层逻辑、实现方式、常见坑都讲清楚，适合正在琢磨多Agent编排的开发者、刚入门AI应用的小白，以及任何希望把Agent系统做扎实的从业者参考。

1. 为什么Agent之间需要“交接班”：从单体到协作的演进

1.1 单体Agent的瓶颈：一个全能选手撑不住复杂业务

先从一个特别常见的现象说起。很多人最初做Agent应用，习惯于把所有的指令、知识、工具全部塞进同一个Agent的系统提示词里，让它扮演客服、导购、技术支持、订单处理等多个角色。这种做法在Demo阶段没问题，可真要放到业务里跑，很快就会被四个问题卡住：

第一个是上下文窗口不够用。为了照顾各种场景，系统提示词可能要写上几千字，再加上历史对话、工具返回结果，分分钟把几十万token的上下文撑满。更麻烦的是，很多业务上下文并不需要一直在场，全塞在一起反而会让模型注意力分散，回答的质量肉眼可见地下降。

第二个是工具集相互干扰。比如一个Agent同时挂了订单查询、商品推荐、退款处理、物流跟踪、优惠券计算等几十个工具。模型在做一个简单的优惠券计算时，很可能误调用一个不相关的工具。这类问题没有规律可循，排查起来相当痛苦。

第三个是提示词内部逻辑冲突。你想让Agent既保持幽默风趣，又要在售后场景里严肃处理纠纷，这本身就是互相矛盾的指令。模型会在这两种风格之间摇摆，最后两边都不讨好。

第四个是故障定位困难。当一个全能Agent输出错误时，你很难判断是哪个工具、哪个角色定义、哪段上下文导致的。因为所有逻辑都被压在一个提示词里，互相耦合。

我自己的体会是：一旦单体Agent的指令超过3000字，工具超过10个，它就开始变得“不稳定”。不是说不能用，而是你每次微调一个小逻辑，都可能影响其他场景的表现。这时候最自然的解法就是拆分——把不同的职责拆给多个Agent，然后让它们通过某种机制协作。而这个“某种机制”里，Handoffs和动态路由就是核心中的核心。

1.2 多Agent协作模式的定位：交接与路由是基础设施

多Agent协作的常见模式有好几种，比如流水线模式（任务依次经过多个专用Agent）、编排器模式（一个主Agent调度多个子Agent）、协商模式（多个Agent相互辩论或投票）。不管用哪种模式，只要Agent之间存在“任务转移”，就必须解决两个基础问题：

第一，当前Agent处理到一半，发现自己不擅长做某事，或者用户请求已经转而涉及另一个领域，它需要主动把“话筒”交给另一个Agent。这个动作就是Handoff。

第二，入口Agent接收到用户请求后，需要判断这个请求应该由哪个Agent来响应。这个决策过程就是路由。如果路由是固定写死的，那是静态路由；如果根据用户意图、上下文动态判断，那就是动态路由。

可以这样理解：动态路由像客服中心的智能排队系统，根据用户按下的按键、说的话、当前队列状态分配工单；而Handoffs则是客服接到一个跨部门问题后，自己先接待、记录信息，然后把电话转接给另一个部门，并且把已经收集到的信息一并传递过去。

这里有一个关键点容易混淆：路由发生在对话开始前或早期，它决定的是“哪个人先接电话”；Handoffs发生在对话中途，它决定的是“当前这个人怎么把工作转出去”。但实际系统中两者经常叠加。比如动态路由把请求分给售后Agent，售后Agent发现用户还要改订单，于是通过Handoff把会话转给订单Agent。所以如果你想做出一个生产级的Agent系统，这两个机制都必须掌握。

2. Handoffs的核心机制与实现路径

2.1 从输出到移交：出手即交接，控制权的转移是一等公民

Handoff在工程上的本质非常简单：它不是一个函数调用，也不是一个普通字符串，而是一个有明确结构的数据对象，插在Agent的输出里。这个对象通常包含三个字段：目标Agent的标识、传给目标Agent的参数、以及一段解释当前情况的说明。

以现在主流Agent框架的概念为例，执行逻辑大致是下面这样：

class Handoff: def __init__(self, target_agent_id, instructions, payload): self.target_agent_id = target_agent_id self.instructions = instructions self.payload = payload class AgentResponse: def __init__(self, output_text, handoff=None): self.output_text = output_text self.handoff = handoff # 如果为None，说明任务到此为止

当执行器（Executor）拿到一个Agent的响应时，会先检查handoff字段是否为空。如果为空，就把output_text返回给用户；如果不为空，就触发一次交接流程：先记录当前Agent的状态，把payload添加到会话上下文中，然后根据target_agent_id找到目标Agent，用“系统提示词 + 历史对话 + instructions + payload”组成新的输入，接着启动目标Agent继续跑。

这里有几个容易理解偏差的点。第一个是：Handoff并不是让当前Agent“先结束再重启”，而是像接力赛一样，把接力棒交出去。所以从用户视角看，对话是连续的，用户不需要重新描述问题。第二个是：instructions字段很关键。它相当于交接时写的一个便签，告诉下一个Agent“为什么转给你，你已经知道什么信息，接下来需要做什么”。没有这个便签，目标Agent只能看到原始对话，很容易又从头问一遍。

我在实际项目中就吃过亏：一开始没写instructions，只把payload传过去，结果目标Agent反复问“请问有什么可以帮助您”，用户以为系统坏了。后来我在每次Handoff时强制要求生成一段不少于50字的交接说明，问题立刻缓解。

2.2 上下文传递与状态保留：别让交接变成失忆

很多Agent交接失败，不是Handoff机制本身的问题，而是上下文传递没做好。这里的分寸很微妙：传太多，token浪费且目标Agent会被无关信息干扰；传太少，目标Agent缺乏必要的背景。

一个比较稳妥的做法是分层传递。基础层是完整的对话历史（前几轮），这是让新Agent理解用户语境的底线；工作层是当前任务的关键状态，比如已经查到的订单号、用户填写的表单、工具返回的结构化数据；优化层是目标Agent真正需要的领域摘要——把“用户与之前Agent聊了什么”浓缩成一段话。

举个例子。用户先问“我的订单什么时候发货”，售后Agent查询后发现订单卡在仓库审核中，然后判定应该让技术支持Agent介入，因为可能是物流系统异常。那么交接时传给技术支持Agent的payload应该包含：订单号、当前状态“待审核”、用户期望“今天收到货”，instructions应该写“用户订单疑似因物流接口故障停滞，请检查系统异常并告知用户解决方案”。至于用户一开始是怎么进客服的、中间问过什么打折商品，这些都可以不传。

我还建议在传参时把结构化数据与自然语言分开。不要只塞一大段对话记录，尽量提供类似JSON的结构化字段：

{ "order_id": "A10023", "current_status": "pending_review", "issue_type": "logistics_failure", "user_expectation": "delivery_today" }

这样目标Agent可以直接读取字段，而不必自己从文本里解析。配合上模型自带的摘要能力，上下文就不会无限膨胀。

还有一个小经验：给每次交接加一个“会话版本号”或者“交接链”。比如第一次交接的payload里记录previous_agent: "support_agent"，第二次交接的记录handoff_chain: ["support_agent", "tech_agent"]。这样如果出现A转B、B又转A的循环，你能从日志里一眼看出来，方便做熔断。

3. 动态路由：如何让请求自动到达正确的Agent

3.1 三种典型路由策略：从笨办法到聪明办法

动态路由负责在最开始就把请求分给合适的Agent。根据复杂度和成本，我习惯把实现方式分成三档：规则路由、语义路由、混合路由。

规则路由是零成本起步的方案。简单来说，就是通过关键词、正则表达式、用户显式指令（比如用户说“我要转人工”）来做一个if-else判断。规则路由的优点是非常快、非常可解释，而且不需要任何模型调用。缺点也明显：语言表达千变万化，用户不会按你的关键词说话。比如你想让“退款”相关请求走售后Agent，用户只要说一句“我不想要了，怎么把钱要回来”，关键词匹配就失效了。

语义路由是更主流的方式。核心思路是把用户的输入文本转成一个向量，然后和每个Agent职责描述向量的相似度做比较，选相似度最高的那个。这种路由的准确率要高得多，因为它理解的是“意思”而不是“字面”。实现上要用到embedding模型。这里需要注意：embedding模型本身是有成本的，而且每次请求都要额外调用一次向量生成接口，延迟会增加几十到几百毫秒。好在对于大多数业务场景，这个延迟完全可以接受。

混合路由则是把两者结合起来：先用规则做快速分流（比如用户明确点击了某个按钮、输入里包含“退款”这种强信号词），如果规则的置信度足够高就直接走路由；否则再调用语义路由兜底。混合路由能大幅降低语义模型的调用量，同时保证高准确率。

下面我用一个表格对比三者的特点：

3.2 语义路由的工程实现：不只是算个余弦相似度

具体到代码层面，一个最简单的语义路由可以这样写：

import numpy as np class SemanticRouter: def __init__(self, embedding_model): self.embedding_model = embedding_model # 每个Agent用一段职责描述注册 self.agents = {} self.agent_embeddings = {} def register(self, agent_id, description): self.agents[agent_id] = description self.agent_embeddings[agent_id] = self.embedding_model.encode(description) def route(self, user_input): query_vec = self.embedding_model.encode(user_input) scores = {} for agent_id, agent_vec in self.agent_embeddings.items(): scores[agent_id] = cosine_similarity(query_vec, agent_vec) best_agent = max(scores, key=scores.get) return best_agent, scores[best_agent] def cosine_similarity(a, b): return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b)))

这段代码本身不复杂，但真正工作中会遇到几个细节。第一是Agent的描述文本怎么写。描述越具体，匹配越准。与其写“客服”，不如写“负责处理商品退换货、退款进度查询、售后投诉受理”，因为语义模型对抽象名词的向量表征往往不如具体动作清晰。第二是别只会选最高分，还要给分数设置一个阈值。比如最高相似分是0.6，但其他Agent都是0.5，这时候其实说明用户的意图可能不在你的Agent覆盖范围内，与其硬分到一个Agent，不如返回一个“未命中”让主Agent做通用回答或追问澄清。

第三是类别不均衡问题。假设订单Agent的注册描述没写清楚，那么很多请求都会落到售后Agent头上。这时候可以用一个小测试集做验证：准备100条不同意图的样本，跑一遍路由，统计每个Agent的召回率和准确率，然后微调描述或者阈值。我见过有人直接问模型“你觉得这段话在聊什么事”，用一个便宜的大模型做初判，再结合embedding得分，效果也不错。

4. 组合实践：一个带有动态路由的Handoff编排系统

4.1 场景设计与架构拆分：先想清楚边界，再写代码

理论讲再多，都不如来一个完整案例。假设我们现在要做一个智能客服系统，面对用户请求包括：查订单、咨询退货政策、报修设备、投诉人工。如果拆得太多，每个Agent都只会干一件事，虽然清晰但用户来回被转来转去，体验很差；如果只拆成两个，又会退化成全能Agent。经过权衡，我设计成四个Agent：

导航Agent：负责用户进来之后的首次接待。它不直接办业务，而是理解用户意图、收集关键信息（比如订单号），然后通过动态路由把任务交给对应的业务Agent。同时它也是兜底者——如果路由不确定，就由它继续和用户对话澄清。

订单Agent：负责查询订单状态、修改发货地址、催单等订单全生命周期操作。

售后Agent：负责退货、退款、换货、补偿等售后相关政策解释与执行。

技术支持Agent：负责设备故障排查、软件使用指导、报修登记。

这样划分后，动态路由挂在导航Agent后面，首次分派走语义路由。而Handoffs出现在两个场景：用户中途从售后转为订单问题，售后Agent主动Handoff给订单Agent；技术支持Agent排查后需要走售后流程，也Handoff给售后Agent。

4.2 核心代码骨架与配置说明：用一套执行器统一管理

为了让动态路由和Handoffs能协同工作，我习惯用一个统一的Agent类和一个执行器来管理所有流程。下面的代码是一个简化版骨架，重点在于展示路由和交接的协作关系：

class Agent: def __init__(self, name, system_prompt, router=None): self.name = name self.system_prompt = system_prompt self.router = router # 该Agent是否附带路由功能 def build_input(self, history, extra_context): return { "system": self.system_prompt, "history": history, "extra": extra_context } def execute_agent(agent, history, extra_context, max_handoffs=3): handoff_count = 0 current_agent = agent while handoff_count <= max_handoffs: response = call_llm(current_agent.build_input(history, extra_context)) if response.handoff is None: return response.output_text # 交接前记录状态，交给下一个Agent handoff_count += 1 extra_context.update({ "handoff_chain": extra_context.get("handoff_chain", []) + [current_agent.name], "current_handoff_reason": response.handoff.instructions }) history.append({"role": "assistant", "content": response.output_text}) history.append({"role": "system", "content": f"现在由{response.handoff.target_agent_id}接手，交接说明：{response.handoff.instructions}"}) current_agent = registry[response.handoff.target_agent_id] return "处理超时，需要人工介入"

如果给导航Agent挂上一个语义路由，那么它的响应就不是直接给用户，而是返回一个内部标记，比如一个route_to字段。执行器看到这个字段后，不把它当成普通对话，而是直接基于路由结果找到目标业务Agent，用同样的交接机制把当前对话传过去。

这里有一个特别重要的配置：最大交接次数。没有这个限制，当两个Agent互相认为对方应该处理时，就会出现无限循环，真金白银地烧token。我一般设3次，超过之后直接触发人工兜底，既节省成本也保护用户体验。

5. 踩坑记录与排查指南

5.1 高频问题速查表：症状、原因与解法

多Agent系统中，90%的问题都集中在交接和路由这两个环节。我整理了一份踩坑速查表，按出现频率排的顺序：

5.2 让交接过程可观测：几个极其有效的调试手段

我自己在搭这类系统的过程中，最大的感受是：多Agent系统的问题很难复现，因为它依赖模型输出，是概率性的。所以调试手段决定了你能多快定位问题。第一个建议是给每次交接生成一个内部ID，并在日志里记录完整交接链。不要只记“handoffs = 1”，要记[导航Agent -> 售后Agent -> 订单Agent]，这样循环问题一目了然。

第二个建议是打印路由得分。每次语义路由完成后，把每个Agent的最终得分都输出到日志里。很多时候你会看到，售后Agent和订单Agent的得分只差0.02，那说明你的路由描述设计得不够好，而不是模型不行。把这些样本收集起来，微调描述文本，准确率能明显提升。

第三个建议是做交接内容审计。由于Handoff的instructions是模型生成的，偶尔会出现胡说八道的情况。我做过一个抓取逻辑：每10次交接里，把其中5次的instructions抽出来人工看一眼，看看是否准确。这个审计成本很低，效果却很好。后来我还尝试在交接前增加一道轻量校验，用规则检查instructions里是否包含目标Agent职责范围内的关键词，如果完全不相关，就触发额外的语义判别，避免交接错。

第四个建议是给执行器加超时熔断。LLM调用本身就慢，交接链越长，响应时间越不可控。我在执行器里增加了一个总体时间预算，比如一个生命周期最长30秒。如果交接加调用超过30秒，直接降级为“正在转接人工”的提示，同步通知后端管理员。这样至少用户端不会一直转圈。

上面这些手段听起来零散，但它们组合起来，就能让黑盒系统变得可观测、可干预。我始终认为，多Agent应用的前期设计再完美，都不如一套健壮的日志和熔断体系来得实在。

最后再分享一点个人体会

搭建过几个带Handoffs和动态路由的项目之后，我最大的体会是：这两个机制的协作潜力，只有在“边界清晰”的Agent团队里才能发挥出来。如果每个Agent的职责描述本身就含糊不清，再好的路由算法和交接协议都会频繁出bug。所以我在设计新项目时，会花大量时间打磨每个Agent的“岗位说明书”，把它们的职责、工具、目标写成一到两句话，并且反复在测试集上验证路由和交接的准确率。

另一个体会是，别迷信“全自动”。动态路由和Handoffs会自动决定绝大多数请求，但你一定要预留人工兜底的口子。我在实际项目里会设置一个“未知意图”Agent，专门处理低置信度的请求，让用户能转接到人工客服。这不是退步，而是让系统在边界处变得优雅。真正好的多Agent系统，不是所有问题都能自动化解决，而是在自动化失效时，知道自己失效了，并且知道下一步该怎么做。

如果你正在做类似的Agent编排，我的建议很简单：先从规则路由和简单Handoff做起，跑通一个最小的交接闭环，再加上语义路由和熔断机制。这条路虽然比直接塞一个超大Prompt麻烦，但走通之后，系统的稳定性、可扩展性和可维护性都会上一个台阶。希望这篇分享能给你一些可落地的思路。