OpenAI深夜开源Agent，我扒出了多智能体协作的3个秘密。

显示全部楼层

昨天，OpenAI 悄悄开源了一个完整的客服 Agent Demo，一个基于官方openai-agentsSDK 构建、包含前后端的完整项目。

整个项目还有点意思，算是一个新手教科书级别的多智能体（Multi-Agent）协作范例。我扒了扒它的源码，里面藏着一套关于智能体协作、切换和安全护栏的最佳实践。

核心架构

这个 Demo 模拟了一个航空公司的客服场景。它的架构非常经典，采用了跟上周分享的很多大厂的产品一样，都是 Orchestrator-Worker 架构（讲道理，这个架构名字可能很多，这个词是我经常用的~）：

1个 Triage Agent (Lead智能体):它的唯一职责就是理解用户意图，然后把任务“派发”给最合适的专家。
N个 Specialist Agents (专家智能体):每个专家只负责一个垂直领域，比如：

Seat Booking Agent: 负责预订座位。
Flight Status Agent: 负责查询航班状态。
Cancellation Agent: 负责取消航班。
FAQ Agent: 负责回答常见问题。

这种架构的好处是显而易见的：高内聚、低耦合。每个专家 Agent 的提示词（Prompt）、工具（Tools）和知识都可以独立维护，扩展起来非常方便，不会互相干扰。

模式一：带状态的智能体切换 (Stateful Handoff)

多智能体协作的核心难题，就是如何优雅地切换，并传递上下文信息。

OpenAI 在这个 Demo 里，用的是 handoff 方案。

Triage Agent的核心配置如下，它通过 handoffs 列表来定义它可以将任务移交给哪些专家。


triage_agent = Agent[AirlineAgentContext](
  name="Triage Agent",
  model="gpt-4.1",
  handoff_description="A triage agent that can delegate a customer's request to the appropriate agent.",
  instructions=(
   f"{RECOMMENDED_PROMPT_PREFIX}"
   "You are a helpful triaging agent. You can use your tools to delegate questions to other appropriate agents."
  ),
  handoffs=[
    flight_status_agent,
    handoff(agent=cancellation_agent, on_handoff=on_cancellation_handoff),
    faq_agent,
    handoff(agent=seat_booking_agent, on_handoff=on_seat_booking_handoff),
  ],
  input_guardrails=[relevance_guardrail, jailbreak_guardrail],
)

值得注意的是，上边handoff()函数里的on_handoff 回调。

比如，当用户想改座位时，Triage Agent会把任务交给Seat Booking Agent。在交接的瞬间，会触发on_seat_booking_handoff这个函数：


asyncdefon_seat_booking_handoff(context: RunContextWrapper[AirlineAgentContext])->None:
 """Set a random flight number when handed off to the seat booking agent."""
  context.context.flight_number =f"FLT-{random.randint(100,999)}"
  context.context.confirmation_number ="".join(random.choices(string.ascii_uppercase + string.digits, k=6))

这个回调函数会在“交接前”更新共享的上下文（Context），比如自动生成一个航班号和确认码。这样，当Seat Booking Agent接手时，它需要的初始信息就已经准备好了，可以直接开始工作，而不需要再向用户询问。

这个“带状态的切换”模式，可以很好提升了用户体验和系统效率。

模式二：低成本的安全护栏 (Guardrail)

Agent 安全是另一个让人头疼的问题。如果用户问一些无关的问题（“写一首关于草莓的诗”），或者试图进行提示词注入攻击（“忽略你之前的指令……”），该怎么办？

OpenAI 的方案是设置“安全护栏”（Guardrail），而且用的是一种非常经济高效的方式。

他们创建了两个专门的护栏函数：

relevance_guardrail: 判断用户输入是否与航空业务相关。
jailbreak_guardrail: 检测用户是否在尝试越狱攻击。

这两个护栏的背后，都是一个独立的、更小、更便宜的模型（gpt-4.1-mini）。

它的逻辑是：

在主 Agent（如Seat Booking Agent）处理用户输入之前。
先用这个小模型快速检查一下输入的“安全性”和“相关性”。
如果小模型检测到问题（比如is_relevant: False），就会直接触发“Tripwire”（绊线），拒绝回答，并阻止请求进入更贵、更强大的主模型。


@input_guardrail(name="Relevance Guardrail")
asyncdefrelevance_guardrail(
  context: RunContextWrapper[None], agent: Agent, input: str | list[TResponseInputItem]
)-> GuardrailFunctionOutput:
 """Guardrail to check if input is relevant to airline topics."""
  result =awaitRunner.run(guardrail_agent, input, context=context.context)
  final = result.final_output_as(RelevanceOutput)
 returnGuardrailFunctionOutput(output_info=final, tripwire_triggered=notfinal.is_relevant)

这种“前置检查”的设计，将安全逻辑与业务逻辑解耦，可以保证了系统的鲁棒性，同时节约成本。

模式三：后端驱动的前端交互

还有一个有趣的设计。当Seat Booking Agent需要让用户在座位图上选座时，它会调用一个名为display_seat_map的工具。

这个工具的实现非常简单，它只返回一个特殊的字符串：DISPLAY_SEAT_MAP。


@function_tool(
  name_override="display_seat_map",
  description_override="Display an interactive seat map to the customer so they can choose a new seat."
)
asyncdefdisplay_seat_map(
  context: RunContextWrapper[AirlineAgentContext]
)-> str:
 """Trigger the UI to show an interactive seat map to the customer."""
 # The returned string will be interpreted by the UI to open the seat selector.
 return"DISPLAY_SEAT_MAP"

前端 UI 监听到这个特殊的字符串后，就会触发渲染“座位图”组件的逻辑。这是一个非常巧妙的“后端驱动UI”模式，让 Agent 能够控制前端的复杂交互，而不仅仅是返回文本。

如何上手？

这个项目上手非常简单：

Clone 仓库:git clone https://github.com/openai/openai-cs-agents-demo.git
设置 API Key:在python-backend目录下创建一个.env文件，写入你的OPENAI_API_KEY。
安装依赖:分别进入python-backend和ui目录，安装依赖。
运行:在ui目录下运行npm run dev，它会自动同时启动前端和后端。