智能体实战30天 shixingxingai/openai-agents-30-day

OpenAI Agents SDK 中文学习教程

一套面向实践的 OpenAI Agents SDK（Python） 中文教程。从 Agent + Runner 两个概念起步，一路讲到工具、会话、流式、多智能体编排、人工介入、安全防护、追踪与测试。

本教程基于 Agents SDK 官方简体中文文档整理，术语译法沿用官方中文版（官方文档 ｜ GitHub 仓库 ｜ 发布说明）。

这套教程的特点

| 特点 | 说明 |
| 只讲原语，不讲概念史 | Agents SDK 只有三个核心原语——Agent / 工具（Tool）/ 安全防护措施（Guardrail），加上 Handoff（任务转移）。理解了它们，剩下都是组合 |
| 代码可直接运行 | 每段代码都是最小可运行片段，import 完整，不需要自己补 |
| 对照官方术语 | 中文讲法，但 API 名字全部保留英文原名，方便你对照官方文档与报错信息 |
| 每章都有「坑」 | 官方文档里散落的 Note/Warning 集中到各章末尾的「常见坑」表 |

学习路径

建议按阶段顺序学，每阶段结束做自测：

1. 入门（01–03）：快速上手 → Agent 与 Runner → 工具系统
2. 运行（04–06）：运行与结果 → 会话与上下文 → 流式传输
3. 编排（07–09）：多智能体编排 → 任务转移 Handoff → 人工介入 HITL
4. 工程化（10–12）：安全防护措施 → 追踪与可观测 → 测试与模型
5. 落地（13–14）：端到端实战项目 ｜ 附录：速查与面试追问

从总览与学习路线开始，那里有完整的阶段地图、预计耗时和 30 天计划。

环境准备

1. 建虚拟环境
mkdir my-agent && cd my-agent
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate

2. 安装
pip install -U openai-agents

3. 配置密钥
export OPENAI_API_KEY=sk-... # Windows PowerShell: $env:OPENAI_API_KEY="sk-..."

按需追加的可选依赖：

pip install -U "openai-agents[voice]" # 语音智能体（STT / TTS）
pip install -U "openai-agents[encrypt]" # 加密会话
pip install -U openai-agents[mcp] # MCP 服务器支持
pip install -U websockets # Responses WebSocket 传输

三条主线

主线 A「能跑通」 01 → 02 → 03 → 04 主线 B「能记住」 05（会话/上下文）→ 06（流式）主线 C「能交付」 07 → 08 → 09 → 10 → 11 → 12

官方文档速查

| 我想…… | 去官方看 |
| 查某个 API 的完整签名 | API Reference |
| 看可运行的完整示例 | examples 目录 |
| 看内置中间件/工具清单 | 工具 ／ 内置工具列表 |
| 追踪在哪儿看 | OpenAI Dashboard |
| 版本变更 | Release notes |

一句话总结每个阶段

| 阶段 | 一句话 |
| 01 快速上手 | 装好环境，跑通第一个 agent |
| 02 Agent 与 Runner | Agent 是配置，Runner 是执行引擎——分工记牢，全书都靠它 |
| 03 工具系统 | @tool 把普通函数变成模型能调的能力 |
| 04 运行与结果 | 三种 Runner.run* 怎么选，RunResult 里有什么 |
| 05 会话与上下文 | 会话管"记住什么"，上下文管"带上什么"——两件事别混 |
| 06 流式传输 | 逐 token 输出 + 语义事件流 + 中断处理 |
| 07 多智能体编排 | 两种范式的选型：管理者（as tools）vs 分流（handoff） |
| 08 任务转移 | 把控制权交给专家的四种方式与筛选器 |
| 09 人工介入 | 敏感操作"先暂停、等批准、再恢复" |
| 10 安全防护措施 | 输入/输出/工具三层防护，含触发器机制 |
| 11 追踪与可观测 | 默认开启的追踪，怎么用好它排障 |
| 12 测试与模型 | 假模型跑测试；OpenAI 与非 OpenAI 模型的接法 |
| 13 端到端实战项目 | 把工具 + 会话 + 护栏 + 追踪缝成一个能上线的服务 |
| 14 附录 | 导入速查表、术语表、面试追问与常见坑总表 |

遇到问题先查这里

- 报错看不懂 → 先查附录 A 导入速查表，多数是名字或导入路径不对。
- 行为不符合预期 → 查附录 D 常见坑总表。
- 准备面试 → 直接刷附录 C 面试高频追问，每题都带可展开的参考答案。

上一级：教程总目录（LangChain / LangGraph 教程） ｜ 从总览与学习路线开始规划进度