TypeScript SDK

Эта библиотека обеспечивает удобный доступ к Claude API из TypeScript или JavaScript.

Установка

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 в настоящее время не поддерживается.

Если вас интересуют другие среды выполнения, откройте issue или проголосуйте за существующий в репозитории 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-5"
});

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

Варианты аутентификации, включая Workload Identity Federation, описаны в разделе Аутентификация. Если ваш ключ API является персональным ключом или ключом сервисного аккаунта с доступом к нескольким рабочим пространствам, укажите идентификатор рабочего пространства в заголовке запроса anthropic-workspace-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);

Документация по каждому методу, параметру запроса и полю ответа доступна в docstrings и отображается при наведении курсора в большинстве современных редакторов.

Подсчёт токенов

Вы можете увидеть точное использование для конкретного запроса через свойство ответа usage, например:

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

Потоковая передача ответов

SDK поддерживает «streaming» (потоковую передачу) ответов с использованием 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-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);

Ошибки инструментов

Чтобы сообщить модели об ошибке из инструмента, выбросьте ToolError из функции run. В отличие от обычного 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);

// Использование инструментов MCP с toolRunner
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

Функции преобразования выбрасывают UnsupportedMCPValueError, если значение MCP не поддерживается Claude API (например, неподдерживаемый тип содержимого, неподдерживаемый MIME-тип, ссылка на ресурс не по http/https).

Пакеты сообщений

Этот SDK поддерживает пакетную обработку в пространстве имён client.messages.batches.

Создание пакета

Message Batches принимает массив запросов, где каждый объект имеет идентификатор custom_id и точно такие же params запроса, как в стандартном Messages API:

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

Получение результатов пакета

После того как пакет сообщений обработан, на что указывает .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 (или объект с такой же структурой)
• Response от fetch (или объект с такой же структурой)
• 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"
  })
});

// Или, если у вас есть веб-API `File`, вы можете передать экземпляр `File`:
await client.files.upload({
  file: new File(["my bytes"], "file.txt", { type: "text/plain" })
});
// Вы также можете передать `Response` из `fetch`:
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;
    }
  });

Коды ошибок следующие:

Идентификаторы запросов

Подробнее об отладке запросов см. в разделе Идентификатор запроса.

Все объектные ответы в 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.

Этот SDK также выбрасывает ошибку, если ожидается, что непотоковый запрос займёт более примерно 10 минут. Передача stream: true или переопределение опции timeout на уровне клиента или запроса отключает эту ошибку.

Ожидаемая задержка запроса, превышающая тайм-аут для непотокового запроса, приведёт к тому, что клиент разорвёт соединение и выполнит повторную попытку, не получив ответа.

Если это поддерживается реализацией fetch, SDK устанавливает опцию TCP socket keep-alive, чтобы уменьшить влияние тайм-аутов неактивных соединений в некоторых сетях. Это можно переопределить, настроив пользовательский прокси.

Автоматическая пагинация

Методы списков в Claude API используют пагинацию. Вы можете использовать синтаксис for await ... of для перебора элементов на всех страницах:

async function fetchAllMessageBatches() {
  const allMessageBatches = [];
  // Автоматически загружает дополнительные страницы по мере необходимости.
  for await (const messageBatch of client.messages.batches.list({ limit: 20 })) {
    allMessageBatches.push(messageBatch);
  }
  return allMessageBatches;
}

В качестве альтернативы вы можете запрашивать по одной странице за раз:

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

// Для ручной постраничной навигации предусмотрены вспомогательные методы:
while (page.hasNextPage()) {
  page = await page.getNextPage();
  // ...
}

Заголовки по умолчанию

SDK автоматически отправляет заголовок anthropic-version со значением 2023-06-01.

При необходимости вы можете переопределить его, установив заголовки по умолчанию для отдельного запроса.

Имейте в виду, что это может привести к некорректным типам и другому неожиданному или неопределённому поведению 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 (например, заголовкам)

К «необработанному» Response, возвращаемому fetch(), можно получить доступ через метод .asResponse() типа APIPromise, который возвращают все методы. Этот метод возвращает результат, как только получены заголовки успешного ответа, и не потребляет тело ответа, поэтому вы можете свободно писать собственную логику разбора или потоковой передачи.

Вы также можете использовать метод .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);

Логирование

Уровни логирования

Вы можете настроить уровень логирования двумя способами:

1. Через переменную окружения ANTHROPIC_LOG
2. С помощью опции клиента 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, которые добавляют к запросам специфичные для среды выполнения опции прокси:

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-sdk: предоставляет клиент AnthropicVertex
• Bedrock: npm install @anthropic-ai/bedrock-sdk: предоставляет клиент AnthropicBedrockMantle, а также AnthropicBedrock для пути bedrock-runtime
• Claude Platform на AWS: npm install @anthropic-ai/aws-sdk: предоставляет клиент AnthropicAws. Передайте workspaceId в конструктор или установите переменную окружения ANTHROPIC_AWS_WORKSPACE_ID. Доступно в бета-версии.
• Foundry: npm install @anthropic-ai/foundry-sdk: предоставляет клиент AnthropicFoundry

Используйте AnthropicBedrockMantle для новых проектов; AnthropicBedrock остаётся для существующих приложений, использующих API Bedrock InvokeModel.

Семантическое версионирование

Этот пакет в целом следует соглашениям SemVer, хотя некоторые обратно несовместимые изменения могут выпускаться как минорные версии:

1. Изменения, затрагивающие только статические типы, без нарушения поведения во время выполнения.
2. Изменения внутренних компонентов библиотеки, которые технически являются публичными, но не предназначены и не документированы для внешнего использования.
3. Изменения, которые, как ожидается, на практике не затронут подавляющее большинство пользователей.

К обратной совместимости относятся серьёзно, чтобы вы могли рассчитывать на плавный процесс обновления.

Часто задаваемые вопросы

Часто задаваемые вопросы, issues и поддержку сообщества см. в репозитории GitHub.

Дополнительные ресурсы

• Репозиторий GitHub
• Справочник API
• Потоковая передача сообщений
• Использование инструментов с Claude