openai-agents-python 智能体编排实战LLM 自主决策与代码确定性控制的双路径设计【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python本文基于 openai-agents-pythonPython Agents SDK官方的多智能体编排文档docs/ko/multi_agent.md韩语版英文源文档为 docs/multi_agent.md系统讲解 LLM 驱动与代码驱动两种编排范式的设计权衡、核心 SDK 模式Agents as tools 与 Handoffs的源码级实现以及结构化输出、流水线串联、评估循环、并行执行等代码编排模式的完整示例。读完后你将能够根据任务特性选择合适的编排策略并直接在仓库的 examples/agent_patterns 示例基础上落地多智能体工作流。两种编排范式让 LLM 决策还是用代码控制流编排Orchestration指的是应用中智能体的执行流程哪些智能体运行、以什么顺序运行、下一步如何决定。openai-agents-python 提供两种主要编排方式让 LLM 自主决策利用 LLM 的智能进行规划与推理由模型自己决定执行哪些步骤通过代码编排用你的代码显式决定智能体的流转逻辑。两者可以混合使用各自在灵活性、速度、成本与可预测性之间有不同的取舍。LLM 驱动的编排给足工具与交接点让模型自主规划智能体是配备了**指令instructions、工具tools与交接handoffs**的 LLM。这意味着面对开放性任务时LLM 可以自主规划解题路径——用工具执行操作、获取数据用 handoffs 把任务委派给子智能体。官方文档给出的典型例子是一个研究智能体它可以配备以下能力用网络搜索在线查找信息用文件搜索与检索查询专有数据和已连接的数据源用**计算机使用computer use**在计算机上执行操作用代码执行完成数据分析通过handoffs委派给擅长规划、报告撰写等细分方向的专家智能体。两大核心 SDK 模式Agents as tools 与 Handoffs在 Python SDK 中最常用的是以下两种编排模式模式工作机制适用场景Agents as tools管理者智能体保持对话控制权通过Agent.as_tool()调用专家智能体希望由一个智能体负责最终答案、需要结合多个专家的输出、或想在一处集中应用 SDK 护栏guardrails时Handoffs分诊triage智能体把对话路由给专家智能体该专家在此后的整个回合内成为活跃智能体希望专家智能体直接面向用户回复、保持提示词焦点集中、或通过 handoff 直接切换活跃指令而不需要管理者复述结果时选择原则agents as tools适用于专家智能体只处理有边界的子任务、但不应接管用户对话的场景handoffs适用于路由本身就是工作流的一部分且选中的专家要接管当前回合剩余部分的场景。两者也可以组合使用分诊智能体先 handoff 给某个专家智能体该专家智能体再在遇到更窄的子任务时把其他智能体当作工具来调用。从源码结构看Agent.as_tool()的文档字符串在 src/agents/agent.py 中明确区分了它与 handoff 的本质差异这也印证了上表的判断handoff 时新智能体接收完整对话历史而作为工具调用时新智能体接收的是由父智能体生成的输入handoff 时新智能体接管对话而作为工具调用时子智能体运行结束后对话由原始智能体继续。as_tool()还提供了若干精细控制参数见 src/agents/agent.pytool_name/tool_description定义工具身份is_enabled支持布尔值或回调用于在运行时动态决定该子智能体是否对 LLM 可见on_stream回调可以接收嵌套智能体运行的流式事件提供后子智能体将以流式模式执行failure_error_function决定子运行失败时是抛异常还是把错误信息回传给 LLM 让其自行调整needs_approval支持对子智能体调用挂起等待人工审批parameters/input_builder则允许用 dataclass 或 Pydantic 模型为嵌套调用定义结构化输入。这些机制使得管理者集中管控的模式在护栏、审批、错误恢复等方面都有落点。LLM 编排的五个关键战术当任务是开放式的、需要依赖 LLM 智能时这种编排方式非常有效。官方文档给出的最重要战术如下在高质量的提示词上投入明确说明有哪些工具可用、如何使用以及智能体必须遵守的约束监控应用并持续迭代找出出错的位置反复改进提示词让智能体能够自省与改进例如在循环中运行并让它自我批评或者把错误信息反馈给它让它自行修正构建擅长单一任务的专家智能体而不是指望一个什么都会的通用智能体投入评估evals通过系统化的评估来训练智能体、持续提升其任务完成能力。理解这些模式背后的核心 SDK 原语可以从 工具文档、Handoffs 文档 和 运行智能体文档 入手。代码驱动的编排更快、更省、更可预测LLM 驱动编排固然强大但通过代码编排可以在速度、成本与性能上让任务更加确定、可预测。官方文档列出了四类常见模式仓库中的 examples/agent_patterns 目录提供了对应的可运行示例该目录的 README 对每个模式都有摘要说明模式一结构化输出 确定性流程利用**结构化输出structured outputs**生成代码可检查的规范数据。例如让智能体把任务分类到几个类别中然后按类别选择下一个智能体。示例 examples/agent_patterns/deterministic.py 完整展示了这条流水线story_outline_agent根据用户输入生成故事大纲outline_checker_agent检查大纲质量并判断是否为科幻故事——它的输出类型是 Pydantic 模型保证代码可以可靠断言class OutlineCheckerOutput(BaseModel): good_quality: bool is_scifi: bool outline_checker_agent Agent( nameoutline_checker_agent, instructionsRead the given story outline, and judge the quality. Also, determine if it is a scifi story., output_typeOutlineCheckerOutput, )代码层面的门控如果质量不达标或不是科幻故事直接exit(0)终止流程通过门控后story_agent基于大纲写出完整故事。整个流程用with trace(Deterministic story flow)包裹使多步工作流在一个 trace 中可观测见 examples/agent_patterns/deterministic.py。模式二流水线串联——把输出转换为下一个输入将一个复杂任务如撰写博客文章拆解为一系列步骤研究、写大纲、写正文、批评、改进——每个步骤由一个智能体执行前一个智能体的输出作为后一个智能体的输入。上面 deterministic 示例中outline_result.final_output直接作为检查智能体输入的写法见 examples/agent_patterns/deterministic.py正是这一模式的最小实现。模式三while 循环 评估智能体LLM-as-a-judgewhile循环的每次迭代中先运行任务智能体产出输出再运行评估智能体对输出打分并给出反馈当评估智能体认为输出满足必备标准时停止。示例 examples/agent_patterns/llm_as_a_judge.py 展示了完整的评估循环生成器智能体负责写故事大纲并如有反馈则据此改进评估智能体的output_type是带枚举分级的 dataclassdataclass class EvaluationFeedback: feedback: str score: Literal[pass, needs_improvement, fail]循环逻辑score pass时 break否则把fFeedback: {result.feedback}作为新的 user 消息追加到输入再跑下一轮。评估智能体的指令中还特意写了第一次尝试绝不给 pass避免循环在第一轮就无谓终止README 补充了一个成本优化技巧初始生成可以用小模型评估反馈用大模型。模式四并行执行用asyncio.gather等 Python 原语并行运行多个互不依赖的智能体以降低延迟也可以生成多个候选结果再挑选最优。示例 examples/agent_patterns/parallelization.py 用三个并行的西语翻译运行 一个挑选最优结果的智能体演示res_1, res_2, res_3 await asyncio.gather( Runner.run(spanish_agent, msg), Runner.run(spanish_agent, msg), Runner.run(spanish_agent, msg), )Handoffs 路由示例examples/agent_patterns/routing.py 演示了 LLM 驱动一侧的典型路由一个分诊智能体接收首条消息按用户语言 handoff 到french_agent/spanish_agent/english_agenttriage_agent Agent( nametriage_agent, instructionsHandoff to the appropriate agent based on the language of the request., handoffs[french_agent, spanish_agent, english_agent], )多轮会话中代码通过result.current_agent获取本轮结束后的活跃智能体下一轮直接用它运行从而保持被 handoff 的专家继续服务的语义见 examples/agent_patterns/routing.py。Agents as tools 示例examples/agent_patterns/agents_as_tools.py 把路由场景改造为工具调用编排智能体通过as_tool()注册三个翻译工具自己决定按顺序调用哪些翻译结果返回给编排智能体——因此可以一次翻译成多种语言。示例中还有一个synthesizer_agent把orchestrator_result.to_input_list()作为输入做最终整合展示了管理者拥有最终答案的完整形态orchestrator_agent Agent( nameorchestrator_agent, instructions( You are a translation agent. You use the tools given to you to translate. If asked for multiple translations, you call the relevant tools in order. You never translate on your own, you always use the provided tools. ), tools[ spanish_agent.as_tool(tool_nametranslate_to_spanish, tool_descriptionTranslate the users message to Spanish), french_agent.as_tool(tool_nametranslate_to_french, tool_descriptionTranslate the users message to French), italian_agent.as_tool(tool_nametranslate_to_italian, tool_descriptionTranslate the users message to Italian), ], )该目录还提供了流式变体 agents_as_tools_streaming.py通过on_stream接入嵌套智能体事件与结构化输入变体 agents_as_tools_structured.py使用as_tool()的parameters参数。此外 hosted_multi_agent_beta.py 演示了实验性的托管式多智能体模式由 Responses API 在服务端协调 GPT 子智能体而 SDK Runner 在本地执行开发者定义的工具。相关文档组合模式与智能体配置参见 智能体文档Agent.as_tool()与管理者风格编排参见 工具文档 中的 Agents as tools 一节专家智能体之间的委派参见 Handoffs 文档每次运行的编排控制与会话状态参见 运行智能体文档最小端到端 handoff 示例参见 快速入门。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考