TypeScript SDK

安装和配置适用于 Node.js、Deno、Bun 和浏览器环境的 Anthropic TypeScript SDK

此库为 TypeScript 或 JavaScript 提供对 Anthropic REST API 的便捷访问。

安装

npm install @anthropic-ai/sdk

要求

支持 TypeScript >= 4.9。

支持以下运行时：

• Node.js 20 LTS 或更高版本（非 EOL）。
• Deno v1.28.0 或更高版本。
• Bun 1.0 或更高版本。
• Cloudflare Workers。
• Vercel Edge Runtime。
• Jest 28 或更高版本，使用 "node" 环境（目前不支持 "jsdom"）。
• Nitro v2.6 或更高版本。
• Web 浏览器：默认禁用以避免暴露你的秘密 API 凭据（参见 API 密钥最佳实践）。通过显式将 dangerouslyAllowBrowser 设置为 true 来启用浏览器支持。

请注意，目前不支持 React Native。

如果你对其他运行时环境感兴趣，请在 GitHub 上提交或投票支持 issue。

用法

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env["ANTHROPIC_API_KEY"] // 这是默认值，可以省略
});

const message = await client.messages.create({
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  model: "claude-opus-4-7"
});

console.log(message.content);

有关认证选项（包括 Workload Identity Federation），请参阅认证。

请求和响应类型

此库包含所有请求参数和响应字段的 TypeScript 定义。你可以像这样导入和使用它们：

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env["ANTHROPIC_API_KEY"] // 这是默认值，可以省略
});

const params: Anthropic.MessageCreateParams = {
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  model: "claude-opus-4-7"
};
const message: Anthropic.Message = await client.messages.create(params);

每个方法、请求参数和响应字段的文档都可以在文档字符串中找到，并会在大多数现代编辑器的悬停提示中显示。

Token 计数

你可以通过 usage 响应属性查看给定请求的精确使用量，例如

const message = await client.messages.create(/* ... */);
console.log(message.usage);
// { input_tokens: 25, output_tokens: 13 }

流式响应

SDK 提供使用 Server Sent Events (SSE) 的流式响应支持。

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const stream = await client.messages.create({
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  model: "claude-opus-4-7",
  stream: true
});
for await (const messageStreamEvent of stream) {
  console.log(messageStreamEvent.type);
}

如果需要取消流，你可以从循环中 break 或调用 stream.controller.abort()。

流式辅助函数

此库为流式消息提供了多种便利功能，例如：

import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic();

const stream = anthropic.messages
  .stream({
    model: "claude-opus-4-7",
    max_tokens: 1024,
    messages: [
      {
        role: "user",
        content: "Say hello there!"
      }
    ]
  })
  .on("text", (text) => {
    console.log(text);
  });

const message = await stream.finalMessage();
console.log(message);

使用 client.messages.stream(...) 进行流式传输会暴露各种辅助函数，包括事件处理器和累积功能。

或者，你可以使用 client.messages.create({ ..., stream: true })，它只返回流中事件的异步可迭代对象，因此使用更少的内存（它不会为你构建最终消息对象）。

工具辅助函数

此 SDK 提供了辅助函数，使在 Messages API 中创建和运行工具变得容易。你可以使用 Zod 模式或 JSON Schema 来描述工具的输入。然后你可以使用 client.beta.messages.toolRunner() 方法运行这些工具。此方法会将所选模型生成的输入传递给正确的工具，并将结果传递回模型。

有关工具使用的更多详情，请参阅与 Claude 的工具使用。

import Anthropic from "@anthropic-ai/sdk";

import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
import { z } from "zod";

const anthropic = new Anthropic();

const weatherTool = betaZodTool({
  name: "get_weather",
  inputSchema: z.object({
    location: z.string()
  }),
  description: "Get the current weather in a given location",
  run: (input) => {
    return `The weather in ${input.location} is foggy and 60°F`;
  }
});

const finalMessage = await anthropic.beta.messages.toolRunner({
  model: "claude-opus-4-7",
  max_tokens: 1000,
  messages: [{ role: "user", content: "What is the weather in San Francisco?" }],
  tools: [weatherTool]
});

console.log(finalMessage.content);

工具错误

