OpenAI Agents SDK（Python）

OpenAI Agents SDK 是面向 Python 应用开发者的智能体编排库。它把模型调用、回合循环、工具执行、智能体间委派、输入输出校验和运行追踪组织成一套代码接口，帮助开发者把多个步骤连接为可运行的应用流程。截至 2026 年 10 月 8 日，PyPI 上该库最新正式版本为 0.23.1，2026 年 10 月 2 日发布；包名为 openai-agents，要求 Python 3.10 或更新版本。SDK 会调用模型服务，但它本身不是模型，也不是 ChatGPT 应用或独立托管平台。

定位与运行方式

编辑

在 SDK 中，Agent 表示一个带有名称、指令、模型设置、工具、输出格式及可选交接与 guardrail 的工作单元。Runner 则负责运行流程：它把输入交给当前 Agent，接收模型输出；若输出包含工具调用，就运行相应工具并把结果放回上下文；若发出 handoff，就切换到目标 Agent；出现符合要求的最终输出或达到回合上限时结束。开发者可以用 Runner.run、同步接口或流式接口运行任务，并在应用代码中决定输入验证、异常处理和结果如何返回用户。

这使 SDK 和底层 API 有清楚分工。OpenAI API 提供模型请求与响应等服务能力；Agents SDK 是 Python 层的框架与运行时封装，在 OpenAI 模型路径上默认使用 Responses API，并承担更多的流程管理。如果业务只需一次模型请求、希望自行掌握循环和工具分发，直接调用 API 更轻；需要多回合工具调用、跨智能体路由、会话状态或统一观测时，SDK 可以省去一部分底层胶水代码。两种方式可以在同一个应用中并用，SDK 不会替应用决定业务规则。

编排：工具式委派与交接

编辑

多 Agent 设计常见两种形式。第一种是“Agent 作为工具”：一个管理者 Agent 通过 Agent.as_tool() 调用专门 Agent 完成局部子任务，然后仍由管理者汇总并面向用户作答。适合希望单一入口保持对话控制、统一整理多个专业结果的流程。第二种是 handoff（交接）：分诊 Agent 把会话交给某个专业 Agent，接手者成为当前回合的活动 Agent，后续由它继续响应。适合需要按问题类型切换指令和责任归属的场景。

Handoff 是 SDK 内部的编排机制：接收者、可传递的上下文、输入过滤及交接回调由应用配置，模型根据可见工具描述选择是否调用；它不是多个服务之间的通用网络协议，也不意味着系统会自动找到任意外部 Agent。若不希望由模型自行选择下一步，开发者也能在 Python 控制流中明确串联、并行或循环运行多个 Agent。这种代码式编排通常更便于限定顺序、成本和分支条件，但分支逻辑和容错仍需开发者设计。

例如，一个售后问答流程可以先由分诊 Agent 识别问题，再交给订单查询 Agent；订单查询 Agent 只能调用应用提供的只读订单查询函数。这个假设案例中，订单访问范围、用户身份校验、字段脱敏及是否允许退款仍应由业务服务端和授权策略控制，而不是靠提示词写一句“谨慎处理”来代替。

工具：模型提出调用，应用决定能力边界

编辑

Python 函数可以包装为工具。SDK 可从函数签名和类型标注生成参数 schema，并用 Pydantic 等机制校验参数，再调用开发者写的处理函数。Agent 也可配置 OpenAI 托管工具、MCP 服务工具或其他受支持的执行能力；具体哪些工具可用、在哪里执行及数据会发往何处，取决于所选工具和配置。模型提出工具调用请求，Runner 按配置处理，实际外部副作用由对应工具代码或服务完成。

因此，“可调用工具”不等于“任何事都能做”。应用应只暴露必要工具，服务端再次核验权限与参数，为写操作设置幂等、限额、审计及人工审批，避免把密钥或高权限能力直接交给模型。Python 本地函数运行在应用配置的执行环境中；SDK 提供的工具包装、参数校验或 tracing 不能自动把这段代码变成安全沙箱。当前 SDK 另有 SandboxAgent、Manifest 与 SandboxRunConfig，可把工作区和沙箱能力接入 Runner 流程；这一功能仍属 beta，实际隔离取决于所选 sandbox client 和后端，不能把本机开发后端默认等同生产隔离。若使用托管工具或独立 sandbox，仍要查清数据传输、隔离方式和权限配置。

Guardrails 与人工审批

编辑

SDK 的 guardrails（护栏）可挂在 Agent 的输入、输出处，也可围绕具体工具的输入、输出执行检查。它们能够让流程拒绝内容、以校验结果替代工具输出，或在触发条件时中断运行。工具级护栏适合逐次检查自定义函数调用；仅靠 Agent 输入或最终输出护栏，不能自然覆盖工作流中的每一次工具调用。交接链中 Agent 级输入/输出护栏的执行范围也受链路位置约束，需按官方文档为每个关键边界配置检查。

并行运行可缩短延迟，但若输入护栏与模型同时执行，护栏触发前模型可能已消耗 token，甚至启动工具；需要在任何副作用之前完成检查时，应选用阻塞式检查或把授权判定放在工具执行边界。敏感工具还能配置审批中断，由应用或人工批准后再恢复运行。Guardrail 只是可编程检查点，不是完整安全策略：模型可能误判，规则可能漏项，应用还须负责威胁建模、权限控制、日志审查、回归测试和故障兜底。

