Claude Platform Docs
CLI、SDK、ライブラリクライアントSDK

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。
  • "node"環境を使用したJest 28以上("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-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で提供されており、ほとんどのモダンなエディタではホバー時に表示されます。

トークンのカウント

特定のリクエストの正確な使用量は、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スキーマまたは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は、関数呼び出しとしても知られるツール使用をサポートしています。詳細については、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(または同じ構造を持つオブジェクト)
  • fetchResponse(または同じ構造を持つオブジェクト)
  • fs.ReadStream
  • toFileヘルパーの戻り値

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

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

エラーコードは以下のとおりです。

ステータスコードエラータイプ
400BadRequestError
401AuthenticationError
403PermissionDeniedError
404NotFoundError
409ConflictError
422UnprocessableEntityError
429RateLimitError
>=500InternalServerError
N/AAPIConnectionError

リクエスト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;

これにより、リクエストまたはクライアントレベルで上書きされない限り、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-5"
  },
  { timeout: 5 * 1000 }
);

タイムアウト時には、APIConnectionTimeoutErrorがスローされます。

タイムアウトしたリクエストはデフォルトで2回リトライされることに注意してください。

長時間のリクエスト

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

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

非ストリーミングリクエストで予想されるリクエストの「latency」(レイテンシ)がタイムアウトより長い場合、 クライアントはレスポンスを受信することなく接続を終了してリトライします。

fetch実装でサポートされている場合、SDKはTCPソケットの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;
}

あるいは、一度に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-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);

ロギング

ログレベル

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

  1. ANTHROPIC_LOG環境変数を使用する
  2. logLevelクライアントオプションを使用する(設定されている場合、環境変数を上書きします)
const client = new Anthropic({
  logLevel: "debug" // Show all log messages
});

利用可能なログレベル(詳細度の高い順):

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

'debug'レベルでは、ヘッダーとボディを含むすべてのHTTPリクエストとレスポンスがログに記録されます。 一部の認証関連ヘッダーはマスクされますが、リクエストおよびレスポンスボディ内の機密データは 引き続き表示される可能性があります。

カスタムロガー

デフォルトでは、このライブラリはglobalThis.consoleにログを出力します。カスタムロガーを提供することもできます。 pinowinstonbunyanconsolasignale@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.getclient.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動詞を使用するリクエストでは、追加のパラメータはクエリに含まれます。その他のすべてのリクエストでは、 追加のパラメータはボディで送信されます。

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

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

ドキュメント化されていないレスポンスプロパティにアクセスするには、レスポンスオブジェクトに// @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を提供できます。

import * as undici from "undici";

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

ベータ機能

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

ほとんどのベータAPI機能には、クライアントの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-sdkAnthropicVertexクライアントを提供
  • Bedrock: npm install @anthropic-ai/bedrock-sdkAnthropicBedrockMantleクライアント、およびbedrock-runtimeパス用のAnthropicBedrockを提供
  • Claude Platform on AWS: npm install @anthropic-ai/aws-sdkAnthropicAwsクライアントを提供。コンストラクタにworkspaceIdを渡すか、ANTHROPIC_AWS_WORKSPACE_ID環境変数を設定してください。ベータ版で利用可能です。
  • Foundry: npm install @anthropic-ai/foundry-sdkAnthropicFoundryクライアントを提供

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

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

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

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

スムーズなアップグレード体験を確実に提供できるよう、後方互換性は真剣に考慮されています。

よくある質問

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

追加リソース

Was this page helpful?