CLI, SDK и библиотекиКлиентские SDK

Python SDK

Установите и настройте Anthropic Python SDK с поддержкой синхронного и асинхронного клиента

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

Документацию по функциям API с примерами кода см. в справочнике API. Эта страница охватывает специфичные для Python функции и конфигурацию SDK.

Установка

pip install anthropic

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

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

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

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

# Поддержка Microsoft Foundry включена в базовый пакет

# Для улучшенной асинхронной производительности с aiohttp
pip install "anthropic[aiohttp]"

Требования

Требуется Python 3.9 или новее.

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

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",
)

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

Рассмотрите возможность использования python-dotenv, чтобы добавить ANTHROPIC_API_KEY="my-anthropic-api-key" в ваш файл .env, чтобы ваш ключ API (API key) не хранился в системе контроля версий.

Информацию о вариантах аутентификации, включая Workload Identity Federation, см. в разделе Аутентификация.

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

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",
    )
    print(message.content)


asyncio.run(main())

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

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

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",
        )
        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",
    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",
    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",
    ) 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", messages=[{"role": "user", "content": "Hello, world"}]
)
print(count.input_tokens)  # 10

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

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

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

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

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",
    tools=[get_weather],
    messages=[
        {"role": "user", "content": "What is the weather in SF?"},
    ],
)
for message in runner:
    print(message)

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

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

Этот SDK предоставляет поддержку Message Batches API через 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",
                "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():

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.beta.files.upload(
    file=Path("/path/to/file"),
)

# Загрузка с использованием байтов
client.beta.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",
    )
except anthropic.APIConnectionError as e:
    print("The server could not be reached")
    print(e.__cause__)  # an underlying Exception, likely raised within httpx
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)

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

Код состояния	Тип ошибки
400	`BadRequestError`
401	`AuthenticationError`
403	`PermissionDeniedError`
404	`NotFoundError`
409	`ConflictError`
422	`UnprocessableEntityError`
429	`RateLimitError`
>=500	`InternalServerError`
N/A	`APIConnectionError`

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

Для получения дополнительной информации об отладке запросов см. Request ID.

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

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

В отличие от других свойств, использующих префикс _, свойство _request_id является публичным. Если не указано иное, все остальные свойства, методы и модули с префиксом _ являются приватными.

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

Определённые ошибки по умолчанию автоматически повторяются 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",
)

Тайм-ауты

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

import httpx
from anthropic import Anthropic

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

# Более детальный контроль:
client = Anthropic(
    timeout=httpx.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",
)

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

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

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

Рассмотрите возможность использования потокового Messages API для более длительных запросов.

Избегайте установки большого значения 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, установленный в 2023-06-01.

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

Переопределение заголовков по умолчанию может привести к некорректным типам и другому неожиданному или неопределённому поведению в 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",
    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",
    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, возвращаемый httpx, можно получить через свойство .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",
)

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

Эти методы возвращают объект APIResponse.

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

Подход .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",
) 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

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

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

Недокументированные конечные точки

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

import httpx

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

print(response.json())

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

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

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

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

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

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

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

import httpx
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=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

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

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

Используйте DefaultHttpxClient и DefaultAsyncHttpxClient вместо «сырых» httpx.Client и httpx.AsyncClient, чтобы гарантировать сохранение конфигурации SDK по умолчанию (такой как тайм-ауты и ограничения на соединения).

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

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

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

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

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

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

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

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

client = Anthropic()

response = 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"],
)

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

Подробные руководства по настройке платформ с примерами кода см.:

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

Провайдер	Клиент	Дополнительные зависимости
Agent Platform	`from anthropic import AnthropicVertex`	`pip install "anthropic[vertex]"`
Bedrock	`from anthropic import AnthropicBedrockMantle`	`pip install "anthropic[bedrock]"`
Bedrock (путь `bedrock-runtime`)	`from anthropic import AnthropicBedrock`	`pip install "anthropic[bedrock]"`
Claude Platform на AWS	`from anthropic import AnthropicAWS`	`pip install "anthropic[aws]"`
Foundry	`from anthropic import AnthropicFoundry`	Нет

Клиент AnthropicAWS находится в бета-версии. Передайте workspace_id в конструктор или установите переменную окружения ANTHROPIC_AWS_WORKSPACE_ID.

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

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

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

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

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

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

print(anthropic.__version__)

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

Was this page helpful?

CLI, SDK и библиотекиКлиентские SDK

Python SDK