要将工具中的错误报告给模型，请从 run 函数中抛出 ToolError。与普通的 Error 不同，ToolError 接受内容块，允许你在错误响应中包含图像或其他结构化内容：

import { ToolError } from "@anthropic-ai/sdk/lib/tools/BetaRunnableTool";

const screenshotTool = betaZodTool({
  name: "take_screenshot",
  inputSchema: z.object({ url: z.string() }),
  run: async (input) => {
    if (!isValidUrl(input.url)) {
      throw new ToolError(`Invalid URL: ${input.url}`);
    }
    const result = await takeScreenshot(input.url);
    if (result.error) {
      // 包含错误截图以便模型可以看到出了什么问题
      throw new ToolError([
        { type: "text", text: `Failed to load page: ${result.error}` },
        {
          type: "image",
          source: { type: "base64", data: result.screenshot, media_type: "image/png" }
        }
      ]);
    }
    return {
      type: "image",
      source: { type: "base64", data: result.screenshot, media_type: "image/png" }
    };
  }
});

如果抛出普通的 Error，消息将被转换为文本内容块。

工具使用

此 SDK 提供工具使用支持，也称为函数调用。有关更多详情，请参阅与 Claude 的工具使用。

MCP 辅助函数

此 SDK 提供了与 Model Context Protocol (MCP) 服务器集成的辅助函数。这些辅助函数将 MCP 类型转换为 Claude API 类型，减少使用 MCP 工具、提示和资源时的样板代码。

import Anthropic from "@anthropic-ai/sdk";
import {
  mcpTools,
  mcpMessages,
  mcpResourceToContent,
  mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const anthropic = new Anthropic();

// 连接到 MCP 服务器
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);

// 使用 MCP 提示
const { messages } = await mcpClient.getPrompt({ name: "my-prompt" });
const response = await anthropic.beta.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});
console.log(response.content);

// 使用 MCP 工具配合 toolRunner
const { tools } = await mcpClient.listTools();
const finalMessage = await anthropic.beta.messages.toolRunner({
  model: "claude-opus-4-7",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Use the available tools" }],
  tools: mcpTools(tools, mcpClient)
});
console.log(finalMessage.content);

// 使用 MCP 资源作为内容
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        mcpResourceToContent(resource),
        { type: "text", text: "Summarize this document" }
      ]
    }
  ]
});

// 将 MCP 资源作为文件上传
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
await anthropic.beta.files.upload({ file: mcpResourceToFile(fileResource) });

MCP 错误处理

如果 MCP 值不被 Claude API 支持（例如不支持的内容类型、不支持的 MIME 类型、非 http/https 资源链接），转换函数会抛出 UnsupportedMCPValueError。

消息批处理

此 SDK 在 client.messages.batches 命名空间下提供消息批处理 API 支持。

创建批处理

消息批处理接受一个请求数组，其中每个对象都有一个 custom_id 标识符，以及与标准 Messages API 完全相同的请求 params：

const batch = await client.messages.batches.create({
  requests: [
    {
      custom_id: "my-first-request",
      params: {
        model: "claude-opus-4-7",
        max_tokens: 1024,
        messages: [{ role: "user", content: "Hello, world" }]
      }
    },
    {
      custom_id: "my-second-request",
      params: {
        model: "claude-opus-4-7",
        max_tokens: 1024,
        messages: [{ role: "user", content: "Hi again, friend" }]
      }
    }
  ]
});

从批处理获取结果

消息批处理处理完成后（由 .processing_status === 'ended' 表示），你可以使用 .batches.results() 访问结果

const results = await client.messages.batches.results(batch.id);
for await (const entry of results) {
  if (entry.result.type === "succeeded") {
    console.log(entry.result.message.content);
  }
}

文件上传

对应文件上传的请求参数可以以多种形式传递：

• File（或具有相同结构的对象）
• fetch Response（或具有相同结构的对象）
• fs.ReadStream
• toFile 辅助函数的返回值

显式设置 content-type，因为 files API 不会为你推断：

import fs from "fs";
import Anthropic, { toFile } from "@anthropic-ai/sdk";

const client = new Anthropic();

