OpenAI Agents SDK：官方多Agent协作框架，5分钟上手

写在前面：为什么你需要一个Agent框架？

如果你用过ChatGPT的API，一定有过这样的困惑——单轮对话还好，可一旦想让AI帮你完成一个复杂任务（比如"帮我查天气、订机票、发邮件通知"），就会发现：大模型本身只是个"嘴强王者"，它只会说，不会做。

你需要的是让AI能调用工具、能把任务拆分给不同的专家Agent、能记住上下文、还能安全地执行操作。这就是Agent框架要解决的问题。

但市面上的选择让人头疼：LangChain太重，学一个概念还没搞懂又来三个；CrewAI偏角色扮演，实用性有限；AutoGen偏学术路线，代码量大到劝退。每个框架都在发明自己的抽象语言，开发者光理解概念就花了一周。

2025年初，OpenAI终于出手了——OpenAI Agents SDK正式开源。这是一个Python优先、轻量级但功能强大的多Agent协作框架，目前已经收获21.8K Star，最新版本v0.14.2。它不教你学新概念，用你熟悉的Python语法就能编排Agent，上手快得让人意外。

今天这篇文章，我会带你从零开始安装、配置，一步步掌握OpenAI Agents SDK的核心用法。不管你是刚接触Agent开发的新手，还是被其他框架折磨过的老手，都能从中找到实用的内容。

一、项目概览：OpenAI Agents SDK是什么？

OpenAI Agents SDK 是OpenAI官方推出的Python Agent框架，核心设计理念可以概括为四个字：Python优先。

它不是一个"又要学新DSL、又要学新概念、又要学新API"的重框架，而是用Python原生语法来编排Agent。你的Python函数就是Agent的工具，你的Python类就是Agent的数据模型，你写的Python代码就是Agent的逻辑。

核心特性一览

和同类框架的对比

简单来说：OpenAI Agents SDK不追求大而全，追求的是"上手就能用，用了就有效"。对于大多数Python开发者来说，这是目前最友好的Agent框架选择。

二、环境准备与安装

2.1 前置条件

• Python 3.9+（推荐3.11+）
• OpenAI API Key（如果用OpenAI模型）
• 或者其他LLM的API Key（框架支持100+种模型）

2.2 安装步骤

第一步：创建虚拟环境（良好的开发习惯）

python -m venv .venv
source .venv/bin/activate  # Windows用户用：.venv\Scripts\activate

第二步：安装核心包

pip install openai-agents

如果你需要语音功能（实时语音Agent）：

pip install 'openai-agents[voice]'

如果你需要Redis存储会话历史（生产环境推荐）：

pip install 'openai-agents[redis]'

也支持用uv安装（更快的包管理器）：

uv init
uv add openai-agents

第三步：设置API Key

export OPENAI_API_KEY=sk-your-api-key-here

建议把这行加到你的 .bashrc 或 .zshrc 里，或者用 .env 文件配合 python-dotenv 管理。

如果你用的是非OpenAI模型（比如国产的通义千问、智谱GLM、DeepSeek等），可以通过环境变量或代码配置来切换模型提供方，后面会详细介绍。

2.3 验证安装

创建一个 hello.py 文件：

import asyncio
from agents import Agent, Runner

async def main():
    agent = Agent(
        name="Assistant",
        instructions="You only respond in haikus.",
    )
    result = await Runner.run(agent, "Tell me about recursion in programming.")
    print(result.final_output)

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

运行：

python hello.py

如果你的API Key配置正确，应该会看到一段俳句风格的回答。这就是最简单的Agent——5行核心代码，一个Agent就跑起来了。

这里有几个关键概念需要解释一下：

• Agent：就是一个有名字、有指令、能调用工具的"AI角色"。instructions 是它的系统提示词，告诉它应该怎么行事。
• Runner：负责运行Agent的执行器。Runner.run() 是异步版本，Runner.run_sync() 是同步版本。
• result.final_output：Agent最终输出的文本结果。

三、核心功能详解

3.1 自定义工具：让你的Agent真正"能干活"

Agent只有嘴是不行的，必须给它装上"手"和"脚"。在OpenAI Agents SDK里，任何Python函数都可以变成Agent的工具——只需要加一个 @function_tool 装饰器。

来看一个带Pydantic验证的天气查询工具：

import asyncio
from typing import Annotated
from pydantic import BaseModel, Field
from agents import Agent, Runner, function_tool

# 定义返回值的数据模型（Pydantic自动校验）
class Weather(BaseModel):
    city: str = Field(description="The city name")
    temperature_range: str = Field(description="The temperature range in Celsius")
    conditions: str = Field(description="The weather conditions")

