Claude Platform 101: основы платформы

Кому подойдёт

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

Что понадобится

Аккаунт в консоли Anthropic, ключ API и пополненный баланс. Это отдельные деньги: подписка на чат доступа к API не даёт, счёт пополняется зарубежной картой. Из России ни консоль, ни api.anthropic.com не открываются без VPN. Знаний хватит базовых: HTTP, JSON, переменные окружения.

Первый запрос: один эндпоинт и три обязательных поля

Вся работа идёт через один адрес: POST https://api.anthropic.com/v1/messages. Заголовки — x-api-key, anthropic-version: 2023-06-01, content-type: application/json. Обязательных полей три: model (строка вида claude-opus-5), max_tokens и messages с ролями user и assistant. Ключ живёт в переменной ANTHROPIC_API_KEY, официальные SDK читают её сами. В репозиторий его не кладут даже в приватный: утёкший ключ тратит ваши деньги молча.

Ответ приходит не строкой: content — массив блоков text, thinking и tool_use, и content[0].text вслепую опасен, при включённом мышлении первым идёт другой блок. Читайте stop_reason (end_turn, max_tokens, tool_use, refusal — причина в stop_details) и usage с числом токенов. Коды ошибок: 401 — ключ, 400 — тело запроса, 429 и 5xx повторяют с паузой по retry-after.

Длинные ответы просите потоком: старшие модели отдают до 128 тысяч выходных токенов, и при большом max_tokens обычный запрос упирается в HTTP-таймаут. В Python это client.messages.stream(...) с get_final_message(), в Node — finalMessage(). Коротким ответам хватает обычного вызова с max_tokens в районе 4–16 тысяч.

Выбор модели: сначала задача, потом идентификатор

Идентификатор пишется без суффикса с датой. Claude Opus 5 (claude-opus-5) — 5 долларов за миллион входных токенов и 25 за миллион выходных при окне 1 млн; Claude Sonnet 5 (claude-sonnet-5) — 3 и 15 при том же окне; Claude Haiku 4.5 (claude-haiku-4-5) — 1 и 5 при окне 200 тысяч; более тяжёлый Claude Fable 5 — 10 и 50. Цены сверяйте с прайсом в консоли: вводные ставки временны.

Уровень диктует тип задачи: классификация обращений, извлечение полей из накладной, маршрутизация тикетов — Haiku; продуктовая логика и работа с инструментами — Sonnet; планирование и длинные агентные сессии — Opus. Дальше не гадайте, а измеряйте: 20–50 настоящих примеров с эталонами, два кандидата, сравнение точности и usage. Обычно дешёвая модель проваливает один подкласс задач — и правильный ход не «всё на Opus», а разделить поток. Список моделей отдаёт GET /v1/models.

Инструменты: как модель дотягивается до вашего кода

Инструмент (tool use) — описание функции в поле tools: имя, описание и input_schema в формате JSON Schema. Описание читает модель, а не ваш коллега: пишите, когда вызывать, когда не вызывать, что значит каждое поле. Расплывчатое «получает данные заказа» даёт вызовы невпопад; «возвращает статус и дату доставки по номеру вида A-12345, не использовать для отмены» — не даёт.

Модель ничего не выполняет сама: она возвращает блок tool_use с именем, input и уникальным id, а stop_reason становится tool_use. Дальше ваш код выполняет функцию, дописывает в историю сообщение ассистента целиком, затем сообщение пользователя с tool_result, где tool_use_id совпадает с id вызова. Если функция упала, всё равно верните tool_result с is_error: true и текстом ошибки — по нему модель поправится, а от молчания диалог ломается.

Поле strict: true вместе с additionalProperties: false и списком required гарантирует, что input придёт строго по схеме. Модель возвращает несколько tool_use в одном сообщении: выполняйте их параллельно и отдавайте все tool_result одним пользовательским сообщением, иначе она перестанет звать инструменты параллельно. Input разбирайте через json.loads или JSON.parse, а не строковым поиском.

Цикл агента: три способа его получить

