昨天，OpenAI 悄悄开源了一个完整的客服 Agent Demo，一个基于官方 openai-agents SDK 构建、包含前后端的完整项目。
整个项目还有点意思，算是一个新手教科书级别的多智能体（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 这个函数：
async def on_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")
async def relevance_guardrail(
context: RunContextWrapper[None], agent: Agent, input: str | list[TResponseInputItem]
) -> GuardrailFunctionOutput:
"""Guardrail to check if input is relevant to airline topics."""
result = await Runner.run(guardrail_agent, input, context=context.context)
final = result.final_output_as(RelevanceOutput)
return GuardrailFunctionOutput(output_info=final, tripwire_triggered=not final.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."
)
async def display_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，它会自动同时启动前端和后端。
