TypeScript SDK

Эта библиотека предоставляет удобный доступ к Anthropic REST 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-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 и будет отображаться при наведении курсора в большинстве современных редакторов.

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

Вы можете увидеть точное использование для конкретного запроса через свойство ответа 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 Schema для описания входных данных инструмента. Затем вы можете запускать эти инструменты с помощью метода 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);

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

Чтобы сообщить модели об ошибке из инструмента, выбросьте 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-4-8",
  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-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

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

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

Этот SDK поддерживает Message Batches API в пространстве имён 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-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" }]
      }
    }
  ]
});

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

После того как пакет сообщений обработан, что обозначается условием .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 "fs";
import Anthropic, { toFile } from "@anthropic-ai/sdk";

const client = new Anthropic();

// Если у вас есть доступ к модулю `fs` в Node, используйте `fs.createReadStream()`:
await client.beta.files.upload({
  file: await toFile(fs.createReadStream("/path/to/file"), undefined, {
    type: "application/json"
  })
});

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

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

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

Дополнительную информацию об отладке запросов см. в разделе Идентификатор запроса.

Все объектные ответы в 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 — все они повторяются по умолчанию.

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

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

Длительные запросы

Избегайте установки большого значения 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-4-8"
  },
  { 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-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);

Логирование

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

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

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, которые добавляют специфичные для среды выполнения опции прокси к запросам:

Бета-функции

Бета-функции доступны до общего релиза, чтобы получить раннюю обратную связь и протестировать новую функциональность. Вы можете проверить доступность всех возможностей и инструментов 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, а также AnthropicBedrock для пути bedrock-runtime
• Vertex AI: npm install @anthropic-ai/vertex-sdk: предоставляет клиент AnthropicVertex
• Foundry: npm install @anthropic-ai/foundry-sdk: предоставляет клиент AnthropicFoundry
• Claude Platform на AWS: npm install @anthropic-ai/aws-sdk: предоставляет клиент AnthropicAws. Передайте workspaceId в конструктор или установите переменную окружения ANTHROPIC_AWS_WORKSPACE_ID. Доступно в бета-версии.

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

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

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

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

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

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

См. репозиторий на GitHub для FAQ, issues и поддержки сообщества.

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

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