Anthropic SDK и Claude Agent SDK

Anthropic SDK — официальные клиентские библиотеки для прямой работы с Claude API. Через Messages API можно генерировать текст, обрабатывать изображения и документы, получать потоковые ответы, вызывать инструменты, запрашивать структурированный вывод и отправлять пакетные задания. Claude Agent SDK решает другую задачу: запускает готовый агентный цикл Claude Code в Python- или TypeScript-приложении.

Как выбрать подходящий инструмент

Claude Agent SDK доступен как библиотека для Python и TypeScript. Если нужен прямой вызов Claude API, используйте Client SDK и реализуйте цикл инструментов самостоятельно.

Установка и авторизация

Python

pip install anthropic

TypeScript

npm install @anthropic-ai/sdk

Клиент по умолчанию читает ключ из переменной окружения ANTHROPIC_API_KEY:

export ANTHROPIC_API_KEY=sk-ant-...

from anthropic import Anthropic

client = Anthropic()

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

Текущая линейка моделей

На 10 сентября 2026 года официальный обзор показывает четыре основные модели:

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

Messages API: минимальный рабочий вызов

Messages API принимает историю сообщений и генерирует следующий ответ ассистента. Системную инструкцию передают в верхнеуровневом поле system; отдельной роли system среди входных сообщений нет.

from anthropic import Anthropic

client = Anthropic()

response = client.messages.create(
    model='claude-sonnet-5',
    max_tokens=1024,
    system='Ты — технический ассистент. Отвечай кратко и по делу.',
    messages=[
        {
            'role': 'user',
            'content': 'Объясни разницу между REST и GraphQL',
        }
    ],
)

for block in response.content:
    if block.type == 'text':
        print(block.text)

Потоковый ответ

На уровне API поток включается параметром stream: true. В Python SDK потоковый интерфейс выглядит так:

