OpenAI Agents SDK #23：把路由逻辑写进 instructions，然后什么都不用写了

instructions="Handoff to the appropriate agent based on the language of the request."

一、routing.py 完整源码精读

Agent 定义层

french_agent  = Agent(name="french_agent",  instructions="You only speak French.")
spanish_agent = Agent(name="spanish_agent", instructions="You only speak Spanish.")
english_agent = Agent(name="english_agent", instructions="You only speak English.")

triage_agent = Agent(
    name="triage_agent",
    instructions="Handoff to the appropriate agent based on the language of the request.",
    handoffs=[french_agent, spanish_agent, english_agent],
)

main() 执行流程

async def main():
    current_agent = triage_agent
    input_items: list[TResponseInputItem] = []
    conversation_id = uuid.uuid4().hex[:16]

while True:
        user_input = input("Enter a message: ")
        input_items.append({"content": user_input, "role": "user"})

with trace("Routing example", group_id=conversation_id):
            result = Runner.run_streamed(current_agent, input=input_items)
            async for event in result.stream_events():
                if not isinstance(event, RawResponsesStreamEvent):
                    continue
                data = event.data
                if isinstance(data, ResponseTextDeltaEvent):
                    print(data.delta, end="", flush=True)
                elif isinstance(data, ResponseContentPartDoneEvent):
                    print()

input_items = result.to_input_list()
        current_agent = result.current_agent

二、handoff 是怎么工作的

"Handoffs are represented as tools to the LLM." 2

1. 用户说「Bonjour, comment ça va?」
2. Runner 调用 triage_agent，LLM 分析语言 → 判定为法语
3. LLM 生成 tool call：transfer_to_french_agent
4. Runner 的 agent loop 检测到这是 handoff call，更新 current_agent = french_agent
5. 重新进入循环，把完整对话历史发给 french_agent
6. french_agent 用法语生成回复，产出 final_output，循环结束

"If the LLM does a handoff, we update the current agent and input, and re-run the loop." 3

"A triage agent routes the conversation to a specialist, and that specialist becomes the active agent for the rest of the turn." 4

handoff() 函数的进阶参数

三、Routing 在四种编排模式里处于什么位置

"In many situations, you have specialized sub-agents that handle specific tasks. You can use handoffs to route the task to the right agent." 5

• 需要根据用户输入动态选择专家，且专家直接回复用户 → Routing
• 任务步骤确定、需要代码级 gate 门控 → Deterministic
• 多个子任务互不依赖、或同一任务多跑择优 → Parallelization
• 输出质量要求高、可接受多轮迭代延迟 → LLM-as-Judge

"Use handoffs when routing itself is part of the workflow and you want the chosen specialist to own the next part of the interaction." 4

"Use agents as tools when a specialist should help with a bounded subtask but should not take over the user-facing conversation." 4

四、生产落地建议

① 路由粒度：专家 Agent 要足够专

② 误路由防护：is_enabled + input_filter 组合拳

from agents.extensions.handoff_filters import remove_all_tools

handoff(
    agent=refund_agent,
    input_filter=remove_all_tools,   # 内置过滤器，移除 tool call 记录
    is_enabled=lambda ctx: is_business_hour(),
)

③ fallback 设计：on_handoff 记录 + 兜底 Agent

当前版本：本文基于 OpenAI Agents SDK v0.17.0。

下期预告 #24：Input Guardrails——Routing 把对话发给专家之前，有一道拦截层可以先跑。guardrail 本身也是并行执行的，原理和 asyncio.gather 有关。