解读 OpenAI 的 Agents SDK：指南

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

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 的主要特性：

• Agent loop：内置 Agent 循环，负责调用工具、将结果发送给 LLM，并循环直至 LLM 完成。
• Python-first：使用内置的语言特性来编排与串联智能体，而无需学习新的抽象。
• Handoffs：用于在多个智能体之间协调与委派的强大功能。
• Guardrails：与智能体并行运行输入校验与检查，如检查失败可提前中断。
• Function tools：将任意 Python 函数转换为工具，自动生成模式并通过 Pydantic 进行验证。
• Tracing：内置追踪，支持可视化、调试与监控工作流，并可使用 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

• Log in 到 cometapi.com。如果你还不是我们的用户，请先注册
• Get the access credential API key 接口的访问凭证 API key。在个人中心的 API token 处点击“Add Token”，获取令牌键：sk-xxxxx 并提交。
• 获取本站的 URL：https://api.cometapi.com/
• 选择 OPENAI_API_KEY endpoint 发送 API 请求并设置请求体。请求方法与请求体可从我们的网站 API 文档获取。我们的网站也提供 Apifox 测试，方便你使用。

4. 设置你的 Agent

定义你的 AI 可以使用哪些工具。假设我们要启用网页搜索和文件检索：

from agent_sdk import Agent, WebSearchTool, FileRetrievalTool

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

agent = Agent(tools=)

现在，你的 Agent 已经知道如何搜索网页并获取文档。

5. 运行

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

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

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

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

Agent 循环

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

1. 使用 Agent 上设置的模型与参数、连同消息历史，调用 LLM。
2. LLM 返回响应，其中可能包含工具调用。
3. 如果响应包含最终输出，循环结束并返回该输出。
4. 如果响应包含 handoff，Agent 将切换为新 Agent，并从第 1 步继续循环。
5. 处理工具调用（如有），并追加工具响应消息。然后从第 1 步继续循环。

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

​最终输出

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

• 如果你在 Agent 上设置了 output_type，当 LLM 使用结构化输出返回该类型的数据时即视为最终输出。
• 如果没有 output_type（即纯文本响应），那么第一个不包含任何工具调用或 handoff 的 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 旨在提供一个概念性框架，展示不同智能体（例如‘分诊 Agent’或‘CRM Agent’）如何通过工具交互与委派机制协作完成任务。”

Agents SDK 的核心组件与架构

OpenAI Agents SDK 建立在简洁而稳健的一组原则之上。其核心是 Agent 的概念：它表示一个带有特定指令并具备使用多种工具能力的语言模型实例。Agent 从接收用户请求开始（如问题或任务定义），将任务分解为可能涉及使用预定义工具的子任务，最终交付完整的响应。这些 Tools 在功能上被描述为可调用的函数；借助 Agents SDK，任何 Python 函数都可以无缝作为工具使用，并通过 Pydantic 提供输入与输出的自动模式验证。例如，表示数据库查询或网页搜索的 Python 函数都可以直接集成到 Agent 的工具集中。

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

Handoff 与多智能体架构

SDK 的能力不仅限于单个 Agent。通过名为 Handoff 的特性，任务可以在多个 Agent 之间转移，使其无缝协作。例如，“分诊 Agent”可以判断入站请求的性质并委派给另一位专长 Agent，或者一个 Agent 的输出作为另一个 Agent 的输入。该系统支持由专长 Agent 分别执行更大任务不同部分的工作流，从而构建复杂的多智能体架构。OpenAI 将该工具包设计为可扩展应用，例如客户支持自动化、研究流程、多步项目、内容创作、销售运营，甚至代码审查。此外，Guardrails 通过对 Agent 输入或输出施加验证规则来增强可靠性。例如，Guardrails 可以强制参数格式合规，或在检测到异常时提前终止循环，从而降低在真实环境中低效执行或不良行为的风险。

编排与监控

除了任务执行之外，Agents SDK 还包含强大的 orchestration 功能，负责工具执行、数据流与循环管理。尽管自动化程度很高，OpenAI 依然重视透明性，为开发者提供实时监控 Agent 活动的工具。通过内置的 Tracing 功能（可在 OpenAI 控制台访问），开发者可以逐步可视化工作流，观察工具何时被调用、使用了哪些输入以及返回了哪些输出。平台利用 OpenAI 的监控基础设施，将 Agent 逻辑的执行分解为 trace 与 span，提供对 Agent 行为的细粒度洞察。这使开发者能够诊断瓶颈、调试问题、优化工作流并跟踪性能。此外，这一追踪架构还支持高级评估，从而对 Agent 的性能进行微调与持续改进。

优势

OpenAI Agents SDK 不仅适用于个人开发者，也为构建基于智能体产品的公司提供了显著优势。让我们从这些优势开始：

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

**降低开发成本：**从零开始构建智能体系统需要大量工程投入。Agents SDK 通过为常见需求提供现成方案——循环管理、API 调用同步、错误处理以及为 LLM 格式化工具输出——来降低成本。其开源属性也支持按公司需求进行定制化。这对初创企业尤为有利，使其能以有限资源构建强大的智能体驱动产品。

**可追溯性与调试：**SDK 集成的跟踪仪表盘为商业应用带来变革。业界对 AI“黑箱”的担忧如今可以通过记录与审计每个智能体步骤来缓解。如果客服智能体给出错误答案，trace 能显示是哪一步工具调用或环节失败。OpenAI 平台的日志/trace 界面提升了智能体的可审计性——这在受监管或需内部审计的行业至关重要。公司因此能更有信心地集成 AI，并在需要时解释结果。

**获取 OpenAI 最新模型与工具：**使用 Agents SDK 意味着可以利用 OpenAI 顶级模型（例如 GPT-4）与当前工具（网页搜索、代码执行）。这相较于依赖更弱模型的替代方案，在质量上具有优势。对于需要高准确度或最新信息的应用（如研究助手、金融分析智能体），OpenAI 模型的性能是一大优势。随着 OpenAI 持续新增工具（并暗示将带来更多集成），SDK 用户可以轻松采用它们。

CometAPI 完全兼容 OpenAI 接口协议，确保无缝集成。你可以避免模型与服务依赖（锁定风险）、降低数据隐私与安全顾虑，并降低成本。利用 OpenAI 强大的模型与工具可能昂贵，有时还会限制性能。CometAPI 提供更低的价格。

结论

OpenAI 致力于通过诸如 Responses API 等创新产品推进 AI 能力。借助这些工具，企业与开发者得以构建更智能、更灵活且高度可靠的 AI 解决方案。这些发展指向一个未来：人工智能将持续带来深远变革，并在各行各业解锁新的可能性。