快速摘要

本教程系列提供了 OpenAI Agents SDK 的完整演练，这是一个专为构建健壮的多智能体应用而设计的框架。它涵盖了智能体系统的整个生命周期——从环境配置和基础 Agent 实例化，到复杂的编排模式、安全护栏和可观测性追踪。系列最后以一个动手实践的深度研究项目收尾，综合运用了所有概念。

适用人群

  • 希望向 AI 工程领域转型的 Python 开发者。
  • 希望使用 OpenAI 官方工具构建生产级多智能体系统的 AI 工程师。
  • 对智能体模式、工具调用和自主工作流感兴趣的爱好者及研究人员。

环境配置 / 前置条件

  1. Python 环境：确保安装了较新版本的 Python（推荐 3.8 以上）。
  2. OpenAI API 密钥：你需要一个有效的 OpenAI API 密钥，并具备兼容模型（如 GPT-4o）的访问权限。
  3. 安装 Agents SDK：通过 pip 安装 OpenAI Agents SDK。
  4. 代码仓库：从 https://github.com/KodySimpson/agents-sdk 克隆官方仓库，以便跟随代码示例操作。

分步教程

1. 环境配置

首先配置本地开发环境，安装必要的依赖项，并安全地设置你的 OpenAI API 密钥。

2. 创建 Agent

学习如何定义核心构建块：Agent 类。这包括设置 Agent 人设、编写清晰的指令以及选择合适的底层大语言模型。

3. 工具调用

为你的 Agent 赋备与外部世界交互的能力。你将定义 Python 函数，将其注册为工具，并允许 Agent 根据用户提示决定何时以及如何执行它们。

4. 交接机制

通过实现交接来探索多智能体协作。该机制允许主 Agent 将对话或任务无缝转交给更专业的 Agent，模拟现实世界中的组织工作流。

5. 追踪与可视化

调试 Agent 通常非常困难。本节介绍如何实施追踪以监控执行流、工具使用和交接路径，随后对这些追踪进行可视化以便于调试。

6. 流式输出

通过实现流式响应改善用户体验。这确保用户能实时看到部分输出，而不是等待整个智能体过程完成后才获得结果。

7. 护栏

在智能体系统中，安全性至关重要。学习实施输入和输出护栏，以防止 Agent 处理恶意提示或生成有害、偏离主题的响应。

8. 多轮对话与上下文管理

在多次用户交互中保持状态和上下文。本节教你如何管理对话历史并注入动态上下文，使 Agent 在长对话中保持连贯。

9. 智能体模式

深入高级架构模式，如编排者-工作者设置、并行执行和路由逻辑，以构建高效且可扩展的 Agent 网络。

10. 深度研究项目

在毕业项目中应用你学到的所有知识：构建一个深度研究 Agent，它能自主搜索、综合并报告复杂主题。

关键陷阱

  • 无限交接循环：定义不当的交接逻辑可能导致 Agent 之间无休止地来回传递任务。务必定义明确的终止条件。
  • 上下文窗口溢出：在多轮对话中，未管理的上下文历史可能超出大模型的 Token 限制，导致崩溃或响应截断。请实施摘要或上下文裁剪策略。
  • 过于严格的护栏：如果护栏过于激进，它们可能会拦截合法的用户查询，严重削弱 Agent 的实用性。需在安全性与灵活性之间取得平衡。
  • 工具定义模糊：如果工具描述不清晰，大模型可能无法正确调用它们或调用错误的工具。请对参数和预期结果保持明确。

Video screenshot

实践检查清单

  • 克隆仓库并安装依赖
  • 在环境变量中配置 OpenAI API 密钥
  • 定义至少两个具有不同人设的 Agent
  • 实现自定义工具并验证 Agent 的工具调用
  • 在 Agent 之间设置交接机制
  • 为你的主 Agent 添加输入/输出护栏
  • 启用追踪以监控 Agent 的决策路径
  • 测试多轮对话的上下文保留能力

原始视频来源

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

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

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

常见落地误区

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

检查清单

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

进一步练习

你可以把同一个任务分别用“纯提示词”“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 提示词、工具说明或护栏规则后，都要重新跑旧样例。不要只看新功能是否可用，还要看旧能力有没有退化。把这些样例放进仓库或内部文档，形成轻量回归测试，长期看比临时调参更可靠。

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

把这套原则写成团队规范后，新成员也能按照同样方式设计、运行和审查智能体任务，内容质量会更稳定。 也更方便日后复盘、迁移和继续优化。 持续迭代。