with client.messages.stream(
    model='claude-sonnet-5',
    max_tokens=1024,
    messages=[
        {'role': 'user', 'content': 'Составь план архитектуры API'}
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end='', flush=True)

Изображения и документы

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

import base64

with open('diagram.png', 'rb') as file:
    image_data = base64.standard_b64encode(file.read()).decode()

response = client.messages.create(
    model='claude-sonnet-5',
    max_tokens=1024,
    messages=[
        {
            'role': 'user',
            'content': [
                {
                    'type': 'image',
                    'source': {
                        'type': 'base64',
                        'media_type': 'image/png',
                        'data': image_data,
                    },
                },
                {
                    'type': 'text',
                    'text': 'Опиши архитектуру на диаграмме и найди слабые места.',
                },
            ],
        }
    ],
)

Для больших файлов отдельно проверьте Files API и поддерживаемый тип документа для выбранной модели. Ограничения на размер, число страниц и формат могут меняться.

Вызов собственных инструментов

Tool use позволяет модели запросить выполнение функции вашего приложения. Модель формирует блок tool_use, а функцию выполняет ваш код. Результат возвращается отдельным блоком tool_result.

tools = [
    {
        'name': 'search_knowledge_base',
        'description': 'Найти документы во внутренней базе знаний по запросу пользователя',
        'input_schema': {
            'type': 'object',
            'properties': {
                'query': {
                    'type': 'string',
                    'description': 'Поисковый запрос',
                },
                'limit': {
                    'type': 'integer',
                    'description': 'Максимальное число результатов',
                    'default': 5,
                },
            },
            'required': ['query'],
        },
    }
]

messages = [
    {'role': 'user', 'content': 'Найди правила оформления отпуска'}
]

response = client.messages.create(
    model='claude-sonnet-5',
    max_tokens=1024,
    tools=tools,
    messages=messages,
)

Продолжение цикла можно оформить так:

import json

allowed_tool_names = {item['name'] for item in tools}
max_iterations = 10

for _ in range(max_iterations):
    if response.stop_reason != 'tool_use':
        break

    messages.append({
        'role': 'assistant',
        'content': response.content,
    })

    tool_results = []
    for block in response.content:
        if block.type != 'tool_use':
            continue
        if block.name not in allowed_tool_names:
            raise ValueError(f'Unknown tool: {block.name}')

        result = execute_function(block.name, block.input)
        tool_results.append({
            'type': 'tool_result',
            'tool_use_id': block.id,
            'content': json.dumps(result, ensure_ascii=False),
        })

    if not tool_results:
        break

    messages.append({'role': 'user', 'content': tool_results})
    response = client.messages.create(
        model='claude-sonnet-5',
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )

Структурированный JSON

Если приложению нужен ответ по заданной схеме, передайте JSON Schema через output_config.format:

import json

response = client.messages.create(
    model='claude-sonnet-5',
    max_tokens=1024,
    output_config={
        'format': {
            'type': 'json_schema',
            'schema': {
                'type': 'object',
                'properties': {
                    'persons': {
                        'type': 'array',
                        'items': {'type': 'string'},
                    },
                    'companies': {
                        'type': 'array',
                        'items': {'type': 'string'},
                    },
                    'dates': {
                        'type': 'array',
                        'items': {'type': 'string'},
                    },
                },
                'required': ['persons', 'companies', 'dates'],
                'additionalProperties': False,
            },
        }
    },
    messages=[
        {'role': 'user', 'content': text_to_analyze}
    ],
)

entities = json.loads(next(
    block.text for block in response.content if block.type == 'text'
))

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

Prompt caching: кэширование повторяющегося контекста

Prompt caching сохраняет префикс запроса: определения инструментов, системные инструкции и сообщения до контрольной точки. Это снижает задержку и стоимость повторной обработки одинакового большого контекста.

Есть два режима:

• автоматический: cache_control задаётся на уровне запроса, а контрольная точка перемещается по мере роста диалога;
• явный: cache_control ставится на конкретный блок в конце стабильного префикса.

По умолчанию используется тип ephemeral со сроком жизни 5 минут. Для сценариев с большими паузами доступен TTL 1h; запись такого кэша стоит дороже.

response = client.messages.create(
    model='claude-sonnet-5',
    max_tokens=1024,
    system=[
        {
            'type': 'text',
            'text': '<большой постоянный контекст>',
            'cache_control': {'type': 'ephemeral'},
        }
    ],
    messages=[
        {'role': 'user', 'content': 'Ответь по этому контексту'}
    ],
)

print(response.usage.cache_creation_input_tokens)
print(response.usage.cache_read_input_tokens)

Автоматический режим включается так:

response = client.messages.create(
    model='claude-sonnet-5',
    max_tokens=1024,
    cache_control={'type': 'ephemeral'},
    system='Постоянная системная инструкция',
    messages=messages,
)

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

У API есть окно обратного поиска в 20 блоков и до четырёх контрольных точек. Минимальная длина кэшируемого префикса зависит от модели и платформы; для Sonnet 5 она составляет 1024 токена. Если cache_creation_input_tokens и cache_read_input_tokens равны нулю, проверьте длину префикса и точное совпадение блоков.

Message Batches: массовая асинхронная обработка

Message Batches API подходит для суммаризации, перевода, классификации, извлечения данных и массовых проверок, которым не нужен немедленный ответ. Пакетная обработка стоит на 50% дешевле стандартных вызовов Messages API.

Ограничения на дату проверки:

• до 100 000 запросов или 256 MB в одном batch, в зависимости от того, какой предел достигнут раньше;
• большинство пакетов завершается менее чем за час, предельное окно обработки составляет 24 часа;
• результаты доступны 29 дней после создания;
• custom_id должен быть уникальным и содержать от 1 до 64 букв, цифр, дефисов или подчёркиваний;
• результаты могут приходить не в порядке исходных запросов;
• внутри batch не поддерживаются stream: true, Fast mode и max_tokens: 0;
• для каждого элемента batch значение max_tokens должно быть не меньше 1.

from anthropic import Anthropic
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = Anthropic()

batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id='post-1',
            params=MessageCreateParamsNonStreaming(
                model='claude-sonnet-5',
                max_tokens=1024,
                messages=[
                    {
                        'role': 'user',
                        'content': 'Суммаризируй текст...',
                    }
                ],
            ),
        ),
        Request(
            custom_id='post-2',
            params=MessageCreateParamsNonStreaming(
                model='claude-sonnet-5',
                max_tokens=1024,
                messages=[
                    {
                        'role': 'user',
                        'content': 'Извлеки ключевые факты...',
                    }
                ],
            ),
        ),
    ]
)

print(batch.id, batch.processing_status)

После завершения обрабатывайте каждую запись по custom_id и типу результата: succeeded, errored, canceled или expired.

for entry in client.messages.batches.results(batch.id):
    print(entry.custom_id, entry.result.type)

Prompt caching можно сочетать с batch. Попадания в кэш при параллельной асинхронной обработке предоставляются на основе доступности, поэтому для общего контекста имеет смысл рассмотреть TTL 1h и одинаковые контрольные точки во всех запросах.

