官方文档不告诉你的事：Agents SDK 2.0 真实踩坑记录

我照着官方文档一行没改，跑了四次，全报错。

第五次我开始怀疑自己的Python环境出问题了。第六次我开始怀疑自己不适合写代码。

如果你也有过这种体验，这篇文章是专门为你写的。

Agents SDK 2.0 的官方文档写得很漂亮，示例代码永远能跑通——因为那些示例刻意回避了所有边界情况。但真实任务不是"问今天天气"，真实任务是多步骤、有上下文依赖、需要工具串联的东西。一旦你往那个方向走，文档就开始沉默了。

本文记录的是我把一个三步串联任务从"跑不通"调到"真能用"的完整过程，包括三个让我掉进去超过一次的坑。读完之后你会有一种具体的收获感——不是"我大概懂了Agent是什么"，而是"我知道那几个地方会出问题，以及怎么修"。

---

为什么"Hello World"是个骗局

Agents SDK 从 1.x 升到 2.0，核心重构了三个地方：

这三个变化，官方文档要么一笔带过，要么完全没提。

检验一个 Agent 是否"真能用"的最低门槛，是让它完成一个多步骤任务：有工具调用、有上下文传递、有格式化输出。单步任务太简单，掩盖了所有边界问题。

---

选一个"刚好够复杂"的任务

本文用的示例任务是：

给定一个公司名，自动搜索官网 → 提取联系邮箱 → 生成一封冷启动邮件草稿

为什么选这个？

• 三步串联，每步都依赖上一步的输出
• 覆盖了工具调用（搜索、提取）+ 上下文传递 + 输出格式化
• 贴近真实业务场景，不是玩具

"写诗"或"问天气"这类任务，一步就完成了，根本暴露不了 SDK 在多步骤任务中的真实行为。选错示例任务，是很多教程文章的通病。

---

从零配置到跑通：完整代码走读

① 环境安装与版本锁定

先把依赖锁死，这是减少玄学报错的第一步：

# requirements.txt
openai-agents==2.0.3
openai==1.35.0
httpx==0.27.0
python-dotenv==1.0.1

⚠️ 重要：openai-agents 2.0.x 和 1.x 的 API 不兼容。如果你的环境里装了旧版本，先 pip uninstall openai-agents 再重装，不要直接 upgrade。

安装命令：

pip install -r requirements.txt

② Agent 定义与工具注册

2.0 的工具注册方式变了。1.x 是用装饰器直接挂在函数上，2.0 要求工具函数必须有完整的类型注解和 docstring——这两样缺一个，工具注册会静默失败（对，又是静默失败）。

from agents import Agent, Tool, Runner
from openai import OpenAI

工具函数：必须有类型注解 + docstring
def search_company_website(company_name: str) -> dict:
"""
搜索公司官网URL。

Args:
company_name: 公司名称

Returns:
包含 url 和 status 字段的字典
"""
# 实际项目里这里接搜索API，这里用mock数据演示
mock_results = {
"OpenAI": {"url": "https://openai.com", "status": "found"},
"Anthropic": {"url": "https://anthropic.com", "status": "found"},
}
result = mock_results.get(company_name, {"url": "", "status": "not_found"})
return result  # 注意：必须返回 dict，不能返回字符串

③ 多步骤任务的编排逻辑

三步任务的执行链路如下：

graph LR
A[输入公司名] --> B[search_company_website]
B --> C{找到官网?}
C -- 是 --> D[extract_contact_email]
C -- 否 --> E[返回错误]
D --> F[generate_cold_email]
F --> G[输出邮件草稿]

Agent 的系统提示需要明确告诉它任务的执行顺序，否则 2.0 的工具调用链可能会乱序执行：

SYSTEM_PROMPT = """
你是一个商务拓展助手。当用户给你一个公司名时，你需要按以下顺序执行：
1. 调用 search_company_website 工具搜索该公司官网
2. 调用 extract_contact_email 工具从官网提取联系邮箱
3. 调用 generate_cold_email 工具生成一封冷启动邮件草稿

每一步都必须等上一步完成后再执行。如果某步失败，立即停止并报告原因。
"""

④ 完整可运行代码

import asyncio
from agents import Agent, Runner
from openai import OpenAI
import os

✅ 如果你在国内，把 base_url 换成这个，其余完全不用改
client = OpenAI(
base_url="https://api.884819.xyz/v1",
api_key=os.getenv("OPENAI_API_KEY")
)

工具1：搜索官网
def search_company_website(company_name: str) -> dict:
"""搜索公司官网URL。返回包含url和status字段的字典。"""
mock_results = {
"OpenAI": {"url": "https://openai.com", "status": "found"},
"Anthropic": {"url": "https://anthropic.com", "status": "found"},
}
return mock_results.get(company_name, {"url": "", "status": "not_found"})

