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和错误与排障。