快速概览

OpenAI Agents SDK 提供了一个健壮的、原生 Python 框架，用于构建多智能体系统。Kody Simpson 的这套教程系列带你走完智能体开发的整个生命周期——从初始化单个智能体到编排包含交接、护栏和追踪的复杂多轮工作流。教程最终以一个深度研究项目收尾，展示了实用的智能体模式。

目标受众

  • 希望转向 AI 和智能体工程领域的 Python 开发者。
  • 希望了解 OpenAI 官方多智能体编排框架的 AI 工程师。
  • 探索如何在 LLM 驱动的应用中实现安全防线（护栏）和上下文管理的软件架构师。

环境配置 / 前置条件

  • Python 3.8+：确保拥有现代的 Python 运行环境。
  • OpenAI API Key：模型调用鉴权所必需。请将其设置为环境变量 (OPENAI_API_KEY)。
  • Agents SDK 安装：通过 pip 安装官方包：pip install openai-agents。
  • 基础 LLM 知识：熟悉系统提示词、工具调用和聊天历史等概念。

分步教程

  1. 创建智能体 (Creating Agents)：首先定义一个具有名称、指令（系统提示词）和指定模型的智能体。Agent 类是 SDK 的基础构建块。
  2. 工具调用 (Tool Calling)：通过定义 Python 函数并对其进行装饰，为智能体配备外部能力，使 LLM 能够调用它们。SDK 会自动处理序列化和执行循环。
  3. 交接 (Handoffs)：通过允许一个智能体将控制权转移给另一个智能体，实现多智能体协作。这对于路由专门任务（例如，分流智能体将任务交接给技术支持智能体）至关重要。
  4. 追踪 (Tracing)：利用 SDK 内置的追踪功能来可视化执行路径、工具调用和交接。这对于调试复杂的智能体链不可或缺。
  5. 流式输出 (Streaming)：实现 Runner.run_streamed 以实时生成事件，允许前端在发生时即时显示部分响应和工具执行情况。
  6. 护栏 (Guardrails)：强制执行输入和输出验证规则。定义在 LLM 处理用户输入之前或生成响应之后运行的验证器，以防止偏题交互或不安全输出。
  7. 上下文管理与多轮对话 (Context Management & Multiturn)：在多个对话轮次中维护状态。学习如何通过运行器传递自定义上下文对象，以便智能体可以访问用户资料、会话数据或外部数据库记录。
  8. 智能体模式与深度研究 (Agentic Patterns & Deep Research)：将所有先前的概念组合成高级架构，如编排者-工作者模式。最终项目演示了如何构建一个深度研究智能体，使其能够自主搜索、综合并报告复杂主题。

关键陷阱

  • 无限交接循环：如果没有适当的护栏或终止条件，智能体可能会无休止地相互交接。务必定义明确的退出条件。
  • 过于严格的护栏：过度的输入/输出验证可能会阻止合法的用户查询，导致智能体反复拒绝有效提示。需要在安全性和灵活性之间取得平衡。
  • 上下文膨胀：传递无限制的对话历史或庞大的上下文对象将迅速耗尽 Token 限制并增加 API 成本。请实施摘要或上下文窗口化策略。

实用检查清单

  • 在环境中设置 OPENAI_API_KEY。
  • 为每个智能体定义清晰、独特的指令，防止角色重叠。
  • 实施至少一个输入护栏以防止提示注入。
  • 在部署到生产环境之前，先在本地使用追踪功能以摸清智能体行为。
  • 在 UI 中优雅地处理流式事件，避免连接挂起。
  • 克隆官方代码库：git clone https://github.com/KodySimpson/agents-sdk。

FAQ

(见下方 FAQ 部分)

原始视频来源

实操补充：把概念落到项目里

如果你已经理解了文章前面的概念，下一步应该把它落到一个小项目中。建议选择一个边界清楚的任务：例如让智能体读取本地文档并生成迁移清单，或者让 Claude Code 修改一个单独组件并运行测试。先写出输入、输出、工具权限和验收标准，再开始执行。这样可以避免把 SDK、模型能力和业务流程混在一起，导致最后只得到一段看似完整但无法验证的说明。

落地时最重要的是分层。模型层负责理解任务和生成候选方案；工具层负责读取文件、调用 API、写入结果；编排层负责记录状态、重试失败步骤、等待人工确认；验证层负责检查输出是否满足标准。不要让一个提示词承担所有职责。只要任务会跨越多个步骤、多个工具或多个人，就应该把这些职责拆开。

常见落地误区

