TypeScript SDK

安裝並設定適用於 Node.js、Deno、Bun 及瀏覽器環境的 Anthropic TypeScript SDK

此函式庫提供從 TypeScript 或 JavaScript 便捷存取 Claude 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 或更高版本。
網頁瀏覽器：預設為停用，以避免暴露您的機密 API 憑證（請參閱 API 金鑰最佳實務）。將 dangerouslyAllowBrowser 明確設為 true 即可啟用瀏覽器支援。

請注意，目前不支援 React Native。

如果您對其他執行環境有興趣，請在 GitHub 儲存庫上開立 issue 或為既有 issue 投票。

使用方式

const client = new Anthropic({
  apiKey: process.env["ANTHROPIC_API_KEY"] // This is the default and can be omitted
});

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

for (const block of message.content) {
  if (block.type === "text") {
    console.log(block.text);
  }
}

如需了解包括 Workload Identity Federation（工作負載身分聯合）在內的驗證選項，請參閱驗證。如果您的 API 金鑰是可存取多個工作區的個人或服務帳戶金鑰，請在 anthropic-workspace-id 請求標頭中設定工作區 ID；選擇工作區說明了此 SDK 的逐請求選項。

請求與回應型別

此函式庫包含所有請求參數與回應欄位的 TypeScript 定義。您可以如下匯入並使用它們：

const client = new Anthropic({
  apiKey: process.env["ANTHROPIC_API_KEY"] // This is the default and can be omitted
});

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

每個方法、請求參數與回應欄位的文件皆可在 docstring 中取得，並會在大多數現代編輯器中於滑鼠懸停時顯示。

計算 token 數量

您可以透過回應的 usage 屬性查看特定請求的確切用量，例如：

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

串流回應

此 SDK 支援使用 Server Sent Events（SSE）進行「streaming」（串流）回應。

const client = new Anthropic();

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

如果您需要取消串流，可以從迴圈中 break，或呼叫 stream.controller.abort()。

串流輔助工具

此函式庫為串流訊息提供多項便利功能，例如：

const anthropic = new Anthropic();

const stream = anthropic.messages
  .stream({
    model: "claude-opus-5",
    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 schema 或 JSON Schema 來描述工具的輸入。接著您可以使用 client.beta.messages.toolRunner() 方法執行這些工具。此方法會負責將所選模型產生的輸入傳遞給正確的工具，並將結果傳回模型。

如需「tool use」（工具使用）的更多詳細資訊，請參閱使用 Claude 進行工具使用。

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-5",
  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 支援工具使用，也稱為函式呼叫（function calling）。如需更多詳細資訊，請參閱使用 Claude 進行工具使用。

MCP 輔助工具

此 SDK 提供與 Model Context Protocol（MCP）伺服器整合的輔助工具。這些輔助工具會將 MCP 型別轉換為 Claude API 型別，減少使用 MCP 工具、提示與資源時的樣板程式碼。

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-5",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});
console.log(response.content);

// 搭配 toolRunner 使用 MCP 工具
const { tools } = await mcpClient.listTools();
const finalMessage = await anthropic.beta.messages.toolRunner({
  model: "claude-opus-5",
  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-5",
  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.files.upload({ file: mcpResourceToFile(fileResource) });

MCP 錯誤處理

如果某個 MCP 值不受 Claude API 支援（例如不支援的內容類型、不支援的 MIME 類型、非 http/https 的資源連結），轉換函式會拋出 UnsupportedMCPValueError。

訊息批次

此 SDK 在 client.messages.batches 命名空間下支援批次處理。

建立批次

Message Batches 接受一個請求陣列，其中每個物件都有一個 custom_id 識別碼，以及與標準 Messages API 完全相同的請求 params：

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

取得批次結果

一旦 Message Batch 處理完成（以 .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 "node:fs";
import Anthropic, { toFile } from "@anthropic-ai/sdk";

const client = new Anthropic();

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

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

// 或是 `Buffer` / `Uint8Array`
await client.files.upload({
  file: await toFile(Buffer.from("my bytes"), "file", { type: "text/plain" })
});
await client.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-5"
  })
  .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;
    }
  });

錯誤代碼如下：

狀態碼	錯誤類型
400	`BadRequestError`
401	`AuthenticationError`
403	`PermissionDeniedError`
404	`NotFoundError`
409	`ConflictError`
422	`UnprocessableEntityError`
429	`RateLimitError`
>=500	`InternalServerError`
N/A	`APIConnectionError`

請求 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-5"
});
console.log(message._request_id); // req_018EeWyXxfu5pfWkrYcMdjWG

重試

某些錯誤預設會自動重試 2 次，並採用短暫的指數退避。連線錯誤（例如因網路連線問題）、408 Request Timeout、409 Conflict、 429 Rate Limit 以及 >=500 的內部錯誤預設皆會重試。

您可以使用 maxRetries 選項來設定或停用此行為：

// 為所有請求設定預設值：
const client = new Anthropic({
  maxRetries: 0 // default is 2
});

// 或者，針對個別請求進行設定：
await client.messages.create(
  {
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5"
  },
  { 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 seconds (default is 10 minutes)
});

// 針對個別請求覆寫：
await client.messages.create(
  {
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5"
  },
  { timeout: 5 * 1000 }
);

逾時時會拋出 APIConnectionTimeoutError。

請注意，逾時的請求預設會重試兩次。

長時間請求

請避免在未使用串流的情況下設定較大的 max_tokens 值。某些網路可能會在一段時間後中斷閒置連線，這可能導致請求失敗或逾時，而未收到來自 Anthropic 的回應。

