OpenAI Agents SDK TypeScript 学习项目

这是一个用 pnpm + TypeScript 编写的 CLI 教学项目，用来学习 OpenAI Agents SDK 的核心开发方式：Agent、function tools、结构化输出、handoffs、guardrails 和 tracing。项目默认使用旧的 Chat Completions/messages 风格，最后单独加一节课介绍新的 Responses 风格。

官方文档入口：

• OpenAI Agents SDK TypeScript
• SDK configuration
• Agents guide
• Tools guide
• Handoffs guide
• Guardrails guide
• Tracing guide

先理解凭据

ChatGPT Plus 订阅不能直接当作 OpenAI API key 使用。这个项目运行 SDK 时需要下面二选一：

• OpenAI API key：从 OpenAI API 平台获取，填入 OPENAI_API_KEY。
• OpenAI-compatible 服务：填写服务提供的 OPENAI_BASE_URL、OPENAI_MODEL 和对应 key。如果服务不校验 key，可以写 OPENAI_API_KEY=dummy。

安装与配置

pnpm install
cp .env.example .env

官方 OpenAI API 示例：

OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-5.4-mini

OpenAI-compatible baseURL 示例：

OPENAI_API_KEY=dummy
OPENAI_BASE_URL=http://localhost:1234/v1
OPENAI_MODEL=your-model-name

项目默认使用 chat_completions 模式，也就是更接近旧的 messages: [{ role, content }] 风格。这样官方 OpenAI API 和多数 OpenAI-compatible 服务都能用同一套课程先跑起来。第 7 课会单独切到 responses 模式，需要官方 OpenAI API。

课程顺序

pnpm dev
pnpm lesson:01
pnpm lesson:02
pnpm lesson:03
pnpm lesson:04
pnpm lesson:05
pnpm lesson:06
pnpm lesson:07
pnpm lesson:08
pnpm lesson:09
pnpm lesson:10
pnpm lesson:11
pnpm lesson:12
pnpm lesson:13
pnpm lesson:14
pnpm lesson:15
pnpm lesson:16
pnpm lesson:17
pnpm lesson:18

推荐顺序：

1. lesson:01：理解最小 Agent。
2. lesson:02：学习 function tool。
3. lesson:03：学习结构化输出。
4. lesson:04：学习多 Agent handoff。
5. lesson:05：学习 guardrail。
6. lesson:06：学习 tracing 和调试思路。
7. lesson:07：了解新的 Responses 风格。
8. lesson:08：学习 agent as tool。
9. lesson:09：学习 session memory。
10. lesson:10：学习 streaming 输出。
11. lesson:11：学习工具错误恢复。
12. lesson:12：学习基于 context 的工具开关。
13. lesson:13：学习查看 run items 调试过程。
14. lesson:14：定位回答慢在哪里。
15. lesson:15：用小评测定位准确率问题。
16. lesson:16：对比提示词调优前后。
17. lesson:17：减少不必要工具调用来提速。
18. lesson:18：用工具 grounding 做事实校验。

文档地图

• 环境准备
• Lesson 01：Basic Agent
• Lesson 02：Function Tool
• Lesson 03：Structured Output
• Lesson 04：Handoffs
• Lesson 05：Guardrails
• Lesson 06：Tracing
• Lesson 07：Responses Style
• Lesson 08：Agent as Tool
• Lesson 09：Session Memory
• Lesson 10：Streaming Output
• Lesson 11：Tool Error Handling
• Lesson 12：Context Enabled Tools
• Lesson 13：Run Items Debug
• Lesson 14：Latency Diagnostics
• Lesson 15：Accuracy Eval
• Lesson 16：Prompt Tuning
• Lesson 17：Reduce Unnecessary Tools
• Lesson 18：Grounded Accuracy Check
• 面试手册：Agent 延迟、准确率与调优
• 兼容服务说明

常用检查

pnpm typecheck
pnpm build

如果 lesson 报认证错误，先检查 .env 是否存在、OPENAI_API_KEY 是否填写、OPENAI_BASE_URL 是否包含 /v1。