企业官网建设流程全解析

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-python（Python 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 提供两种主要编排方式：

1. 让 LLM 自主决策：利用 LLM 的智能进行规划与推理，由模型自己决定执行哪些步骤；
2. 通过代码编排：用你的代码显式决定智能体的流转逻辑。

两者可以混合使用，各自在灵活性、速度、成本与可预测性之间有不同的取舍。

LLM 驱动的编排：给足工具与交接点，让模型自主规划

智能体是配备了**指令（instructions）、工具（tools）与交接（handoffs）**的 LLM。这意味着面对开放性任务时，LLM 可以自主规划解题路径——用工具执行操作、获取数据，用 handoffs 把任务委派给子智能体。官方文档给出的典型例子是一个"研究智能体"，它可以配备以下能力：

• 用网络搜索在线查找信息；
• 用文件搜索与检索查询专有数据和已连接的数据源；
• 用**计算机使用（computer use）**在计算机上执行操作；
• 用代码执行完成数据分析；
• 通过handoffs委派给擅长规划、报告撰写等细分方向的专家智能体。

两大核心 SDK 模式：Agents as tools 与 Handoffs

在 Python SDK 中，最常用的是以下两种编排模式：

选择原则：agents as tools适用于"专家智能体只处理有边界的子任务、但不应接管用户对话"的场景；handoffs适用于"路由本身就是工作流的一部分，且选中的专家要接管当前回合剩余部分"的场景。

两者也可以组合使用：分诊智能体先 handoff 给某个专家智能体，该专家智能体再在遇到更窄的子任务时，把其他智能体当作工具来调用。

从源码结构看，Agent.as_tool()的文档字符串在 src/agents/agent.py 中明确区分了它与 handoff 的本质差异，这也印证了上表的判断：

1. handoff 时，新智能体接收完整对话历史；而作为工具调用时，新智能体接收的是由父智能体生成的输入；
2. handoff 时，新智能体接管对话；而作为工具调用时，子智能体运行结束后，对话由原始智能体继续。

as_tool()还提供了若干精细控制参数（见 src/agents/agent.py）：tool_name/tool_description定义工具身份；is_enabled支持布尔值或回调，用于在运行时动态决定该子智能体是否对 LLM 可见；on_stream回调可以接收嵌套智能体运行的流式事件（提供后子智能体将以流式模式执行）；failure_error_function决定子运行失败时是抛异常还是把错误信息回传给 LLM 让其自行调整；needs_approval支持对子智能体调用挂起等待人工审批；parameters/input_builder则允许用 dataclass 或 Pydantic 模型为嵌套调用定义结构化输入。这些机制使得"管理者集中管控"的模式在护栏、审批、错误恢复等方面都有落点。

LLM 编排的五个关键战术

当任务是开放式的、需要依赖 LLM 智能时，这种编排方式非常有效。官方文档给出的最重要战术如下：

1. 在高质量的提示词上投入：明确说明有哪些工具可用、如何使用，以及智能体必须遵守的约束；
2. 监控应用并持续迭代：找出出错的位置，反复改进提示词；
3. 让智能体能够自省与改进：例如在循环中运行并让它自我批评，或者把错误信息反馈给它让它自行修正；
4. 构建擅长单一任务的专家智能体，而不是指望一个"什么都会"的通用智能体；
5. 投入评估（evals）：通过系统化的评估来训练智能体、持续提升其任务完成能力。

理解这些模式背后的核心 SDK 原语，可以从 工具文档、Handoffs 文档 和 运行智能体文档 入手。

代码驱动的编排：更快、更省、更可预测

LLM 驱动编排固然强大，但通过代码编排可以在速度、成本与性能上让任务更加确定、可预测。官方文档列出了四类常见模式，仓库中的 examples/agent_patterns 目录提供了对应的可运行示例（该目录的 README 对每个模式都有摘要说明）：

模式一：结构化输出 + 确定性流程

利用**结构化输出（structured outputs）**生成代码可检查的规范数据。例如让智能体把任务分类到几个类别中，然后按类别选择下一个智能体。

示例 examples/agent_patterns/deterministic.py 完整展示了这条流水线：

1. story_outline_agent根据用户输入生成故事大纲；
2. outline_checker_agent检查大纲质量并判断是否为科幻故事——它的输出类型是 Pydantic 模型，保证代码可以可靠断言：

class OutlineCheckerOutput(BaseModel): good_quality: bool is_scifi: bool outline_checker_agent = Agent( name="outline_checker_agent", instructions="Read the given story outline, and judge the quality. Also, determine if it is a scifi story.", output_type=OutlineCheckerOutput, )

3. 代码层面的"门控"：如果质量不达标或不是科幻故事，直接exit(0)终止流程；
4. 通过门控后，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-judge）

while循环的每次迭代中：先运行任务智能体产出输出，再运行评估智能体对输出打分并给出反馈；当评估智能体认为输出满足必备标准时停止。

示例 examples/agent_patterns/llm_as_a_judge.py 展示了完整的评估循环：

• 生成器智能体负责写故事大纲，并"如有反馈则据此改进"；
• 评估智能体的output_type是带枚举分级的 dataclass：

@dataclass class EvaluationFeedback: feedback: str score: Literal["pass", "needs_improvement", "fail"]

• 循环逻辑：score == "pass"时 break；否则把f"Feedback: {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_agent：

triage_agent = Agent( name="triage_agent", instructions="Handoff 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( name="orchestrator_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_name="translate_to_spanish", tool_description="Translate the user's message to Spanish"), french_agent.as_tool(tool_name="translate_to_french", tool_description="Translate the user's message to French"), italian_agent.as_tool(tool_name="translate_to_italian", tool_description="Translate the user's 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