快速入门 openai agents sdk

OpenAI Agents SDK让你能够以一个轻量、易用且几乎没有抽象层的包来构建智能体 AI 应用。它是我们此前用于智能体实验的项目 Swarm 的生产就绪升级版。Agents SDK 只有一小组基本组件：

智能体，即配备了 instructions 和 tools 的 LLM
Agents as tools / 任务转移，允许智能体将特定任务委派给其他智能体
安全防护措施，用于验证智能体的输入和输出

结合 Python，这些基本组件足以表达工具与智能体之间的复杂关系，并让你无需陡峭的学习曲线即可构建真实世界应用。此外，SDK 内置了追踪功能，可让你可视化并调试智能体工作流，还能对其进行评估，甚至为你的应用微调模型。

使用 Agents SDK 的原因

SDK 有两个核心设计原则：

功能足够丰富，值得使用；同时基本组件足够少，能够快速上手。
开箱即用，同时你也可以精确自定义实际发生的行为。

以下是 SDK 的主要特性：

智能体循环：内置智能体循环，可处理工具调用，将结果发送回 LLM，并持续运行直到任务完成。
Python 优先：使用内置语言特性来进行智能体编排与链式调用，而无需学习新的抽象。
Agents as tools / 任务转移：一种强大的机制，用于在多个智能体之间协调和委派工作。
沙箱智能体：在真实隔离的工作区中运行专用智能体，支持由清单定义的文件、沙箱客户端选择以及可恢复的沙箱会话。
安全防护措施：与智能体执行并行运行输入验证和安全检查，并在检查未通过时快速失败。
工具调用：将任意 Python 函数转换为工具，并自动生成 schema 和基于 Pydantic 的验证。
MCP 服务工具调用：内置 MCP 服务工具集成，其工作方式与工具调用相同。
会话：一个持久化记忆层，用于在智能体循环中维护工作上下文。
Human in the loop：内置机制，用于在智能体运行过程中引入人工参与。
追踪：内置追踪功能，用于可视化、调试和监控工作流，并支持 OpenAI 的评估、微调和蒸馏工具套件。
Realtime Agents：使用 gpt-realtime-1.5 构建强大的语音智能体，支持自动中断检测、上下文管理、安全防护措施等功能。

Agents SDK 还是 Responses API

对于 OpenAI 模型，SDK 默认使用 Responses API，但它在模型调用之上增加了一层更高层级的运行时。

在以下情况下，直接使用 Responses API：

你想自己掌控循环、工具分发和状态处理
你的工作流生命周期较短，主要是返回模型响应

在以下情况下，使用 Agents SDK：

你希望运行时来管理轮次、工具执行、安全防护措施、任务转移或会话
你的智能体需要产出工件，或跨多个协调步骤运行
你需要真实工作区或通过沙箱智能体实现可恢复执行

你不需要在全局范围内二选一。很多应用会使用 SDK 来管理工作流，同时在更底层的路径中直接调用 Responses API。

快速入门

安装 Agents SDK

python 复制代码

pip install openai-agents 
或者 uv add openai-agents

创建你的第一个智能体

官网给的使用示例是默认你直接用的云端的大模型服务，但是实际在公司都用的是自己部署的大模型，甚至自己学习也都是通过本地用Ollama部署一个进行使用，因此我这里直接用这种方式写代码，方便大部分人可以直接看懂和使用：

python 复制代码

import asyncio
from openai import AsyncOpenAI
from agents import Agent, Runner, OpenAIChatCompletionsModel

async def main():
    # 1. 创建一个指向本地 Ollama 服务的客户端
    # api_key 可以随便填，Ollama 默认不校验
    local_client = AsyncOpenAI(
        api_key="ollama",
        base_url="http://localhost:11434/v1"
    )

    # 2. 使用这个客户端来定义一个模型配置
    # 确保 model 名称和你用 'ollama run' 启动的模型名一致
    local_model = OpenAIChatCompletionsModel(
        model="qwen2.5:7b",
        openai_client=local_client
    )

    # 3. 创建智能体时，使用我们自定义的模型配置
    agent = Agent(
        name="本地助手",
        instructions="你是一个运行在本地的 AI 助手。",
        model=local_model
    )

    result = await Runner.run(agent, "你好，请介绍一下你自己。")
    print(result.final_output)

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

为智能体提供工具

光会聊天还不够，真正的智能体需要能"做事"。我们可以通过 @function_tool 装饰器为它赋予能力。

python 复制代码

import asyncio
from agents import Agent, Runner, function_tool

# 1. 定义一个工具函数
@function_tool
def 历史冷知识() -> str:
    """返回一个有趣的历史冷知识。"""
    return "你知道吗？鲨鱼比树木的历史还要悠久。"

# 2. 将工具添加到智能体中
agent = Agent(
    name="历史导师",
    instructions="回答历史问题。当用户想了解一些有趣的事实，或者你的回答需要佐证时，请使用历史冷知识工具。",
    tools=[历史冷知识], # 在这里注册工具
)

async def main():
    result = await Runner.run(
        agent,
        "给我讲讲远古地球上有什么 surprising 的生物。",
    )
    print(result.final_output)

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

多智能体协作（任务转移）

当任务变得复杂时，一个"全能"智能体可能不如一个"专家团队"来得高效。SDK 支持"任务转移"（Handoff），让一个智能体将任务委派给更专业的同事。

定义专家团队

我们创建两个专家智能体，并用 handoff_description 告诉"前台"他们是干什么的。

python 复制代码

from agents import Agent

history_tutor_agent = Agent(
    name="历史专家",
    handoff_description="专门负责回答所有历史相关问题。",
    instructions="你是一位历史专家，回答要清晰简洁。",
)

math_tutor_agent = Agent(
    name="数学专家",
    handoff_description="专门负责解决所有数学问题，并逐步解释过程。",
    instructions="你是一位数学专家，解释问题要一步一步来，并给出演算示例。",
)

定义调度员（Triage Agent）

这个智能体不负责具体回答，只负责判断问题类型，并将其"转移"给正确的专家。

python 复制代码

triage_agent = Agent(
    name="调度员",
    instructions="你是一个调度员，负责分析用户的问题，并将其分配给最合适的专家。",
    handoffs=[历史专家, 数学专家], # 这是关键！定义了它可以转移任务的对象列表
)

运行智能体编排

Runner 会自动处理复杂的流程：接收问题 -> 调度员判断 -> 转移给专家 -> 专家回答。

python 复制代码

import asyncio
from agents import Runner

async def main():
    result = await Runner.run(
        triage_agent,
        "美国的第一任总统是谁？",
    )
    print(result.final_output)
    # 你可以看到最终是哪个专家回答了问题
    print(f"回答者：{result.last_agent.name}")

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

参考文献

https://openai.github.io/openai-agents-python/zh/quickstart/