# 用装饰器把Python函数变成Agent工具
@function_tool
def get_weather(city: Annotated[str, "The city to get the weather for"]) -> Weather:
    """Get the current weather information for a specified city."""
    print("[debug] get_weather called")
    return Weather(city=city, temperature_range="14-20C", conditions="Sunny with wind.")

# 把工具挂到Agent上
agent = Agent(
    name="Hello world",
    instructions="You are a helpful agent.",
    tools=[get_weather],
)

async def main():
    result = await Runner.run(agent, input="What's the weather in Tokyo?")
    print(result.final_output)

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

这段代码做了几件事：

1. 定义数据模型 Weather：用Pydantic的 BaseModel 描述返回值的结构。每个字段都有 description，Agent会根据这些描述来决定什么时候调用这个工具。
2. 创建工具函数 getweather：用 @functiontool 装饰器标记。函数的参数类型注解 Annotated[str, "描述"] 会自动变成工具的参数说明。函数的docstring也会被Agent读取。
3. 挂载到Agent：把工具放到 Agent 的 tools 列表里。

运行后，Agent会自动判断需要调用 get_weather 工具，传入参数 "Tokyo"，拿到返回值后组织成自然语言回答你。

关键点：你不需要写任何JSON Schema或工具描述模板——Python的类型注解和docstring就够了。这就是"Python优先"的含义。

3.2 多Agent交接：让专业的人做专业的事

单个Agent什么都会是不现实的。现实中，我们需要多个专业Agent各司其职，需要时互相转交任务。

来看一个客户服务系统的真实案例（来自项目官方示例）：

from agents import Agent, Runner, RunContext, handoff
from pydantic import BaseModel

# 1. 定义共享上下文——所有Agent都能访问
class AirlineAgentContext(BaseModel):
    passenger_name: str = ""
    confirmation_number: str = ""
    seat_number: str = ""
    flight_number: str = ""

# 2. FAQ Agent——专门回答常见问题
faq_agent = Agent[AirlineAgentContext](
    name="FAQ Agent",
    instructions="""
    You are a FAQ agent for an airline company.
    Use the faq_lookup_tool to answer questions about airline policies.
    If the question is not FAQ-related, hand off to the Triage Agent.
    """,
    tools=[faq_lookup_tool],
)

# 3. 座位预订 Agent——专门处理座位变更
seat_booking_agent = Agent[AirlineAgentContext](
    name="Seat Booking Agent",
    instructions="""
    You are a seat booking agent for an airline company.
    Use the update_seat tool to change passenger seats.
    When done, hand off back to the Triage Agent.
    """,
    tools=[update_seat],
)

# 4. 分诊 Agent——负责判断问题类型，分发给对应的专家Agent
triage_agent = Agent[AirlineAgentContext](
    name="Triage Agent",
    instructions="""
    You are a triage agent for an airline company.
    Determine the type of inquiry and hand off to the appropriate agent.
    - For FAQ questions, hand off to the FAQ Agent.
    - For seat changes, hand off to the Seat Booking Agent.
    """,
    handoffs=[faq_agent, seat_booking_agent],
)

这里的几个核心概念：

• Agent Context（上下文）：AirlineAgentContext 是一个Pydantic模型，存储乘客信息。所有Agent共享同一个上下文实例，所以FAQ Agent查到的信息，Seat Booking Agent也能看到。
• Handoff（交接）：handoffs 参数列出了当前Agent可以把工作转交给哪些Agent。当分诊Agent判断用户想改座位时，它会把对话"交接"给座位预订Agent，用户不需要重新描述问题。
• 多Agent协作网络：Agent之间不是简单的线性调用，而是形成网状协作关系。FAQ Agent处理完可以交回分诊Agent，分诊Agent再决定下一步。

为什么这很重要？ 因为每个Agent的instructions可以做得更精准（专家比通才好用），系统更容易维护和扩展（加个新Agent就行），调试也更容易（看哪个Agent出了问题）。

3.3 Agent作为工具：更灵活的协作方式

除了"交接"（转移控制权），Agent还可以作为工具被另一个Agent调用——这意味着A Agent可以"借用"B Agent的能力，但不需要把控制权转出去。

from agents import Agent, Runner, Runner.run

# 把Agent包装成工具
research_tool = research_agent.as_tool(
    tool_name="research",
    tool_description="Research a topic and return findings"
)

# 主Agent可以把其他Agent当工具用
writer_agent = Agent(
    name="Writer",
    instructions="You are a writer. Use the research tool to gather information.",
    tools=[research_tool],
)

"交接"和"作为工具"的区别：

