Agents SDK 简介与设计哲学

从 Swarm 到 Agents SDK 的演进

2024 年 10 月，OpenAI 发布了实验性框架 Swarm，用极简 API 展示了多 Agent 协作的可能性。Swarm 的核心思想是：Agent 之间通过"移交控制权（Handoff）"协作，每个 Agent 只做自己擅长的事情。

Swarm 虽然受到开发者热捧，但它是"教育目的"的原型——没有生产可靠性保障、没有追踪系统、没有护栏机制。2025 年 3 月，OpenAI 将这些思想提炼并升级，正式发布了 openai-agents SDK，作为构建生产级 Agent 系统的官方框架。

核心设计理念

理解 Agents SDK 的三个设计原则，才能用好这个框架：

与其他框架的对比

在使用 OpenAI Agents SDK 之前，了解它与主流框架的区别，有助于做出正确的技术选型：

核心概念速览

Agents SDK 的所有功能都建立在五个核心概念之上：

安装与环境配置

# 安装 openai-agents SDK（需要 Python 3.11+）
pip install openai-agents

# 如果需要语音功能（可选）
pip install "openai-agents[voice]"

# 验证安装
python -c "import agents; print(agents.__version__)"

# 配置 API Key（推荐使用环境变量）
import os
from agents import set_default_openai_key

# 方式 1：环境变量（推荐，生产环境必用）
# 在 .env 文件或系统中设置：OPENAI_API_KEY=sk-...
# SDK 自动读取，无需手动设置

# 方式 2：代码中显式设置（仅用于开发测试）
set_default_openai_key("sk-...")

# 方式 3：自定义 OpenAI Client（用于代理、Ollama 等场景）
from openai import AsyncOpenAI
from agents import set_default_openai_client

custom_client = AsyncOpenAI(
    api_key="sk-...",
    base_url="https://your-proxy.com/v1"  # 自定义端点
)
set_default_openai_client(custom_client)

第一个 Agent：你好，世界

以下是一个完整的最小可运行示例，包含了 Agents SDK 的核心工作流：

# hello_agent.py — 第一个 OpenAI Agent
import asyncio
from agents import Agent, Runner

# ── 定义 Agent ────────────────────────────────────────────
# name: Agent 的身份标识（出现在追踪日志中）
# instructions: 系统提示词，定义 Agent 的角色和行为规范
# model: 使用的 OpenAI 模型
agent = Agent(
    name="助手",
    instructions="你是一个友善、专业的 AI 助手。用中文回答问题，回答简洁有力。",
    model="gpt-4o-mini"  # 轻量模型，成本低
)

# ── 运行 Agent ────────────────────────────────────────────
async def main():
    # Runner.run() 是核心入口：输入用户消息，返回 Run 结果
    result = await Runner.run(agent, "你好！请介绍一下你自己。")

    # final_output 是 Agent 的最终文字回复
    print(result.final_output)

# ── 执行 ──────────────────────────────────────────────────
if __name__ == "__main__":
    asyncio.run(main())

# 输出示例：
# 你好！我是一个 AI 助手，专注于提供准确、简洁的回答。
# 有什么我可以帮助你的吗？

同步版本（适合脚本场景）

from agents import Agent, Runner

agent = Agent(
    name="助手",
    instructions="你是一个简洁的 AI 助手。",
    model="gpt-4o-mini"
)

# run_sync 不需要 asyncio.run()，适合简单脚本
result = Runner.run_sync(agent, "Python 的 GIL 是什么？")
print(result.final_output)

Run 结果对象详解

Runner.run() 返回一个 RunResult 对象，包含这次 Agent 运行的完整信息：

result = await Runner.run(agent, "查询今天的天气")

# ── 最常用字段 ────────────────────────────────────────────
result.final_output       # str：Agent 的最终回复文字
result.final_output_as(MyModel)  # 如果设置了结构化输出，转为 Pydantic 模型

# ── 消息历史 ──────────────────────────────────────────────
result.new_items          # list：本次 Run 新产生的所有消息（含工具调用）
result.to_input_list()    # list：将结果转为下次 Run 的输入，实现多轮对话

# ── 追踪信息 ──────────────────────────────────────────────
result.last_agent         # Agent：最后执行的 Agent（Handoff 后可能不同）

# ── 实际使用示例 ──────────────────────────────────────────
print(f"最终回复：{result.final_output}")
print(f"共 {len(result.new_items)} 条消息（含工具调用）")
print(f"最后执行的 Agent：{result.last_agent.name}")

名词解释：SDK 专属术语表

理解执行流程图