OpenAI Agents SDK 入门实战：Agent、Handoff 与 Guardrail 三件套跑通第一个智能体

云上的幻象2026-10-047 分钟阅读2,672 字30

100%

OpenAI Agents SDK 入门实战：Agent、Handoff 与 Guardrail 三件套跑通第一个智能体

OpenAI Agents SDK 三句话讲完：Agent 定义角色，Handoff 转交任务，Guardrail 拦危险输入

OpenAI Agents SDK 是官方开源的轻量智能体框架（Python 端 pip install openai-agents），它的设计哲学是「原语少但正交」：Agent 管配置，Runner 管循环，Handoff 管接力，Guardrail 管围栏。本文带你把四个原语串起来，跑通第一个生产可用的智能体。

最小可运行示例

from agents import Agent, Runner

agent = Agent(name="助手", instructions="你是一个简洁的中文助手")
result = Runner.run_sync(agent, "用一句话解释递归")
print(result.final_output)

Runner 有三个入口：run_sync() 同步阻塞、run() 异步、run_streamed() 流式。底层是一个固定循环：调 LLM → 有工具调用就执行再回填 → 有 handoff 就切换当前智能体再来一轮 → 产出最终输出就结束，超过 max_turns 抛 MaxTurnsExceeded。理解这个循环，后面所有行为都能推出来。

Handoff：让专业的事交给专业的智能体

Handoff 是一次「控制权移交」：前台智能体判断当前问题属于哪个专域，把对话连同输入一起交给对方。典型用法是分诊模式：

from agents import Agent

refund = Agent(name="退款专员", instructions="只处理退款流程")
billing = Agent(name="账单专员", instructions="只处理账单查询")
triage = Agent(
    name="前台",
    instructions="识别用户意图并转交对应专员",
    handoffs=[refund, billing],
)

转交时可用 handoff_input_filter 清洗传给下一个智能体的输入，比如剥掉内部系统提示。深层的模式拆解可以参考本站的智能体任务移交一文。

Guardrail：在 LLM 跑起来之前先拦一道

护栏和 handoff 是独立机制：护栏在输入进入主循环前（或输出离开前）执行校验，不通过直接触发 tripwire 中止。官方推荐用一个小模型做判断：

from agents import Agent, Runner, InputGuardrail, GuardrailFunctionOutput
from pydantic import BaseModel

class Check(BaseModel):
    is_valid: bool
    reasoning: str

guard_agent = Agent(
    name="问题筛选",
    instructions="判断问题是否属于业务范围，不属于则 is_valid=False",
    output_type=Check,
)

async def guard(ctx, agent, input_data):
    r = await Runner.run(guard_agent, input_data, context=ctx.context)
    return GuardrailFunctionOutput(
        output_info=r.final_output_as(Check),
        tripwire_triggered=not r.final_output.is_valid,
    )

main = Agent(name="客服", instructions="...", input_guardrails=[InputGuardrail(guardrail_function=guard)])

捕获 InputGuardrailTripwireTriggered 异常即可优雅拒绝越界请求。注意护栏是智能体级的，要全组织统一策略时官方另提供了集中式 Guardrails 库。