• 交接（Handoff）：控制权转移，当前Agent退出，目标Agent接管对话。类似电话转接。
• 作为工具（as_tool）：当前Agent保持控制权，只是调用另一个Agent获得结果，然后继续工作。类似打电话请教专家。

根据场景选择合适的协作方式，是设计好Agent系统的关键。

3.4 安全护栏：防止Agent"乱来"

Agent有了工具调用能力后，如果不加约束，可能会做出危险操作（比如删除数据库、泄露用户隐私）。Guardrails（安全护栏） 就是用来解决这个问题的。

来看一个工具级别的安全护栏示例：

from agents import Agent, Runner, function_tool, guardrail
from agents.guardrails import reject_content, raise_exception

# 工具输入护栏：检查调用参数是否包含敏感词
@tool_input_guardrail
def check_sensitive_input(ctx, agent, tool_args):
    sensitive_words = ["password", "secret", "credentials"]
    for word in sensitive_words:
        if word in str(tool_args).lower():
            return reject_content(f"不允许查询敏感词：{word}")
    return None  # 通过检查

# 工具输出护栏：检查返回结果是否包含敏感数据
@tool_output_guardrail
def check_sensitive_output(ctx, agent, tool_result):
    import re
    # 检查是否包含SSN（美国社会安全号）等敏感数据
    ssn_pattern = r'\d{3}-\d{2}-\d{4}'
    if re.search(ssn_pattern, str(tool_result)):
        return reject_content("输出包含敏感数据（SSN），已拦截")
    return None  # 通过检查

# 挂载护栏到工具
@function_tool(guardrails=[check_sensitive_input, check_sensitive_output])
def query_database(query: str) -> str:
    """Query the company database."""
    # 实际的数据库查询逻辑
    return "..."

护栏的两种拦截方式：

• reject_content()：拒绝这次操作，但Agent会继续执行（可以换别的方式完成任务）。就像一个温和的保安说"这条路不行，走另一条路吧"。
• raise_exception()：直接抛异常，完全中止执行。就像紧急制动按钮。

护栏可以在三个层级生效：

1. 输入护栏（Input Guardrail）：检查用户输入是否安全
2. 工具输入护栏（Tool Input Guardrail）：检查Agent传给工具的参数
3. 工具输出护栏（Tool Output Guardrail）：检查工具返回给Agent的结果

这在企业场景下非常重要——你不希望你的客服Agent把用户的身份证号原样输出给第三方API吧？

3.5 沙箱Agent：在安全隔离环境中执行任务

这是0.14版本的重磅新功能。沙箱Agent可以在隔离的环境中执行任务——比如操作文件、运行命令、打补丁——而不会影响宿主系统。

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.entries import GitRepo
from agents.sandbox.sandboxes import UnixLocalSandboxClient

# 创建沙箱Agent
agent = SandboxAgent(
    name="Workspace Assistant",
    instructions="Inspect the sandbox workspace before answering.",
    # 定义沙箱中的资源
    default_manifest=Manifest(
        entries={
            "repo": GitRepo(repo="openai/openai-agents-python", ref="main"),
        }
    ),
)

# 在沙箱环境中运行
result = Runner.run_sync(
    agent,
    "Inspect the repo README and summarize what this project does.",
    run_config=RunConfig(sandbox=SandboxRunConfig(client=UnixLocalSandboxClient())),
)
print(result.final_output)

沙箱Agent的应用场景：

• 代码审查：在隔离环境中拉取代码仓库，分析后给出建议
• 安全测试：在沙箱里运行不可信的命令，不会影响真实系统
• 数据处理：在隔离环境中处理敏感文件，防止数据泄露
• 自动化运维：在沙箱中试运行脚本，确认安全后再应用到生产环境

Manifest 定义了沙箱里有哪些资源（Git仓库、本地文件等），SandboxRunConfig 定义了沙箱的运行环境。当前支持 UnixLocalSandboxClient（本地沙箱），后续可能会支持云端沙箱。

3.6 会话管理：让Agent"记得住"

在多轮对话中，Agent需要记住之前聊过什么。OpenAI Agents SDK内置了会话管理功能：

from agents import Agent, Runner
from agents.sessions import InMemorySession

agent = Agent(name="Chat Bot", instructions="You are a helpful assistant.")

# 创建内存会话（生产环境可用Redis会话）
session = InMemorySession()

# 第一轮对话
result1 = await Runner.run(agent, "My name is Xiao Ming", session=session)

# 第二轮对话——Agent会记住你的名字
result2 = await Runner.run(agent, "What's my name?", session=session)
print(result2.final_output)  # 会回答"Xiao Ming"

对于生产环境，推荐使用Redis会话来持久化对话历史：

pip install 'openai-agents[redis]'

