OpenAI Agents SDK 入门指南用轻量级 Python 框架构建多智能体应用【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python本指南基于 OpenAI Agents SDK 官方文档日语版索引页与仓库源码系统梳理该框架的核心组件、设计原则、主要功能特性、与 Responses API 的选型对比并给出可立即运行的安装与 Hello world 示例以及一套按目标检索文档的学习路径。读完本文你将掌握 SDK 的三大基础组件Agent、Agents as tools / Handoffs、Guardrails如何协作知道何时该用 SDK、何时直接调用 Responses API并能据此规划下一步的深入学习路线。什么是 OpenAI Agents SDKOpenAI Agents SDK 是一个抽象极少的轻量级、易用型 Python 包用于构建智能体Agent型 AI 应用。它是 OpenAI 此前智能体实验项目 Swarm 的生产环境升级版核心设计目标是让开发者以最低的学习成本表达工具与智能体之间的复杂关系。从仓库的 顶层导出模块 可以看到整个 SDK 的能力都收敛在极少数核心类型上。官方文档将其归纳为三大基础组件primitives智能体Agent配备了指令instructions和工具tools的 LLMAgents as tools / 任务转移Handoffs允许智能体将特定任务委派给其他智能体的机制安全防护措施Guardrails用于校验智能体输入与输出的机制。将这三大组件与 Python 语言本身组合即可表达工具与智能体之间足够复杂的关系构建真实应用而无需陡峭的学习曲线。此外SDK 内置**追踪tracing**能力可用于可视化、调试智能体流程、进行评估甚至针对应用微调模型。从源码结构看这些组件在 src/agents/agent.pyAgent类支持tools、handoffs、input_guardrails、output_guardrails、instructions等构造参数、src/agents/handoffsHandoff机制与 src/agents/guardrail.pyInputGuardrail/OutputGuardrail及input_guardrail/output_guardrail装饰器中均有对应实现三者在 src/agents/run.py 的Runner中被统一编排执行。为什么选择 Agents SDKSDK 的设计由两条原则驱动功能足够多、值得使用同时基础组件足够少、易于快速上手开箱即用表现良好又允许你对真实执行细节进行精确自定义。主要功能特性特性说明智能体Agents使用指令、工具、安全防护措施、任务转移以及持续运行直至任务完成的内置循环构建智能体沙箱智能体Sandbox agents在真正隔离的工作区中运行专项智能体支持由清单manifest定义的文件、沙箱客户端选择与可恢复的沙箱会话实时智能体Realtime agents使用gpt-realtime-2.1、自动中断检测、上下文管理、安全防护措施等构建强大的语音智能体语音智能体Voice agents构建语音转文本 智能体工作流 文本转语音组合的语音管线Python 优先Python-first使用内置语言特性编排与串联智能体无需学习新的抽象概念Agents as tools / 任务转移在多个智能体之间协调与委派工作的强大机制安全防护措施Guardrails在智能体执行的同时并行运行输入校验与安全检查校验不通过时快速失败函数工具Function tools通过自动生成 schema 与 Pydantic 校验将任意 Python 函数转换为工具MCP 服务器工具调用内置集成可将远程 MCP 工具与函数工具一起暴露给智能体会话Sessions在智能体循环中维护工作上下文的持久化记忆层人在回路Human in the loop在智能体运行期间引入人工参与的内置机制追踪Tracing内置的可视化、调试、监控工作流能力并支持 OpenAI 的评估、微调与蒸馏工具套件上述特性在仓库中均有落地实现例如函数工具由 src/agents/tool.py 中的function_tool装饰器与 src/agents/function_schema.py 的 schema 自动生成逻辑支撑MCP 集成位于 src/agents/mcp会话Session抽象位于 src/agents/memory含 SQLite、OpenAI Conversations 等实现追踪系统位于 src/agents/tracing支持trace、agent_span、generation_span等 API并默认通过 BatchTraceProcessor 将 span 批量导出。Agents SDK 还是 Responses APISDK 对 OpenAI 模型默认使用 Responses API但将模型调用包装在更高层级的运行时中。二者的选择取决于你想把控制权交给谁适合直接使用 Responses API 的场景希望自行掌控循环loop、工具分派tool dispatch与状态处理工作流生命周期短主要目标就是返回模型响应。适合使用 Agents SDK 的场景希望由运行时管理轮次turns、工具执行、安全防护措施、任务转移或会话智能体需要生成产物artifacts或需要跨多个协调步骤完成操作需要通过沙箱智能体获得真实工作区或可恢复执行能力。两者并非全局二选一。许多应用会用 SDK 管理受控工作流同时对低层级执行路径直接调用 Responses API。这一点在Runner的实现中也得到印证Runner.run()等入口最终通过模型提供者provider解析出模型并调用底层 API见 src/agents/run.py 与 src/agents/models上层并不强制锁定某一种模型协议。安装pip install openai-agents仓库 docs/quickstart.md 提供了更完整的安装流程先创建项目与虚拟环境python -m venv .venv再安装 SDK也可使用uv add openai-agents等方式随后设置 OpenAI API Key。设置 API Key运行示例前需设置环境变量OPENAI_API_KEYexport OPENAI_API_KEYsk-...Windows PowerShell 下使用$env:OPENAI_API_KEY sk-...Windows 命令提示符下使用set OPENAI_API_KEYsk-...。此外SDK 还提供了编程式配置入口例如 src/agents/init.py 中的set_default_openai_key()、set_default_openai_client()与set_default_openai_api(chat_completions | responses)可在未设置环境变量时指定默认密钥或切换默认 API。Hello world 示例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) # Code within the code, # Functions calling themselves, # Infinite loops dance.运行此代码时请确保已设置OPENAI_API_KEY环境变量示例背后的运行机制从源码看Runner提供了三种运行方式见 docs/running_agents.md 与 src/agents/run.pyRunner.run()异步运行返回RunResultRunner.run_sync()同步方法内部本质是执行run()Runner.run_streamed()异步流式运行返回RunResultStreaming可逐事件消费流式输出。调用任一方法时传入起始智能体与输入字符串、Responses API 格式的输入项列表或用于恢复的RunState运行器会执行一个循环调用 LLM → 若输出被判定为最终输出则结束若请求任务转移则切换智能体与输入继续循环若产生工具调用则执行工具、追加结果并继续循环超过max_turns默认 10则抛出MaxTurnsExceeded异常传max_turnsNone可关闭该限制。仓库 examples/basic/hello_world.py 提供了上述示例的异步完整版本可作为直接运行参考。下一步入门路径如果你希望系统性地学习官方推荐的顺序是通过快速入门构建第一个文本智能体然后在运行智能体中决定如何跨轮次传递状态例如result.to_input_list()手动控制、session...交给 SDK 存取历史或用previous_response_id/conversation_id复用 OpenAI 服务端状态如果任务依赖真实文件、仓库或每个智能体独立的隔离工作区状态请阅读沙箱智能体快速入门如果你正在任务转移handoffs与管理器式编排manager-style orchestration之间做选择请阅读智能体编排。其中编排选择可参考 docs/multi_agent.md 的对比Agents as tools模式下管理器智能体保持对对话的控制、通过Agent.as_tool()调用专家智能体适合一个智能体拥有最终答案、合并多个专家输出的场景Handoffs模式下分诊智能体将对话路由给专家、由专家接管当前回合的剩余部分适合专家直接回应、保持提示词聚焦的场景。两者也可组合使用。按目标检索文档路径选择表当你知道要做什么、但不确定该看哪个页面时直接使用下表目标入门页面构建第一个文本智能体并查看一次完整运行快速入门添加函数工具、托管工具或 agents as tools工具在真正隔离的工作区中运行编码、审查或文档智能体沙箱智能体快速入门 和 沙箱客户端在任务转移与管理器式编排之间选择智能体编排跨轮次保留记忆运行智能体 和 会话使用 OpenAI 模型、WebSocket 传输或非 OpenAI 提供商模型检查输出、运行项、中断和恢复状态运行结果使用gpt-realtime-2.1构建低延迟语音智能体实时智能体快速入门 和 实时传输构建语音转文本 / 智能体 / 文本转语音管线语音管线快速入门更多代码示例与资源仓库提供了覆盖核心模式的完整可运行脚本可作为官方文档的补充参考examples/basic/hello_world.py首次运行的最简示例examples/basic/tools.py函数工具示例examples/agent_patterns/routing.py多智能体路由示例examples/agent_patterns涵盖并行化、确定性流程、人在回路、输入/输出护栏等更多编排模式。综上所述OpenAI Agents SDK 以极少的抽象覆盖了从单智能体到多智能体编排、从文本到语音与沙箱工作区的完整能力矩阵。你可以从本文的 Hello world 示例出发结合快速入门跑通第一个智能体再依据路径选择表按需深入对应模块。【免费下载链接】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-python本指南基于 OpenAI Agents SDK 官方文档日语版索引页与仓库源码系统梳理该框架的核心组件、设计原则、主要功能特性、与 Responses API 的选型对比并给出可立即运行的安装与 Hello world 示例以及一套按目标检索文档的学习路径。读完本文你将掌握 SDK 的三大基础组件Agent、Agents as tools / Handoffs、Guardrails如何协作知道何时该用 SDK、何时直接调用 Responses API并能据此规划下一步的深入学习路线。什么是 OpenAI Agents SDKOpenAI Agents SDK 是一个抽象极少的轻量级、易用型 Python 包用于构建智能体Agent型 AI 应用。它是 OpenAI 此前智能体实验项目 Swarm 的生产环境升级版核心设计目标是让开发者以最低的学习成本表达工具与智能体之间的复杂关系。从仓库的 顶层导出模块 可以看到整个 SDK 的能力都收敛在极少数核心类型上。官方文档将其归纳为三大基础组件primitives智能体Agent配备了指令instructions和工具tools的 LLMAgents as tools / 任务转移Handoffs允许智能体将特定任务委派给其他智能体的机制安全防护措施Guardrails用于校验智能体输入与输出的机制。将这三大组件与 Python 语言本身组合即可表达工具与智能体之间足够复杂的关系构建真实应用而无需陡峭的学习曲线。此外SDK 内置**追踪tracing**能力可用于可视化、调试智能体流程、进行评估甚至针对应用微调模型。从源码结构看这些组件在 src/agents/agent.pyAgent类支持tools、handoffs、input_guardrails、output_guardrails、instructions等构造参数、src/agents/handoffsHandoff机制与 src/agents/guardrail.pyInputGuardrail/OutputGuardrail及input_guardrail/output_guardrail装饰器中均有对应实现三者在 src/agents/run.py 的Runner中被统一编排执行。为什么选择 Agents SDKSDK 的设计由两条原则驱动功能足够多、值得使用同时基础组件足够少、易于快速上手开箱即用表现良好又允许你对真实执行细节进行精确自定义。主要功能特性特性说明智能体Agents使用指令、工具、安全防护措施、任务转移以及持续运行直至任务完成的内置循环构建智能体沙箱智能体Sandbox agents在真正隔离的工作区中运行专项智能体支持由清单manifest定义的文件、沙箱客户端选择与可恢复的沙箱会话实时智能体Realtime agents使用gpt-realtime-2.1、自动中断检测、上下文管理、安全防护措施等构建强大的语音智能体语音智能体Voice agents构建语音转文本 智能体工作流 文本转语音组合的语音管线Python 优先Python-first使用内置语言特性编排与串联智能体无需学习新的抽象概念Agents as tools / 任务转移在多个智能体之间协调与委派工作的强大机制安全防护措施Guardrails在智能体执行的同时并行运行输入校验与安全检查校验不通过时快速失败函数工具Function tools通过自动生成 schema 与 Pydantic 校验将任意 Python 函数转换为工具MCP 服务器工具调用内置集成可将远程 MCP 工具与函数工具一起暴露给智能体会话Sessions在智能体循环中维护工作上下文的持久化记忆层人在回路Human in the loop在智能体运行期间引入人工参与的内置机制追踪Tracing内置的可视化、调试、监控工作流能力并支持 OpenAI 的评估、微调与蒸馏工具套件上述特性在仓库中均有落地实现例如函数工具由 src/agents/tool.py 中的function_tool装饰器与 src/agents/function_schema.py 的 schema 自动生成逻辑支撑MCP 集成位于 src/agents/mcp会话Session抽象位于 src/agents/memory含 SQLite、OpenAI Conversations 等实现追踪系统位于 src/agents/tracing支持trace、agent_span、generation_span等 API并默认通过 BatchTraceProcessor 将 span 批量导出。Agents SDK 还是 Responses APISDK 对 OpenAI 模型默认使用 Responses API但将模型调用包装在更高层级的运行时中。二者的选择取决于你想把控制权交给谁适合直接使用 Responses API 的场景希望自行掌控循环loop、工具分派tool dispatch与状态处理工作流生命周期短主要目标就是返回模型响应。适合使用 Agents SDK 的场景希望由运行时管理轮次turns、工具执行、安全防护措施、任务转移或会话智能体需要生成产物artifacts或需要跨多个协调步骤完成操作需要通过沙箱智能体获得真实工作区或可恢复执行能力。两者并非全局二选一。许多应用会用 SDK 管理受控工作流同时对低层级执行路径直接调用 Responses API。这一点在Runner的实现中也得到印证Runner.run()等入口最终通过模型提供者provider解析出模型并调用底层 API见 src/agents/run.py 与 src/agents/models上层并不强制锁定某一种模型协议。安装pip install openai-agents仓库 docs/quickstart.md 提供了更完整的安装流程先创建项目与虚拟环境python -m venv .venv再安装 SDK也可使用uv add openai-agents等方式随后设置 OpenAI API Key。设置 API Key运行示例前需设置环境变量OPENAI_API_KEYexport OPENAI_API_KEYsk-...Windows PowerShell 下使用$env:OPENAI_API_KEY sk-...Windows 命令提示符下使用set OPENAI_API_KEYsk-...。此外SDK 还提供了编程式配置入口例如 src/agents/init.py 中的set_default_openai_key()、set_default_openai_client()与set_default_openai_api(chat_completions | responses)可在未设置环境变量时指定默认密钥或切换默认 API。Hello world 示例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) # Code within the code, # Functions calling themselves, # Infinite loops dance.运行此代码时请确保已设置OPENAI_API_KEY环境变量示例背后的运行机制从源码看Runner提供了三种运行方式见 docs/running_agents.md 与 src/agents/run.pyRunner.run()异步运行返回RunResultRunner.run_sync()同步方法内部本质是执行run()Runner.run_streamed()异步流式运行返回RunResultStreaming可逐事件消费流式输出。调用任一方法时传入起始智能体与输入字符串、Responses API 格式的输入项列表或用于恢复的RunState运行器会执行一个循环调用 LLM → 若输出被判定为最终输出则结束若请求任务转移则切换智能体与输入继续循环若产生工具调用则执行工具、追加结果并继续循环超过max_turns默认 10则抛出MaxTurnsExceeded异常传max_turnsNone可关闭该限制。仓库 examples/basic/hello_world.py 提供了上述示例的异步完整版本可作为直接运行参考。下一步入门路径如果你希望系统性地学习官方推荐的顺序是通过快速入门构建第一个文本智能体然后在运行智能体中决定如何跨轮次传递状态例如result.to_input_list()手动控制、session...交给 SDK 存取历史或用previous_response_id/conversation_id复用 OpenAI 服务端状态如果任务依赖真实文件、仓库或每个智能体独立的隔离工作区状态请阅读沙箱智能体快速入门如果你正在任务转移handoffs与管理器式编排manager-style orchestration之间做选择请阅读智能体编排。其中编排选择可参考 docs/multi_agent.md 的对比Agents as tools模式下管理器智能体保持对对话的控制、通过Agent.as_tool()调用专家智能体适合一个智能体拥有最终答案、合并多个专家输出的场景Handoffs模式下分诊智能体将对话路由给专家、由专家接管当前回合的剩余部分适合专家直接回应、保持提示词聚焦的场景。两者也可组合使用。按目标检索文档路径选择表当你知道要做什么、但不确定该看哪个页面时直接使用下表目标入门页面构建第一个文本智能体并查看一次完整运行快速入门添加函数工具、托管工具或 agents as tools工具在真正隔离的工作区中运行编码、审查或文档智能体沙箱智能体快速入门 和 沙箱客户端在任务转移与管理器式编排之间选择智能体编排跨轮次保留记忆运行智能体 和 会话使用 OpenAI 模型、WebSocket 传输或非 OpenAI 提供商模型检查输出、运行项、中断和恢复状态运行结果使用gpt-realtime-2.1构建低延迟语音智能体实时智能体快速入门 和 实时传输构建语音转文本 / 智能体 / 文本转语音管线语音管线快速入门更多代码示例与资源仓库提供了覆盖核心模式的完整可运行脚本可作为官方文档的补充参考examples/basic/hello_world.py首次运行的最简示例examples/basic/tools.py函数工具示例examples/agent_patterns/routing.py多智能体路由示例examples/agent_patterns涵盖并行化、确定性流程、人在回路、输入/输出护栏等更多编排模式。综上所述OpenAI Agents SDK 以极少的抽象覆盖了从单智能体到多智能体编排、从文本到语音与沙箱工作区的完整能力矩阵。你可以从本文的 Hello world 示例出发结合快速入门跑通第一个智能体再依据路径选择表按需深入对应模块。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考