解读 OpenAI 的 Agents SDK：指南

OpenAI 正在推出多项新产品：Responses API、用于网页和文件搜索的内置工具、计算机使用工具，以及开源的 Agents SDK。Responses API 使开发者能够在其技术之上构建智能体，而 Agents SDK 则可帮助他们将智能体与其他 Web 工具和流程连接起来，自动执行满足用户或业务需求的“工作流”。

2025 年常被誉为“智能体之年”，OpenAI 的举措被视为行业关键一步。Agents SDK 使开发者能够在真实的多步骤场景中轻松利用 OpenAI 的最新进展（例如更强的推理能力、多模态交互以及新的安全技术）。对 LLM 开发者和 AI 智能体构建者而言，Agents SDK 提供一套“构建模块”，用于创建和管理自主的 AI 系统。

Agents SDK 的意义在于其有能力解决在生产环境中部署 AI 智能体的挑战。传统上，将强大的 LLM 能力转化为多步骤工作流非常耗费人力，需要大量自定义规则编写、顺序式提示设计，以及在缺乏适当可观测性工具的情况下不断试错。借助 Agents SDK 及 Responses API 等相关新 API 工具，OpenAI 旨在显著简化这一过程，使开发者能够以更少的投入构建更复杂、更可靠的智能体。

什么是 Agents SDK

OpenAI 借助发布 Agents SDK 大举回归开源领域。这是一套工具包，旨在帮助开发者管理、协调并优化智能体工作流——甚至可以构建由其他非 OpenAI 模型驱动的智能体，例如竞争对手 Anthropic 和 Google 的模型，或 DeepSeek、Qwen、Mistral 以及 Meta 的 Llama 系列等开源模型。

为什么使用 Agents SDK

该 SDK 的两项核心设计原则：

1. 功能足够丰富以值得使用，但原语足够精简以便快速上手。
2. 开箱即用体验优秀，同时您可以精确自定义具体行为。

以下为 SDK 的主要功能：

• 智能体循环：内置循环，负责调用工具、将结果发送给 LLM，并循环直至 LLM 完成。
• Python 优先：使用语言内置特性来编排与串联智能体，无需学习新的抽象。
• 交接：强大的特性，用于在多个智能体之间进行协调与委派。
• 护栏：在智能体并行运行输入验证与检查，若检查失败可提前中断。
• 函数工具：将任意 Python 函数变为工具，自动生成模式并通过 Pydantic 进行验证。
• 追踪：内置追踪，可视化、调试和监控工作流，并使用 OpenAI 的评估、微调和蒸馏工具套件。

如何使用 Openai Agents SDK

1. 设置您的 Python 环境

python -m venv env
source env/bin/activate

2. 安装 Agents SDK

pip install openai-agents

3. 设置 OPENAI_API_KEY 环境变量

通过 CometAPI 自由设置 OPENAI_API_KEY API

• 登录 cometapi.com。如果您尚未成为我们的用户，请先注册
• 获取接口的访问凭证 API key。在个人中心的 API token 处点击“Add Token”，获取令牌密钥：sk-xxxxx 并提交。
• 获取该站点的 URL：https://api.cometapi.com/
• 选择 OPENAI_API_KEY 端点发送 API 请求并设置请求体。请求方法与请求体可从我们的站点 API 文档获取。我们的网站也提供 Apifox 测试供您使用。

4. 设置您的智能体

定义 AI 可使用的工具。比如我们要启用网页搜索和文件检索：

from agent_sdk import Agent, WebSearchTool, FileRetrievalTool

search_tool = WebSearchTool(api_key="your_api_key")
file_tool = FileRetrievalTool()

agent = Agent(tools=)

现在，您的智能体已经能够进行网页搜索并获取文档。

5. 运行

与传统聊天机器人不同，这个 AI 会根据用户输入自动决定使用哪种工具：

def agent_task(query):
    result = agent.use_tool("web_search", query)
    return result

response = agent_task("Latest AI research papers")
print(response)

无需人工干预——只需自主执行。

智能体循环

当您调用 Runner.run() 时，SDK 会运行一个循环，直到得到最终输出：

1. 使用智能体上的模型与设置、以及消息历史调用 LLM。
2. LLM 返回响应，响应中可能包含工具调用。
3. 如果响应包含最终输出，循环结束并返回该输出。
4. 如果响应包含交接，智能体会切换到新智能体并从第 1 步继续循环。
5. 处理工具调用（如有），并追加工具响应消息。然后从第 1 步继续循环。

您可以使用 max_turns 参数来限制循环执行的次数。

​最终输出

最终输出是智能体在循环中产出的最后结果：

• 如果在智能体上设置了 output_type，则当 LLM 使用结构化输出返回该类型的内容时，视为最终输出。
• 如果未设置 output_type（即纯文本响应），则第一个不包含任何工具调用或交接的 LLM 响应被视为最终输出。

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 Agents SDK 旨在作为一个概念性框架，演示不同智能体（例如‘Triage Agent’或‘CRM Agent’）如何通过工具交互与委派机制协作完成任务。”

Agents SDK 的核心组件与架构

