Python SDK

Anthropic Python SDK обеспечивает удобный доступ к Claude API из приложений на Python. Он поддерживает как синхронные, так и асинхронные операции, «streaming» (потоковая передача), а также интеграции с Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), Claude Models on Google Cloud (Google managed) и Microsoft Foundry.

Установка

pip install anthropic

Для интеграций с конкретными платформами или повышения производительности асинхронного режима установите пакет с дополнительными зависимостями:

# Для поддержки Amazon Bedrock
pip install "anthropic[bedrock]"

# Для поддержки Google Cloud
pip install "anthropic[vertex]"

# Для поддержки Claude Platform on AWS
pip install "anthropic[aws]"

# Поддержка Microsoft Foundry входит в базовый пакет

# Для повышения производительности async с aiohttp
pip install "anthropic[aiohttp]"

Чтобы использовать Claude Models on Google Cloud (Anthropic managed), выполните pip install "anthropic[google_cloud]".

Требования

Требуется Python 3.10 или новее. Если вы обновляетесь с версии SDK 0.x, см. руководство по миграции на v1, где приведён список несовместимых изменений.

Использование

import os
from anthropic import Anthropic

client = Anthropic(
    # Это значение по умолчанию, его можно не указывать
    api_key=os.environ.get("ANTHROPIC_API_KEY"),
)

message = client.messages.create(
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Hello, Claude",
        }
    ],
    model="claude-opus-5-5",
)

for block in message.content:
    if block.type == "text":
        print(block.text)

Сведения о вариантах аутентификации, включая Workload Identity Federation, см. в разделе Аутентификация. Если ваш ключ API является ключом персональной или сервисной учётной записи, который не привязан к рабочему пространству, укажите идентификатор рабочего пространства в заголовке запроса anthropic-workspace-id; в разделе Выбор рабочего пространства показан вариант указания для каждого запроса в этом SDK.

Асинхронное использование

import os
import asyncio
from anthropic import AsyncAnthropic

client = AsyncAnthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY"),
)


async def main() -> None:
    message = await client.messages.create(
        max_tokens=1024,
        messages=[
            {
                "role": "user",
                "content": "Hello, Claude",
            }
        ],
        model="claude-opus-5-5",
    )
    print(message.content)


asyncio.run(main())

Использование aiohttp для лучшей параллельности

Для повышения производительности асинхронного режима вы можете использовать HTTP-бэкенд aiohttp вместо используемого по умолчанию httpx2:

import os
import asyncio
from anthropic import AsyncAnthropic, DefaultAioHttpClient


async def main() -> None:
    async with AsyncAnthropic(
        api_key=os.environ.get("ANTHROPIC_API_KEY"),
        http_client=DefaultAioHttpClient(),
    ) as client:
        message = await client.messages.create(
            max_tokens=1024,
            messages=[
                {
                    "role": "user",
                    "content": "Hello, Claude",
                }
            ],
            model="claude-opus-5-5",
        )
        print(message.content)


asyncio.run(main())

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

SDK поддерживает потоковую передачу ответов с использованием «Server-Sent Events» (события, отправляемые сервером), или SSE.

client = Anthropic()

stream = client.messages.create(
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Hello, Claude",
        }
    ],
    model="claude-opus-5-5",
    stream=True,
)
for event in stream:
    print(event.type)

Асинхронный клиент использует точно такой же интерфейс:

client = AsyncAnthropic()

stream = await client.messages.create(
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Hello, Claude",
        }
    ],
    model="claude-opus-5-5",
    stream=True,
)
async for event in stream:
    print(event.type)

Вспомогательные средства для потоковой передачи

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

async def main() -> None:
    async with client.messages.stream(
        max_tokens=1024,
        messages=[
            {
                "role": "user",
                "content": "Say hello there!",
            }
        ],
        model="claude-opus-5-5",
    ) as stream:
        async for text in stream.text_stream:
            print(text, end="", flush=True)
        print()

        message = await stream.get_final_message()
        print(message.to_json())


asyncio.run(main())

Потоковая передача с помощью client.messages.stream(...) предоставляет различные вспомогательные средства, включая накопление и события, специфичные для SDK.

В качестве альтернативы вы можете использовать client.messages.create(..., stream=True), который возвращает только итерируемый объект событий потока и использует меньше памяти (он не собирает для вас итоговый объект сообщения).

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

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

message = client.messages.create(...)
print(message.usage)
# Usage(input_tokens=25, output_tokens=13)

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

count = client.messages.count_tokens(
    model="claude-opus-5-5",
    messages=[{"role": "user", "content": "Hello, world"}],
)
print(count.input_tokens)  # 10

Использование инструментов