工具2：提取邮箱
def extract_contact_email(url: str) -> dict:
"""从给定URL提取联系邮箱。返回包含email和confidence字段的字典。"""
mock_emails = {
"https://openai.com": {"email": "[email protected]", "confidence": 0.9},
"https://anthropic.com": {"email": "[email protected]", "confidence": 0.85},
}
return mock_emails.get(url, {"email": "", "confidence": 0.0})

工具3：生成邮件
def generate_cold_email(company_name: str, contact_email: str) -> dict:
"""生成冷启动邮件草稿。返回包含subject和body字段的字典。"""
return {
"subject": f"合作探讨 - 关于与{company_name}的潜在合作机会",
"body": f"您好，\n\n我注意到{company_name}在行业内的出色工作...",
"to": contact_email
}

定义 Agent
agent = Agent(
name="business_dev_agent",
model="gpt-4o",           # 或替换为 deepseek-chat 等
client=client,
instructions="""
你是一个商务拓展助手。当用户给你一个公司名时，按顺序执行：
1. 调用 search_company_website 搜索官网
2. 调用 extract_contact_email 提取邮箱
3. 调用 generate_cold_email 生成邮件草稿
每步失败立即停止并报告原因。
""",
tools=[
search_company_website,
extract_contact_email,
generate_cold_email,
],
max_turns=15,  # ✅ 显式设置，不要依赖默认值
)

异步运行
async def main():
result = await Runner.run(
agent,
input="帮我处理公司：OpenAI"
)
print(result.final_output)

if __name__ == "__main__":
asyncio.run(main())

💡 文中代码调用的模型接口，我用的是 [api.884819.xyz](https://api.884819.xyz)——兼容 OpenAI 格式，国内直连无需代理，把 base_url 换一行就能跑。调试阶段高频调用也不心疼，价格比官方便宜不少。

>

> # 只需改这一行，其余代码完全不动

---

3 个新手必踩的坑

坑 1：工具返回值格式不对，Agent 静默失败不报错

# ❌ 错误写法：返回字符串
def search_company_website(company_name: str) -> str:
return f"找到官网：https://openai.com"  # 看起来没问题，实际是坑

# ❌ 实际输出（Agent 失忆状态）
我已经搜索了该公司，但未能获取到有效的联系信息。
建议您直接访问公司官网查找联系方式。

# ✅ 正确写法：返回结构化 dict
def search_company_website(company_name: str) -> dict:
return {"url": "https://openai.com", "status": "found"}

# ✅ 修复后输出
已找到 OpenAI 官网：https://openai.com
正在提取联系邮箱...
找到邮箱：[email protected]
邮件草稿已生成：主题"合作探讨..."

---

坑 2：多轮上下文被截断，Agent "失忆"

# ❌ 第11轮之后的输出（上下文被截断）
我需要先搜索 OpenAI 的官网...
（重新开始搜索，忘记已经搜过了）

# ✅ 显式设置 max_turns，根据任务复杂度调整
agent = Agent(
...
max_turns=30,  # 三步任务，每步最多10轮推理，留足余量
)

同时，如果你的任务确实很长，考虑把它拆成多个子 Agent，每个子 Agent 负责一步，通过 handoff 传递结果。这是 2.0 推荐的架构模式，但文档里藏得很深。

---

坑 3：流式输出和同步调用混用导致死锁

# ❌ 错误：在 async 函数里调用同步方法
async def main():
result = Runner.run_sync(agent, input="...")  # 死锁触发
print(result)

# ✅ 修复：async 上下文用 await，同步上下文用 run_sync
async def main():
result = await Runner.run(agent, input="...")  # ✅
print(result.final_output)

或者如果你不想用 async：
def main_sync():
result = Runner.run_sync(agent, input="...")  # ✅ 纯同步场景
print(result.final_output)

---

跑通之后，下一步能做什么

Agent 跑通是起点，不是终点。三个方向：

---

SDK 1.x vs 2.0 关键变更速查

---

现在你手里有了别人没有的东西：不是"我看完了一篇 Agent 教程"，而是三个具体的肌肉记忆——工具返回值用 dict、max_turns 显式设置、同步异步不混用。下次遇到这三类问题，你的反应时间会比从头 Google 快得多。

跑通之后我做的第一件事，是把这个 Agent 包成一个 FastAPI 服务。然后发现了一个比今天这三个坑加起来还要隐蔽的问题——Agent 在高并发下会出现工具调用的"幻觉污染"：多个并发请求之间的工具调用结果会发生交叉污染，导致 A 用户的 Agent 拿到了 B 用户请求的工具返回值。

下一篇我们来专门拆解这个。

---

💡 8848AI 平台说明：文中所有代码调用的模型接口均可通过 [api.884819.xyz](https://api.884819.xyz) 访问。用户名+密码注册即可，新用户注册即送体验 token，国产模型（Deepseek/千问等）完全免费，没有月租，按量付费，适合调试阶段高频测试。

#AI教程 #AgentsSDK #Python #AI开发 #踩坑记录 #8848AI #LLM应用开发 #Agent实战