OpenAI Agents SDK 构建在一套简洁而稳健的原则之上。其核心是 Agent 概念，即指定语言模型实例，配以特定指令并具备使用多种工具的能力。智能体从接收用户请求开始——例如问题或任务定义——随后将任务拆解为可能需要使用预定义工具的子任务，并最终交付完整响应。Tools 在功能上被描述为可调用函数；借助 Agents SDK，任何 Python 函数都可无缝充当工具，且通过 Pydantic 提供输入与输出的自动模式验证。例如，代表数据库查询工具或网页搜索工具的 Python 函数可以直接集成到智能体的工具箱中。

另一个关键组成是 Agent Loop，定义了解决任务的迭代过程。智能体从初始尝试回答开始，评估自己是否具备足够信息或需要执行外部操作。必要时，智能体调用相关工具、处理输出，并重新评估任务。该循环会重复，直到智能体以“我完成了”的响应标示任务完成。Agents SDK 自主管理这一过程，简化开发流程，自动化工具调用、结果处理与迭代重试等重复性工作。这样，开发者可以更专注于定义工作流与智能体能力，而无需过多关注底层机制。OpenAI 将这一方法描述为 Python-first，强调使用熟悉的 Python 构造（如循环、条件与函数调用），而非特定领域语言（DSL）。借助这种灵活性，开发者可用原生 Python 语法编排互联的智能体。

交接与多智能体架构

SDK 的能力超越单个智能体。通过称为 Handoff 的特性，任务可以在多个智能体之间转移，使它们得以无缝协作。例如，“Triage Agent”可能负责识别传入请求的性质，并将其委派给另一个专门智能体；或者一个智能体的输出作为另一个智能体的输入。该体系支持由专门智能体执行更大任务不同部分的工作流，赋能复杂的多智能体架构。此外，Guardrails 通过对智能体输入或输出施加验证规则来提升可靠性。例如，护栏可以强制参数格式合规，或在检测到异常时提前终止循环，从而降低在真实世界运行中的低效执行或不期望行为等风险。

编排与监控

除了任务执行，Agents SDK 还包含强大的编排特性，负责工具执行、数据流与循环管理。尽管自动化程度很高，OpenAI 仍将透明度置于优先级，为开发者配备实时监控智能体活动的工具。通过 OpenAI 仪表板中的内置 Tracing 功能，开发者可以逐步可视化工作流，观察何时调用工具、所用输入以及返回的输出。平台利用 OpenAI 的监控基础设施将智能体逻辑的执行分解为 trace 与 span，为智能体行为提供细粒度洞察。这使得开发者可以诊断瓶颈、调试问题、优化工作流并跟踪性能。此外，追踪架构还支持更复杂的评估，从而实现智能体性能的微调与持续改进。

优势

OpenAI Agents SDK 不仅适用于个人开发者，对构建基于 AI 智能体产品的公司也具有显著优势。先来看看这些优势：

**快速原型到生产：**Agents SDK 以极少的代码与配置实现复杂智能体行为，缩短从想法到产品的周期。例如，主流加密平台 Coinbase 使用 SDK 快速搭建并部署多智能体支持系统。在企业搜索助手等领域，企业也可集成 SDK 的网页与文件搜索工具，以快速交付价值。通过卸载编排细节，开发者可将精力集中在产品特定功能上。

**降低研发成本：**从零构建智能体系统需要巨大的工程投入。Agents SDK 通过为通用需求提供现成方案来降低成本——循环管理、API 调用同步、错误处理以及面向 LLM 的格式化工具输出。其开源特性也便于定制以满足企业需求。对初创公司而言，这是福音，使其在资源有限的情况下也能构建强大的智能体驱动产品。

**可追溯与调试：**SDK 的集成追踪仪表板改变了业务应用。行业对 AI “黑箱”的担忧如今可以通过将每一步智能体行为记录与审计来缓解。如果客服智能体给出错误答案，追踪信息会显示哪个工具调用或步骤失败。OpenAI Platform 的日志/追踪界面提升了智能体的可审计性——这在受监管或内部审计约束的行业至关重要。由此，企业可更为自信地集成 AI，明确在需要时如何解释结果。

**获取 OpenAI 最新模型与工具：**使用 Agents SDK 即可利用 OpenAI 的顶级模型（例如 GPT-4）和当前工具（网页搜索、代码执行）。相比依赖较弱模型的替代方案，这带来质量优势。对需要高准确性或最新信息的应用（例如研究助手、金融分析智能体），OpenAI 模型的性能具有明显优势。随着 OpenAI 添加更多工具（暗示将引入更多集成），SDK 用户也能轻松采用。

CometAPI 完全兼容 OpenAI 接口协议，确保无缝集成。您可以避免模型与服务的依赖（锁定风险）、降低数据隐私与安全顾虑，并减少成本。依赖 OpenAI 的强大模型与工具可能价格较高且有时受限于性能。CometAPI 提供更具性价比的价格。

相关主题 [CometAPI：终极 AI 模型集成平台](https://www.cometapi.com/gpt-4-5-api/)

结论

OpenAI 通过 Responses API 等创新产品致力于推进 AI 能力。借助这些工具，企业与开发者有机会构建更智能、更具适应性且高度可靠的 AI 解决方案。这些进展指向一个未来：人工智能将在各行业持续推动有影响力的变革并解锁新的可能性。