// 如果你可以访问 Node `fs`，使用 `fs.createReadStream()`：
await client.beta.files.upload({
  file: await toFile(fs.createReadStream("/path/to/file"), undefined, {
    type: "application/json"
  })
});

// 或者如果你有 web `File` API，你可以传递 `File` 实例：
await client.beta.files.upload({
  file: new File(["my bytes"], "file.txt", { type: "text/plain" })
});
// 你也可以传递 `fetch` `Response`：
await client.beta.files.upload({
  file: await fetch("https://somesite/file")
});

// 或 `Buffer` / `Uint8Array`
await client.beta.files.upload({
  file: await toFile(Buffer.from("my bytes"), "file", { type: "text/plain" })
});
await client.beta.files.upload({
  file: await toFile(new Uint8Array([0, 1, 2]), "file", { type: "text/plain" })
});

错误处理

当库无法连接到 API，或 API 返回非成功状态码（即 4xx 或 5xx 响应）时，会抛出 APIError 的子类：

const message = await client.messages
  .create({
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-4-7"
  })
  .catch(async (err) => {
    if (err instanceof Anthropic.APIError) {
      console.log(err.status); // 400
      console.log(err.name); // BadRequestError
      console.log(err.headers); // {server: 'nginx', ...}
    } else {
      throw err;
    }
  });

错误代码如下：

请求 ID

有关调试请求的更多信息，请参阅请求 ID。

SDK 中的所有对象响应都提供 _request_id 属性，该属性从 request-id 响应头添加，以便你可以快速记录失败的请求并向 Anthropic 报告。

const message = await client.messages.create({
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  model: "claude-opus-4-7"
});
console.log(message._request_id); // req_018EeWyXxfu5pfWkrYcMdjWG

重试

某些错误默认会自动重试 2 次，带有短暂的指数退避。连接错误（例如，由于网络连接问题）、408 请求超时、409 冲突、429 速率限制和 >=500 内部错误默认都会重试。

你可以使用 maxRetries 选项来配置或禁用此功能：

// 为所有请求配置默认值：
const client = new Anthropic({
  maxRetries: 0 // 默认为 2
});

// 或者按请求配置：
await client.messages.create(
  {
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-4-7"
  },
  { maxRetries: 5 }
);

超时

请求默认在 10 分钟后超时。但是，如果你指定了较大的 max_tokens 值并且_没有_使用流式传输，默认超时将使用以下公式动态计算：

const minimum = 10 * 60;
const calculated = (60 * 60 * maxTokens) / 128_000;
return calculated < minimum ? minimum * 1000 : calculated * 1000;

这将导致最多 60 分钟的超时，按 max_tokens 参数缩放，除非在请求或客户端级别被覆盖。

你可以使用 timeout 选项配置此值：

// 为所有请求配置默认值：
const client = new Anthropic({
  timeout: 20 * 1000 // 20 秒（默认为 10 分钟）
});

// 按请求覆盖：
await client.messages.create(
  {
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-4-7"
  },
  { timeout: 5 * 1000 }
);

超时时会抛出 APIConnectionTimeoutError。

请注意，超时的请求默认会重试两次。

长请求

避免在不使用流式传输的情况下设置较大的 max_tokens 值。某些网络可能会在一段时间后断开空闲连接，这可能导致请求失败或超时而无法收到来自 Anthropic 的响应。

如果非流式请求预计超过大约 10 分钟，SDK 也会抛出错误。传递 stream: true 或在客户端或请求级别覆盖 timeout 选项会禁用此错误。

非流式请求的预期请求延迟超过超时时间将导致客户端终止连接并在未收到响应的情况下重试。

当 fetch 实现支持时，SDK 设置了 TCP socket keep-alive 选项以减少某些网络上空闲连接超时的影响。可以通过配置自定义代理来覆盖此设置。

自动分页

Claude API 中的列表方法是分页的。你可以使用 for await ... of 语法遍历所有页面的项目：

async function fetchAllMessageBatches() {
  const allMessageBatches = [];
  // 根据需要自动获取更多页面。
  for await (const messageBatch of client.messages.batches.list({ limit: 20 })) {
    allMessageBatches.push(messageBatch);
  }
  return allMessageBatches;
}

或者，你可以一次请求单个页面：

