Anthropic SDK

使用 Anthropic 官方 Python 或 TypeScript SDK 呼叫 AGTCloud Messages 相容介面。

Anthropic 官方 SDK 可以透過自訂 Base URL 呼叫 AGTCloud 的 Anthropic Messages 相容入口。本教學分別提供 Python 和 TypeScript 的安裝、非串流請求與串流輸出範例。

本頁只覆蓋 Messages 呼叫。批次處理、檔案、管理介面及其他 Anthropic 平台資源是否可用，應以 AGTCloud API Reference 為準。

準備工作

開始前，請確認你已經：

在 API Keys 頁面建立 AGTCloud API Key；
從模型廣場複製支援 Anthropic Messages 的完整模型 ID；
準備 Python 3.9+ 或 Node.js 20+ 的伺服器端執行環境。

本頁使用 MODEL_ID 和 your-api-key 作為預留位置。請勿在瀏覽器前端、行動裝置安裝套件或公開倉庫中儲存真實 API Key。

安裝 SDK

python -m pip install anthropic

建議安裝目前穩定版，並透過專案的相依性鎖定檔固定實際使用的版本。

設定 API Key

將 API Key 儲存到伺服器端環境變數：

export AGTCLOUD_API_KEY="your-api-key"

範例程式碼會從 AGTCLOUD_API_KEY 讀取憑證，並明確傳給 Anthropic SDK。SDK 會使用 x-api-key Header 傳送該憑證，並自動新增 Messages 請求所需的 anthropic-version Header。

建立用戶端並傳送請求

Base URL 使用本頁顯示的 API Origin，不要追加 /v1 或 /v1/messages。SDK 會在該地址後串接 Messages 路徑。

import os

from anthropic import Anthropic

api_key = os.environ["AGTCLOUD_API_KEY"]

client = Anthropic(
    api_key=api_key,
    base_url="https://api.agtcloud.cn",
)

message = client.messages.create(
    model="MODEL_ID",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "請用三句話介紹你自己。",
        }
    ],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

Anthropic Messages 的 content 是內容區塊陣列。讀取文字時應檢查內容區塊類型，不要假設回應始終只有一個文字區塊。工具呼叫、圖片和其他內容類型會使用不同的區塊結構。

串流輸出

import os

from anthropic import Anthropic

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

with client.messages.stream(
    model="MODEL_ID",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "請簡要解釋什麼是向量檢索。",
        }
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

串流 Messages 透過 SSE 事件傳回。正式環境應同時處理連線中斷、逾時、限流以及串流結束前未收到完整內容等情況。

常見問題

現象	檢查項
`401` 或 `403`	確認 `AGTCLOUD_API_KEY` 已載入、沒有多餘空格，並且憑證仍然有效
`404` 或路徑異常	`base_url` / `baseURL` 只填寫 `https://api.agtcloud.cn`，不要追加 `/v1` 或完整端點
模型不可用	將 `MODEL_ID` 替換為目前 API Key 可見且支援 Anthropic Messages 的模型 ID
請求欄位不受支援	核對目標模型能力，並參閱 Anthropic Messages Reference 的欄位定義
TypeScript 在瀏覽器中拒絕執行	Anthropic SDK 預設面向伺服器端環境；不要為了繞過限制而把 API Key 暴露給瀏覽器
串流內容為空	檢查事件類型，並確認程式碼讀取的是 `text_delta` 或 SDK 提供的文字流輔助介面

本教學使用 x-api-key

請把 AGTCloud API Key 傳入 SDK 的 api_key / apiKey 參數，由 SDK 按 Messages 協議傳送 x-api-key。不要在同一次呼叫中自行新增另一套驗證 Header。

下一步

檢視 Anthropic Messages API Reference瞭解 Content Blocks、工具呼叫、延伸思考和完整回應欄位。
已有原廠 SDK 專案可以參考原廠 SDK 移轉逐項替換設定並迴歸測試。
請求失敗時，參閱驗證與 API Key和錯誤與疑難排解。