OpenAI Agents SDK 实战手册快速搭建轻量多智能体工作流的完整指南【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-pythonOpenAI Agents SDK 是官方出品的轻量多智能体框架一个 pip 包就能跑通从单智能体到多智能体协作的完整链路帮你省掉手写 LLM 循环、会话历史和工具调度的重复劳动。 项目定位与选型理由这是一个面向 Python 开发者的 Agent 编排框架核心就是Agent加Runner你声明智能体的指令、工具和协作关系它负责执行循环、历史管理和追踪。它不绑定供应商OpenAI 模型之外还支持 100 多个其他 LLM。对比维度OpenAI Agents SDK直接手写 LLM 调用循环易用性Agent/Runner 声明式定义几十行起步需自维护循环、重试、工具解析扩展性内置 handoffs、护栏、会话、沙箱每加一个能力都要自己造轮子生态成熟度官方维护示例与文档齐全可接 Logfire 等外部追踪无它不做重型工作流引擎没有 DAG 可视化编排那套包袱适合想要快、清晰、可控的团队。⚡ 五分钟上手要求 Python 3.10安装命令就两条pip install openai-agents最小可运行示例先设置好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把它跑起来并拿到RunResultfinal_output就是最终文本。整个执行循环——调模型、处理工具调用、决定是否交接——都由 Runner 内部管理你不需要自己写任何 while 循环。语音、Redis 会话等能力通过可选依赖组安装如pip install openai-agents[voice]按需添加即可。 核心概念拆解白话理解多智能体框架多智能体工作流架构示意Triage Agent 根据请求路由到不同语言专家智能体并可挂载工具与 MCP 服务Agent智能体一个配了指令、工具和协作规则的 LLM。好比一家餐厅里职责明确的厨师——只负责自己擅长的那道菜。你关心它因为它是所有编排的最小单元一切流程都由它组合而成。Handoff交接智能体之间转移控制权的机制对模型表现为一个名为transfer_to_xxx的工具。好比前台把客人引导给对应柜台的专员工客人对话无缝换人接。你关心它因为这是分诊 专家这类多智能体模式的地基。Tool工具让智能体产生实际动作的函数可以是本地 Python 函数、MCP 服务或托管工具。好比厨师手里的锅铲和调料台。你关心它因为模型只会说话工具让它能查数据、调接口、改文件。Session会话跨多次运行自动管理对话历史省去手动拼接.to_input_list()。好比服务员的记事本客人下次坐下不用重新自我介绍。你关心它因为多轮对话的状态管理是多智能体框架里最容易出 bug 的地方。 一个真实场景 walkthrough多语言客服自动分派设定场景客服入口收到用户消息系统先判断语言再交给对应语言的专家智能体回复全程留痕可查。流程按时间线走用户输入Hola, ¿cómo estás? 进入分诊智能体路由/交接分诊智能体的 LLM 判断这是西班牙语发出transfer_to_spanish_agent工具调用Runner 检测到交接后把当前智能体切换为西语智能体回到执行循环工具调用本例省略实际可挂在西语智能体上查订单等工具结构化输出result.final_output得到回复result.last_agent告诉你最终是谁答的方便审计和落库。核心代码只有这些与 examples/agent_patterns/routing.py 同款模式from agents import Agent, Runner spanish_agent Agent(namespanish_agent, instructionsYou only speak Spanish.) english_agent Agent(nameenglish_agent, instructionsYou only speak English.) triage_agent Agent( nameTriage agent, instructionsHand off based on the language of the request., handoffs[spanish_agent, english_agent], ) result Runner.run_sync(triage_agent, Hola, como estas?) print(result.final_output, result.last_agent.name)逐行白话解读前两个Agent是专家instructions限定其只说一种语言行为边界清晰第三个triage_agent是前台handoffs参数就是它的可转接名单SDK 会自动为每个目标生成transfer_to_*工具Runner.run_sync一次调用内部完成了分诊 → 交接 → 专家回复整个循环last_agent.name打印出来即可确认这次回复由哪个智能体负责天然适合做客服质检。 进阶能力速览能力一句话说明典型适用场景参考护栏 Guardrails对输入/输出做并行安全检查不通过可拦截客服内容合规、防提示注入护栏文档会话管理 SessionsSQLite/Redis/SQLAlchemy 等多种后端持久化对话多轮客服、跨实例恢复上下文会话文档追踪 Tracing自动记录 LLM 生成、工具调用、交接全过程线上问题定位、成本分析追踪文档沙箱智能体在隔离工作区里读写文件、执行命令代码修复、数据分析类长任务沙箱智能体文档人在环 HITL暂停运行等待人工审批工具调用敏感操作二次确认HITL 文档 踩坑与调优建议分诊智能体频繁选错专家→ 先给每个专家写handoff_description把何时该转给它写清楚这比改分诊 prompt 更有效。输出格式不稳定下游解析报错→ 别靠 prompt 口头约定用output_type指定 Pydantic 模型做结构化输出让 SDK 帮你校验。线上出 bug 却说不清模型在想什么→ 追踪默认开启先去看 Trace 面板确认是哪一步交接工具生成出的问题再用trace()给自定义代码段补 span而不是盲目加日志。工具调用死循环或反复触发同一工具→ 检查工具描述是否过于模糊导致模型误判调用时机必要时用tool_use_behavior控制工具结果回传方式。多轮对话历史越拼越长、成本飙升→ 用 Session 让 SDK 管理历史并设置轮次上限不要无脑全量回放。 生态与部署路径本地开发直接从 examples/basic/hello_world.py 这类脚本起步仓库自带 Makefile 和完整测试克隆仓库即可对照调试。分布式与会话存储Redis、SQLAlchemy 等会话后端通过可选依赖启用多实例部署时对话状态不再依赖单机内存见 会话文档 与 内存模块源码。沙箱与长任务SandboxAgent支持 Docker、Unix 本地等多种客户端适合需要文件系统状态的编码型任务入口在 沙箱智能体文档。定位一句话轻量、可解释、以 Python 原生写法做智能体编排的官方 SDK。下一步克隆仓库把examples/目录下的 routing 和 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 实战手册：快速搭建轻量多智能体工作流的完整指南
OpenAI Agents SDK 实战手册快速搭建轻量多智能体工作流的完整指南【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-pythonOpenAI Agents SDK 是官方出品的轻量多智能体框架一个 pip 包就能跑通从单智能体到多智能体协作的完整链路帮你省掉手写 LLM 循环、会话历史和工具调度的重复劳动。 项目定位与选型理由这是一个面向 Python 开发者的 Agent 编排框架核心就是Agent加Runner你声明智能体的指令、工具和协作关系它负责执行循环、历史管理和追踪。它不绑定供应商OpenAI 模型之外还支持 100 多个其他 LLM。对比维度OpenAI Agents SDK直接手写 LLM 调用循环易用性Agent/Runner 声明式定义几十行起步需自维护循环、重试、工具解析扩展性内置 handoffs、护栏、会话、沙箱每加一个能力都要自己造轮子生态成熟度官方维护示例与文档齐全可接 Logfire 等外部追踪无它不做重型工作流引擎没有 DAG 可视化编排那套包袱适合想要快、清晰、可控的团队。⚡ 五分钟上手要求 Python 3.10安装命令就两条pip install openai-agents最小可运行示例先设置好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把它跑起来并拿到RunResultfinal_output就是最终文本。整个执行循环——调模型、处理工具调用、决定是否交接——都由 Runner 内部管理你不需要自己写任何 while 循环。语音、Redis 会话等能力通过可选依赖组安装如pip install openai-agents[voice]按需添加即可。 核心概念拆解白话理解多智能体框架多智能体工作流架构示意Triage Agent 根据请求路由到不同语言专家智能体并可挂载工具与 MCP 服务Agent智能体一个配了指令、工具和协作规则的 LLM。好比一家餐厅里职责明确的厨师——只负责自己擅长的那道菜。你关心它因为它是所有编排的最小单元一切流程都由它组合而成。Handoff交接智能体之间转移控制权的机制对模型表现为一个名为transfer_to_xxx的工具。好比前台把客人引导给对应柜台的专员工客人对话无缝换人接。你关心它因为这是分诊 专家这类多智能体模式的地基。Tool工具让智能体产生实际动作的函数可以是本地 Python 函数、MCP 服务或托管工具。好比厨师手里的锅铲和调料台。你关心它因为模型只会说话工具让它能查数据、调接口、改文件。Session会话跨多次运行自动管理对话历史省去手动拼接.to_input_list()。好比服务员的记事本客人下次坐下不用重新自我介绍。你关心它因为多轮对话的状态管理是多智能体框架里最容易出 bug 的地方。 一个真实场景 walkthrough多语言客服自动分派设定场景客服入口收到用户消息系统先判断语言再交给对应语言的专家智能体回复全程留痕可查。流程按时间线走用户输入Hola, ¿cómo estás? 进入分诊智能体路由/交接分诊智能体的 LLM 判断这是西班牙语发出transfer_to_spanish_agent工具调用Runner 检测到交接后把当前智能体切换为西语智能体回到执行循环工具调用本例省略实际可挂在西语智能体上查订单等工具结构化输出result.final_output得到回复result.last_agent告诉你最终是谁答的方便审计和落库。核心代码只有这些与 examples/agent_patterns/routing.py 同款模式from agents import Agent, Runner spanish_agent Agent(namespanish_agent, instructionsYou only speak Spanish.) english_agent Agent(nameenglish_agent, instructionsYou only speak English.) triage_agent Agent( nameTriage agent, instructionsHand off based on the language of the request., handoffs[spanish_agent, english_agent], ) result Runner.run_sync(triage_agent, Hola, como estas?) print(result.final_output, result.last_agent.name)逐行白话解读前两个Agent是专家instructions限定其只说一种语言行为边界清晰第三个triage_agent是前台handoffs参数就是它的可转接名单SDK 会自动为每个目标生成transfer_to_*工具Runner.run_sync一次调用内部完成了分诊 → 交接 → 专家回复整个循环last_agent.name打印出来即可确认这次回复由哪个智能体负责天然适合做客服质检。 进阶能力速览能力一句话说明典型适用场景参考护栏 Guardrails对输入/输出做并行安全检查不通过可拦截客服内容合规、防提示注入护栏文档会话管理 SessionsSQLite/Redis/SQLAlchemy 等多种后端持久化对话多轮客服、跨实例恢复上下文会话文档追踪 Tracing自动记录 LLM 生成、工具调用、交接全过程线上问题定位、成本分析追踪文档沙箱智能体在隔离工作区里读写文件、执行命令代码修复、数据分析类长任务沙箱智能体文档人在环 HITL暂停运行等待人工审批工具调用敏感操作二次确认HITL 文档 踩坑与调优建议分诊智能体频繁选错专家→ 先给每个专家写handoff_description把何时该转给它写清楚这比改分诊 prompt 更有效。输出格式不稳定下游解析报错→ 别靠 prompt 口头约定用output_type指定 Pydantic 模型做结构化输出让 SDK 帮你校验。线上出 bug 却说不清模型在想什么→ 追踪默认开启先去看 Trace 面板确认是哪一步交接工具生成出的问题再用trace()给自定义代码段补 span而不是盲目加日志。工具调用死循环或反复触发同一工具→ 检查工具描述是否过于模糊导致模型误判调用时机必要时用tool_use_behavior控制工具结果回传方式。多轮对话历史越拼越长、成本飙升→ 用 Session 让 SDK 管理历史并设置轮次上限不要无脑全量回放。 生态与部署路径本地开发直接从 examples/basic/hello_world.py 这类脚本起步仓库自带 Makefile 和完整测试克隆仓库即可对照调试。分布式与会话存储Redis、SQLAlchemy 等会话后端通过可选依赖启用多实例部署时对话状态不再依赖单机内存见 会话文档 与 内存模块源码。沙箱与长任务SandboxAgent支持 Docker、Unix 本地等多种客户端适合需要文件系统状态的编码型任务入口在 沙箱智能体文档。定位一句话轻量、可解释、以 Python 原生写法做智能体编排的官方 SDK。下一步克隆仓库把examples/目录下的 routing 和 handoffs 示例跑一遍多智能体框架的骨架就通了。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考