简介:本文面向开发者解析 OpenAI Agents SDK 的核心概念、安装配置、基础示例、多智能体转交、非 OpenAI 模型接入与排错方法,并补充知识库、沙箱、安全护栏及模型选型建议,帮助读者快速构建可观测、可维护的 Agent 系统。
OpenAI Agents SDK 是一个面向多智能体工作流的轻量级开源框架,目标不是简单封装聊天机器人,而是把模型推理、工具调用、任务转交、输入输出校验和运行追踪组合成一套可编排的工程范式。对于希望快速验证 Agent 原型、搭建客服助手、代码助手或多角色协作系统的团队来说,它提供了较低的学习成本和较清晰的扩展路径。
OpenAI Agents SDK 可以视为早期智能体实验项目 Swarm 思路的工程化延续。它保留“多个智能体分工协作”的设计理念,但更强调可落地能力:开发者可以用少量核心概念搭建流程,再根据业务需要逐步加入工具、护栏、追踪、自定义模型和第三方服务接入。
从架构上看,SDK 围绕“智能体循环”展开:模型接收用户输入后,判断是否调用工具;工具返回结果后,模型继续推理,直到生成最终答案或触发任务转交。这种模式让 Agent 不只是“回答问题”,而是能够“执行任务”。
不过,SDK 的具体版本、运行要求和接口细节会持续演进。本文示例以官方公开能力为准,建议读者在实际接入前核验官方最新版本。若使用 Python 版本,建议使用受支持的新版 Python 环境;若使用 JavaScript/TypeScript 版本,需要关注 Node.js 要求,建议使用长期支持版本,例如 Node.js 22 或更高,具体以官方发布页为准。
| 项目 | 建议 | 说明 |
|---|---|---|
| Python | 建议使用官方支持的新版本 | 用于运行 Python SDK 示例 |
| Node.js | 建议使用 LTS 版本,如 Node.js 22+ | 用于 JavaScript/TypeScript SDK |
| agents 包 | 建议锁定稳定版本 | 避免升级导致行为变化 |
| 模型 | 支持 OpenAI 模型、OpenAI 兼容模型或自定义适配器 | 非 OpenAI 模型需验证工具调用与转交能力 |
| API Key | 建议通过环境变量注入 | 避免硬编码到代码仓库 |
OpenAI Agents SDK 的学习成本相对可控,核心概念主要集中在 Agent、Handoffs、Guardrails 和 Tracing。理解这四个概念,就能搭建起大多数多智能体应用的基本骨架。
| 概念 | 作用 | 关键配置 | 常见排错 |
|---|---|---|---|
| Agent | 定义角色、指令和可用工具 | name、instructions、tools | 指令不清晰、角色边界模糊 |
| Handoffs | 将任务转交给另一个 Agent | handoffs 列表、转交说明 | 模型未触发转交、目标 Agent 配置错误 |
| Guardrails | 在输入或输出前后做校验 | 输入护栏、输出护栏 | 拦截规则过严、错误信息不明确 |
| Tracing | 记录运行过程,辅助定位问题 | 日志、追踪节点、工具调用记录 | 未开启日志、转交路径不清晰 |
其中,Agent 是基本单位;Handoffs 负责跨角色协作;Guardrails 提供安全边界;Tracing 则让复杂流程变得可观测。对于企业应用来说,后两者尤其重要,因为多智能体系统的问题往往不在“单轮回答”,而在“任务是否走错了节点”。
下面的示例展示如何创建一个基础客服 Agent。注意,这不是“零配置即可复制”的最小脚本,而是需要准备运行环境、安装依赖并配置密钥后执行的基础示例。
在开始之前,需要完成以下准备:
pip install openai-agentsOPENAI_API_KEY安装命令示例:
pip install openai-agents
设置密钥示例:
export OPENAI_API_KEY="your_api_key_here"
from agents import Agent, Runneragent = Agent(name="客服助手",instructions="你是耐心的客服助手,先确认用户问题,再给出清晰步骤。",)result = Runner.run_sync(agent, "如何重置账户密码?")print(result.final_output)
这个示例的核心不是复杂逻辑,而是展示 Agent 的基本工作方式:开发者定义角色和指令,运行器负责调用模型并返回结果。如果运行失败,可以先检查以下几项:
openai-agentsOPENAI_API_KEY如果要接入真实业务,还需要继续增加工具、护栏、日志和错误处理。
当任务涉及多个专业角色时,可以使用 Handoffs 进行编排。例如,综合客服负责识别用户意图,账单助手专门处理退款、支付失败和账单问题。
from agents import Agent, Runnerbilling_agent = Agent(name="账单助手",instructions="你负责处理账单、退款和支付失败问题。",)support_agent = Agent(name="综合客服",instructions=("你是综合客服。如果用户问题涉及账单、退款、支付失败,""请转交给账单助手;其他问题直接回答。"),handoffs=[billing_agent],)result = Runner.run_sync(support_agent,"我上周的订单为什么退款失败?",)print(result.final_output)
在这个流程中,综合客服先理解用户意图,再把账单相关问题转交给账单助手。相比把所有逻辑塞进一个提示词,这种方式更容易维护,也更方便针对每个角色单独优化指令和工具。
Handoff 是否能触发,并不只取决于代码里是否配置了 handoffs,还依赖模型对指令的理解、角色边界描述、模型工具调用能力,以及当前运行的上下文。
如果转交没有按预期发生,可以按以下顺序排查:
handoffs 是否确实传入 Agent。instructions 是否明确写出转交条件,例如“涉及退款时必须转交给账单助手”。对于生产环境,建议在日志中记录任务转交前后状态,包括原始输入、当前 Agent、目标 Agent、转交原因和最终结果。这样可以避免系统“看起来运行了”,但实际走了错误路径。
虽然名称中包含 OpenAI,但 OpenAI Agents SDK 的设计并不是只服务于 OpenAI 模型。开发者可以通过 OpenAI 兼容接口、适配器或自定义模型客户端,将模型调用指向其他模型服务。
接入非 OpenAI 模型时,不能只完成 openai.OpenAI 客户端初始化,还需要把模型或客户端注入到 Agent 的运行链路中。否则,SDK 仍可能使用默认配置发起请求。
通常有以下几种方式:
下面给出一个示意代码,展示如何将 Agent 指向兼容模型服务。实际使用时,请根据官方最新接口、目标模型名称和兼容能力调整。
import osfrom openai import AsyncOpenAIfrom agents import Agent, Runner, OpenAIResponsesModelclient = AsyncOpenAI(api_key=os.getenv("CUSTOM_MODEL_API_KEY"),base_url="https://qianfan.baidubce.com/v2/",)model = OpenAIResponsesModel(model="替换为实际可用模型名称",openai_client=client,)agent = Agent(name="通用助手",instructions="请根据用户问题给出简洁、准确的回答。",model=model,)result = Runner.run_sync(agent, "介绍一下知识管理工具")print(result.final_output)
如果目标服务仅支持 Chat Completions 风格接口,或者 SDK 版本提供了其他模型适配器,可以替换为对应的兼容模型类。如果现有适配器无法满足需求,就需要自定义模型实现,至少覆盖消息转换、请求发送、响应解析、错误处理和工具调用结果回填。
非 OpenAI 模型接入不能只验证“能回复一句话”,还需要验证:
如果模型只支持普通文本生成,不支持工具调用,那么 Agent 的复杂能力会明显受限。因此,选型时不能只看单次回答效果,还要看它在智能体流程中的稳定性。
当 OpenAI Agents SDK 从原型走向企业环境,通常需要考虑知识库、代码执行、训练部署和安全治理。下面三类扩展比较常见。
Agent 经常需要回答企业内部知识。若使用支持知识库搜索的接口,可以把知识库检索作为工具接入。例如,在 Response API 场景中,可以通过 knowledge_search 工具传入知识库 ID,让模型基于知识库内容生成回答。
不过,这种方式有前置条件:
如果知识库内容包含客户信息、合同、财务或内部流程,建议先建立数据权限模型,再让 Agent 调用检索接口。否则,可能出现模型回答正确,但权限越界的问题。
对于 Code Agent、数据分析 Agent 或自动化运维 Agent,模型生成的代码需要安全执行。此时可以引入 Agent 沙箱服务,它提供安全隔离、快速启动和多语言执行环境,适合运行 AI 生成的代码并降低对宿主系统的风险。
生产环境中建议至少满足以下安全清单:
对于自动化运维类 Agent,还需要增加人工确认环节,尤其是涉及发布、回滚、扩容、删除资源等高风险操作时,不能让模型单独完成全部决策。
如果企业不仅要调用模型,还要进行数据管理、模型训练、推理部署和运维监控,可以结合千帆大模型平台的全生命周期能力进行建设。这类平台通常覆盖数据管理、模型开发、推理服务和部署支持,适合从原型走向生产环境。
在企业落地过程中,建议提前规划:
这些能力不会让 Agent 看起来更“聪明”,但会显著决定系统是否可上线、可维护、可追责。
多智能体系统上线后,成本往往不只看单次调用价格,还取决于任务成功率、平均轮次、工具调用次数和失败重试率。一个便宜但容易出错的模型,可能因为反复重试导致总成本更高;一个能力更强的模型,如果只处理简单任务,也可能造成资源浪费。
选型时建议关注以下几点:
如果团队只是初步选型,可以访问百度智能云词元所(https://cloud.baidu.com/product-s/token_exchange.html?from=article)进行模型能力和价格对比。不过,任何选型结论都需要结合自身业务流量、真实任务分布和压测结果判断,不能只依赖静态参数或单次演示。
它是一个面向多智能体工作流的开源框架,提供 Agent、工具调用、任务转交、安全护栏和追踪能力。它适合构建客服助手、代码助手、知识问答、任务编排和多角色协作系统。
Python 用户可安装 openai-agents,并设置 OPENAI_API_KEY 或自定义模型客户端。JavaScript/TypeScript 用户需要使用对应 npm 包,并确认 Node.js 版本满足要求。建议先运行单 Agent 示例,再逐步加入工具、护栏和追踪。
常见问题包括:未设置 API Key、模型服务不可达、SDK 版本不兼容、工具调用失败、Handoff 未触发、指令描述不清、日志缺失导致难以定位、第三方模型不支持多轮消息格式等。建议先用最小路径验证模型连通性,再逐步增加复杂能力。
不一定。多智能体适合职责清晰、需要分工协作的任务。如果任务本身很简单,单 Agent 加工具可能更稳定、更容易维护。多智能体系统的价值在于降低复杂流程的维护成本,而不是天然提升回答质量。
OpenAI Agents SDK 的价值在于用较少的概念完成多智能体应用的搭建:Agent 负责角色与工具,Handoffs 负责任务转交,Guardrails 负责安全边界,Tracing 负责运行追踪。它既适合快速原型开发,也能通过自定义工具和外部服务逐步扩展到企业场景。
对于开发者来说,建议从基础示例开始,先确认安装、密钥、模型和运行环境正常,再加入多智能体协作、非 OpenAI 模型适配、知识库检索、沙箱执行和安全护栏。对于企业团队来说,除了关注模型能力,还要重点关注权限、审计、成本控制、灰度发布和故障排错。只有在原型验证、压测和治理机制都完善之后,多智能体系统才更适合进入生产环境。