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 Python包名openai-agents是一个轻量级的多智能体工作流框架用几十行 Python 代码就能把多个智能体、工具调用、会话记忆和运行追踪组合成可调试的 Agent 应用。它支持 OpenAI 的 Responses 与 Chat Completions 接口也可接入其他厂商的 100 多个大模型适合需要用 Python 构建客服机器人、工具型助手或多智能体协作系统的开发者。它解决什么问题直接用大模型 API 做应用很快会遇到几件重复且麻烦的事多轮对话历史要自己拼每次请求前手动维护消息数组换模型、换接口就要重写一遍。多个角色要自己调度想让分诊角色把退款问题转给退款角色得自己解析跳转逻辑、拼接上下文、控制循环。模型调用工具的流程要手写解析函数调用参数、执行、把结果回填给模型、再等下一轮回复这套循环每个项目都要重写一次。出了错很难回溯一次运行里模型说了什么、调了哪个工具、耗时多少日志里一片混乱。这个框架把上面这些胶水代码收进一个 Runner 循环里你声明好智能体和它们的协作关系框架负责循环调用模型、执行工具、传递控制权并提供内置追踪面板帮你复盘每一步。30 秒认识项目一句话定位Python 生态里偏轻量的多智能体编排框架核心抽象是智能体 工具 交接 会话 追踪。关键能力智能体Agent配了指令、工具和交接的大模型封装是工作流的基本单元交接Handoff把一个智能体的控制权整体移交给另一个天然支持总机转专席式分工工具Tools把 Python 函数、MCP 服务器、托管工具统一成智能体可调用的动作会话Sessions自动管理跨运行的对话历史追踪Tracing内置的运行记录可查每一步的输入输出与耗时护栏与人在环Guardrails / HITL对输入输出做校验关键操作可暂停等人工确认。适用场景多角色客服/售后系统、需要调工具的任务型助手、需要持久记忆的多轮应用、需要审计与调试的智能体流程。不适用场景一次性的单轮模型调用直接用模型 SDK 更省事、Node.js/前端栈项目、对延迟极端敏感的实时链路这类更适合它的 Realtime 方案但复杂度更高。从 0 到 1 跑通如何安装并运行第一个多智能体示例最低要求是Python 3.10 及以上注意不是 3.9低版本装依赖会失败。准备环境并安装也支持用uv add openai-agents代替最后一条python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install openai-agents # 可选组按需安装 pip install openai-agents[voice] # 语音流水线 pip install openai-agents[redis] # Redis 会话在运行前导出模型服务的密钥例如OPENAI_API_KEY。最简示例——一个智能体、一次同步运行约 8 行代码即可看到最终输出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)预期输出是模型生成的一首短诗文本。Runner.run_sync是同步入口如果想在异步程序里跑改用await Runner.run(...)。跑通之后建议浏览 examples/ 目录里面有基础、MCP、记忆、语音、沙箱等分类示例按目录名找对应场景即可。核心能力怎么用让多个智能体分工交接与智能体当工具交接的本质是框架自动把转给某个智能体注册成一个工具模型自己决定何时触发。给分诊智能体传handoffs[...]列表它就能在对话中把控制权移交给西班牙语、英语等专席import asyncio from agents import Agent, Runner spanish Agent(nameSpanish, instructionsYou only speak Spanish.) english Agent(nameEnglish, instructionsYou only speak English.) triage Agent(nameTriage, instructionsHand off by request language., handoffs[spanish, english]) async def main(): print((await Runner.run(triage, Hola!)).final_output) asyncio.run(main())运行结果是一段西班牙语回复说明控制权已经落到西班牙语智能体身上。除交接外框架还支持智能体作为工具Agent.as_tool不把对话交给对方而是像调函数一样调用另一个智能体并拿到它的结构化结果适合主管派活、下属回报的编排。两者怎么选可以看 docs/handoffs.md。让智能体动手函数工具与 MCP 工具把普通 Python 函数用function_tool装饰一下就能被模型按参数调用例如天气查询函数模型返回调用意图后框架负责执行函数并把结果回填给模型继续回答。除了本地函数还可以挂载 MCP模型上下文协议服务器上的工具集——MCP 可以理解成给智能体用的标准工具接口仓库里 examples/mcp/ 下有文件系统、Git 等现成演示。给行为上保险护栏与人工确认护栏Guardrails是在智能体输入/输出两侧挂的检查器发现越界内容可以中止运行或改写结果人在环机制则支持在工具调用前暂停等人工批准再继续适合发邮件、退款这类不可逆操作。参考 examples/agent_patterns/ 里的human_in_the_loop.py、output_guardrails.py。记住上下文会话管理会话解决的问题是上一轮说了什么不用你手动传。使用方式很简单创建一个会话对象如SQLiteSession(conversation_123)本地 SQLite 文件即数据库之后每次运行都传入session会话实例参数框架会自动把历史消息带进下一次调用。第二轮问它在哪个州这类指代问题时智能体仍能理解你在说金门大桥。除 SQLite 外还支持 SQLAlchemy、Redis、MongoDB 等后端详见 docs/sessions.md 与 examples/memory/。看懂每一步内置追踪每次运行默认生成一条追踪记录哪个智能体说了什么、调了哪个工具、每段耗时多少在界面上是一棵可展开的树点开某节点还能看到对应的模型请求与响应属性。上图就是一个分诊 → 审批 → 汇总链路的追踪视图交接节点Handoff和工具调用fetch_data、send_email都能单独定位耗时。追踪设计为可扩展的也可以对接外部目的地细节见 docs/tracing.md。典型工作流场景输入框架处理输出客服分诊用户自然语言提问分诊智能体判断业务类型触发交接专席智能体调用查询工具并回答由最合适的专席给出的最终答复全程可追踪多轮记忆助手第二轮的指代性提问它在哪个州Runner 自动从会话中取出上一轮历史连同新消息发给模型基于完整上下文的答案无需手动维护消息数组工具增强问答东京今天天气如何模型生成函数调用参数 → 框架执行get_weather→ 结果回填模型模型把工具返回值组织成自然语言回答以客服分诊为例完整代码见 examples/customer_service/main.py用户消息先进入分诊智能体分诊智能体不直接回答而是选择一个交接工具被选中的专席接着处理必要时再交棒给汇总智能体。整个过程你只需要声明谁可以交接给谁循环、消息传递、历史拼接都由 Runner 完成。进阶与扩展沙箱、语音与部署沙箱智能体SandboxAgent当任务需要读写文件、跑命令、打补丁并保持工作区状态时可以启用预置沙箱的智能体。它在隔离环境中运行网络访问可经过网关拦截适合长时程的任务型工作。macOS/Linux 可用UnixLocalSandboxClient在本机跑Windows 建议搭配 Docker 客户端需openai-agents[docker]组介绍见 docs/sandbox_agents.md 和 examples/sandbox/。实时与语音RealtimeAgent通过 WebSocket 提供低延迟的语音/多模态交互VoicePipeline则把语音转文字 → 智能体工作流 → 文字转语音串成一条流水线需要openai-agents[voice]组示例在 examples/voice/。跨厂商模型默认接 OpenAI但框架是供应商无关的——装上litellm或any-llm可选组后可把智能体的模型指向其他厂商适合做对比实验或规避单一供应商。持久化与部署会话后端可换成 Redis/SQLAlchemy 支撑分布式部署需要长时程、可恢复的工作流时仓库提供了 Temporal 等可选集成可结合人在环机制做审批式任务。常见坑与排查一运行就报鉴权错误框架本身不替你管理密钥运行前必须导出OPENAI_API_KEY或对应提供商的密钥环境变量否则第一次调用模型即失败。Python 版本不够包要求 3.10在 3.9 环境安装会报依赖解析错误升级解释器或另建虚拟环境即可。同步/异步混用结果是空的Runner.run返回协程同步脚本里要写Runner.run_sync或把逻辑包进asyncio.run忘了await会得到coroutine was never awaited警告和空结果。会话失忆历史只在同一个会话实例 每次运行都传session参数时才会累积。忘传参数、或每轮新建不同 id 的会话都会让第二轮看起来像第一轮。换了模型后行为变样默认行为按 OpenAI 接口调优切换其他提供商后结构化输出、工具参数等细节可能有差异建议先跑仓库里的对应测试用例再上业务。选型与使用建议适合使用技术栈是 Python且任务天然可拆成多个角色分诊/专席、检索/写作、执行/审核需要工具调用 人工确认 运行追踪这类工程化能力而不是裸调模型需要跨轮记忆或未来可能切换模型供应商希望现在就把模型层和编排层解耦。谨慎使用单次问答、单次函数调用这类简单场景直接调模型 SDK 更轻前端/Node 项目此仓库是 Python 实现前端团队应评估官方对应的 JS/TS 版本对链路延迟和实时性有硬指标的场景Realtime 方案可行但复杂度明显更高先做小规模验证。可替代思路只需 function calling 时用模型自带 SDK 自己维护循环即可如果核心诉求是可恢复的长时程工作流而非智能体编排本身可优先考虑工作流引擎类方案再按需引入本框架做智能体层。下一步建议按这个顺序动手先跑通上文的最简示例再用 examples/customer_service/main.py 体验一次真实的多智能体交接最后打开 docs/quickstart.md 对照文档补齐会话与护栏配置。核心源码集中在 src/agents/想深入 Runner 循环或交接实现时可以直接从run.py、handoffs/目录读起。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenAI Agents SDK Python：轻量级多智能体工作流框架选型与上手指南
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 Python包名openai-agents是一个轻量级的多智能体工作流框架用几十行 Python 代码就能把多个智能体、工具调用、会话记忆和运行追踪组合成可调试的 Agent 应用。它支持 OpenAI 的 Responses 与 Chat Completions 接口也可接入其他厂商的 100 多个大模型适合需要用 Python 构建客服机器人、工具型助手或多智能体协作系统的开发者。它解决什么问题直接用大模型 API 做应用很快会遇到几件重复且麻烦的事多轮对话历史要自己拼每次请求前手动维护消息数组换模型、换接口就要重写一遍。多个角色要自己调度想让分诊角色把退款问题转给退款角色得自己解析跳转逻辑、拼接上下文、控制循环。模型调用工具的流程要手写解析函数调用参数、执行、把结果回填给模型、再等下一轮回复这套循环每个项目都要重写一次。出了错很难回溯一次运行里模型说了什么、调了哪个工具、耗时多少日志里一片混乱。这个框架把上面这些胶水代码收进一个 Runner 循环里你声明好智能体和它们的协作关系框架负责循环调用模型、执行工具、传递控制权并提供内置追踪面板帮你复盘每一步。30 秒认识项目一句话定位Python 生态里偏轻量的多智能体编排框架核心抽象是智能体 工具 交接 会话 追踪。关键能力智能体Agent配了指令、工具和交接的大模型封装是工作流的基本单元交接Handoff把一个智能体的控制权整体移交给另一个天然支持总机转专席式分工工具Tools把 Python 函数、MCP 服务器、托管工具统一成智能体可调用的动作会话Sessions自动管理跨运行的对话历史追踪Tracing内置的运行记录可查每一步的输入输出与耗时护栏与人在环Guardrails / HITL对输入输出做校验关键操作可暂停等人工确认。适用场景多角色客服/售后系统、需要调工具的任务型助手、需要持久记忆的多轮应用、需要审计与调试的智能体流程。不适用场景一次性的单轮模型调用直接用模型 SDK 更省事、Node.js/前端栈项目、对延迟极端敏感的实时链路这类更适合它的 Realtime 方案但复杂度更高。从 0 到 1 跑通如何安装并运行第一个多智能体示例最低要求是Python 3.10 及以上注意不是 3.9低版本装依赖会失败。准备环境并安装也支持用uv add openai-agents代替最后一条python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install openai-agents # 可选组按需安装 pip install openai-agents[voice] # 语音流水线 pip install openai-agents[redis] # Redis 会话在运行前导出模型服务的密钥例如OPENAI_API_KEY。最简示例——一个智能体、一次同步运行约 8 行代码即可看到最终输出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)预期输出是模型生成的一首短诗文本。Runner.run_sync是同步入口如果想在异步程序里跑改用await Runner.run(...)。跑通之后建议浏览 examples/ 目录里面有基础、MCP、记忆、语音、沙箱等分类示例按目录名找对应场景即可。核心能力怎么用让多个智能体分工交接与智能体当工具交接的本质是框架自动把转给某个智能体注册成一个工具模型自己决定何时触发。给分诊智能体传handoffs[...]列表它就能在对话中把控制权移交给西班牙语、英语等专席import asyncio from agents import Agent, Runner spanish Agent(nameSpanish, instructionsYou only speak Spanish.) english Agent(nameEnglish, instructionsYou only speak English.) triage Agent(nameTriage, instructionsHand off by request language., handoffs[spanish, english]) async def main(): print((await Runner.run(triage, Hola!)).final_output) asyncio.run(main())运行结果是一段西班牙语回复说明控制权已经落到西班牙语智能体身上。除交接外框架还支持智能体作为工具Agent.as_tool不把对话交给对方而是像调函数一样调用另一个智能体并拿到它的结构化结果适合主管派活、下属回报的编排。两者怎么选可以看 docs/handoffs.md。让智能体动手函数工具与 MCP 工具把普通 Python 函数用function_tool装饰一下就能被模型按参数调用例如天气查询函数模型返回调用意图后框架负责执行函数并把结果回填给模型继续回答。除了本地函数还可以挂载 MCP模型上下文协议服务器上的工具集——MCP 可以理解成给智能体用的标准工具接口仓库里 examples/mcp/ 下有文件系统、Git 等现成演示。给行为上保险护栏与人工确认护栏Guardrails是在智能体输入/输出两侧挂的检查器发现越界内容可以中止运行或改写结果人在环机制则支持在工具调用前暂停等人工批准再继续适合发邮件、退款这类不可逆操作。参考 examples/agent_patterns/ 里的human_in_the_loop.py、output_guardrails.py。记住上下文会话管理会话解决的问题是上一轮说了什么不用你手动传。使用方式很简单创建一个会话对象如SQLiteSession(conversation_123)本地 SQLite 文件即数据库之后每次运行都传入session会话实例参数框架会自动把历史消息带进下一次调用。第二轮问它在哪个州这类指代问题时智能体仍能理解你在说金门大桥。除 SQLite 外还支持 SQLAlchemy、Redis、MongoDB 等后端详见 docs/sessions.md 与 examples/memory/。看懂每一步内置追踪每次运行默认生成一条追踪记录哪个智能体说了什么、调了哪个工具、每段耗时多少在界面上是一棵可展开的树点开某节点还能看到对应的模型请求与响应属性。上图就是一个分诊 → 审批 → 汇总链路的追踪视图交接节点Handoff和工具调用fetch_data、send_email都能单独定位耗时。追踪设计为可扩展的也可以对接外部目的地细节见 docs/tracing.md。典型工作流场景输入框架处理输出客服分诊用户自然语言提问分诊智能体判断业务类型触发交接专席智能体调用查询工具并回答由最合适的专席给出的最终答复全程可追踪多轮记忆助手第二轮的指代性提问它在哪个州Runner 自动从会话中取出上一轮历史连同新消息发给模型基于完整上下文的答案无需手动维护消息数组工具增强问答东京今天天气如何模型生成函数调用参数 → 框架执行get_weather→ 结果回填模型模型把工具返回值组织成自然语言回答以客服分诊为例完整代码见 examples/customer_service/main.py用户消息先进入分诊智能体分诊智能体不直接回答而是选择一个交接工具被选中的专席接着处理必要时再交棒给汇总智能体。整个过程你只需要声明谁可以交接给谁循环、消息传递、历史拼接都由 Runner 完成。进阶与扩展沙箱、语音与部署沙箱智能体SandboxAgent当任务需要读写文件、跑命令、打补丁并保持工作区状态时可以启用预置沙箱的智能体。它在隔离环境中运行网络访问可经过网关拦截适合长时程的任务型工作。macOS/Linux 可用UnixLocalSandboxClient在本机跑Windows 建议搭配 Docker 客户端需openai-agents[docker]组介绍见 docs/sandbox_agents.md 和 examples/sandbox/。实时与语音RealtimeAgent通过 WebSocket 提供低延迟的语音/多模态交互VoicePipeline则把语音转文字 → 智能体工作流 → 文字转语音串成一条流水线需要openai-agents[voice]组示例在 examples/voice/。跨厂商模型默认接 OpenAI但框架是供应商无关的——装上litellm或any-llm可选组后可把智能体的模型指向其他厂商适合做对比实验或规避单一供应商。持久化与部署会话后端可换成 Redis/SQLAlchemy 支撑分布式部署需要长时程、可恢复的工作流时仓库提供了 Temporal 等可选集成可结合人在环机制做审批式任务。常见坑与排查一运行就报鉴权错误框架本身不替你管理密钥运行前必须导出OPENAI_API_KEY或对应提供商的密钥环境变量否则第一次调用模型即失败。Python 版本不够包要求 3.10在 3.9 环境安装会报依赖解析错误升级解释器或另建虚拟环境即可。同步/异步混用结果是空的Runner.run返回协程同步脚本里要写Runner.run_sync或把逻辑包进asyncio.run忘了await会得到coroutine was never awaited警告和空结果。会话失忆历史只在同一个会话实例 每次运行都传session参数时才会累积。忘传参数、或每轮新建不同 id 的会话都会让第二轮看起来像第一轮。换了模型后行为变样默认行为按 OpenAI 接口调优切换其他提供商后结构化输出、工具参数等细节可能有差异建议先跑仓库里的对应测试用例再上业务。选型与使用建议适合使用技术栈是 Python且任务天然可拆成多个角色分诊/专席、检索/写作、执行/审核需要工具调用 人工确认 运行追踪这类工程化能力而不是裸调模型需要跨轮记忆或未来可能切换模型供应商希望现在就把模型层和编排层解耦。谨慎使用单次问答、单次函数调用这类简单场景直接调模型 SDK 更轻前端/Node 项目此仓库是 Python 实现前端团队应评估官方对应的 JS/TS 版本对链路延迟和实时性有硬指标的场景Realtime 方案可行但复杂度明显更高先做小规模验证。可替代思路只需 function calling 时用模型自带 SDK 自己维护循环即可如果核心诉求是可恢复的长时程工作流而非智能体编排本身可优先考虑工作流引擎类方案再按需引入本框架做智能体层。下一步建议按这个顺序动手先跑通上文的最简示例再用 examples/customer_service/main.py 体验一次真实的多智能体交接最后打开 docs/quickstart.md 对照文档补齐会话与护栏配置。核心源码集中在 src/agents/想深入 Runner 循环或交接实现时可以直接从run.py、handoffs/目录读起。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考