Этот SDK поддерживает «tool use» (использование инструментов), также известное как вызов функций. Подробнее см. в разделе Использование инструментов с Claude.

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

SDK предоставляет вспомогательные средства для определения и запуска инструментов в виде обычных функций Python. Декоратор @beta_tool генерирует схему инструмента на основе сигнатуры функции и её docstring:

import json
from anthropic import Anthropic, beta_tool

client = Anthropic()


@beta_tool
def get_weather(location: str) -> str:
    """Get the weather for a given location.

    Args:
        location: The city and state, for example, San Francisco, CA
    Returns:
        A JSON-encoded string with the location, temperature, and weather condition.
    """
    return json.dumps(
        {
            "location": location,
            "temperature": "68°F",
            "condition": "Sunny",
        }
    )


# Используйте tool_runner для автоматической обработки вызовов инструментов
runner = client.beta.messages.tool_runner(
    max_tokens=1024,
    model="claude-opus-5-5",
    tools=[get_weather],
    messages=[
        {"role": "user", "content": "What is the weather in SF?"},
    ],
)
for message in runner:
    print(message)

На каждой итерации выполняется запрос к API. Если ответ содержит вызов одного из заданных инструментов, инструмент вызывается автоматически, а результат возвращается непосредственно модели на следующей итерации.

Чтобы запустить инструмент использования браузера или инструмент использования компьютера с этим SDK, см. раздел Использование браузера и компьютера с наборами инструментов SDK.

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

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

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

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

client.messages.batches.create(
    requests=[
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-opus-5-5",
                "max_tokens": 1024,
                "messages": [{"role": "user", "content": "Hello, world"}],
            },
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-5-5",
                "max_tokens": 1024,
                "messages": [{"role": "user", "content": "Hi again, friend"}],
            },
        },
    ]
)

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

После того как пакет сообщений обработан, на что указывает .processing_status == 'ended', вы можете получить доступ к результатам с помощью .batches.results():

client = anthropic.Anthropic()
batch_id = "batch_abc123"
result_stream = client.messages.batches.results(batch_id)
for entry in result_stream:
    if entry.result.type == "succeeded":
        print(entry.result.message.content)

Загрузка файлов

Параметры запроса, соответствующие загрузке файлов, можно передавать в различных формах:

• Объект PathLike (например, pathlib.Path)
• Кортеж (filename, content, content_type)
• Файлоподобный объект BinaryIO

from pathlib import Path
from anthropic import Anthropic

client = Anthropic()

# Загрузка по пути к файлу
client.files.upload(
    file=Path("/path/to/file"),
)

# Загрузка из байтов
client.files.upload(
    file=("file.txt", b"my bytes", "text/plain"),
)

Асинхронный клиент использует точно такой же интерфейс. Если вы передаёте экземпляр PathLike, содержимое файла автоматически считывается асинхронно.

Обработка ошибок

Когда библиотеке не удаётся подключиться к API или API возвращает код состояния, отличный от успешного (то есть ответ 4xx или 5xx), выбрасывается подкласс APIError:

import anthropic
# ...
try:
    message = client.messages.create(
        max_tokens=1024,
        messages=[
            {
                "role": "user",
                "content": "Hello, Claude",
            }
        ],
        model="claude-opus-5-5",
    )
except anthropic.APIConnectionError as e:
    print("The server could not be reached")
    print(e.__cause__)  # an underlying Exception, likely raised within httpx2
except anthropic.RateLimitError as e:
    print("A 429 status code was received; we should back off a bit.")
except anthropic.APIStatusError as e:
    print("Another non-200-range status code was received")
    print(e.status_code)
    print(e.response)

Коды ошибок:

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

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

Все объектные ответы в SDK предоставляют свойство _request_id, которое берётся из заголовка ответа request-id, чтобы вы могли быстро регистрировать неудачные запросы и сообщать о них в Anthropic.

message = client.messages.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    model="claude-opus-5-5",
)
print(message._request_id)  # e.g., req_018EeWyXxfu5pfWkrYcMdjWG

Повторные попытки

Некоторые ошибки по умолчанию автоматически повторяются 2 раза с короткой экспоненциальной задержкой. Ошибки подключения (например, из-за проблем с сетевым соединением), 408 Request Timeout, 409 Conflict, 429 Rate Limit и внутренние ошибки >=500 по умолчанию повторяются.

Вы можете использовать параметр max_retries, чтобы настроить или отключить это поведение:

# Настройте значение по умолчанию для всех запросов:
client = Anthropic(
    max_retries=0,  # default is 2
)

# Или настройте для отдельного запроса:
client.with_options(max_retries=5).messages.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    model="claude-opus-5-5",
)