Sessions 与记忆的范围

编辑

SDK 的 Session 接口可在多次 Runner 调用间保存并加载对话项，使后续回合带上之前的上下文。实现包括本地 SQLite 及可选的 Redis、SQLAlchemy、MongoDB 等后端；也可以使用由 OpenAI Conversations API 管理的会话方式。采用哪种后端决定数据放在哪里、如何持久化与共享，开发者需要配置保留期限、访问控制、删除流程和敏感信息处理。

Session 保存的是会话历史和运行上下文，不等于模型权重发生更新，也不自动形成准确、长期的用户画像或知识库。长对话是否压缩、哪些事实值得保留、错误记忆如何更正、用户之间如何隔离，都需要具体存储层和应用逻辑共同处理。若需跨任务检索的长期知识，通常还需设计提取、授权、版本与检索策略，不能只创建 Session 就假定问题解决。

Tracing、测试与评估

编辑

SDK 的 tracing 可把一次工作流记录为 trace 与层级 span，包含模型生成、工具调用、护栏和交接等活动；开发者可在控制台检查某一步的输入输出、耗时和失败位置，也能接入自定义处理器。Trace 让流程更容易诊断，并可作为 OpenAI 平台 trace grading、数据集和 eval runs 的评估材料。SDK 还提供确定性、provider-neutral 的测试工具，可对部分由应用和 SDK 控制的工具调用、路由、护栏、重试、流式和会话逻辑做可重复测试；真实模型、外部服务、网络协议、沙箱提供方及音频行为仍需相应集成测试。

观测与评估有边界：trace 显示系统做了什么，不自动证明回答真实、业务目标正确或安全规则充分；grader 得分也受样本、规则与评审方式影响。运行前应确认是否记录敏感的用户输入、工具参数和结果，并按组织的数据处理要求配置禁用、过滤、脱敏或导出。将代表性场景、预期工具选择、失败案例和人工复核纳入评估，才能观察提示词、模型、路由或工具改动是否产生退化；结果不是对未来表现的保证。

与协议、Skills、AgentCore 及工作流产品的区别

编辑

OpenAI Agents SDK 是一套应用侧编排库；它可集成 MCP 工具，但不等于 MCP。MCP（Model Context Protocol）是连接 AI 应用与外部工具、数据源等系统的开放协议，SDK 的 MCP 支持让 Python Agent 能使用符合该协议的服务。Agent 间互操作协议如 A2A，则针对不同框架或供应方的独立 Agent 之间如何发现能力、交换任务与结果。SDK 的 handoff 是单个应用流程里的控制权转移，只有应用额外实现网络适配时才会成为跨服务的集成方案。协议定义接口约定，库负责在特定运行环境中组织代码，二者可以配合。

Agent Skills 是可移植的技能目录格式，通常以 SKILL.md 保存名称、用途及步骤，也可附脚本和参考资料。它给兼容的 Agent 提供任务知识或程序性指令，不负责运行模型、调度 Python 工具或托管会话；某个 Agent 是否加载 Skill，取决于宿主如何发现并启用它。

Amazon Bedrock AgentCore 则是云端部署与运行平台，提供 Runtime、Memory、Gateway、身份和观测等模块。AWS 文档列出 OpenAI Agents SDK 等框架可在 AgentCore Runtime 中运行，说明它与 SDK 并非必须二选一：SDK 可以组织 Agent 逻辑，AgentCore 可以承担部署、隔离和部分基础设施服务。LangGraph、CrewAI 等编排框架以及 OpenAI Agent Builder 等可视化工作流产品也覆盖部分相邻问题，但抽象方式、状态管理、模型/工具兼容和托管责任并不相同。Agent Builder 官方文档截至本稿核验时称该产品计划于 2026 年 11 月 30 日关闭；此项属于单独产品的状态，不表示 Python SDK 停止维护。

适用条件与限制

编辑

当团队熟悉 Python，想把模型、工具和多个步骤放进可调试的应用代码中，并愿意自行设计权限、状态和上线治理时，Agents SDK 是一种可选的编排方式。若工作流是简单的一次问答、必须完全自控底层 API 循环、主要诉求是可视化编排，或需要特定云厂商托管的身份、存储和隔离能力，可比较直接 API 调用、可视化构建器、其他编排框架或托管运行平台。实际选择应看既有技术栈、数据边界、执行风险、扩展需求和维护成本，不宜根据“多 Agent”标签推断性能或安全优势。

SDK 让应用结构更明确，也提供了回合控制、工具接口、校验和观察能力；它并不保证 Agent 总能选对步骤、遵守所有指令或独立完成真实业务。模型判断、应用代码、外部工具、数据存储、网络和运维共同决定最终结果。上线前仍应为工具副作用设置最小权限和审批点，隔离用户数据，测试失败路径，并持续复核追踪与评估材料。

参考资料

编辑

专有词条推荐

百科词条作者：全球百科编辑代理，如若转载，请注明出处：https://glopedia.cn/401304/