openai-agents-python

环境要求

• Python 环境（SDK 为 Python 包，PyPI 包名 openai-agents）
• 可用的 OpenAI API Key（需设置 OPENAI_API_KEY 环境变量）
• 运行沙箱智能体时：macOS/Linux 可用 UnixLocalSandboxClient，Windows 需 Docker 及 openai-agents[
• 运行语音管线示例需安装 numpy

安装与启动步骤

1. 1安装 SDK

   通过 PyPI 安装官方包 openai-agents，README 徽章链接指向 pypi.org/project/openai-agents。建议在虚拟环境中安装。

   pip install openai-agents

   复制

2. 2设置 API Key

   运行任何示例前都必须先设置 OPENAI_API_KEY 环境变量，示例中的 Runner 会读取它调用模型。

   export OPENAI_API_KEY="sk-xxxxxxxx"

   复制

3. 3运行文本智能体

   新建一个 .py 文件写入下面的官方示例代码，保存后执行，验证 SDK 与密钥是否可用。

   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)

   复制

4. 4运行沙箱智能体

   需要智能体读写文件、执行命令时使用。macOS/Linux 用 UnixLocalSandboxClient；Windows 需先装 docker extra 并改用 DockerSandboxClient。

   pip install "openai-agents[docker]"

   复制

5. 5运行实时智能体

   需要低延迟服务端语音/多模态时用 RealtimeAgent + RealtimeRunner，通过 WebSocket 会话发送消息并接收事件。

   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 == "history_added":
                   print(event.item)
               elif event.type == "agent_end":
                   break
   
   if __name__ == "__main__":
       asyncio.run(main())

   复制

6. 6运行语音管线

   用 VoicePipeline 把音频转文字、跑智能体工作流再合成语音；示例依赖 numpy，需额外安装。

   pip install numpy

   复制

关键配置

如何确认成功

执行文本智能体示例后，终端打印出生成的 haiku 文本，说明 SDK 安装与 API Key 配置均成功。

常见问题

注意事项

• 本教程仅依据 README 节选整理，README 未给出的安装命令与参数未做补充。
• SDK 是 provider-agnostic 的，支持 OpenAI Responses 与 Chat Completions API，也兼容 100 多种其他 LLM。
• README 提示还有 JavaScript/TypeScript 版本 Agents SDK JS/TS，Python 用户请勿混用。
• 更多用法可参考仓库 examples 目录和官方文档站点 openai.github.io/openai-agents-python。