企业官网建设流程全解析

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 SDK

OpenAI Agents SDK 是一个抽象极少的轻量级、易用型 Python 包，用于构建智能体（Agent）型 AI 应用。它是 OpenAI 此前智能体实验项目 Swarm 的生产环境升级版，核心设计目标是让开发者以最低的学习成本表达"工具与智能体之间的复杂关系"。

从仓库的 顶层导出模块 可以看到，整个 SDK 的能力都收敛在极少数核心类型上。官方文档将其归纳为三大基础组件（primitives）：

• 智能体（Agent）：配备了指令（instructions）和工具（tools）的 LLM；
• Agents as tools / 任务转移（Handoffs）：允许智能体将特定任务委派给其他智能体的机制；
• 安全防护措施（Guardrails）：用于校验智能体输入与输出的机制。

将这三大组件与 Python 语言本身组合，即可表达工具与智能体之间足够复杂的关系，构建真实应用而无需陡峭的学习曲线。此外，SDK 内置**追踪（tracing）**能力，可用于可视化、调试智能体流程、进行评估，甚至针对应用微调模型。

从源码结构看，这些组件在 src/agents/agent.py（Agent类，支持tools、handoffs、input_guardrails、output_guardrails、instructions等构造参数）、src/agents/handoffs（Handoff机制）与 src/agents/guardrail.py（InputGuardrail/OutputGuardrail及@input_guardrail/@output_guardrail装饰器）中均有对应实现，三者在 src/agents/run.py 的Runner中被统一编排执行。

为什么选择 Agents SDK

SDK 的设计由两条原则驱动：

1. 功能足够多、值得使用，同时基础组件足够少、易于快速上手；
2. 开箱即用表现良好，又允许你对真实执行细节进行精确自定义。

主要功能特性

上述特性在仓库中均有落地实现：例如函数工具由 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 API？

SDK 对 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_KEY：

export OPENAI_API_KEY=sk-...

Windows PowerShell 下使用$env:OPENAI_API_KEY = "sk-..."，Windows 命令提示符下使用set "OPENAI_API_KEY=sk-..."。此外，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(name="Assistant", instructions="You 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 loop's dance.

（运行此代码时，请确保已设置OPENAI_API_KEY环境变量）

示例背后的运行机制

从源码看，Runner提供了三种运行方式（见 docs/running_agents.md 与 src/agents/run.py）：

1. Runner.run()：异步运行，返回RunResult；
2. Runner.run_sync()：同步方法，内部本质是执行run()；
3. Runner.run_streamed()：异步流式运行，返回RunResultStreaming，可逐事件消费流式输出。

调用任一方法时，传入起始智能体与输入（字符串、Responses API 格式的输入项列表，或用于恢复的RunState），运行器会执行一个循环：调用 LLM → 若输出被判定为最终输出则结束；若请求任务转移则切换智能体与输入继续循环；若产生工具调用则执行工具、追加结果并继续循环；超过max_turns（默认 10）则抛出MaxTurnsExceeded异常，传max_turns=None可关闭该限制。

仓库 examples/basic/hello_world.py 提供了上述示例的异步完整版本，可作为直接运行参考。

下一步：入门路径

如果你希望系统性地学习，官方推荐的顺序是：

1. 通过快速入门构建第一个文本智能体；
2. 然后在运行智能体中决定如何跨轮次传递状态（例如result.to_input_list()手动控制、session=...交给 SDK 存取历史，或用previous_response_id/conversation_id复用 OpenAI 服务端状态）；
3. 如果任务依赖真实文件、仓库或每个智能体独立的隔离工作区状态，请阅读沙箱智能体快速入门；
4. 如果你正在"任务转移（handoffs）"与"管理器式编排（manager-style orchestration）"之间做选择，请阅读智能体编排。

其中编排选择可参考 docs/multi_agent.md 的对比：Agents as tools模式下管理器智能体保持对对话的控制、通过Agent.as_tool()调用专家智能体，适合"一个智能体拥有最终答案、合并多个专家输出"的场景；Handoffs模式下分诊智能体将对话路由给专家、由专家接管当前回合的剩余部分，适合"专家直接回应、保持提示词聚焦"的场景。两者也可组合使用。

按目标检索文档：路径选择表

当你知道要做什么、但不确定该看哪个页面时，直接使用下表：

更多代码示例与资源

仓库提供了覆盖核心模式的完整可运行脚本，可作为官方文档的补充参考：

• 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