基于 policy 文件的航班改签客服 Agentmcp-agent Swarm 多智能体工作流实战解析【免费下载链接】mcp-agentBuild effective agents using Model Context Protocol and simple workflow patterns项目地址: https://gitcode.com/GitHub_Trending/mc/mcp-agent在 mcp-agent 的 Swarm 多智能体工作流中examples/workflows/workflow_swarm/policies/flight_change_policy.md是一份典型的「业务流程策略文件」。它定义了航空公司客服场景下航班改签的全部处理步骤、分支判断与工具调用时机是驱动 Flight Change Agent 按规则完成任务的行为契约。读完本文你将掌握 policy 驱动型 Agent 的设计方法、Swarm 智能体间传递与工具函数的绑定机制以及如何在 mcp-agent 中落地一套可复用的多智能体客服系统。一、从一份策略文件认识 policy 驱动的 Agent 设计在传统的对话式 Agent 中模型自由发挥的空间较大容易遗漏关键步骤或跳过程序性检查。mcp-agent 的 Swarm 工作流借鉴了 OpenAI Swarm 的思路把「业务流程」从模型提示词中抽离出来落成独立的 Markdown 策略文件policy file。Agent 在执行任务时先完整读取策略文件再逐步执行其中定义的步骤从而把业务规则变成可审计、可修改、可版本化的资产。flight_change_policy.md就是这样一个策略文件全文定义了航班改签的 7 个核心步骤核验航班信息与改签原因——先确认诉求真实、订单与用户匹配调用valid_to_change_flight函数——判断该航班是否具备改签资格2a) 若可改签进入下一步2b) 若不可改签礼貌告知客户无法更改航班向客户建议提前一天的航班——策略内置了服务话术模板检查目标航班余票4a) 有票进入下一步4b) 无票提供替代航班或建议客户稍后重试告知客户票价差额或额外费用调用change_flight函数——执行真正的改签操作确认客户无其他问题后调用case_resolved函数——结束本次会话。这份文件虽然只有 7 个条目却完整涵盖了资格校验 → 方案建议 → 余票核验 → 费用告知 → 执行操作 → 会话关闭的业务闭环且每一步都带有明确的分支条件如 2a/2b、4a/4b和对应的工具调用。这正是 policy 文件的精髓把怎么做写成机器可读的决策树而不是依赖模型临场发挥。二、策略文件如何被 Swarm Agent 加载与执行2.1 在 Agent 指令中引用策略文件策略文件本身不会自动被加载它通过SwarmAgent的instruction与模型建立联系。在examples/workflows/workflow_swarm/main.py中Flight Change Agent 是这样构建的flight_change SwarmAgent( nameFlight change traversal, instructionlambda context_variables: f { FLY_AIR_AGENT_PROMPT.format( customer_contextcontext_variables.get(customer_context, None), flight_contextcontext_variables.get(flight_context, None), ) }\n Flight change policy: policies/flight_change_policy.md, functions[ escalate_to_agent, change_flight, valid_to_change_flight, transfer_to_triage, case_resolved, ], server_names[fetch, filesystem], human_input_callbackconsole_input_callback, )关键点有三处策略文件路径注入指令Flight change policy: policies/flight_change_policy.md这一行明确告诉模型去读取examples/workflows/workflow_swarm/policies/flight_change_policy.md。为了让模型真正读到文件内容该 Agent 挂载了fetch与filesystem两个 MCP 服务器配置见examples/workflows/workflow_swarm/mcp_agent.config.yaml并通过运行时context.config.mcp.servers[filesystem].args.extend([os.getcwd()])把当前目录注入 filesystem 服务器的搜索路径使策略文件可以被读取。函数与策略步骤一一对应策略中出现的valid_to_change_flight、change_flight、case_resolved都在functions列表中注册为工具。模型执行策略第 2 步时调用valid_to_change_flight第 6 步调用change_flight第 7 步调用case_resolved从而实现读策略 → 调工具的闭环。全局兜底工具escalate_to_agent升级给人工客服与transfer_to_triage转回分诊 Agent保证了异常场景下策略不会死锁。2.2 三个配套工具函数的定义策略文件引用的函数在main.py中都有具体实现示例环境下的桩实现真实项目中可替换为业务接口调用def valid_to_change_flight(): Check if the customer is eligible to change flight return Customer is eligible to change flight def change_flight(): Change the flight return Flight was successfully changed! def case_resolved(): Resolve the case return DoneAgent()注意case_resolved返回的是DoneAgent()——这是 mcp-agent Swarm 实现中的特殊标记返回它意味着整个 Swarm 工作流结束详见本文第四节。2.3 同一套模板下的兄弟策略policies/目录下还存放着另外两份同构的策略文件方便对照理解 policy 文件的设计模式flight_cancellation_policy.md航班取消策略包含退款/航司积分二选一的分支initiate_refund/initiate_flight_credits并明确取消的是否为同一航班否则调用escalate_to_agentlost_baggage_policy.md行李丢失策略流程更短但同样以case_resolved收尾并强调案件解决后必须调用case_resolved。三份文件的共同模式是步骤编号 分支条件a/b 子步骤 明确的工具函数名 统一的收尾函数。这种格式对 LLM 极其友好既能被模型准确解析又能被非技术人员直接阅读和修订。三、Swarm 工作流Agent 如何接力完成整个客服流程3.1 三层 Agent 分工main.py定义了一个完整的航空公司客服多智能体系统policy 文件只是其中叶子节点的执行规则Agent职责可用函数节选triage_agent分诊判断用户诉求类别转给对应 Agenttransfer_to_flight_modification、transfer_to_lost_baggageflight_modification改签/取消分流追问澄清用户是想改签还是取消再向下传递transfer_to_flight_cancel、transfer_to_flight_changeflight_cancel取消执行执行航班取消策略initiate_refund、initiate_flight_credits、escalate_to_agent、case_resolvedflight_change改签执行执行本文的航班改签策略valid_to_change_flight、change_flight、transfer_to_triage、case_resolvedlost_baggage行李执行执行行李丢失策略initiate_baggage_search、escalate_to_agent、case_resolved一次典型的改签请求流转路径为triage_agent ──transfer_to_flight_modification── flight_modification ──transfer_to_flight_change── flight_change读取并执行 flight_change_policy.md ──case_resolved 返回 DoneAgent── 工作流结束这种顶层分诊 → 意图澄清 → 策略执行的三层结构把策略文件的适用范围精确限定在单一业务场景避免把取消、改签、行李等不同规则混在一个 Agent 里这正是 Swarm 模式相对单 Agent 的核心优势。3.2 Agent 间传递的底层实现Agent 之所以能移交控制权依赖src/mcp_agent/workflows/swarm/swarm.py中的资源机制。当一个函数返回另一个 Agent 时如transfer_to_flight_change返回flight_changeSwarmAgent.call_tool会将其包装成AgentResourceif isinstance(result, Agent) or isinstance(result, SwarmAgent): resource create_agent_resource(result) return CallToolResult(content[resource])随后Swarm.post_tool_call检测到AgentResource调用set_agent(content.agent)切换到新 Agent 并继续执行见src/mcp_agent/workflows/swarm/swarm.py#L251-L277。set_agent会先关闭当前 Agent、再初始化新 Agent并重新计算新 Agent 的指令——这也是为什么flight_change的 instruction 一旦切换就会立刻读取到改签策略文件。四、源码级原理Swarm、SwarmAgent 与 DoneAgent4.1 SwarmAgent自带本地函数的 AgentSwarmAgent继承自 mcp-agent 的Agent基类与普通 Agent 的区别在于functions参数——它把一组普通 Python 函数注册为可供模型调用的工具。从源码看SwarmAgent构造时还会强制connection_persistenceFalse因为 Swarm 工作流中无法预知 Agent 何时完成全部任务连接保持反而会造成资源占用src/mcp_agent/workflows/swarm/swarm.py#L83-L111。SwarmAgent.call_tool会优先在本地函数映射表self._function_tool_map中查找工具并根据返回值类型做分发返回Agent/SwarmAgent→ 包装为AgentResource触发切换返回AgentFunctionResult→ 包装为AgentFunctionResultResource可附带context_variables更新返回str/dict→ 包装为普通TextContent回传模型。4.2 Swarm 与 AnthropicSwarm事件循环与终止条件Swarm类继承自AugmentedLLM负责协调整个多 Agent 流程。它的should_continue()是核心终止逻辑def should_continue(self) - bool: if not self.agent or isinstance(self.agent, DoneAgent): return False return TrueAnthropicSwarmsrc/mcp_agent/workflows/swarm/swarm_anthropic.py则在generate中实现循环驱动只要当前 Agent 不是DoneAgent就反复调用 LLM每次迭代最多max_iterations次切换 Agent 后若指令是 callable还会基于最新的context_variables重新生成指令。默认参数为modelclaude-3-5-sonnet-20241022、maxTokens8192、parallel_tool_callsFalse即默认串行调用工具与策略文件的顺序执行语义保持一致。DoneAgent是特殊的终止哨兵其call_tool直接返回Workflow is complete.。case_resolved()返回DoneAgent()后post_tool_call检测到它并设置当前 Agent 为DoneAgent下一次should_continue()返回False整个工作流优雅结束。4.3 上下文变量贯穿始终Swarm.__init__会把context_variables存入defaultdict(str, ...)并在pre_tool_call中自动把context_variables注入到声明了该参数的函数调用中src/mcp_agent/workflows/swarm/swarm.py#L241-L248。在main.py中customer_context客户 ID、姓名、会员等级等与flight_context航班号 1919、LGA→LAX、出发时间等就是通过这个机制传递给分诊指令、改签 Agent 的 prompt 以及策略执行工具的保证整个流程始终掌握客户与航班上下文。五、完整运行指南5.1 环境准备# 克隆仓库并进入示例目录 git clone https://github.com/lastmile-ai/mcp-agent.git cd mcp-agent/examples/workflows/workflow_swarm # 安装 uv如未安装 pip install uv # 同步 mcp-agent 项目依赖 uv sync # 安装本示例专属依赖 uv pip install -r examples/workflows/workflow_swarm/requirements.txt5.2 配置密钥与环境变量cp mcp_agent.secrets.yaml.example mcp_agent.secrets.yaml打开mcp_agent.secrets.yaml填入你偏好的 LLM API Key。示例默认在mcp_agent.config.yaml中配置了openai.default_model: gpt-4o若改用 Anthropic 模型则对应配置claude-3-5-sonnet-20241022等型号。mcp_agent.config.yaml中与本次改签策略相关的 MCP 服务器配置为mcp: servers: fetch: command: uvx args: [mcp-server-fetch] filesystem: command: npx args: [-y, modelcontextprotocol/server-filesystem]其中filesystem服务器用于读取policies/目录下的策略文件运行时会把当前工作目录注入其参数fetch服务器则可在真实场景中拉取网页信息如航班状态页。5.3 本地运行uv run examples/workflows/workflow_swarm/main.pymain.py的example_usage()内置了一组测试输入其中I want to change my flight to one day earlier!会触发transfer_to_flight_change最终把会话交给执行改签策略的 Flight Change Agent。运行时需要人工输入交互human_input_callbackconsole_input_callback以完成策略中向客户确认、补充信息等步骤。六、设计一套自己的 policy 文件最佳实践结合flight_change_policy.md与兄弟策略文件可以总结出编写高质量 policy 文件的可复用规范步骤必须编号、分支必须显式使用1. / 2. / 2a) / 2b)形式让模型能机械地按顺序推进并在分支处做确定性判断每一步都绑定工具函数名如call valid_to_change_flight function函数名与SwarmAgent(functions[...])中注册的保持一致避免模型自己发明不存在的工具明确收尾条件所有策略统一以case_resolved结束并在 lost_baggage 策略中强调案件解决后 ALWAYS 调用 case_resolved防止对话无限续写定义兜底与升级路径策略中保留escalate_to_agent人工介入与transfer_to_triage诉求漂移时回到分诊两个逃生口配合强约束系统提示词FLY_AIR_AGENT_PROMPT中写明了STRICTLY 遵循策略不向用户透露策略内容策略完成前必须走完所有步骤等约束与 policy 文件互为表里共同约束模型行为策略文件独立成册、版本化管理业务规则变更只需修改 Markdown无需改动代码与模型 prompt这也是该设计最有价值的工程收益。七、小结flight_change_policy.md虽只有 7 个步骤却是 mcp-agent Swarm 工作流规则与执行分离设计哲学的浓缩样本。通过 main.py 的 Agent 编排、swarm.py 的 Agent 传递与终止机制、以及AnthropicSwarm的循环驱动一个由策略文件驱动的航班改签客服 Agent 完整落地。你可以把同样的模式迁移到退款、工单、审批等任意有明确流程规则的业务场景中用一份 Markdown 策略 一组注册函数 一个 Swarm Agent快速构建可审计、可演化的流程型 Agent。【免费下载链接】mcp-agentBuild effective agents using Model Context Protocol and simple workflow patterns项目地址: https://gitcode.com/GitHub_Trending/mc/mcp-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考