Цикл выглядит скромно: отправили запрос, посмотрели stop_reason; пришёл tool_use — выполнили инструменты, дописали результаты, отправили снова; end_turn — вышли. Пятнадцать строк кода. Работу делают ограничители: предел итераций, общий таймаут, белый список действий и подтверждение человека перед необратимым — списанием денег, отправкой письма, удалением. Логируйте каждый вызов с аргументами, иначе разбирать поведение агента нечем.

Писать цикл руками не обязательно. В SDK есть исполнитель инструментов (tool runner): декоратор @beta_tool и client.beta.messages.tool_runner(...) в Python, betaZodTool в TypeScript, хуки на каждом шаге дают место подтверждениям и логам. Третий вариант — управляемые агенты (managed agents, бета managed-agents-2026-04-01): Anthropic держит и цикл, и контейнер-песочницу на сессию, агент создаётся один раз через POST /v1/agents, сессии на него ссылаются, сверху есть расписания и лимит расходов.

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

Расширенное мышление и уровень усилий

Расширенное мышление включается параметром thinking с типом adaptive: модель сама решает, сколько рассуждать перед ответом. Фиксированный budget_tokens на текущих моделях возвращает 400 — переносить его из старых примеров не нужно. У Claude Opus 5 мышление работает по умолчанию, даже если параметр не передан.

Глубину регулирует output_config.effort: low, medium, high, xhigh, max, по умолчанию high. Для рутины ставьте low — меньше преамбул и лишних вызовов инструментов; для кода и агентных прогонов хорош xhigh; max берегите там, где корректность дороже денег. Выключать мышление совсем не стоит: с типом disabled модель иногда пишет вызов инструмента текстом вместо блока tool_use — запрос успешен, функция не вызвана, ошибки нет.

Содержимое рассуждения по умолчанию скрыто: блоки thinking приходят с пустым текстом, display со значением summarized даёт сводку. Токены мышления оплачиваются как выходные при любом режиме показа. В многоходовом диалоге возвращайте блоки thinking в историю без изменений. Префилл (заранее заданное начало ответа ассистента) запрещён: формат задавайте через output_config.format или системный промпт.

Готовые инструменты и навыки

Часть инструментов исполняется на стороне Anthropic — обработчик писать не нужно, достаточно объявить их в tools по типу. Веб-поиск (web_search_20260209) ищет в сети, веб-загрузка (web_fetch_20260209) открывает только те ссылки, что уже есть в переписке, выполнение кода (code_execution_20260521) даёт песочницу с python-docx, python-pptx, matplotlib и pypdf: отчёт в DOCX или график вернутся файлом. Домены сужаются через allowed_domains или blocked_domains, но не через оба сразу.

Ошибки серверных инструментов не бросают исключение: приходит ответ 200 и блок с полем error_code, а content веб-поиска при успехе список, при ошибке объект — проверяйте тип перед обращением по индексу.

Навыки (skills) упаковывают повторяющуюся экспертизу: папка с инструкцией и файлами, которую модель подключает в песочнице выполнения кода. Передаются они в поле container вместе с инструментом code_execution и бета-заголовками code-execution-2025-08-25 и skills-2025-10-02. Так «как мы делаем квартальный отчёт» описывается один раз и не раздувает системный промпт. Файлы для нескольких запросов грузите через Files API и ссылайтесь по file_id; PDF можно передать напрямую в base64, до 32 МБ на запрос.

MCP: один разъём вместо десяти интеграций

MCP (Model Context Protocol) — открытый протокол: внешний сервер отдаёт набор инструментов и ресурсов, а клиент их подключает. Выгода арифметическая: вместо интеграции на каждую связку «модель — система» вы пишете один MCP-сервер к базе, трекеру или CRM. Его видят все клиенты — приложение, редактор, десктоп.

В API это коннектор из двух половин сразу: mcp_servers с элементом типа url, где заданы адрес и имя, и tools с элементом mcp_toolset, у которого mcp_server_name равен тому же имени, плюс бета-заголовок mcp-client-2025-11-20. Одна половина без второй отклоняется как ошибка валидации — частая осечка при первом подключении. Для модели такие инструменты неотличимы от ваших собственных, цикл обработки не меняется.

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

Контекст и деньги: токены, кэш, чистка

