OpenAI SDK

OpenAI 公式 Python および TypeScript SDK はカスタム Base URLをサポートしています。クライアントに https://api.agtcloud.cn/v1 を指定した後、同じ SDK メソッドを使用して、AGTCloud の Chat Completions および Responses 互換エンドポイントを呼び出すことができます。

このページはサーバー側アプリケーション用です。ブラウザ フロントエンド、デスクトップアプリケーション インストール パッケージ、モバイル コードは長期間安全に保存できません。実際の認証情報を持つ API Key および OpenAI クライアントは直接作成しないでください。

Chat と Responsesを選ぶ

どちらのエントリも同じ AGTCloud API Keyを使用しますが、モデルのサポート範囲が異なる場合があります。モデルがサポートするプロトコルを モデルマーケットプレイス で確認し、例の MODEL_ID を完全なモデル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 バージョンをプロジェクト ロック ファイルに書き込みます。バージョンをアップグレードするときは、クライアントの初期化、応答タイプ、およびストリーミング処理ロジックを再検証する必要があります。

API Keyを設定する

サーバー側の環境変数を通じて API Keyを提供することをお勧めします。次の設定は、セキュリティ プレースホルダーの例にすぎません。実際の展開中に、代わりにクラウド プラットフォーム キー サービスを使用できます。

export AGTCLOUD_API_KEY="your-api-key"

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",
)

Responsesを使用する

Responses は input でテキストまたは Typed Items を指定します。成功したレスポンスには、ステータス、Output Items、トークン使用量が含まれます。SDK の output_text で、レスポンス内のテキスト出力をまとめて取得できます。

response = client.responses.create(
    model="MODEL_ID",
    instructions="日本語で簡潔かつ正確に回答してください。",
    input="API 集約サービスがどのような課題の解決に適しているか、3 つのポイントで説明してください。",
)

print(response.output_text)

output_text は、通常のテキスト結果を読み取るのに適しています。関数呼び出し、検索結果、推論項目、またはその他の型を処理する必要がある場合は、Message 型を保持するだけでなく、response.output を順番に走査する必要があります。完全な構造については、OpenAI Responses Reference を参照してください。

Chat Completionsを使用する

Chat Completions は、順序付きの messages を使用します。通常のテキスト出力は、最初の Choice のアシスタントメッセージから取得します。

completion = client.chat.completions.create(
    model="MODEL_ID",
    messages=[
        {
            "role": "developer",
            "content": "日本語で簡潔かつ正確に回答してください。",
        },
        {
            "role": "user",
            "content": "API 集約サービスがどのような課題の解決に適しているか、3 つのポイントで説明してください。",
        },
    ],
)

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)

状態を引き継ぐ（プラットフォーム側の対応が必要）

モデル、アカウント、上流チャネルが応答のストレージと継続をサポートしている場合、応答の最初のラウンドを保存し、その 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 ItemとOutput Itemを送信してください。完全な履歴を維持する場合は、プレーンテキストだけをコピーするのではなく、アプリケーションに必要なメッセージ、推論、ツール呼び出しの関係も保存してください。

タイムアウト、再試行、エラー

OpenAI SDK は、HTTP エラーを対応する例外タイプに変換し、部分的な接続エラー、タイムアウト、レート制限、およびサーバー エラーに対して制限付きの自動再試行を実行します。本番アプリケーションでは、長時間の待機や繰り返しの消費を避けるために、リクエストの種類に基づいてタイムアウトと再試行の上限を明示的に設定する必要があります。

完全なAPI Key 、機密データを含むリクエスト本文、または未処理のユーザー コンテンツをログに記録しないでください。応答でリクエスト ID が提供される場合は、特定のリクエストを見つけやすくするために、その ID をエラー ログに保存することをお勧めします。

完了チェック

• クライアント Base URL は https://api.agtcloud.cn/v1 であり、重複する /v1 はなく、特定のエンドポイント パスは追加されません。
• API Key フロントエンド コードやバージョン管理を入力せずに、信頼できるサーバー環境から読み取ります。
• MODEL_ID は、現在のAPI Keyで利用可能で、対象プロトコルをサポートするモデルに置き換えられました。
• 通常のリクエストは、テキスト、ステータス、Usageを正しく読み取ります。
• ストリーミング コードは、テキストの増分、完了イベント、エラー イベントを区別できます。
• ツールまたはマルチモーダル リクエストは、対応する機能を明示的にサポートするモデルだけに送信してください。

Providerの構成を体系的に置き換える必要がある既存のプロジェクトがある場合は、公式SDKからの移行 を参照してください。チャット構造を Responses に再構築する必要がある場合は、Chat → Responses を参照してください。