AI Agent / 系统课时
多 Agent 协作案例实现
多 Agent 协作案例实现
当一个任务同时要求架构设计、风险分析和验收标准时,把所有要求塞进单个提示词往往难以追踪责任。本课实现一个“协调 Agent + 专家 Agent”案例,让不同角色独立产出,再由协调者标记缺口并汇总结果,交由验收环节处理冲突。
学习目标
- 把复杂任务拆成边界清晰、可独立验证的 Agent 职责
- 用 Python 编排多个专家 Agent,并汇总各自的执行结果
- 为多 Agent 流程补上失败边界、输出契约和验收条件
把任务拆成可协作的职责
示例任务是“为电商客服 Agent 制定上线方案”。协调者不直接完成全部内容,而是分别调用架构专家、风险专家和验收专家。三个专家收到同一业务目标,但使用不同指令,只对自己的产物负责;编排层负责保证三项任务都被调度、记录缺口并汇总文本。业务验收仍要检查专家结论之间的冲突。
这种拆法的关键不是 Agent 数量,而是每个角色都能产生独立可检查的中间结果。如果两个 Agent 的职责高度重叠,增加角色只会增加调用成本和不一致概率。

搭建可运行案例
把代码保存为 multi_agent.py。Python 3.11 及以上可直接运行 python multi_agent.py,默认使用本地模拟专家。每个专家有独立超时,任务列表与展示顺序都由程序决定。
import argparse
import asyncio
GOAL = "为电商客服 Agent 制定上线方案"
EXPERTS = {
"架构方案": ("architecture_expert", "给出组件边界、调用链和降级策略。"),
"主要风险": ("risk_expert", "给出数据、工具和权限风险及缓解措施。"),
"验收门槛": ("acceptance_expert", "给出可操作、可判定的上线检查项。"),
}
async def run_one(section, worker, timeout):
try:
text = await asyncio.wait_for(worker(GOAL), timeout=timeout)
except TimeoutError:
return section, "超时", None
except Exception:
return section, "调用失败", None
if not isinstance(text, str) or not text.strip():
return section, "输出无效", None
return section, "完成", text.strip()
async def review(workers, timeout):
return await asyncio.gather(
*(run_one(section, workers[section], timeout) for section in EXPERTS)
)
def display(results):
for section, status, text in results:
print(f"{section} [{status}]")
if text is not None:
print(text)
missing = [section for section, status, _ in results if status != "完成"]
if missing:
print("未完成:", "、".join(missing))
async def architecture(goal):
return "读取商品政策后回答,政策未覆盖时转人工。"
async def risk(goal):
return "按用户身份校验订单访问权限,防止跨账号读取。"
async def acceptance(goal):
return "跨账号查询测试必须全部被拒绝。"
async def slow_risk(goal):
await asyncio.Event().wait()
def sdk_workers(model="gpt-4.1-mini"):
from agents import Agent, Runner
def build_worker(name, instructions):
agent = Agent(name=name, instructions=instructions, model=model)
async def worker(goal):
result = await Runner.run(agent, goal, max_turns=3)
return result.final_output
return worker
return {
section: build_worker(name, instructions)
for section, (name, instructions) in EXPERTS.items()
}
async def main(live):
if live:
display(await review(sdk_workers(), timeout=20))
return
workers = {"架构方案": architecture, "主要风险": risk, "验收门槛": acceptance}
display(await review(workers, timeout=0.05))
print()
display(await review({**workers, "主要风险": slow_risk}, timeout=0.05))
if __name__ == "__main__":
parser = argparse.ArgumentParser()
parser.add_argument("--live", action="store_true")
asyncio.run(main(parser.parse_args().live))默认运行的预期输出
架构方案 [完成]
读取商品政策后回答,政策未覆盖时转人工。
主要风险 [完成]
按用户身份校验订单访问权限,防止跨账号读取。
验收门槛 [完成]
跨账号查询测试必须全部被拒绝。
架构方案 [完成]
读取商品政策后回答,政策未覆盖时转人工。
主要风险 [超时]
验收门槛 [完成]
跨账号查询测试必须全部被拒绝。
未完成: 主要风险如需调用真实模型,在虚拟环境安装 python -m pip install openai-agents==0.24.0,确认账号可访问示例模型,并在本机环境变量中配置 OPENAI_API_KEY,再运行 python multi_agent.py --live。实际模型文本会随运行变化,调用模型可能产生费用。
区分固定编排与经理模式
固定编排在代码里列明必需专家,再按状态验收。OpenAI Agents SDK 还支持用 Agent.as_tool() 把专家注册成经理 Agent 的工具,经理可按任务选择调用时机和整合方式。选用经理模式时,提示词只能表达偏好。若三项必须完成,需要检查实际调用与结果记录,或用固定编排控制必需步骤。
asyncio.gather() 将三个子任务交给事件循环,结果按输入顺序返回。协程要在等待异步操作时交还执行权。同步阻塞调用会拖住其他任务,也会影响超时。wait_for() 超时后请求取消,并等待取消处理完成,返回可能晚于设置的秒数。外部服务可能已收到请求或已执行副作用。SDK 的 max_turns 限制 Agent 运行轮次,时间、调用费用和外部副作用需要各自控制。
为协作增加工程边界
示例只检查输出为非空文本。上线门槛可以定义必须有可执行步骤及通过条件,再由程序检查字段,由评审方核对专家间的冲突。生产日志保留每个专家的执行状态和调用标识。存在缺项时,由流程明确选择重试、使用经批准的降级结果或转人工,并按策略处理已经完成的任务。
当一个任务能被单 Agent 一次完成且结果容易验证时,没有必要拆成多 Agent。协作系统真正的价值来自职责隔离、独立验证和可控编排,而不是角色数量本身。