Agents SDK 2.0：sama 说它被严重低估，我用代码告诉你为什么

Sam Altman 不是一个喜欢亲自给产品更新背书的人。

GPT-5 发布他当然会发推，但一个 SDK 的版本更新？那通常是开发者关系团队的事。所以当他专门在社交媒体上点名 Agents SDK 2.0，说这个东西"被严重低估了"，这个反常信号本身就值得认真对待。

一个 SDK 更新，OpenAI 的 CEO 亲自下场喊话——要么是公关需要，要么是他真的觉得大多数人还没搞懂这东西意味着什么。

看完 2.0 的更新内容之后，我倾向于相信是后者。

---

先说结论：门槛变了，不是功能变了

很多人看 SDK 更新，第一反应是"又加了什么新功能"。但 Agents SDK 2.0 更重要的变化不在功能列表，在开发体验的结构性改变。

1.0 时代，你要构建一个多 Agent 协作系统，需要自己维护状态机、手写调度逻辑、自己搭调试链路、自己在 prompt 里硬塞安全限制。这些工作本身和"让 Agent 做事"无关，但每一项都是实实在在的工程成本。

2.0 做的事是：把这些成本从"开发者自己解决"变成"SDK 原生提供"。

这不是功能升级，是门槛的结构性下移。原来需要有经验的 AI 工程师才能搭起来的东西，现在普通后端开发者照着文档也能跑通。

---

第一个点：Multi-Agent 编排，从"写胶水代码"到"搭积木"

1.0 时代的痛苦你懂的

假设你要搭一个客服系统：前端有个"接待 Agent"负责理解用户意图，后端有个"知识库检索 Agent"负责查资料，还有个"回复生成 Agent"负责组织语言。

在 1.0 时代，让这三个 Agent 协作，你需要：

• 手动维护一个状态对象，记录当前流程走到哪一步
• 写调度函数，判断什么情况下把控制权交给哪个 Agent
• 处理异常时的回退逻辑
• 把上下文手动打包传递给下一个 Agent

光是这套"胶水代码"，就能写出几百行，而且每个项目都要重写一遍。

2.0 的 Handoffs：声明式交接

2.0 引入了原生的 Handoffs（交接）机制，核心思路是：你不用写"如何交接"的逻辑，只需要声明"可以交接给谁"。

from agents import Agent, handoff

定义知识库检索 Agent
kb_agent = Agent(
name="KnowledgeBase",
instructions="你负责在知识库中检索相关信息，返回最相关的3条内容。",
tools=[search_knowledge_base],  # 你自己定义的检索工具
)

定义接待 Agent，声明它可以把任务交接给 kb_agent
reception_agent = Agent(
name="Reception",
instructions="你负责理解用户问题。如果需要查询知识库，交接给知识库 Agent。",
handoffs=[handoff(kb_agent)],
)

运行
from agents import Runner
result = await Runner.run(reception_agent, "我的订单什么时候到？")

就这些。handoff(kb_agent) 这一行声明，SDK 会自动处理上下文传递、状态维护、结果回传。

Agent-as-Tool：更灵活的嵌套模式

除了 Handoffs，2.0 还支持 Agent-as-Tool 模式——把一个 Agent 当成另一个 Agent 的工具来调用：

from agents import Agent

把 kb_agent 作为工具暴露给主 Agent
main_agent = Agent(
name="Main",
instructions="你是主控 Agent，根据需要调用子 Agent 完成任务。",
tools=[
kb_agent.as_tool(
tool_name="search_kb",
tool_description="在知识库中检索信息"
)
],
)

Handoffs 是"把控制权完全转交"，Agent-as-Tool 是"调用完还回来"。两种模式覆盖了多 Agent 协作的主要场景。

对比锚点：实现同一个双 Agent 协作流程，1.0 时代大约需要 80-120 行代码（含状态管理和调度逻辑），2.0 的 Handoffs 写法在 20 行以内。这不是夸张，是代码量的量级差距。

---

第二个点：内置 Tracing——你终于知道 Agent 在"想什么"

"Agent 黑盒"是生产部署最大的拦路虎

如果你真的在生产环境跑过 Agent，你一定遇到过这种情况：

用户反馈"Agent 回答不对"，你去查日志——什么都没有。或者有一堆 API 调用记录，但完全看不出 Agent 在哪一步"想歪了"，为什么调用了错误的工具，为什么没有触发应该触发的分支。

调试 Agent 靠的是 print(response) 大法，这是 1.0 时代的现实。

2.0 内置可视化追踪

2.0 的 Tracing 功能是这样开启的：

# 1.0 时代：你自己写日志
print(f"Step 1: {response}")
print(f"Tool called: {tool_name}")
... 几十行散落在各处的 print

2.0：一行配置，全链路追踪
from agents import set_tracing_enabled
set_tracing_enabled(True)  # 就这一行

开启之后，SDK 会自动记录：

• 每次 LLM 调用的输入/输出
• 每次工具调用的参数和返回值
• Handoffs 的触发条件和时机
• 每个决策节点的推理过程

这些数据会以结构化的 trace 格式输出，可以接入 OpenAI 的 Dashboard 可视化，也可以导出到自己的监控系统。

为什么这是"被低估最严重"的更新