Тайм-ауты

По умолчанию время ожидания запросов истекает через 10 минут. Вы можете настроить это с помощью параметра timeout, который принимает число с плавающей точкой или объект httpx2.Timeout:

import httpx2
from anthropic import Anthropic

# Настройка значения по умолчанию для всех запросов:
client = Anthropic(
    timeout=20.0,  # 20 seconds (default is 10 minutes)
)

# Более детальная настройка:
client = Anthropic(
    timeout=httpx2.Timeout(60.0, read=5.0, write=10.0, connect=2.0),
)

# Переопределение для отдельного запроса:
client.with_options(timeout=5.0).messages.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    model="claude-opus-5-5",
)

При истечении тайм-аута SDK выбрасывает APITimeoutError.

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

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

Избегайте установки большого значения max_tokens без использования потоковой передачи. Некоторые сети могут разрывать неактивные соединения через определённое время, что может привести к сбою запроса или истечению тайм-аута без получения ответа от Anthropic.

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

Если ожидаемая «latency» (задержка) запроса без потоковой передачи превышает тайм-аут, клиент разорвёт соединение и повторит попытку, не получив ответа.

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

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

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

client = Anthropic()

all_batches = []
# Автоматически загружает дополнительные страницы по мере необходимости.
for batch in client.messages.batches.list(limit=20):
    all_batches.append(batch)
print(all_batches)

Для асинхронной итерации:

async def main() -> None:
    all_batches = []
    async for batch in client.messages.batches.list(limit=20):
        all_batches.append(batch)
    print(all_batches)


asyncio.run(main())

В качестве альтернативы вы можете использовать методы .has_next_page(), .next_page_info() или .get_next_page() для более детального управления работой со страницами:

first_page = await client.messages.batches.list(limit=20)

if first_page.has_next_page():
    print(f"will fetch next page using these details: {first_page.next_page_info()}")
    next_page = await first_page.get_next_page()
    print(f"number of items we just fetched: {len(next_page.data)}")

# Уберите `await` при синхронном использовании.

Или работать непосредственно с возвращёнными данными:

first_page = await client.messages.batches.list(limit=20)

print(f"next page cursor: {first_page.last_id}")
for batch in first_page.data:
    print(batch.id)

# Уберите `await` при синхронном использовании.

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

SDK автоматически отправляет заголовок anthropic-version со значением версии API для данной мажорной версии SDK (см. Семантическое версионирование).

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

# Задайте заголовки по умолчанию для всех запросов клиента
client = Anthropic(
    default_headers={"anthropic-version": "My-Custom-Value"},
)

# Или переопределите их для отдельного запроса
client.messages.with_raw_response.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    model="claude-opus-5-5",
    extra_headers={"anthropic-version": "My-Custom-Value"},
)

Система типов

Параметры запроса

Вложенные параметры запроса являются TypedDicts. Ответы являются моделями Pydantic, которые также имеют вспомогательные методы, например для сериализации обратно в JSON (v1, v2).

Типизированные запросы и ответы обеспечивают автодополнение и документацию в вашем редакторе. Если вы хотите видеть ошибки типов в VS Code, чтобы раньше обнаруживать ошибки, установите для python.analysis.typeCheckingMode значение basic.

Модели ответов

Чтобы преобразовать модель Pydantic в словарь, используйте вспомогательные методы:

message = client.messages.create(...)

# Преобразовать в строку JSON
json_str = message.to_json()

# Преобразовать в словарь
data = message.to_dict()

Различие между null и отсутствующими полями

В ответах можно различать поля, которые явно имеют значение null, и поля, которые не были возвращены (отсутствуют):

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
if response.my_field is None:
    if "my_field" not in response.model_fields_set:
        print("field was not in the response")
    else:
        print("field was null")

Расширенное использование

Доступ к необработанным данным ответа (например, к заголовкам)

К «необработанному» объекту Response, возвращаемому httpx2, можно получить доступ через свойство .with_raw_response клиента. Это полезно для доступа к заголовкам ответа или другим метаданным:

client = Anthropic()

response = client.messages.with_raw_response.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    model="claude-opus-5-5",
)

print(response.headers.get("request-id"))
message = (
    response.parse()
)  # get the object that `messages.create()` would have returned
print(message.content)

Эти методы возвращают объект APIResponse. В асинхронном клиенте они возвращают AsyncAPIResponse, а для .parse(), .read(), .text() и .json() необходимо использовать await.

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

Подход с .with_raw_response сразу считывает всё тело ответа при выполнении запроса. Чтобы вместо этого получать тело ответа потоком, используйте .with_streaming_response, который требует менеджера контекста и считывает тело ответа только при вызове .read(), .text(), .json(), .iter_bytes(), .iter_text(), .iter_lines() или .parse(). В асинхронном клиенте это асинхронные методы.

