用OpenAI Agents SDK Python搭建多智能体工作流从安装、运行到调试的三步上手法【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-pythonOpenAI Agents SDK包名openai-agents是 OpenAI 开源的 Python 多智能体工作流框架。它把智能体开发中最容易重复造轮子的部分——Agent 定义、工具调用、智能体间交接、会话记忆、运行追踪——打包成一套小库你只管写业务逻辑循环调度的脏活它来干。这套框架不绑定模型厂商默认走 OpenAI 的 Responses 和 Chat Completions API也支持通过扩展接入其他 100 多家 LLM 提供商。本文带你走完能装、能跑、能调的最小路径并讲清楚它适合你的哪些场景。它解决什么问题别手写智能体循环了如果你从零做过 LLM 应用大概率写过这样一段代码调模型 → 解析响应 → 发现是工具调用就执行、把结果塞回消息列表 → 再调模型 → 直到模型给出最终答案。再往后一点你会开始处理更多分支这个任务该转给哪个专家智能体多轮对话的历史往哪存敏感输入怎么拦出了问题去翻哪里每加一个需求主循环就膨胀一圈最后没人敢动。OpenAI Agents SDK 的做法是把这些分支收敛成明确的构件Runner 负责循环调模型、分发工具调用、处理交接直到拿到最终输出才返回你不需要自己 while True。Handoff 是一种特殊工具智能体可以把话交给别人控制权自动切换而不是你手写路由。Session 管历史跨多次运行自动维护对话上下文。Tracing 管排查每一步模型调用、工具执行都自动记录成可回放的时间线。一句话它不是又一个提示词模板库而是一个替你维护智能体主循环的运行时。如何快速安装3 分钟跑通第一个 Agent环境要求不高Python 3.10 或更高装包只需一条命令pip install openai-agents按需安装可选依赖组语音流水线加openai-agents[voice]Redis 会话加openai-agents[redis]。装好后确保环境变量里配好了OPENAI_API_KEY然后写一个最小例子——定义智能体、同步运行、打印结果from agents import Agent, Runner agent Agent(nameAssistant, instructionsYou are a helpful assistant) result Runner.run_sync(agent, Write a haiku about recursion in programming.) print(result.final_output)四行代码就是完整闭环Agent声明它是谁、怎么做事Runner.run_sync负责跑完整个循环并返回带final_output的结果对象。异步场景把run_sync换成run即可。关键能力拆解它到底给了你什么工具调用让 Agent 真的动手给函数加一个function_tool装饰器或直接用函数挂到tools参数上模型就能在对话中发起调用SDK 负责执行并把结果回填。除了本地函数它还支持 MCP 协议的工具服务和托管工具接入现成的工具生态不需要自己写适配层。交接Handoffs把任务转给专家智能体当你的业务天然分工——比如按语言分流、按问题类型分诊——交接就是核心机制。做法是把多个专家智能体列进handoffs参数from agents import Agent, Runner spanish Agent(nameSpanish agent, instructionsYou only speak Spanish.) english Agent(nameEnglish agent, instructionsYou only speak English.) triage Agent( nameTriage agent, instructionsHand off to the agent matching the language of the request., handoffs[spanish, english], ) print(Runner.run_sync(triage, Hola, ¿cómo estás?).final_output)分诊智能体判断请求语言后直接把控制权交给对应专家整个过程对调用方透明。官方仓库里有一个航空客服的多智能体示例分诊、改座、FAQ 检索各管一摊examples/customer_service/。交接只是协作方式之一。另一种更硬的方式是Agents as tools把一个智能体整体包装成另一个智能体的工具调用方拿到的是一段结构化结果控制权始终不离开调用方。前者适合接管对话后者适合委托子任务。会话Sessions跨运行记住上下文多轮对话应用里你需要自己维护消息历史。接入 SDK 的会话能力后每次运行把同一个session对象传给 Runner 就行第一轮问金门大桥在哪个城市第二轮直接问它在哪个州智能体自动记得前文。内置实现覆盖了常见后端——SQLiteSession适合本地开发OpenAIConversationsSession依托云端Redis、MongoDB、SQLAlchemy 等后端通过可选依赖组接入。想用自己的存储实现Session协议即可。追踪Tracing看清每一步花了多久调试智能体最痛苦的是它为什么这么做。SDK 默认对每次运行自动埋点哪一次模型调用、耗时多少、参数是什么、哪个工具执行了几毫秒、在哪里发生了交接全部按时间线呈现。这种时间线在排查多智能体跑偏时尤其有用——你能直接看到控制权在哪一步转手、哪个工具返回了异常值。追踪是插件化的除了官方可视化界面也可以对接第三方可观测后端。接入 MCP 工具时每个工具调用同样会在追踪里单独成项方便定位是哪个服务慢了。护栏Guardrails与人在环给自动执行上保险护栏是挂在智能体输入和输出上的校验逻辑输入侧可以拦截恶意或越界的请求输出侧可以检查回复是否合规不通过就中止运行。另一个实用机制是人在环Human in the loop把某个工具标记为需要审批后模型发起调用时运行会暂停等你的代码或用户批准后再继续。删文件、发资金这类高危操作建议默认走这条路径。沙箱智能体给长任务一个真工作区如果任务不只是聊而是要读文件、跑命令、改代码并保持工作区状态SDK 提供SandboxAgent预配置一个容器化的沙箱工作区智能体在里面干活你的应用通过网关访问内部数据并拦截不可信的外发请求。本地 macOS/Linux 可直接用Windows 或生产环境可接 Docker 或托管沙箱客户端。适合哪些场景对照你的业务判断适合直接上手的多轮对话助手需要跨请求记忆Session 结构化输出基本够用。任务分诊与路由客服、工单、技术支持类场景用分诊智能体 交接拆给专家智能体代码量很小。工具密集型 Agent查天气、查库存、操作文件、调 MCP 服务工具调用是这套 SDK 最成熟的部分。需要审计和评估的智能体Tracing 时间线可以直接当回归测试的素材配合评估流程迭代提示词。需要额外评估的复杂的 DAG 编排它给你的是循环 交接 工具原语不是可视化流程引擎。分支逻辑复杂时编排代码还是你自己写只是写法更整洁。强一致性长事务持久化长运行任务需要借助 Temporal 等外部方案SDK 本身不管任务恢复。更多可运行的参考实现可以直接看示例目录examples/其中agent_patterns子目录按模式分类路由、并行化、护栏、流式等basic子目录是入门小例。常见限制动手前要知道的边界默认面向 OpenAI 系 API。接入其他厂商如通过 LiteLLM 扩展可行但部分依赖 Responses API 的行为结构化输出细节、托管工具等在非 OpenAI 模型上可能有功能落差选型前先验证你的目标模型。版本仍在 0.x。迭代快意味着 API 有变动可能升级时留意 changelog生产环境建议锁定版本。可视化追踪依赖其配套平台。如果你要求数据完全不出内网需要自行评估对接自建可观测后端。沙箱和语音是可选能力依赖额外安装组且沙箱在不同操作系统的可用客户端不一样部署前确认平台支持。落地建议让智能体稳定跑起来的五件事提示词写明工具契约。在 instructions 里说清每个工具干什么、何时用、参数从哪来——模型选错工具十有八九是说明不够。一个智能体只擅长一件事。与其养一个万能智能体不如拆成职责单一的专家再用交接串起来。高危工具默认加审批。删除、支付、外发类操作挂上人在环护栏兜底。会话持久化从第一天就做。哪怕本地 SQLite也能让你重启后用户不失忆后期换 Redis 或数据库只是换 Session 实现。用 Tracing 驱动迭代。每次改提示词前后各跑一遍对比时间线和输出比凭感觉调有效得多。更多模式化的完整代码可以对照 examples/agent_patterns/ 和官方文档 docs/ 阅读。总结OpenAI Agents SDK 的价值在于把智能体开发里最琐碎的循环调度层收进库里你写 Agent、工具和业务规则Runner 负责跑Tracing 负责事后复盘。对需要工具调用、多智能体协作、会话记忆和运行可观测性的 Python 项目它能把原型到上线的路径明显缩短。如果你的场景恰好落在这些点上建议先跑通本文的最小例子再按业务逐步叠加交接、护栏和会话能力。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考