MCP и внешние инструменты

Model Context Protocol, или MCP, стандартизирует подключение внешних инструментов и источников данных. В экосистеме Claude MCP упоминается как интеграция API и как возможность Agent SDK.

MCP-интерфейсы и beta-заголовки меняются. Перед реализацией сверяйте формат запроса с актуальной документацией Anthropic для выбранной интеграции.

Claude Agent SDK

Claude Agent SDK запускает в приложении тот же агентный цикл и механизмы управления контекстом, которые использует Claude Code. SDK предоставляет встроенные инструменты для чтения и изменения файлов, выполнения команд и веб-поиска, а также hooks, дочерних агентов, MCP, разрешения и возобновляемые сессии.

Выбирайте Agent SDK, когда задача требует самостоятельного планирования нескольких шагов и работы со средой. Для обычного чат-бота или строго управляемого бизнес-процесса часто проще использовать Client SDK и собственный цикл инструментов.

Для долгих асинхронных агентов, где Anthropic управляет средой и сессиями, документация предлагает отдельно рассматривать Managed Agents. Это другой продукт, а не режим Claude Agent SDK.

Ошибки, таймауты и повторные попытки

Обрабатывайте как минимум четыре класса сбоев:

• сетевые ошибки и таймауты;
• ограничение частоты запросов;
• ошибки запроса, которые нельзя исправить повтором;
• временные серверные ошибки и перегрузку.

Параметры ретраев, таймаутов и названия исключений зависят от версии SDK. Общая схема выглядит так:

import anthropic

client = anthropic.Anthropic(
    max_retries=5,
    timeout=30.0,
)

try:
    response = client.messages.create(
        model='claude-sonnet-5',
        max_tokens=1024,
        messages=[{'role': 'user', 'content': 'Привет'}],
    )
except anthropic.RateLimitError:
    # Поставить запрос в очередь или повторить позже с backoff
    ...
except anthropic.APIStatusError as error:
    print(error.status_code, error.response)
except anthropic.APIConnectionError:
    # Проверить сеть и политику повторов
    ...

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

Полезные сценарии

Ответы по внутренней базе знаний

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

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

Извлечение данных из документов

Исходные данные: текст или поддерживаемый документ и JSON Schema. Приложение запрашивает структурированный вывод, проверяет обязательные поля и сохраняет результат.

Наблюдаемый результат: строка из ответа разбирается как JSON и проходит проверку схемы. Для юридически или финансово значимых документов добавьте проверку человеком.

Массовая обработка контента

Исходные данные: набор независимых текстов, для которых немедленный ответ не требуется. Каждый запрос получает уникальный custom_id и отправляется через Message Batches API.

Наблюдаемый результат: ответы сопоставляются с исходными задачами по custom_id; ошибки и истёкшие запросы попадают в отдельную очередь повторной обработки.

Агент для работы с репозиторием

Исходные данные: изолированная рабочая копия проекта, тестовая команда и ограниченный набор разрешений. Claude Agent SDK анализирует файлы, предлагает или вносит изменения и запускает проверку.

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

Как проверить интеграцию

Минимальная проверка Client SDK:

1. Установите SDK и задайте ANTHROPIC_API_KEY.
2. Отправьте короткий Messages API-запрос.
3. Проверьте, что ответ содержит текстовый блок.
4. Запишите response.id, используемую модель, stop_reason и поля usage.
5. Повторите тест с заведомо неверным параметром и убедитесь, что приложение регистрирует ошибку.

Для инструментов дополнительно проверьте:

• неизвестное имя инструмента отклоняется приложением;
• параметры валидируются до выполнения;
• несколько параллельных tool_use возвращаются одним пользовательским сообщением с соответствующими tool_result;
• цикл останавливается по лимиту итераций;
• опасное действие требует отдельного разрешения.

Для prompt caching смотрите cache_creation_input_tokens на первом запросе и cache_read_input_tokens на повторном запросе с тем же префиксом. Для batch проверяйте финальный статус и число элементов во всех категориях результатов.

Чеклист перед запуском

Официальные ссылки

• Models overview
• Messages API: Create a Message
• Prompt caching
• Message Batches
• Claude Agent SDK overview

Следующий шаг

Claude Code — кодинг-агент от Anthropic

Связанные материалы

• Статья: AI Native без шаманства: как строить ИИ-системы, которые реально работают
• Блог: Anthropic выпустил официальное руководство по промптингу Fable
• База знаний: Anthropic Claude — линейка моделей и API

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

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov