OpenAI SDK

使用 OpenAI Python 或 TypeScript SDK 调用 AGTCloud Chat Completions 与 Responses。

OpenAI 官方 Python 和 TypeScript SDK 支持自定义 Base URL。将客户端指向 https://api.agtcloud.cn/v1 后，可以使用相同的 SDK 方法调用 AGTCloud 的 Chat Completions 与 Responses 兼容入口。

本页适用于服务端应用。浏览器前端、桌面应用安装包和移动端代码无法安全保存长期 API Key，不应直接创建带有真实凭证的 OpenAI 客户端。

选择 Chat 还是 Responses

入口	适合场景	输入与输出
Responses	新应用、Typed Items、内置工具、有状态续接和语义化流式事件	`input` → `output[]`，文本可通过 SDK 的 `output_text` 便捷读取
Chat Completions	已有消息对话项目、广泛兼容的聊天客户端和函数调用	`messages` → `choices[].message`

两种入口使用相同的 AGTCloud API Key，但模型支持范围可能不同。请在模型广场确认模型支持的协议，并用完整模型 ID 替换示例中的 MODEL_ID。

准备工作

开始前，请确认已经：

在 API Keys 页面创建 AGTCloud API Key；
准备支持 Chat Completions 或 Responses 的模型 ID；
使用 Python 3.10+ 或 Node.js 22+ 的受信任服务端运行环境；
为项目启用依赖锁文件，不在生产环境中无控制地自动升级 SDK。

运行环境要求会随 SDK 版本变化。升级 SDK 前，请同时核对当前官方支持范围和项目的部署环境。

安装 SDK

python -m pip install openai

安装完成后，将实际解析出的 SDK 版本写入项目锁文件。升级版本时，应重新验证客户端初始化、响应类型和 Streaming 处理逻辑。

配置 API Key

建议通过服务端环境变量提供 API Key。下面的设置仅作为安全占位示例，实际部署时可以改用云平台密钥服务。

export AGTCLOUD_API_KEY="your-api-key"

不要把 API Key 写进客户端应用

TypeScript SDK 默认不会在浏览器中启用凭证调用。不要通过浏览器配置、公开环境变量或关闭 SDK 安全限制来绕过这一保护；应由自己的服务端调用 AGTCloud API。

创建 OpenAI 客户端

客户端 Base URL 必须填写 https://api.agtcloud.cn/v1。不要只填写 API Origin，也不要继续追加 /chat/completions 或 /responses；SDK 会根据调用的方法拼接具体路径。

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AGTCLOUD_API_KEY"],
    base_url="https://api.agtcloud.cn/v1",
)

Python SDK 使用下划线形式的 base_url。

使用 Responses

Responses 使用 input 表达文本或 Typed Items，成功响应包含状态、Output Items 和 Token 用量。SDK 提供 output_text，用于汇总响应中的文本输出。

response = client.responses.create(
    model="MODEL_ID",
    instructions="请使用简洁、准确的中文回答。",
    input="用三点说明 API 聚合服务适合解决什么问题。",
)

print(response.output_text)

output_text 适合读取普通文本结果。需要处理函数调用、搜索结果、推理项或其他类型时，应按顺序遍历 response.output，不能只保留 Message 类型。完整结构见 OpenAI Responses Reference。

使用 Chat Completions

Chat Completions 使用按顺序排列的 messages。普通文本通常位于第一个 Choice 的 Assistant Message 中。

completion = client.chat.completions.create(
    model="MODEL_ID",
    messages=[
        {
            "role": "developer",
            "content": "请使用简洁、准确的中文回答。",
        },
        {
            "role": "user",
            "content": "用三点说明 API 聚合服务适合解决什么问题。",
        },
    ],
)

print(completion.choices[0].message.content)

如果模型返回工具调用，message.content 可以为空，应改为检查 message.tool_calls。字段说明见 Chat Completions Reference。

接收流式输出

OpenAI SDK 会把 SSE 响应暴露为可迭代事件流。Responses 的事件具有明确的 type；下例只打印文本增量，业务代码还应处理完成、失败和中断状态。

stream = client.responses.create(
    model="MODEL_ID",
    input="请用一句话介绍你自己。",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

Chat 与 Responses 的流式事件不同

Chat Completions 返回 Chat Completion Chunk，并通过 choices[].delta 提供增量；Responses 返回 response.* 事件。不要用同一套事件解析器处理两种协议。完整事件结构见流式输出指南。

有状态续接（需平台支持）

当模型、账户和上游渠道支持响应存储与续接时，可以保存首轮响应，并把它的 ID 作为 previous_response_id 传入下一次请求：

first = client.responses.create(
    model="MODEL_ID",
    store=True,
    input="记住项目代号是 Aurora。",
)

second = client.responses.create(
    model="MODEL_ID",
    previous_response_id=first.id,
    input="项目代号是什么？",
)

print(second.output_text)

使用 previous_response_id 时，上一轮的 instructions 不会自动成为本轮指令。需要持续生效的行为约束，应在新请求中再次传入。

如果当前调用链不支持响应存储或续接，请由应用自行维护历史，并在下一轮 input 中提交需要保留的 Input 与 Output Items。维护完整历史时，不能只复制纯文本，还需要保留业务所需的消息、推理和工具调用关系。

超时、重试与错误

OpenAI SDK 会将 HTTP 错误转换为对应异常类型，并对部分连接错误、超时、限流和服务端错误执行有限的自动重试。生产应用仍应根据请求类型显式设置超时和重试上限，避免长时间等待或重复消耗。

现象	优先检查
`401`	环境变量是否加载、API Key 是否完整、运行进程是否读取了新值
`403`	当前 API Key 是否具有目标模型或接口权限
`404`	Base URL 是否为 `https://api.agtcloud.cn/v1`，模型是否支持当前调用入口
`429`	请求频率、并发量和账户可用额度
`5xx` 或连接失败	记录状态码和请求上下文，采用带退避与上限的重试策略
SDK 类型不包含文档字段	升级到当前稳定版 SDK，并确认所用方法与协议一致

不要在日志中记录完整 API Key、含敏感数据的请求体或未经处理的用户内容。如果响应提供 Request ID，建议在错误日志中保存该标识，便于定位具体请求。

完成检查

客户端 Base URL 为 https://api.agtcloud.cn/v1，没有重复 /v1，也没有附加具体端点路径。
API Key 从可信服务端环境读取，没有进入前端代码或版本控制。
MODEL_ID 已替换为当前 API Key 可见且支持目标入口的模型。
普通请求能够正确读取文本、状态和用量。
Streaming 代码能区分文本增量、完成事件和错误事件。
工具或多模态请求只向明确支持相应能力的模型发送。

如果已有项目需要系统性替换服务商配置，请继续阅读原厂 SDK 迁移；需要将 Chat 结构重构为 Responses 时，参阅 Chat → Responses。

本页目录