openai--openai-agents-python/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

OpenAI Agents SDK

OpenAI Agents SDK 是一款轻量而强大的框架，用于构建多智能体工作流。它与提供商无关（provider-agnostic），支持 OpenAI Responses 和 Chat Completions API，以及 100 多种其他 LLM。

Note

在找 JavaScript/TypeScript 版本？请查看 Agents SDK JS/TS.

核心概念：

1. Agents: 配置了指令、工具、防护栏（guardrails）和交接（handoffs）的 LLM
2. Sandbox Agents: 预配置为与容器协同工作的智能体，可在较长的时间跨度内执行任务。
3. Agents as tools / Handoffs: 将特定任务委派给其他智能体
4. Tools: 多种工具使智能体能够执行操作（函数、MCP、托管工具）
5. Guardrails: 可配置的安全检查，用于输入和输出验证
6. Human in the loop: 内置机制，可在智能体运行过程中引入人工参与
7. Sessions: 跨智能体运行自动管理对话历史
8. Tracing: 内置智能体运行追踪，便于查看、调试和优化工作流
9. Realtime Agents: 使用 gpt-realtime-2.1 构建功能完备的强大语音智能体

浏览 examples 目录查看 SDK 的实际用法，并阅读我们的 documentation 了解更多详情。

快速开始

开始前，请先配置 Python 环境（需要 Python 3.10 或更高版本），然后安装 OpenAI Agents SDK 包。

venv

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install openai-agents

如需语音支持，请使用可选的 voice 依赖组安装：pip install 'openai-agents[voice]'。如需 Redis 会话支持，请使用可选的 redis 依赖组安装：pip install 'openai-agents[redis]'。

uv

如果你熟悉 uv, 安装该包会更加简便：

uv init
uv add openai-agents

如需语音支持，请使用可选的 voice 依赖组安装：uv add 'openai-agents[voice]'。如需 Redis 会话支持，请使用可选的 redis 依赖组安装：uv add 'openai-agents[redis]'。

运行你的第一个智能体

SDK 支持三种主要方式来运行智能体。在运行以下任一示例之前，请设置 OPENAI_API_KEY 环境变量。

运行沙盒智能体

当智能体需要检查文件、运行命令、应用补丁，或在较长任务中保持工作区状态时，请使用 SandboxAgent。

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 = 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。

from agents import Agent, Runner

agent = Agent(name="Assistant", instructions="You are a helpful assistant")

result = Runner.run_sync(agent, "Write a haiku about recursion in programming.")
print(result.final_output)

# Code within the code,
# Functions calling themselves,
# Infinite loop's dance.

（Jupyter notebook 用户请参阅 hello_world_jupyter.ipynb)

运行实时智能体

通过 WebSocket 实现低延迟、服务端语音与多模态体验时，请使用 RealtimeAgent。

import asyncio
from agents.realtime import RealtimeAgent, RealtimeRunner

async def main() -> None:
    agent = RealtimeAgent(name="Assistant", instructions="You are a helpful voice assistant. Keep responses short.")
    runner = RealtimeRunner(starting_agent=agent)
    session = await runner.run()

    async with session:
        await session.send_message("Say hello in one short sentence.")
        async for event in session:
            if event.type == "audio":
                # Forward or play event.audio.data.
                pass
            elif event.type == "history_added":
                print(event.item)
            elif event.type == "agent_end":
                break

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

浏览 examples 目录查看 SDK 的实际用法，并阅读我们的 documentation 了解更多详情。

致谢

我们要感谢开源社区的杰出贡献，尤其是：

• Pydantic
• Requests
• MCP Python SDK
• Griffe

本库包含以下可选依赖：

• websockets
• SQLAlchemy
• any-llm and LiteLLM

我们还依赖以下工具来管理项目：

• uv and ruff
• mypy and Pyright
• pytest and Coverage.py
• MkDocs

我们致力于持续将 Agents SDK 构建为开源框架，以便社区中的其他人能够在我们的方法基础上进行扩展。