let page = await client.messages.batches.list({ limit: 20 });
for (const messageBatch of page.data) {
  console.log(messageBatch);
}

// 提供了便捷方法用于手动分页：
while (page.hasNextPage()) {
  page = await page.getNextPage();
  // ...
}

默认头

SDK 自动发送设置为 2023-06-01 的 anthropic-version 头。

如果需要，你可以通过按请求设置默认头来覆盖它。

请注意，这样做可能导致 SDK 中的类型不正确和其他意外或未定义行为。

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const message = await client.messages.create(
  {
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-4-7"
  },
  { headers: { "anthropic-version": "My-Custom-Value" } }
);

高级用法

访问原始响应数据（例如头）

fetch() 返回的"原始" Response 可以通过所有方法返回的 APIPromise 类型上的 .asResponse() 方法访问。此方法在收到成功响应的头后立即返回，不会消耗响应体，因此你可以自由编写自定义解析或流式逻辑。

你也可以使用 .withResponse() 方法获取原始 Response 和解析后的数据。与 .asResponse() 不同，此方法会消耗响应体，在解析完成后返回。

const client = new Anthropic();

const response = await client.messages
  .create({
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-4-7"
  })
  .asResponse();
console.log(response.headers.get("X-My-Header"));
console.log(response.statusText); // 访问底层的 Response 对象

const { data: message, response: raw } = await client.messages
  .create({
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-4-7"
  })
  .withResponse();
console.log(raw.headers.get("X-My-Header"));
console.log(message.content);

日志记录

日志级别

日志级别可以通过两种方式配置：

1. 通过 ANTHROPIC_LOG 环境变量
2. 使用 logLevel 客户端选项（如果设置则覆盖环境变量）

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  logLevel: "debug" // 显示所有日志消息
});

可用的日志级别，从最详细到最不详细：

• 'debug' - 显示调试消息、信息、警告和错误
• 'info' - 显示信息消息、警告和错误
• 'warn' - 显示警告和错误（默认）
• 'error' - 仅显示错误
• 'off' - 禁用所有日志记录

在 'debug' 级别，所有 HTTP 请求和响应都会被记录，包括头和正文。某些与认证相关的头会被脱敏，但请求和响应正文中的敏感数据可能仍然可见。

自定义日志记录器

默认情况下，此库记录到 globalThis.console。你也可以提供自定义日志记录器。支持大多数日志库，包括 pino、winston、bunyan、consola、signale 和 @std/log。如果你的日志记录器不起作用，请提交 issue。

提供自定义日志记录器时，logLevel 选项仍然控制哪些消息被发出，低于配置级别的消息不会发送到你的日志记录器。

import Anthropic from "@anthropic-ai/sdk";
import pino from "pino";

const logger = pino();

const client = new Anthropic({
  logger: logger.child({ name: "Anthropic" }),
  logLevel: "debug" // 将所有消息发送到 pino，允许它过滤
});

发送自定义/未文档化的请求

此库针对已文档化 API 的便捷访问进行了类型化。如果你需要访问未文档化的端点、参数或响应属性，该库仍然可以使用。

未文档化的端点

要向未文档化的端点发送请求，你可以使用 client.get、client.post 和其他 HTTP 动词。客户端上的选项（如重试）在发送这些请求时会被遵守。

await client.post("/some/path", {
  body: { some_prop: "foo" },
  query: { some_query_arg: "bar" }
});

未文档化的请求参数

要使用未文档化的参数发送请求，你可以在未文档化的参数上使用 // @ts-expect-error。此库不会在运行时验证请求是否匹配类型，因此你发送的任何额外值都会按原样发送。

client.messages.create({
  // ...
  // @ts-expect-error baz is not yet public
  baz: "undocumented option"
});

对于使用 GET 动词的请求，任何额外参数将在查询中，所有其他请求将在正文中发送额外参数。

如果你想显式发送额外参数，可以使用 query、body 和 headers 请求选项。

未文档化的响应属性

要访问未文档化的响应属性，你可以在响应对象上使用 // @ts-expect-error，或将响应对象转换为所需的类型。与请求参数一样，SDK 不会验证或去除来自 API 的响应中的额外属性。

自定义 fetch 客户端

