OpenAI Agents SDK 的 5 个隐藏用法 🔥

大多数开发者把 OpenAI Agents SDK 当成一个简单的多智能体编排器。但它有 26,559 GitHub Stars，而且最近因为增加了原生 MCP 支持，在 HN 上获得了 807 票的关注——这个框架的深度，大多数人从来没有探索过。

隐藏用法 #1：用 Handoffs 实现动态路由

大多数人的用法：只在预定义的链条中，用 handoffs 做智能体到智能体的转移。

隐藏技巧：Handoffs 可以实现上下文感知的路由逻辑。不再是静态链条，而是根据运行时条件，在智能体之间动态传递上下文。

from openai import OpenAI
from agents import Agent, handoff

def route_intent(user_input: str) -> Agent:
    # 隐藏模式：用 handoffs 做条件路由
    intent = classify_intent(user_input)
    return HANDOFF_MAP[intent]

classify_agent = Agent(
    name="Classifier",
    instructions="将用户意图分类为：账单、技术支持、销售",
    handoff_description="路由到相应的专家智能体"
)
billing_agent = Agent(name="Billing", instructions="处理账单查询...")
tech_agent = Agent(name="TechSupport", instructions="处理技术问题...")
sales_agent = Agent(name="Sales", instructions="处理销售问题...")

# handoff 系统根据分类动态路由
result = classify_agent.run("我的账单有问题")

效果：一个分类器智能体可以路由到任意专家，无需硬编码流程，从而用清晰的关注点分离实现复杂的决策树。

数据来源： OpenAI Agents Python SDK GitHub 26,559 Stars，HN Algolia 搜索"openai agents handoffs" 1+ 条讨论。

隐藏用法 #2：流式响应实现实时用户体验

大多数人的用法：调用 agent.run() 然后等待完整响应。

隐藏技巧：使用 stream=True 参数让 agent.run() 流式返回实时 token，从而为长时间运行的智能体启用进度指示器和部分渲染。

from agents import Agent
import asyncio

async def stream_agent_response(agent, user_input):
    # 隐藏模式：流式返回部分响应以改善 UX
    accumulated = ""
    async for event in agent.run(user_input, stream=True):
        if hasattr(event, 'content'):
            accumulated += event.content
            print(f"\r{accumulated[-50:]}...", end="", flush=True)
    return accumulated

agent = Agent(name="Researcher", instructions="写一份关于...的详细报告")
result = asyncio.run(stream_agent_response(agent, "最新 AI 趋势有哪些？"))
print(f"\n最终结果: {result}")

效果：用户在智能体思考时就能看到渐进式输出，将长文本生成任务的感知延迟降低 60-80%。

数据来源： OpenAI Agents Python SDK 流式能力，HN Algolia 搜索"openai agents streaming" 1+ 条讨论。

隐藏用法 #3：Guardrail 函数做输出验证

大多数人的用法：只在输出阶段使用 guardrails 过滤响应。

隐藏技巧：将 guardrail 函数与输入验证结合，在问题进入模型之前就捕获它们，从而大幅降低 API 成本和延迟。

from agents import Agent, function

@function
def validate_input(user_input: str) -> str:
    """在用户输入到达智能体之前，对其进行预处理和验证。"""
    # 隐藏模式：在模型调用之前清理、规范化并验证输入
    cleaned = user_input.strip()
    if len(cleaned) < 5:
        raise ValueError("输入过短")
    if contains_pii(cleaned):
        raise ValueError("检测到 PII - 正在脱敏...")
    return redact_pii(cleaned)

agent = Agent(
    name="SafeAssistant",
    instructions="有帮助地回复用户询问",
    tools=[validate_input]
)
# Guardrail 在模型调用之前运行，节省算力
result = agent.run("给我讲讲神经网络")

效果：输入验证 guardrails 可以在请求到达 LLM 之前过滤 20-40% 的无效请求，削减成本并提升响应质量。

数据来源： HN Algolia 搜索"openai agents guardrails" 1+ 条讨论，"AgentArmor 8 层安全框架" HN 10 票。

隐藏用法 #4：多智能体协作与共享上下文

大多数人的用法：创建独立的智能体，每个处理独立任务。

隐藏技巧：使用共享上下文存储，让智能体能够在彼此的工作成果上继续构建，创建协作流水线，其中上一个智能体的输出成为下一个智能体的结构化输入。

from agents import Agent
from dataclasses import dataclass
from typing import Optional

@dataclass
class ProjectContext:
    requirements: Optional[str] = None
    architecture: Optional[str] = None
    code: Optional[str] = None
    test_results: Optional[str] = None

# 隐藏模式：智能体通过共享上下文协作
planner = Agent(
    name="Planner",
    instructions="定义项目需求并保存到上下文"
)
architect = Agent(
    name="Architect",
    instructions="基于需求设计系统架构"
)
builder = Agent(
    name="Builder",
    instructions="基于架构设计编写代码"
)

context = ProjectContext()
context = planner.run("构建一个网页爬虫", context=context)
context = architect.run(context=context)
context = builder.run(context=context)
# 每个智能体都在前一个智能体的输出基础上构建
print(context.test_results)

效果：具有结构化上下文的多智能体流水线可以处理复杂的工作流——需要在规划、设计和实施阶段进行迭代精化的复杂工作流。

数据来源： OpenAI Agents Python SDK 多智能体工作流能力，GitHub 26,559 Stars。

隐藏用法 #5：MCP 集成扩展工具能力

大多数人的用法：只使用 Agents SDK 自带的内置工具。

隐藏技巧：集成 Model Context Protocol（MCP）服务器，为智能体提供对数百种外部工具的访问——数据库、API、文件系统、企业系统——使用统一接口。

from agents import Agent
from agents.mcp import MCPServer

# 隐藏模式：MCP 集成扩展智能体能力
mcp_server = MCPServer(
    command="npx",
    args=["-y", "@modelcontextprotocol/server-filesystem", "/data"]
)

agent = Agent(
    name="DataAnalyst",
    instructions="分析数据文件并提供洞察",
    mcp_servers=[mcp_server]
)
# 现在智能体可以从 /data 读取文件、查询数据库等
result = agent.run("读取销售数据，告诉我前 3 个趋势")