providers.md

OpenAI-compatible 服务说明

这个项目支持填写 OPENAI_BASE_URL 来使用兼容 OpenAI API 协议的服务。配置后，项目会：

• 创建 new OpenAI({ baseURL, apiKey })。
• 调用 setDefaultOpenAIClient() 让 Agents SDK 使用该客户端。
• 使用 chat_completions 模式，提高兼容概率。

推荐配置

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

如果服务要求真实 key，把 dummy 换成服务提供的 key。

能力差异

不同兼容服务的支持程度可能不同：

• 普通文本对话通常最容易兼容。
• Function tool 需要服务支持 tool/function calling。
• 结构化输出可能依赖 JSON schema 或工具调用能力。
• Handoff 本质上也会依赖模型正确选择工具。
• Tracing 的 OpenAI 控制台可视化通常只适用于官方 OpenAI API；本项目在 baseURL 模式下默认关闭 tracing 导出，避免第三方 key 触发 OpenAI tracing 401。
• lesson:07 的 Responses 风格需要官方 OpenAI API，不作为兼容服务默认课程。

排查顺序

1. 先运行 pnpm lesson:01，确认基础对话可用。
2. 再运行 pnpm lesson:02，确认工具调用可用。
3. 再运行 pnpm lesson:03，确认结构化输出可用。
4. 如果失败，检查模型名、baseURL、服务日志和兼容服务文档。