CLI、SDK 與函式庫用戶端 SDK

TypeScript SDK

為 Node.js、Deno、Bun 和瀏覽器環境安裝與設定 Anthropic TypeScript SDK

此函式庫提供從 TypeScript 或 JavaScript 便捷存取 Anthropic REST API 的方式。

如需包含程式碼範例的 API 功能文件，請參閱 API 參考。本頁面涵蓋 TypeScript 特定的 SDK 功能與設定。

安裝

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 上開啟或投票支持相關議題。

使用方式

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-4-8"
});

console.log(message.content);

如需了解包含「Workload Identity Federation」（工作負載身分聯合）在內的驗證選項，請參閱驗證。

請求與回應型別

此函式庫包含所有請求參數和回應欄位的 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-4-8"
};
const message: Anthropic.Message = await client.messages.create(params);

每個方法、請求參數和回應欄位的文件都可在 docstrings 中找到，並會在大多數現代編輯器中於滑鼠懸停時顯示。

計算 token 數量

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

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

串流回應

SDK 支援使用「Server Sent Events」（伺服器傳送事件），即 SSE 來進行串流回應。

const client = new Anthropic();

const stream = await client.messages.create({
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  model: "claude-opus-4-8",
  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-4-8",
    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 schemas 或 JSON Schemas 來描述工具的輸入。然後，您可以使用 client.beta.messages.toolRunner() 方法來執行這些工具。此方法會處理將所選模型產生的輸入傳遞給正確的工具，並將結果傳回給模型。

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

MCP 輔助功能

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

Claude API 也支援 mcp_servers 參數，讓 Claude 能直接連接到遠端 MCP 伺服器。當您有可透過 URL 存取的遠端伺服器且只需要工具支援時，請使用 mcp_servers。當您需要本機 MCP 伺服器、提示、資源，或對 MCP 連線有更多控制需求時，請使用 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-4-8",
  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-4-8",
  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-8",
  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 錯誤處理

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

訊息批次

此 SDK 在 client.messages.batches 命名空間下支援 Message Batches API。

建立批次

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

const batch = await client.messages.batches.create({
  requests: [
    {
      custom_id: "my-first-request",
      params: {
        model: "claude-opus-4-8",
        max_tokens: 1024,
        messages: [{ role: "user", content: "Hello, world" }]
      }
    },
    {
      custom_id: "my-second-request",
      params: {
        model: "claude-opus-4-8",
        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 "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-8"
  })
  .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-4-8"
});
console.log(message._request_id); // req_018EeWyXxfu5pfWkrYcMdjWG

重試

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

您可以使用 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-4-8"
  },
  { 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-4-8"
  },
  { timeout: 5 * 1000 }
);

逾時時，會拋出 APIConnectionTimeoutError。

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

長時間請求

對於執行時間較長的請求，請考慮使用串流 Messages API。

避免在不使用串流的情況下設定較大的 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-4-8"
  },
  { 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-4-8"
  })
  .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-4-8"
  })
  .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。如果您的記錄器無法運作，請開啟議題。

提供自訂記錄器時，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，為請求新增執行環境特定的代理選項：

Beta 功能

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

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

例如，若要使用 Files API：

const client = new Anthropic();
const response = await client.beta.messages.create({
  model: "claude-opus-4-8",
  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"]
});

執行環境支援

平台整合

如需包含程式碼範例的詳細平台設定指南，請參閱：

TypeScript SDK 支援以下平台：

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

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

語意化版本控制

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

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

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

常見問題

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

其他資源

Was this page helpful?

CLI、SDK 與函式庫用戶端 SDK

TypeScript SDK

為 Node.js、Deno、Bun 和瀏覽器環境安裝與設定 Anthropic TypeScript SDK

此函式庫提供從 TypeScript 或 JavaScript 便捷存取 Anthropic REST API 的方式。

如需包含程式碼範例的 API 功能文件，請參閱 API 參考。本頁面涵蓋 TypeScript 特定的 SDK 功能與設定。

安裝

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 上開啟或投票支持相關議題。

使用方式

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-4-8"
});

console.log(message.content);

如需了解包含「Workload Identity Federation」（工作負載身分聯合）在內的驗證選項，請參閱驗證。

請求與回應型別

此函式庫包含所有請求參數和回應欄位的 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-4-8"
};
const message: Anthropic.Message = await client.messages.create(params);

每個方法、請求參數和回應欄位的文件都可在 docstrings 中找到，並會在大多數現代編輯器中於滑鼠懸停時顯示。

計算 token 數量

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

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

串流回應

SDK 支援使用「Server Sent Events」（伺服器傳送事件），即 SSE 來進行串流回應。

const client = new Anthropic();

const stream = await client.messages.create({
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  model: "claude-opus-4-8",
  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-4-8",
    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(...) 進行串流會提供各種便利的輔助工具，包括事件處理器和累積功能。

工具輔助功能

如需工具使用的更多詳細資訊，請參閱使用 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-4-8",
  max_tokens: 1000,
  messages: [{ role: "user", content: "What is the weather in San Francisco?" }],
  tools: [weatherTool]
});

console.log(finalMessage.content);

工具錯誤

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

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-4-8",
  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-4-8",
  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-8",
  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 錯誤處理

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

訊息批次

此 SDK 在 client.messages.batches 命名空間下支援 Message Batches API。

建立批次

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

const batch = await client.messages.batches.create({
  requests: [
    {
      custom_id: "my-first-request",
      params: {
        model: "claude-opus-4-8",
        max_tokens: 1024,
        messages: [{ role: "user", content: "Hello, world" }]
      }
    },
    {
      custom_id: "my-second-request",
      params: {
        model: "claude-opus-4-8",
        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 "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-8"
  })
  .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-4-8"
});
console.log(message._request_id); // req_018EeWyXxfu5pfWkrYcMdjWG

重試

您可以使用 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-4-8"
  },
  { 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-4-8"
  },
  { timeout: 5 * 1000 }
);

逾時時，會拋出 APIConnectionTimeoutError。

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

長時間請求

對於執行時間較長的請求，請考慮使用串流 Messages API。

如果非串流請求預期會超過約 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-4-8"
  },
  { headers: { "anthropic-version": "My-Custom-Value" } }
);

進階用法

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

您也可以使用 .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-8"
  })
  .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-4-8"
  })
  .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 請求和回應都會被記錄，包括標頭和主體。某些與驗證相關的標頭會被遮蔽，但請求和回應主體中的敏感資料可能仍然可見。

自訂記錄器

提供自訂記錄器時，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" }
});

未記載的請求參數

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

對於使用 GET 動詞的請求，任何額外參數都會放在查詢字串中，所有其他請求則會將額外參數放在主體中。

如果您想明確傳送額外引數，可以使用 query、body 和 headers 請求選項來達成。

未記載的回應屬性

自訂 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，為請求新增執行環境特定的代理選項：

Beta 功能

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

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

例如，若要使用 Files API：

const client = new Anthropic();
const response = await client.beta.messages.create({
  model: "claude-opus-4-8",
  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"]
});

執行環境支援

平台整合

如需包含程式碼範例的詳細平台設定指南，請參閱：

TypeScript SDK 支援以下平台：

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

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

語意化版本控制

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

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

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

常見問題

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

其他資源

Was this page helpful?

安裝

需求

使用方式

請求與回應型別

計算 token 數量

串流回應

串流輔助工具

工具輔助功能

工具錯誤

工具使用

MCP 輔助功能

MCP 錯誤處理

訊息批次

建立批次

從批次取得結果

檔案上傳

處理錯誤

請求 ID

重試

逾時

長時間請求

自動分頁

預設標頭

進階用法

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

記錄

記錄層級

自訂記錄器

發出自訂/未記載的請求

未記載的端點

未記載的請求參數

未記載的回應屬性

自訂 fetch 用戶端

Fetch 選項

設定代理

Beta 功能

執行環境支援

瀏覽器使用

平台整合

語意化版本控制

常見問題

其他資源

安裝

需求

使用方式

請求與回應型別

計算 token 數量

串流回應

串流輔助工具

工具輔助功能

工具錯誤

工具使用

MCP 輔助功能

MCP 錯誤處理

訊息批次

建立批次

從批次取得結果

檔案上傳

處理錯誤

請求 ID

重試

逾時

長時間請求

自動分頁

預設標頭

進階用法

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

記錄

記錄層級

自訂記錄器

發出自訂/未記載的請求

未記載的端點

未記載的請求參數

未記載的回應屬性

自訂 fetch 用戶端

Fetch 選項

設定代理

Beta 功能

執行環境支援

瀏覽器使用