原厂 SDK 迁移
将现有 OpenAI、Anthropic 或 Gemini SDK 应用接入 AGTCloud，并系统检查兼容边界。
如果应用已经使用 OpenAI、Anthropic 或 Gemini SDK，通常可以保留原有 SDK 和业务框架，将客户端连接到 AGTCloud 的同类兼容协议。迁移不只是替换地址：鉴权、模型 ID、自动拼接路径、请求字段和响应解析都需要一起检查。
保持协议一致
OpenAI、Anthropic Messages 和 Gemini Generate Content 是三套不同协议。请在同一协议内替换服务地址；如果同时更换协议，请按照一次完整的接口重构进行设计和测试。
迁移前盘点
先记录当前应用真实使用的能力，避免只验证最简单的文本请求。
| 检查项 | 需要记录的内容 |
|---|---|
| SDK | 包名、语言、版本和同步或异步 Client |
| 协议 | Chat Completions、Responses、Messages 或 Generate Content |
| 模型 | 当前模型 ID，以及代码中是否存在模型白名单 |
| 输入 | 文本、图片、文件、系统指令和历史消息 |
| 输出 | 文本快捷属性、完整响应对象和自定义解析逻辑 |
| Streaming | 事件类型、增量拼接和结束条件 |
| 工具 | 工具定义、调用 ID、参数解析和结果回传 |
| 可靠性 | 超时、重试、限流、日志和回退策略 |
最小变更
三种 SDK 都需要确认以下配置，但填写方式由 SDK 决定。
| 配置 | 迁移动作 |
|---|---|
| API 地址 | 使用本页对应教程给出的 Origin 或 Base URL，确认 SDK 是否自动追加版本路径 |
| API Key | 从环境变量读取 AGTCloud API Key，不写入源码或仓库 |
| 模型 ID | 使用当前 API Key 可见且支持目标协议的模型 |
| 请求方法 | 保持原协议的 Client 方法，例如 chat.completions.create 或 messages.create |
| 响应读取 | 对照 AGTCloud Reference 检查文本、工具、Usage 和错误结构 |
按 SDK 迁移
OpenAI SDK 可以调用 Chat Completions 和 Responses。AGTCloud Base URL 包含 /v1。
| 迁移前 | 迁移后 |
|---|---|
| 原服务的 API Key | AGTCLOUD_API_KEY 环境变量 |
| 原服务的 Base URL 或 SDK 默认地址 | https://api.agtcloud.cn/v1 |
| 原模型名称 | 当前 API Key 可见的 MODEL_ID |
| 原有 Chat 或 Responses 方法 | 保持同一个 Client 方法 |
不要重复追加 /v1
https://api.agtcloud.cn/v1 已经包含版本路径。不要再配置成 https://api.agtcloud.cn/v1/v1，也不要填写完整的 /chat/completions 或 /responses 端点。
完整安装、Client 初始化和 Python、TypeScript 示例请参阅 OpenAI SDK。
不能只改三个配置的情况
以下场景需要调整业务代码，而不是只替换 Base URL、Key 和模型：
- 应用从 Chat Completions 改为 Responses；
- 应用跨 OpenAI、Anthropic 或 Gemini 协议迁移；
- 代码直接依赖某个 SDK 的响应类、快捷属性或流式事件；
- 工具调用使用了协议专属的定义和结果回传结构；
- 多模态内容块、系统指令或角色名称发生变化；
- SDK 自动拼接路径，而原项目传入的是完整端点 URL；
- 应用依赖原服务专属的模型发现、文件上传或托管工具。
验证迁移结果
验证最小文本请求
先发送一个不使用 Streaming、工具或多模态内容的请求。确认请求发送到预期 API 地址，并能够读取文本响应。
恢复生产所需能力
按照 Streaming、工具调用、结构化输出、多模态和多轮状态的顺序逐项恢复。每次只增加一种能力，便于定位差异。
检查非成功路径
至少验证无效 API Key、错误模型 ID、超时、限流和连接中断。确认应用能够读取状态码和错误信息，不会无限重试。
对比业务结果
不要只检查 HTTP 200。同步比较文本内容、工具参数、结束原因、Usage、流式结束条件和日志中的 Request ID。
分阶段切换与回滚
- 为新旧 Provider 保留独立配置，不在业务代码中散落地址和模型名称。
- 先让开发或测试流量使用 AGTCloud，再逐步扩大范围。
- 记录每个阶段的成功率、延迟、错误类型和功能差异。
- 保留原 Provider 配置和可控的回退开关，确认稳定后再清理旧配置。
不要依赖静默忽略
某些兼容实现可能接受未知字段但不执行对应能力。验证时需要观察真实结果和响应结构，不能只根据状态码判断字段已经生效。
下一步
- 查看 SDK 概览 选择对应教程；
- 查看 API Key、Base URL 与认证；
- 如果准备从 Chat 迁移到 Responses，请继续阅读 Chat Completions → Responses；
- 遇到状态码或请求失败时，参考 错误与排障。