Установите и настройте Anthropic Python SDK с поддержкой синхронного и асинхронного клиента

Установка

pip install anthropic

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

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

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

# Поддержка Microsoft Foundry включена в базовый пакет

# Для улучшенной асинхронной производительности с aiohttp
pip install "anthropic[aiohttp]"

Требования

Требуется Python 3.9 или новее.

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

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",
)

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

Информацию о вариантах аутентификации, включая Workload Identity Federation, см. в разделе Аутентификация.

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

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",
    )
    print(message.content)


asyncio.run(main())

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

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",
        )
        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",
    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",
    stream=True,
)
async for event in stream:
    print(event.type)

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

async def main() -> None:
    async with client.messages.stream(
        max_tokens=1024,
        messages=[
            {
                "role": "user",
                "content": "Say hello there!",
            }
        ],
        model="claude-opus-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())

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

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

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

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

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

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

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

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",
    tools=[get_weather],
    messages=[
        {"role": "user", "content": "What is the weather in SF?"},
    ],
)
for message in runner:
    print(message)

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

Этот SDK предоставляет поддержку Message Batches API через client.messages.batches.

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

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

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

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.beta.files.upload(
    file=Path("/path/to/file"),
)

# Загрузка с использованием байтов
client.beta.files.upload(
    file=("file.txt", b"my bytes", "text/plain"),
)

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

import anthropic
# ...
try:
    message = client.messages.create(
        max_tokens=1024,
        messages=[
            {
                "role": "user",
                "content": "Hello, Claude",
            }
        ],
        model="claude-opus-5",
    )
except anthropic.APIConnectionError as e:
    print("The server could not be reached")
    print(e.__cause__)  # an underlying Exception, likely raised within httpx
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)

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

Код состояния	Тип ошибки
400	`BadRequestError`
401	`AuthenticationError`
403	`PermissionDeniedError`
404	`NotFoundError`
409	`ConflictError`
422	`UnprocessableEntityError`
429	`RateLimitError`
>=500	`InternalServerError`
N/A	`APIConnectionError`

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

Для получения дополнительной информации об отладке запросов см. Request ID.

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

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

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

Тайм-ауты

import httpx
from anthropic import Anthropic

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

# Более детальный контроль:
client = Anthropic(
    timeout=httpx.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",
)

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

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

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

Рассмотрите возможность использования потокового Messages API для более длительных запросов.

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

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())

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, установленный в 2023-06-01.

# Установить заголовки по умолчанию для всех запросов клиента
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",
    extra_headers={"anthropic-version": "My-Custom-Value"},
)

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

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

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

Чтобы преобразовать модель 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",
    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")

Продвинутое использование

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

client = Anthropic()

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

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

Эти методы возвращают объект APIResponse.

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

with client.messages.with_streaming_response.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    model="claude-opus-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

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

Недокументированные конечные точки

import httpx

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

print(response.json())

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

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

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

import httpx
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=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

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

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

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

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

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

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

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

client = Anthropic()

response = 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"],
)

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

Подробные руководства по настройке платформ с примерами кода см.:

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

Провайдер	Клиент	Дополнительные зависимости
Agent Platform	`from anthropic import AnthropicVertex`	`pip install "anthropic[vertex]"`
Bedrock	`from anthropic import AnthropicBedrockMantle`	`pip install "anthropic[bedrock]"`
Bedrock (путь `bedrock-runtime`)	`from anthropic import AnthropicBedrock`	`pip install "anthropic[bedrock]"`
Claude Platform на AWS	`from anthropic import AnthropicAWS`	`pip install "anthropic[aws]"`
Foundry	`from anthropic import AnthropicFoundry`	Нет

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

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

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

print(anthropic.__version__)

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

Was this page helpful?

Установка

Требования

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Тайм-ауты

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

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

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

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

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

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

Обработка null и отсутствующих полей

Продвинутое использование

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Установка

Требования

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Тайм-ауты

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

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

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

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

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

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

Обработка null и отсутствующих полей

Продвинутое использование

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Установка

Требования

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Тайм-ауты

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

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

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

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

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

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

Обработка null и отсутствующих полей

Продвинутое использование

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

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

Логирование

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

Недокументированные конечные точки

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

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

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

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

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

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

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

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

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

Установка

Требования

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Тайм-ауты

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

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

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

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

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

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

Обработка null и отсутствующих полей

Продвинутое использование

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

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

Логирование

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

Недокументированные конечные точки

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

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

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

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

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

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

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

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

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