SDK 概览
按协议选择 OpenAI、Anthropic 或 Gemini 客户端 SDK，并完成接入前检查。
AGTCloud 提供 OpenAI、Anthropic 和 Gemini 兼容入口。已经使用相应原厂 SDK 的服务端项目，通常可以保留主要调用方式，并将 API 地址、API Key 和模型 ID 替换为 AGTCloud 配置。
SDK 只能按照其对应协议组织请求。选择前请先确认目标模型支持的协议，不要仅根据模型名称判断兼容性。
选择客户端 SDK
| SDK | 对应协议 | 鉴权方式 | 适合场景 |
|---|---|---|---|
| OpenAI SDK | Chat Completions、Responses | Bearer API Key | 已有 OpenAI SDK 项目，或需要消息对话、Typed Items、流式输出和工具调用 |
| Anthropic SDK | Anthropic Messages | x-api-key 与版本 Header | 已有 Anthropic Messages 项目，或需要 Content Blocks 和 Anthropic 工具结构 |
| Gemini SDK | Gemini Generate Content | Bearer API Key | 已有 Gemini SDK 项目，或需要 contents、parts 和 Gemini 原生内容结构 |
SDK 不会自动转换协议
OpenAI 的 messages 或 input、Anthropic 的 Content Blocks、Gemini 的 contents 和 parts 是不同的数据结构。请使用与现有业务代码一致的协议教程；如果需要跨协议重构，请先阅读原厂 SDK 迁移。
三种协议的主要区别
| 对比项 | OpenAI SDK | Anthropic SDK | Gemini SDK |
|---|---|---|---|
| 主要入口 | Chat Completions、Responses | Messages | Generate Content |
| 对话输入 | messages 或 input | messages 与 Content Blocks | contents 与 parts |
| 普通文本输出 | Chat Message 或 Responses Output Items | content 内容块 | candidates[].content.parts |
| 流式结构 | Chat Delta 或 response.* 事件 | Messages SSE 事件 | Stream Generate Content |
| 工具结构 | Function Tools 与 Responses 内置工具 | tool_use、tool_result | functionCall、functionResponse |
完整字段、枚举和响应结构应以对应 API Reference 为准。SDK 教程重点说明客户端安装、初始化和结果读取，不重复展开全部 Schema。
接入前准备
创建 API Key
前往 API Keys 页面创建 AGTCloud API Key，并将它保存在服务端环境变量或密钥管理服务中。
不要把真实 API Key 写进浏览器代码、移动端安装包、公开仓库、截图或日志。
选择服务端运行环境
Python 和 TypeScript SDK 都应运行在可信服务端环境中。安装当前稳定版 SDK，并通过项目的依赖锁文件固定实际使用的版本。
建议的验证顺序
- 安装 SDK 并确认应用能够读取 API Key。
- 配置教程给出的 Base URL，不填写完整的业务端点路径。
- 使用纯文本和最少字段发送一次非流式请求。
- 检查文本结果、结束状态和 Token 用量。
- 再按业务需要验证 Streaming、工具、多模态或结构化输出。
- 为超时、限流和服务端错误增加日志与受控重试。
协议存在不代表模型支持全部能力
同一协议下的不同模型可能具有不同的输入模态、工具、结构化输出和流式能力。请求出现字段不支持或模型不可用时，请先核对模型信息和对应 API Reference。
下一步
- 使用 OpenAI SDK 调用 Chat Completions 或 Responses。
- 使用 Anthropic SDK 调用 Messages。
- 使用 Gemini SDK 调用 Generate Content。
- 已有原厂项目可以前往原厂 SDK 迁移查看迁移检查项。
- 请求失败时，参阅错误与排障。