Claude API и Anthropic SDK: основы

В предыдущей статье мы разобрали, как Claude Agent SDK: программная сборка агентов берёт управление агентным циклом на себя: вы запускаете query(), а дальше Claude сам планирует шаги, вызывает инструменты и решает, когда задача выполнена. Но иногда нужен другой уровень контроля — когда цикл реализуете вы сами, стоимость каждого токена на счету, или логика слишком нестандартна для готового агентного движка. Именно для этого существует Anthropic Client SDK и лежащий под ним Claude API.

Суть разделения проста: Agent SDK — это агентный движок с готовой оркестрацией; Client SDK — это тонкая обёртка над HTTP-API, где вы полностью контролируете каждый запрос и цикл вызова инструментов.

Установка и аутентификация

Антропик предоставляет официальные SDK на семи языках: Python, TypeScript/Node.js, C#, Go, Java, PHP, Ruby. Для большинства задач хватает Python или TypeScript.

# Python
pip install anthropic

# TypeScript / Node.js
npm install @anthropic-ai/sdk

Аутентификация — через переменную окружения ANTHROPIC_API_KEY. SDK подхватывает её автоматически; явно передавать ключ нужно только в нестандартных сценариях:

import anthropic

# Вариант 1: SDK читает ANTHROPIC_API_KEY из env сам
client = anthropic.Anthropic()

# Вариант 2: явная передача (например, в multi-tenant приложении)
client = anthropic.Anthropic(api_key="sk-ant-...")

При прямых HTTP-запросах нужны два обязательных заголовка: x-api-key со значением ключа и anthropic-version: 2023-06-01. SDK добавляет их автоматически — это одна из главных причин его использовать вместо requests/fetch.

Базовый URL API: https://api.anthropic.com. Если ваша инфраструктура требует конкретного облака — Anthropic поддерживает Amazon Bedrock, Google Vertex AI, Claude Platform on AWS и Microsoft Foundry. ID моделей при этом различаются (подробнее ниже).

Messages API: анатомия запроса

Центральный эндпоинт — POST /v1/messages. Минимальный запрос выглядит так:

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Объясни, что такое tail call optimization"}
    ]
)
print(message.content[0].text)

Три обязательных параметра: model (идентификатор модели), max_tokens (жёсткий потолок на длину ответа) и messages (массив с историей диалога).

Ключевой момент: Messages API — stateless. Состояние не хранится на стороне Anthropic между вызовами. При каждом запросе вы передаёте полную историю переписки — именно поэтому массив messages содержит все предыдущие реплики целиком.

sequenceDiagram
    participant App as Ваш код
    participant API as Claude API

    App->>API: POST /v1/messages\n{model, messages: [turn1]}
    API-->>App: {content, stop_reason, usage}
    Note over App: Сохраняем ответ локально

    App->>API: POST /v1/messages\n{model, messages: [turn1, reply1, turn2]}
    API-->>App: {content, stop_reason, usage}
    Note over API: API не хранит историю —\nвы передаёте её каждый раз целиком

System-промпт передаётся отдельным параметром верхнего уровня — не как элемент в messages:

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    system="Ты — опытный ревьюер кода. Отвечай кратко и по делу.",
    messages=[
        {"role": "user", "content": "Посмотри на этот SQL-запрос: SELECT * FROM users"},
        {"role": "assistant", "content": "SELECT * — плохая практика: тянет лишние колонки и ломает кэш."},
        {"role": "user", "content": "Как лучше?"}
    ]
)

Анатомия ответа и stop_reason

Ответ — структурированный JSON. В Python SDK это объект Message с типизированными полями:

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [{"type": "text", "text": "SELECT id, name, email FROM users"}],
  "model": "claude-sonnet-4-6",
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 87, "output_tokens": 12}
}

Поле stop_reason показывает, почему модель остановилась:

usage — ваш счётчик токенов для расчёта стоимости. Поле input_tokens включает всё: system-промпт, всю историю сообщений, инструкции. На это стоит обращать внимание — при длинных диалогах контекст быстро дорожает.

Семейство моделей и их идентификаторы

По состоянию на июнь 2026 года линейка выглядит следующим образом. Claude Fable 5 (claude-fable-5) — самая мощная публично доступная модель с контекстным окном 1М токенов и максимальным выводом 128k токенов.

Основной рабочий набор — три уровня:

> Важно об именовании. Начиная с поколения 4.6, идентификаторы модели не содержат дату — claude-sonnet-4-6 — и являются фиксированными снимками, а не «вечнозелёными» указателями. Старые модели вида claude-sonnet-4-5-20250929 с датой в ID тоже зафиксированы. Если в вашем коде есть псевдоним вида claude-sonnet-4-0 — это указатель на конкретный dated snapshot; лучше прописывать полный ID явно.

В других облаках идентификаторы отличаются: Bedrock использует формат anthropic.claude-opus-4-8, Vertex AI — claude-opus-4-8 (без префикса). Claude Platform on AWS использует те же ID, что и прямой Claude API.

> На заметку об Opus 4.7 и новее: параметры temperature, top_p и top_k на этих моделях не поддерживаются — передача ненулевых значений вернёт ошибку 400. Управляйте стилем ответа через промпт.

Что ещё есть в API

Messages API — основной, но не единственный эндпоинт. В General Availability:

• Message Batches API (POST /v1/messages/batches) — асинхронная обработка больших объёмов запросов со скидкой 50% к стоимости. Пока ответ не нужен немедленно — это самый дешёвый способ работать с API.
• Token Counting API (POST /v1/messages/count_tokens) — подсчёт токенов до отправки запроса. Помогает управлять расходами и не превышать лимиты контекстного окна.
• Models API (GET /v1/models) — программный список доступных моделей с их возможностями и лимитами токенов.

В Beta:

• Files API — загрузка файлов для использования в нескольких вызовах API (без повторной передачи данных).
• Agents API / Sessions API — инфраструктура Claude Managed Agents: версионированные конфигурации агентов и stateful-сессии в управляемых sandbox-окружениях.

За деталями по prompt caching и экономии на крупных нагрузках — в статье Промпт-кэширование, батчи и оптимизация затрат. За tool use и streaming — в Tool use, MCP и потоковая передача в API.

Client SDK vs Agent SDK: итоговое разделение

Если коротко:

Client SDK:  вы → [запрос] → API → [ответ] → вы → [решаете что дальше]
Agent SDK:   вы → [задача] → движок → [сам крутит цикл] → итог → вы

Client SDK выбирают, когда важен полный контроль над каждым шагом: кастомная логика tool loop, точный учёт стоимости, интеграция в существующий оркестратор, минимальный оверхед. Типичный пример — LLM-judge в тестовом пайплайне, классификатор запросов, генерация embeddings-adjacent контента с жёсткой постобработкой.

Agent SDK выбирают, когда задача — «сделай X с кодовой базой» и вы хотите делегировать агентный цикл целиком. Большинство сценариев внутри Claude Code — это Agent SDK под капотом.

See also

• Claude Agent SDK: программная сборка агентов — более высокий уровень абстракции над тем же API
• Tool use, MCP и потоковая передача в API — как дать модели инструменты и читать ответы потоком
• Промпт-кэширование, батчи и оптимизация затрат — как снизить стоимость при высокой нагрузке
• Выбор модели и режимы мышления — когда нужен Opus, Sonnet или Haiku в интерактивной работе
• Headless-режим и скриптинг через CLI — лёгкая альтернатива SDK для простых скриптов