with client.messages.with_streaming_response.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    model="claude-opus-5-5",
) as response:
    print(response.headers.get("request-id"))

    for line in response.iter_lines():
        print(line)

Менеджер контекста необходим для того, чтобы ответ был надёжно закрыт.

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

SDK использует модуль стандартной библиотеки logging.

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

export ANTHROPIC_LOG=debug

Трассировка OpenTelemetry

Когда ваше приложение регистрирует провайдер трассировщика OpenTelemetry, SDK создаёт спан для каждого отправляемого запроса. Чтобы отправлять спаны на вашу платформу наблюдаемости, см. Настройка OpenTelemetry с Claude SDK.

Выполнение пользовательских/недокументированных запросов

Эта библиотека типизирована для удобного доступа к документированному API. Если вам нужен доступ к недокументированным эндпоинтам, параметрам или свойствам ответа, библиотеку всё равно можно использовать.

Недокументированные эндпоинты

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

import httpx2

response = client.post(
    "/foo",
    cast_to=httpx2.Response,
    body={"my_param": True},
)

print(response.json())

Недокументированные параметры запроса

Если вы хотите явно отправить дополнительный параметр, это можно сделать с помощью параметров запроса extra_query, extra_body и extra_headers.

Недокументированные свойства ответа

Чтобы получить доступ к недокументированным свойствам ответа, вы можете обращаться к дополнительным полям, например response.unknown_prop. Вы также можете получить все дополнительные поля модели Pydantic в виде словаря с помощью response.model_extra.

Настройка HTTP-клиента

SDK отправляет запросы с помощью httpx2 — совместимого по API форка httpx. Чтобы настроить HTTP-клиент, включая прокси и транспорты, передайте собственный клиент httpx2 в качестве http_client:

import httpx2
from anthropic import Anthropic, DefaultHttpxClient

client = Anthropic(
    # Или используйте переменную окружения `ANTHROPIC_BASE_URL`
    base_url="http://my.test.server.example.com:8083",
    http_client=DefaultHttpxClient(
        proxy="http://my.test.proxy.example.com",
        transport=httpx2.HTTPTransport(local_address="0.0.0.0"),
    ),
)

Вы также можете настроить клиент для отдельного запроса с помощью with_options():

client.with_options(http_client=DefaultHttpxClient(...))

Инструменты трассировки и мокирования, которые модифицируют сам httpx, такие как HTTPXClientInstrumentor из OpenTelemetry, интеграция httpx в Sentry, respx или pytest-httpx, по умолчанию не видят запросы SDK. Чтобы использовать их, вызовите httpx2.alias_httpx() один раз при запуске, до того как что-либо импортирует httpx. Это приводит к тому, что import httpx разрешается в httpx2 для всего процесса.

Управление HTTP-ресурсами

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

with Anthropic() as client:
    message = client.messages.create(...)

# HTTP-клиент закрывается автоматически

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

Бета-функции становятся доступны до общего выпуска, чтобы получить ранние отзывы и протестировать новую функциональность. Доступность всех возможностей и инструментов Claude можно проверить в обзоре функций.

Доступ к большинству бета-функций API можно получить через свойство beta клиента. Чтобы включить определённую бета-функцию, необходимо добавить соответствующий бета-заголовок в поле betas при создании сообщения.

Например, чтобы включить редактирование контекста:

client = Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    betas=["context-management-2025-06-27"],
)

Интеграции с платформами

Все шесть классов клиентов входят в базовый пакет anthropic:

Клиент AnthropicAWS находится в стадии бета-тестирования. Передайте workspace_id в конструктор или установите переменную окружения ANTHROPIC_AWS_WORKSPACE_ID. Клиент AnthropicGoogleCloud также находится в стадии бета-тестирования. Передайте workspace_id в конструктор или установите переменную окружения ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID. О том, как клиент определяет идентификатор рабочего пространства, см. в разделе Определение проекта, расположения и рабочего пространства.

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

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

Каждая мажорная версия этого SDK по умолчанию отправляет одну версию API в заголовке anthropic-version, и с каждой новой версией API выходит новая мажорная версия. Первая мажорная версия, отправляющая 2026-10-21, — это 2.0.0; см. Миграция на версию API 2026-10-21.

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

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

Определение установленной версии

Если вы обновились до последней версии, но не видите ожидаемых новых функций, скорее всего, ваше окружение Python всё ещё использует более старую версию. Определить версию, используемую во время выполнения, можно так:

print(anthropic.__version__)

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

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