默认情况下，此库期望定义了全局 fetch 函数。

如果你想使用不同的 fetch 函数，你可以填充全局：

import fetch from "my-fetch";

globalThis.fetch = fetch;

或将其传递给客户端：

import Anthropic from "@anthropic-ai/sdk";
import fetch from "my-fetch";

const client = new Anthropic({ fetch });

Fetch 选项

如果你想设置自定义 fetch 选项而不覆盖 fetch 函数，你可以在创建客户端或发出请求时提供 fetchOptions 对象。（请求特定选项覆盖客户端选项。）

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  fetchOptions: {
    // `RequestInit` 选项
  }
});

配置代理

要修改代理行为，你可以提供自定义 fetchOptions，向请求添加运行时特定的代理选项：

import Anthropic from "@anthropic-ai/sdk";
import * as undici from "undici";

const proxyAgent = new undici.ProxyAgent("http://localhost:8888");
const client = new Anthropic({
  fetchOptions: {
    dispatcher: proxyAgent
  }
});

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  fetchOptions: {
    proxy: "http://localhost:8888"
  }
});

import Anthropic from "npm:@anthropic-ai/sdk";

const httpClient = Deno.createHttpClient({ proxy: { url: "http://localhost:8888" } });
const client = new Anthropic({
  fetchOptions: {
    client: httpClient
  }
});

测试功能

测试功能在正式发布前可用，以获取早期反馈和测试新功能。你可以在构建 Claude 概述中查看 Claude 所有功能和工具的可用性。

你可以通过客户端的 beta 属性访问大多数测试 API 功能。要启用特定的测试功能，你需要在创建消息时将适当的测试头添加到 betas 字段中。

例如，要使用 Files API：

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
const response = await client.beta.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "Please summarize this document for me." },
        {
          type: "document",
          source: {
            type: "file",
            file_id: "file_abc123"
          }
        }
      ]
    }
  ],
  betas: ["files-api-2025-04-14"]
});

运行时支持

浏览器使用

启用 dangerouslyAllowBrowser 选项可能是危险的，因为它会在客户端代码中暴露你的秘密 API 凭据。Web 浏览器本质上不如服务器环境安全，任何有权访问浏览器的用户都可能检查、提取和滥用这些凭据。这可能导致使用你的凭据进行未授权访问，并可能危及敏感数据或功能。

什么时候这可能不危险？

在某些场景中，启用浏览器支持可能不会带来重大风险：

• 内部工具： 如果应用程序仅在受控的内部环境中使用，且用户是受信任的，凭据暴露的风险可以得到缓解。
• 开发或调试目的： 临时启用此功能可能是可接受的，前提是凭据是短期的、不在生产环境中使用或经常轮换。

平台集成

TypeScript SDK 支持以下平台：

• Bedrock： npm install @anthropic-ai/bedrock-sdk：提供 AnthropicBedrockMantle 客户端，以及 AnthropicBedrock 用于 bedrock-runtime 路径
• Vertex AI： npm install @anthropic-ai/vertex-sdk：提供 AnthropicVertex 客户端
• Foundry： npm install @anthropic-ai/foundry-sdk：提供 AnthropicFoundry 客户端
• Claude Platform on AWS： npm install @anthropic-ai/aws-sdk：提供 AnthropicAws 客户端。向构造函数传递 workspaceId 或设置 ANTHROPIC_AWS_WORKSPACE_ID 环境变量。目前处于测试阶段。

新项目请使用 AnthropicBedrockMantle；AnthropicBedrock 保留给使用 Bedrock InvokeModel API 的现有应用程序。

语义化版本控制

此包通常遵循 SemVer 约定，但某些不向后兼容的更改可能作为次要版本发布：

1. 仅影响静态类型而不破坏运行时行为的更改。
2. 对库内部的更改，这些更改在技术上是公开的，但不打算或不对外部使用进行文档化。
3. 在实践中预计不会影响绝大多数用户的更改。

向后兼容性被认真对待，以确保你可以依赖平稳的升级体验。

常见问题

请参阅 GitHub 仓库 了解常见问题、issue 和社区支持。

附加资源

• GitHub 仓库
• API 参考
• 流式传输 Messages
• 与 Claude 的工具使用