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以降。
Webブラウザ：シークレット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-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);

各メソッド、リクエストパラメータ、レスポンスフィールドのドキュメントはdocstringで提供されており、ほとんどの最新エディタではホバー時に表示されます。

トークンのカウント

特定のリクエストの正確な使用量は、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スキーマまたはJSONスキーマを使用してツールへの入力を記述できます。その後、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は、「function calling」（関数呼び出し）とも呼ばれるツール使用をサポートしています。詳細については、Claudeでのツール使用を参照してください。

MCPヘルパー

このSDKは、Model Context Protocol (MCP)サーバーとの統合のためのヘルパーを提供します。これらのヘルパーはMCP型をClaude API型に変換し、MCPツール、プロンプト、リソースを扱う際のボイラープレートを削減します。

Claude APIは、ClaudeがリモートMCPサーバーに直接接続できるmcp_serversパラメータもサポートしています。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エラー処理

変換関数は、MCP値がClaude APIでサポートされていない場合（例：サポートされていないコンテンツタイプ、サポートされていない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ヘルパーの戻り値

files APIはcontent-typeを推測しないため、明示的に設定してください。

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`

リクエスト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エラーはすべてデフォルトでリトライされます。

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;

これにより、リクエストまたはクライアントレベルでオーバーライドされない限り、max_tokensパラメータによってスケーリングされた最大60分のタイムアウトになります。

これは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がスローされます。

なお、タイムアウトしたリクエストはデフォルトで2回リトライされます。

長時間のリクエスト

長時間実行されるリクエストには、ストリーミングMessages APIの使用を検討してください。

ストリーミングを使用せずに大きなmax_tokens値を設定することは避けてください。一部のネットワークでは、一定時間後にアイドル接続が切断される場合があり、Anthropicからのレスポンスを受信せずにリクエストが失敗またはタイムアウトする可能性があります。

このSDKは、非ストリーミングリクエストが約10分を超えると予想される場合にもエラーをスローします。stream: trueを渡すか、クライアントまたはリクエストレベルでtimeoutオプションをオーバーライドすると、このエラーは無効になります。

非ストリーミングリクエストの予想されるリクエストレイテンシがタイムアウトよりも長い場合、クライアントはレスポンスを受信せずに接続を終了してリトライします。

fetch実装でサポートされている場合、SDKは一部のネットワークでのアイドル接続タイムアウトの影響を軽減するために、TCPソケットキープアライブオプションを設定します。これは、カスタムプロキシを設定することでオーバーライドできます。

自動ページネーション

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;
}

あるいは、一度に1ページずつリクエストすることもできます。

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);

ロギング

すべてのログメッセージはデバッグのみを目的としています。ログメッセージの形式と内容は、リリース間で変更される可能性があります。

ログレベル

ログレベルは2つの方法で設定できます。

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関数を使用したい場合は、グローバルをポリフィルするか：

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を提供できます。

ベータ機能

ベータ機能は、早期フィードバックを得て新機能をテストするために、一般リリース前に利用可能です。Claudeのすべての機能とツールの利用可能性は、Claudeで構築する概要で確認できます。

ほとんどのベータAPI機能には、クライアントの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クライアントを提供
Claude Platform on AWS： npm install @anthropic-ai/aws-sdk：AnthropicAwsクライアントを提供。コンストラクタにworkspaceIdを渡すか、ANTHROPIC_AWS_WORKSPACE_ID環境変数を設定してください。ベータ版で利用可能です。

新規プロジェクトにはAnthropicBedrockMantleを使用してください。AnthropicBedrockは、BedrockのInvokeModel APIを使用している既存のアプリケーション向けに引き続き提供されます。

セマンティックバージョニング

このパッケージは一般的にSemVerの規約に従いますが、特定の後方互換性のない変更がマイナーバージョンとしてリリースされる場合があります。

実行時の動作を壊さずに静的型のみに影響する変更。
技術的には公開されているが、外部使用を意図またはドキュメント化されていないライブラリ内部への変更。
実際には大多数のユーザーに影響を与えないと予想される変更。

スムーズなアップグレード体験を確保するため、後方互換性は真剣に考慮されています。

よくある質問

FAQ、issue、コミュニティサポートについては、GitHubリポジトリを参照してください。

追加リソース

Was this page helpful?

CLI、SDK、ライブラリクライアントSDK

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を作成するか、既存の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-4-8"
});

console.log(message.content);

Workload Identity Federationを含む認証オプションについては、認証を参照してください。

リクエストとレスポンスの型

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);

トークンのカウント

特定のリクエストの正確な使用量は、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がスローされた場合、メッセージはテキストコンテンツブロックに変換されます。

ツール使用

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エラー処理

メッセージバッチ

このSDKは、client.messages.batches名前空間の下でMessage Batches APIをサポートしています。

バッチの作成

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ヘルパーの戻り値

files APIはcontent-typeを推測しないため、明示的に設定してください。

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

エラー処理

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`

リクエストID

リクエストのデバッグの詳細については、リクエストIDを参照してください。

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 }
);

タイムアウト

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

これは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がスローされます。

なお、タイムアウトしたリクエストはデフォルトで2回リトライされます。

長時間のリクエスト

長時間実行されるリクエストには、ストリーミングMessages APIの使用を検討してください。

自動ページネーション

async function fetchAllMessageBatches() {
  const allMessageBatches = [];
  // 必要に応じて追加のページを自動的に取得します。
  for await (const messageBatch of client.messages.batches.list({ limit: 20 })) {
    allMessageBatches.push(messageBatch);
  }
  return allMessageBatches;
}

あるいは、一度に1ページずつリクエストすることもできます。

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データへのアクセス（例：ヘッダー）

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);

ロギング

すべてのログメッセージはデバッグのみを目的としています。ログメッセージの形式と内容は、リリース間で変更される可能性があります。

ログレベル

ログレベルは2つの方法で設定できます。

ANTHROPIC_LOG環境変数を使用
logLevelクライアントオプションを使用（設定されている場合は環境変数をオーバーライドします）

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

利用可能なログレベル（詳細度の高い順）：

'debug' - デバッグメッセージ、情報、警告、エラーを表示
'info' - 情報メッセージ、警告、エラーを表示
'warn' - 警告とエラーを表示（デフォルト）
'error' - エラーのみを表示
'off' - すべてのロギングを無効化

カスタムロガー

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
});

カスタム/ドキュメント化されていないリクエストの作成

ドキュメント化されていないエンドポイント

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

追加の引数を明示的に送信したい場合は、query、body、およびheadersリクエストオプションを使用できます。

ドキュメント化されていないレスポンスプロパティ

fetchクライアントのカスタマイズ

デフォルトでは、このライブラリはグローバルなfetch関数が定義されていることを前提としています。

別のfetch関数を使用したい場合は、グローバルをポリフィルするか：

import fetch from "my-fetch";

globalThis.fetch = fetch;

またはクライアントに渡すことができます。

import fetch from "my-fetch";

const client = new Anthropic({ fetch });

Fetchオプション

const client = new Anthropic({
  fetchOptions: {
    // `RequestInit` オプション
  }
});

プロキシの設定

プロキシの動作を変更するには、ランタイム固有のプロキシオプションをリクエストに追加するカスタムfetchOptionsを提供できます。

ベータ機能

例えば、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クライアントを提供
Claude Platform on AWS： npm install @anthropic-ai/aws-sdk：AnthropicAwsクライアントを提供。コンストラクタにworkspaceIdを渡すか、ANTHROPIC_AWS_WORKSPACE_ID環境変数を設定してください。ベータ版で利用可能です。

セマンティックバージョニング

このパッケージは一般的にSemVerの規約に従いますが、特定の後方互換性のない変更がマイナーバージョンとしてリリースされる場合があります。

実行時の動作を壊さずに静的型のみに影響する変更。
技術的には公開されているが、外部使用を意図またはドキュメント化されていないライブラリ内部への変更。
実際には大多数のユーザーに影響を与えないと予想される変更。

スムーズなアップグレード体験を確保するため、後方互換性は真剣に考慮されています。

よくある質問

FAQ、issue、コミュニティサポートについては、GitHubリポジトリを参照してください。

追加リソース

Was this page helpful?

インストール

要件

使用方法

リクエストとレスポンスの型

トークンのカウント

ストリーミングレスポンス

ストリーミングヘルパー

ツールヘルパー

ツールエラー

ツール使用

MCPヘルパー

MCPエラー処理

メッセージバッチ

バッチの作成

バッチからの結果の取得

ファイルアップロード

エラー処理

リクエストID

リトライ

タイムアウト

長時間のリクエスト

自動ページネーション

デフォルトヘッダー

高度な使用方法

生のResponseデータへのアクセス（例：ヘッダー）

ロギング

ログレベル

カスタムロガー

カスタム/ドキュメント化されていないリクエストの作成

ドキュメント化されていないエンドポイント

ドキュメント化されていないリクエストパラメータ

ドキュメント化されていないレスポンスプロパティ

fetchクライアントのカスタマイズ

Fetchオプション

プロキシの設定

ベータ機能

ランタイムサポート

ブラウザでの使用

プラットフォーム統合

セマンティックバージョニング

よくある質問

追加リソース

インストール

要件

使用方法

リクエストとレスポンスの型

トークンのカウント

ストリーミングレスポンス

ストリーミングヘルパー

ツールヘルパー

ツールエラー

ツール使用

MCPヘルパー

MCPエラー処理

メッセージバッチ

バッチの作成

バッチからの結果の取得

ファイルアップロード

エラー処理

リクエストID

リトライ

タイムアウト

長時間のリクエスト

自動ページネーション

デフォルトヘッダー

高度な使用方法

生のResponseデータへのアクセス（例：ヘッダー）

ロギング

ログレベル

カスタムロガー

カスタム/ドキュメント化されていないリクエストの作成

ドキュメント化されていないエンドポイント

ドキュメント化されていないリクエストパラメータ

ドキュメント化されていないレスポンスプロパティ

fetchクライアントのカスタマイズ

Fetchオプション

プロキシの設定

ベータ機能

ランタイムサポート

ブラウザでの使用