第一个误区是把示例代码直接搬进生产环境。教程里的代码通常省略权限、日志、幂等和异常恢复，真实项目必须补齐这些部分。第二个误区是只追求模型回答质量，却忽略输入数据质量。没有干净的上下文，再强的模型也只能猜。第三个误区是没有回滚方案。凡是会写数据库、发消息、改文件的动作，都要能追踪、能撤销、能解释。

检查清单

  • 是否明确了最终产物，而不是只说“帮我分析”？
  • 是否把工具权限限制到当前任务所需的最小集合？
  • 是否保留了中间产物，方便发现错误发生在哪一步？
  • 是否为失败、超时和人工确认设计了路径？
  • 是否有测试、schema 校验、截图或人工审查作为验收？

OpenAI Agents SDK Tutorial (FULL SERIES)

进一步练习

你可以把同一个任务分别用“纯提示词”“SDK 工具调用”“带编排的工作流”三种方式实现。比较它们的差异：纯提示词最快，但难复用；SDK 工具调用适合中等复杂度；带编排的工作流最重，但最适合长任务和生产环境。这个对比能帮助你判断什么时候该简单处理，什么时候值得引入完整架构。

Agents SDK 项目结构建议

一个可维护的 Agents SDK 项目可以按四个目录组织。agents 目录放不同角色的 Agent 定义，例如客服、研究、代码审查；tools 目录放工具封装，例如搜索、数据库读取、文件写入；guardrails 目录放输入和输出检查；workflows 目录放业务编排。这样做的好处是，模型提示词、工具权限和业务流程不会互相缠在一起。

每个 Agent 都应该有明确职责，不要把所有工具都塞给一个万能 Agent。比如研究 Agent 可以搜索和整理资料，但不能写数据库；发布 Agent 可以写 CMS，但必须收到已审核内容；审查 Agent 只负责检查格式、事实和风险。角色越清楚，越容易调试，也越容易在团队里分配责任。

Handoff 的实际使用方式

Handoff 不是炫技功能，它适合处理“当前 Agent 已经识别出任务类型，但自己不是最合适执行者”的情况。例如入口 Agent 负责判断用户意图：如果是退款问题，交给客服 Agent；如果是技术故障，交给技术支持 Agent；如果是内容发布，交给编辑 Agent。交接时要传递上下文摘要、已确认事实、未解决问题和禁止动作。

不要在没有理由的情况下频繁交接。每一次交接都会增加上下文丢失和行为不一致的风险。你可以设置交接条件：只有当任务类型明确、目标 Agent 拥有必要工具、当前 Agent 无法继续时，才允许 handoff。

Guardrails 的具体设计

护栏可以分为输入护栏和输出护栏。输入护栏检查用户请求是否包含敏感动作、越权要求或缺失关键信息。输出护栏检查回答是否包含禁止内容、是否遗漏必要字段、是否满足 JSON schema、是否需要人工确认。对于内容生成任务，还可以检查标题是否自然、正文是否足够详细、FAQ 是否有实际价值。

护栏最好返回结构化结果，例如 pass、reason、required_action。这样主流程可以决定继续、重写、请求人工确认或终止。不要只让护栏输出一段自然语言建议，否则后续流程很难可靠处理。

追踪和调试

追踪记录应该能回答五个问题：用户原始目标是什么；哪个 Agent 接手了任务；调用了哪些工具；每次工具返回了什么；最终输出为什么通过验收。没有追踪时，多智能体系统一旦出错，就只能靠猜。开启追踪后，你可以定位是提示词问题、工具问题、交接问题还是护栏问题。

最小上线版本

如果你要把 Agents SDK 用到真实业务里，建议先做一个最小上线版本。它只支持一种任务类型，只开放两三个工具，只输出固定 schema，并且所有外部副作用都需要人工确认。这个版本看起来不够炫，但最容易验证。等它在真实样本上稳定运行后，再增加更多 Agent、更多工具和自动执行动作。

上线前请准备三份材料：一份成功样例，一份失败样例，一份边界样例。成功样例用于确认主流程可用；失败样例用于测试错误恢复；边界样例用于测试护栏是否会阻止越权或低质量输出。只要这三类样例没有跑通，就不要急着让智能体接触生产数据。

维护建议

每次修改 Agent 提示词、工具说明或护栏规则后，都要重新跑旧样例。不要只看新功能是否可用，还要看旧能力有没有退化。把这些样例放进仓库或内部文档，形成轻量回归测试，长期看比临时调参更可靠。

最后请记住：智能体系统的难点不是让模型说出漂亮答案，而是让每个步骤都能被追踪、被验证、被恢复。只要这个原则成立，后续无论换模型还是换工具，整体架构都能继续演进。