Платите вы за токены, и выход дороже входа примерно впятеро. Считать их на глаз не надо: POST /v1/messages/count_tokens принимает тот же набор полей, что и обычный запрос, и возвращает точное число входных токенов. Умножьте результат на цену модели и на число вызовов в сутки — месячная смета готова за десять минут.

Главный рычаг экономии — кэширование промпта. Пометьте стабильный префикс полем cache_control типа ephemeral: повторные запросы с тем же началом читают его из кэша дешевле. Совпадение считается по точному префиксу в порядке tools, system, messages; минимум около 1024 токенов, точек разметки не больше четырёх. Проверка одна: usage.cache_read_input_tokens во втором запросе больше нуля. Стабильный ноль означает убийцу кэша: текущую дату в системном промпте, несортированный JSON, плавающий порядок инструментов.

Чистка контекста (context editing) выкидывает из истории старые результаты вызовов: clear_tool_uses_20250919, бета context-management-2025-06-27
Компакция (compaction) сворачивает раннюю часть диалога в сводку у порога около 150 тысяч токенов, бета compact-2026-01-12
При компакции возвращайте в историю весь response.content, а не только текст, иначе состояние теряется молча
Пакетная обработка (POST /v1/messages/batches) вдвое дешевле, но ответы приходят вразнобой — сопоставляйте по custom_id

Практика

Создайте ключ, положите его в ANTHROPIC_API_KEY и отправьте curl-ом запрос к /v1/messages; распечатайте stop_reason и usage.
Возьмите 20 реальных примеров с эталонными ответами, прогоните на claude-haiku-4-5 и claude-opus-5, сравните точность и токены.
Опишите инструмент со строгой схемой — get_order_status с обязательным order_id, strict: true, additionalProperties: false — и верните tool_result с ответом функции.
Замкните цикл: повторяйте запрос, пока приходит tool_use, с пределом в 10 итераций, таймаутом, логом вызовов и веткой is_error.
Прогоните сложный пример при effort low и high, сравните ответ и число выходных токенов.
Вынесите системный промпт и инструменты в кэшируемый префикс, проверьте cache_read_input_tokens и посчитайте через count_tokens стоимость тысячи прогонов.

Проверьте себя

Я отправляю запрос к /v1/messages с нуля и объясняю блоки content, stop_reason и usage.
Я выбираю модель по замерам на своих примерах и называю цену за миллион токенов.
Мои инструменты вызываются вовремя благодаря описанию и схеме, а параллельные tool_result идут одним сообщением.
В моём цикле есть предел итераций, обработка ошибок инструмента и подтверждение перед необратимым действием.
Я вижу попадания в кэш в usage и называю месячную смету до выката.

Частые вопросы

Нужна ли платная подписка на Claude, чтобы работать с API?

Подписка на чат и API — разные продукты с раздельной оплатой. Для API нужен ключ в консоли и пополненный баланс, счёт выставляется по факту потраченных токенов. Бесплатного продакшн-тарифа нет, стартовые кредиты заканчиваются быстро.

Можно ли работать из России?

Ни консоль, ни api.anthropic.com из России без VPN не открываются, а пополнение баланса требует зарубежной карты. Настройками SDK это не обходится: base_url меняет адрес, а не вопрос доступа и оплаты. Если сервис нужен под боевую нагрузку, планируйте инфраструктуру и платёжный контур за пределами страны.

Чем tool use отличается от MCP?

Tool use — механизм внутри одного запроса: вы описали функцию, модель попросила её вызвать, вы вернули результат. MCP — протокол, по которому приложение подключает внешние наборы инструментов от отдельных серверов. Инструменты, пришедшие по MCP, попадают модели тем же способом, так что обработка ответа не меняется.

Расширенное мышление сильно повышает счёт?

Токены рассуждения оплачиваются как выходные, по дорогой ставке, поэтому влияние заметное. Управляется это параметром effort: low для рутины, high для содержательных задач, max там, где ошибка дороже денег. Прежде чем поднимать effort на всём потоке, прогоните два уровня на своих примерах и сравните usage.

Чтобы пройти практику, нужен рабочий доступ

Подключим подписку на ваш аккаунт: оплата картой РФ, по СБП или криптой, пароль от аккаунта не нужен. Обычно за 15 минут в рабочее время.

Подключить Claude Pro — 2 490 ₽ Все уроки