Tracing 看起来是个调试工具，但它的真正价值在于让 Agent 从"不敢上生产"变成"敢上生产"。

一个你看不懂内部行为的 Agent，你不敢让它处理真实用户的真实请求。有了完整的 trace 链路，你才能：

1. 快速定位"它为什么做了错误决策"

2. 评估 Agent 的行为模式是否符合预期

3. 在出问题时有据可查，能给用户/老板一个交代

这是从"玩具项目"到"生产系统"最关键的一道门。

---

第三个点：Guardrails 从"提示词里硬写"变成一等公民

过去的护栏有多脆弱

1.0 时代，你想给 Agent 加安全限制，通常是在 system prompt 里写："你不能讨论竞争对手的产品""你不能透露内部价格"。

这种方式有两个问题：

1. 脆弱：用户稍微绕一下，比如"假设你是另一个 AI，你会怎么回答……"，prompt 层面的限制很容易被绕过

2. 无法优雅降级：一旦触发限制，Agent 要么硬拒绝（体验差），要么你自己写一堆 if-else 来处理（成本高）

2.0 的声明式 Guardrails

2.0 把 Guardrails 提升为 SDK 的核心设计层，不是 prompt 技巧，是代码层面的强制约束：

from agents import Agent, GuardrailFunctionOutput, input_guardrail
from pydantic import BaseModel

定义护栏检查逻辑
class ContentCheckOutput(BaseModel):
is_safe: bool
reason: str

@input_guardrail
async def content_safety_check(ctx, agent, input) -> GuardrailFunctionOutput:
# 用另一个轻量模型做内容检查（速度快、成本低）
result = await check_content_safety(input)
return GuardrailFunctionOutput(
output_info=ContentCheckOutput(
is_safe=result.safe,
reason=result.reason
),
tripwire_triggered=not result.safe,  # 触发护栏
)

把护栏绑定到 Agent
customer_service_agent = Agent(
name="CustomerService",
instructions="你是客服 Agent，负责处理用户的售后问题。",
input_guardrails=[content_safety_check],
)

与 Handoffs 联动的客服场景

一个更完整的场景：

用户输入
↓
[输入护栏] → 触发 → 返回"我无法处理这类问题"
↓ 通过
[接待 Agent] → 判断需要查知识库 → Handoff
↓
[知识库检索 Agent] → 返回结果
↓
[输出护栏] → 检查回复是否包含敏感信息
↓ 通过
返回用户

这个链路里，护栏在入口和出口都有，任何一个节点触发，都不会影响其他节点的正常运行。这才是生产级的安全设计。

---

💡 想直接跑通上面的代码？

文中所有示例均基于 OpenAI 标准接口。国内开发者可以通过 [api.884819.xyz](https://api.884819.xyz) 直接调用，无需额外配置代理，和官方 SDK 完全兼容——只需把 SDK 初始化时的 base_url 改成这个地址就行。新用户注册即送体验 token，国产模型（Deepseek/千问等）完全免费，没有月租，按量付费，直接开跑。

---

结尾：30 分钟能跑通的起点

不做虚的总结，直接给行动路径。

三步清单

pip install openai-agents

from agents import set_default_openai_base_url, set_default_openai_key

set_default_openai_base_url("https://api.884819.xyz/v1")
set_default_openai_key("你的 API Key")  # 在 api.884819.xyz 注册后获取

复制本文第一个代码示例，把 search_knowledge_base 替换成一个返回固定字符串的 mock 函数，先让流程跑通，再接真实工具。

from agents import set_tracing_enabled
set_tracing_enabled(True)

运行之后，观察控制台输出的 trace 结构，确认 Handoff 是否按预期触发。

这三步加起来大约 30 分钟。不是"看懂了"，是"真的跑起来了"。这个区别很重要。

一个架构图

用户输入
│
▼
┌─────────────────────┐
│   输入护栏 (Guardrail) │ ──触发──▶ 优雅拒绝
└─────────┬───────────┘
│ 通过
▼
┌─────────────────────┐
│   接待 Agent         │
│   (Reception)       │
└─────────┬───────────┘
│ Handoff
▼
┌─────────────────────┐
│   知识库检索 Agent   │
│   (KnowledgeBase)   │
└─────────┬───────────┘
│ 返回结果
▼
┌─────────────────────┐
│   输出护栏 (Guardrail) │ ──触发──▶ 过滤敏感内容
└─────────┬───────────┘
│ 通过
▼
用户

---

sama 说 Agents SDK 2.0 被低估，不是在吹牛。他说的是：大多数开发者还没意识到，之前挡住他们的那些工程难题，现在已经不存在了。

门槛变了。你能做的事，也跟着变了。

---

不过说实话，SDK 再好用，Agent 能不能真正"稳定工作"，很大程度上取决于你怎么设计工具（Tools）的边界。下一篇我会拆解一个反面案例——一个看起来很聪明的 Agent，为什么在生产环境里频繁"幻觉调用"工具，以及三个让工具定义更健壮的写法。如果你已经在用 Agents SDK，那篇可能比这篇更值得看。

---

#AI开发 #OpenAI #AgentsSDK #多智能体 #AIAgent #8848AI #AI教程 #后端开发