TypeScript SDK

Эта библиотека предоставляет удобный доступ к REST API Anthropic из 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, см. в разделе Аутентификация.



Типы запросов и ответов

Эта библиотека включает определения 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(). Этот метод обрабатывает передачу входных данных, сгенерированных выбранной моделью, в нужный инструмент и передачу результата обратно модели.

Подробнее об использовании инструментов см. в разделе Использование инструментов с 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.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-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 (или объект с такой же структурой)
• 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.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-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;
    }
  });

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



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

Для получения дополнительной информации об отладке запросов см. Request 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;

что приведет к тайм-ауту до 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, вы можете либо заменить глобальную (polyfill):

import fetch from "my-fetch";

globalThis.fetch = fetch;

Либо передать ее клиенту:

import fetch from "my-fetch";

const client = new Anthropic({ fetch });



Опции fetch

Если вы хотите установить пользовательские опции fetch без переопределения функции fetch, вы можете предоставить объект fetchOptions при создании клиента или выполнении запроса. (Опции, специфичные для запроса, переопределяют опции клиента.)

const client = new Anthropic({
  fetchOptions: {
    // Параметры `RequestInit`
  }
});



Настройка прокси

Чтобы изменить поведение прокси, вы можете предоставить пользовательские fetchOptions, которые добавляют специфичные для среды выполнения опции прокси к запросам:

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 при создании сообщения.

Например, чтобы использовать Files API:

const client = new Anthropic();
const response = await client.beta.messages.create({
  model: "claude-opus-5",
  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 поддерживает следующие платформы:

• 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 остается для существующих приложений, использующих Bedrock InvokeModel API.



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

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

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

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



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

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



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

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