如果預期非串流請求的時間會超過約 10 分鐘，此 SDK 也會拋出錯誤。傳遞 stream: true 或在用戶端或請求層級覆寫 timeout 選項即可停用此錯誤。

若非串流請求的預期延遲（latency）超過逾時時間，將導致用戶端終止連線並在未收到回應的情況下重試。

當 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 中出現不正確的型別以及其他非預期或未定義的行為。

const client = new Anthropic();

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

進階用法

存取原始 Response 資料（例如標頭）

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-5"
  })
  .asResponse();
console.log(response.headers.get("X-My-Header"));
console.log(response.statusText); // access the underlying Response object

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

日誌記錄

日誌層級

您可以透過兩種方式設定日誌層級：

透過 ANTHROPIC_LOG 環境變數
使用 logLevel 用戶端選項（若有設定，會覆寫環境變數）

const client = new Anthropic({
  logLevel: "debug" // Show all log messages
});

可用的日誌層級，從最詳細到最精簡：

'debug' - 顯示偵錯訊息、資訊、警告與錯誤
'info' - 顯示資訊訊息、警告與錯誤
'warn' - 顯示警告與錯誤（預設）
'error' - 僅顯示錯誤
'off' - 停用所有日誌記錄

在 'debug' 層級，所有 HTTP 請求與回應都會被記錄，包括標頭與主體。部分與驗證相關的標頭會被遮蔽，但請求與回應主體中的敏感資料仍可能可見。

自訂記錄器

預設情況下，此函式庫會記錄至 globalThis.console。您也可以提供自訂記錄器。大多數日誌函式庫皆受支援，包括 pino、winston、bunyan、consola、signale 以及 @std/log。如果您的記錄器無法運作，請開立 issue。

提供自訂記錄器時，logLevel 選項仍會控制要發出哪些訊息；低於所設定層級的訊息將不會傳送至您的記錄器。

import pino from "pino";

const logger = pino();

const client = new Anthropic({
  logger: logger.child({ name: "Anthropic" }),
  logLevel: "debug" // Send all messages to pino, allowing it to filter
});

發出自訂／未記載的請求

此函式庫的型別設計是為了便捷存取已記載的 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 函式，可以對全域進行 polyfill：

import fetch from "my-fetch";

globalThis.fetch = fetch;

或將其傳遞給用戶端：

import fetch from "my-fetch";

const client = new Anthropic({ fetch });

Fetch 選項

如果您想設定自訂 fetch 選項而不覆寫 fetch 函式，可以在建立用戶端或發出請求時提供 fetchOptions 物件。（請求專屬的選項會覆寫用戶端選項。）

const client = new Anthropic({
  fetchOptions: {
    // `RequestInit` 選項
  }
});

設定代理

若要修改代理行為，您可以提供自訂的 fetchOptions，為請求加入執行環境專屬的代理選項：

import * as undici from "undici";

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

Beta 功能

Beta 功能會在正式發布前提供，以取得早期回饋並測試新功能。您可以在使用 Claude 進行建構概覽中查看 Claude 所有功能與工具的可用性。

您可以透過用戶端的 beta 屬性存取大多數 beta API 功能。若要啟用特定的 beta 功能，您需要在建立訊息時將適當的 beta 標頭加入 betas 欄位。

例如，若要啟用上下文編輯：

const client = new Anthropic();
const response = await client.beta.messages.create({
  model: "claude-opus-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  betas: ["context-management-2025-06-27"]
});

執行環境支援

平台整合

TypeScript SDK 支援以下平台：

Agent Platform： npm install @anthropic-ai/vertex-sdk：提供 AnthropicVertex 用戶端
Bedrock： npm install @anthropic-ai/bedrock-sdk：提供 AnthropicBedrockMantle 用戶端，以及用於 bedrock-runtime 路徑的 AnthropicBedrock
Claude Platform on AWS： npm install @anthropic-ai/aws-sdk：提供 AnthropicAws 用戶端。請將 workspaceId 傳遞給建構函式，或設定 ANTHROPIC_AWS_WORKSPACE_ID 環境變數。目前為 beta 版。
Foundry： npm install @anthropic-ai/foundry-sdk：提供 AnthropicFoundry 用戶端

新專案請使用 AnthropicBedrockMantle；AnthropicBedrock 則保留給使用 Bedrock InvokeModel API 的既有應用程式。

語意化版本

此套件大致遵循 SemVer 慣例，但某些不向後相容的變更可能會以次要版本發布：

僅影響靜態型別、不破壞執行時行為的變更。
對函式庫內部的變更，這些內部在技術上是公開的，但並非為外部使用而設計或記載。
預期實際上不會影響絕大多數使用者的變更。

我們非常重視向後相容性，以確保您能享有順暢的升級體驗。

常見問題

請參閱 GitHub 儲存庫以取得常見問題、issue 與社群支援。

安裝

需求

使用方式

請求與回應型別

計算 token 數量

串流回應

串流輔助工具

工具輔助工具

工具錯誤

工具使用

MCP 輔助工具

MCP 錯誤處理

訊息批次

建立批次

取得批次結果

檔案上傳

處理錯誤

請求 ID

重試

逾時

長時間請求

自動分頁

預設標頭

進階用法

存取原始 Response 資料（例如標頭）

日誌記錄

日誌層級

自訂記錄器

發出自訂／未記載的請求

未記載的端點

未記載的請求參數

未記載的回應屬性

自訂 fetch 用戶端

Fetch 選項

設定代理

Beta 功能

執行環境支援

瀏覽器使用

平台整合

語意化版本

常見問題

其他資源

安裝

需求