from agents.sessions import RedisSession

session = RedisSession(redis_url="redis://localhost:6379")

3.7 链路追踪：让Agent流程"看得见"

多Agent系统的调试是个大难题。OpenAI Agents SDK内置了Tracing功能，可以可视化地追踪整个Agent执行流程：

from agents import trace

with trace("Customer service flow") as t:
    result = await Runner.run(triage_agent, "I want to change my seat")
    # 会在OpenAI Dashboard上显示：
    # Triage Agent → Seat Booking Agent → Tool: update_seat → Response

追踪信息会发送到OpenAI的Dashboard，你可以看到：

• 每个Agent的输入和输出
• 工具调用的参数和返回值
• Agent之间的交接路径
• 执行时间分布
• LLM的token消耗

这对调试和优化Agent系统至关重要——不用再靠打日志来猜哪里出了问题。

3.8 使用非OpenAI模型

OpenAI Agents SDK不局限于OpenAI模型。通过集成LiteLLM和any-llm，它支持100+种LLM，包括国产模型：

from agents import Agent, Runner, ModelSettings
from agents.models import create_model

# 使用DeepSeek模型
agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
    model="deepseek/deepseek-chat",
)

# 或者用自定义模型配置
agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
    model=create_model(
        provider="litellm",
        model_name="deepseek/deepseek-chat",
        api_key="your-deepseek-api-key",
    ),
)

对于国内开发者来说，这大幅降低了使用门槛。你可以用国产模型（DeepSeek、通义千问、智谱GLM等）来运行Agent，不用走OpenAI的API。

四、实战场景：三个典型应用

场景一：智能客服系统

最经典的多Agent场景。用分诊Agent分发到FAQ Agent、退换货Agent、物流Agent，每个专业Agent处理自己领域的问题。结合Guardrails防止敏感信息泄露，结合Session保持对话上下文。

架构：用户 → 分诊Agent → FAQ Agent / 售后Agent / 物流Agent → 用户

场景二：代码审查助手

用沙箱Agent拉取代码仓库，在隔离环境中分析代码质量、检查安全漏洞、给出修改建议。不会影响真实代码仓库，审查完自动输出报告。

架构：开发者提交代码 → 沙箱Agent（拉取仓库 → 分析 → 输出报告） → 开发者

场景三：数据分析Agent

用函数工具连接数据库，Agent自动理解用户需求、生成查询、分析结果、输出图表。Guardrails确保不会查询或泄露敏感数据。

架构：用户提问 → Agent（理解需求 → 调用数据库工具 → 分析结果） → 返回答案

五、常见问题与踩坑指南

Q1：必须用OpenAI模型吗？

不是。框架支持100+种LLM，包括DeepSeek、通义千问、智谱GLM、Llama等。见3.8节。

Q2：Session存在哪里？重启会丢失吗？

默认是 InMemorySession，重启会丢失。生产环境建议用 RedisSession，持久又快速。

Q3：多Agent交接时上下文丢失怎么办？

确保所有Agent共享同一个Context对象，Context会随交接自动传递。

Q4：如何调试Agent的决策过程？

使用内置的 trace 功能，在OpenAI Dashboard可视化查看每个Agent和工具调用的细节。

Q5：和LangChain什么关系？能一起用吗？

两者是独立的框架。OpenAI Agents SDK更轻量、更Python原生。如果你已经用了LangChain，可以逐步迁移；如果从零开始，推荐直接用Agents SDK。

Q6：生产环境需要注意什么？

• 用Redis会话替代内存会话
• 加好Guardrails，防止越权操作
• 用Tracing监控Agent行为
• 对工具调用做速率限制
• 考虑沙箱Agent处理不可信输入

六、小结

OpenAI Agents SDK最大的价值不在于它"又多了一个Agent框架"，而在于它用最Python的方式解决了Agent开发的核心痛点——让开发者不用学新概念，用熟悉的Python语法就能编排复杂的多Agent系统。

核心亮点回顾：

• 轻量级：5行代码启动第一个Agent
• Python原生：类型注解、装饰器、Pydantic，没有新概念要学
• 多Agent协作：交接和工具调用两种模式，灵活组合
• 安全护栏：从输入到输出的多层保护
• 沙箱Agent：0.14新功能，安全执行不可信操作
• 100+模型：不绑定OpenAI，国产模型友好

如果你正在找一个上手快、功能全、不用学新语言的Agent框架，OpenAI Agents SDK值得认真试试。

项目地址：https://github.com/openai/openai-agents-python

安装：pip install openai-agents

文档：https://openai.github.io/openai-agents-python/

Star数：21.8K | 最新版本：v0.14.2 | 语言：Python