Разработка с Claude API

Первый запрос и анатомия сообщений

Всё общение идёт через один эндпоинт: POST https://api.anthropic.com/v1/messages. Заголовка три: x-api-key, anthropic-version 2023-06-01 и content-type application/json. В теле обязательны model (claude-opus-5, claude-sonnet-5, claude-haiku-4-5), max_tokens и массив messages. Официальные SDK есть для Python, TypeScript, Java, Go, Ruby, PHP и C# — тот же запрос без ручной сборки JSON.

Поле messages — история диалога: объекты с полями role (user или assistant) и content. Первым идёт user, дальше роли чередуются, а content бывает и строкой, и массивом блоков: text, image, document, tool_use, tool_result. API не хранит состояние: историю целиком присылаете вы, поэтому входные токены десятой реплики включают все девять предыдущих.

Ответ тоже не строка: content — массив блоков, stop_reason принимает end_turn, max_tokens, tool_use или refusal, usage считает входные и выходные токены. Читать content[0].text вслепую нельзя — первым может идти блок thinking. Параметр max_tokens жёсткий, на нём текст обрывается на полуслове: ставьте порядка 16000, для потоковых ответов до 64000. Контекст пятого поколения — миллион токенов, у Haiku 4.5 — двести тысяч; точные лимиты отдаёт GET /v1/models.

Системный промпт: где живут роль и правила

Системный промпт — отдельное поле верхнего уровня рядом с messages, а не реплика в диалоге. Туда идёт неизменное: роль и задача, формат ответа, домашние правила («сумму всегда возвращай в копейках»), границы («про юридические последствия не рассуждай, отдавай контакт юриста»). Инструкции оттуда весят больше пользовательского текста — это рычаг против попыток вывернуть бота через ввод. Работает конкретика вроде «если данных не хватает, верни status со значением insufficient_data», а «ты гениальный эксперт мирового уровня» не добавляет ничего.

Отрицания модель держит хуже предписаний: вместо «не пиши длинно» — «не больше трёх предложений». Переменное в system класть нельзя: время до секунды, идентификатор запроса или имя клиента убивают кэш, работающий по совпадению префикса. Предзаполнение ответа ассистента, приём из старых примеров, на моделях 4.6 и новее возвращает 400 — формат задают через output_config.format.

Промптинг, который даёт измеримый эффект

Отделяйте инструкции от данных: письмо, документ, код оборачивайте в теги и ссылайтесь по имени, объёмное ставьте в начало, а вопрос и требования — в конец. Три-пять пар «вход — ожидаемый выход» дают больше, чем абзац описаний, особенно если среди них есть пограничный случай и случай «данных не хватает».

Думать модель просят параметром thinking с типом adaptive, глубину задаёт output_config.effort: low, medium, high, xhigh, max. Для классификации хватает low, для спорного договора берите high; рассуждение по умолчанию в ответ не попадает, показать его позволяет display summarized. У пятого поколения нет temperature и top_p — запрос с ними вернёт 400. JSON не выпрашивайте словами: структуру дают output_config.format со схемой и strict у инструментов.

• Разделяйте инструкцию и данные тегами, вопрос ставьте последним
• Давайте 3–5 примеров, включая пограничный и «нет данных»
• Включайте adaptive thinking и подбирайте effort под сложность задачи
• Структуру ответа задавайте схемой, а не просьбой в тексте
• Проверяйте каждую правку промпта на наборе кейсов, а не на одном

Оценка промптов: цифры вместо ощущений

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

Проверки трёх видов: детерминированные (сравнение полей, парсинг JSON, регулярка) — дешёвые, ими покрывайте максимум; эвристические (длина, язык ответа, выдуманный номер заказа); оценка моделью-судьёй для тона и полноты. Судье дайте рубрику для оценок 1, 3 и 5 и просите сначала обоснование, потом оценку. Гоняйте набор перед каждой правкой промпта и сменой модели, фиксируя долю правильных ответов, стоимость и задержку по 95-му перцентилю. Через Batch API это вдвое дешевле, результаты приходят в пределах суток и сопоставляются по custom_id.

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

Инструмент описывается в массиве tools тремя полями: name, description и input_schema в формате JSON Schema. Описание — не комментарий для коллег, а промпт: в нём сказано, когда инструмент применять и когда нет. «Возвращает статус заказа по номеру; использовать, только если номер назван явно, не угадывать» работает лучше, чем «получить заказ».

Цикл такой: вы шлёте запрос с tools, получаете ответ со stop_reason tool_use — там имя инструмента, аргументы и tool_use_id; исполняете функцию у себя; дописываете ответ ассистента целиком, следом сообщение user из блоков tool_result с теми же tool_use_id — и повторяете запрос. Несколько инструментов сразу — все результаты одним сообщением, иначе модель перестанет вызывать их параллельно. Упавший инструмент отдавайте как tool_result с is_error: молчаливая потеря результата ломает диалог.

Аргументы разбирайте парсером JSON, а не поиском подстроки: экранирование строк у разных моделей разное, а схему подстрахуйте через strict и additionalProperties false. Веб-поиск и исполнение кода выполняются на стороне Anthropic — результат приходит в том же ответе, свой цикл не нужен, тарифицируются отдельно. В SDK есть tool runner, который крутит цикл за вас; ручной цикл нужен там, где перед вызовом стоит подтверждение оператора.

Свои данные: контекст, поиск и цитаты

Модель не знает ни вашей базы знаний, ни вчерашних заказов. Первый путь — положить всё в контекст: миллион токенов вмещает порядка полутора тысяч страниц и стоит около пяти долларов за запрос на Opus 5, так что нужен небольшой корпус и кэш. Второй путь — RAG: документы режут на куски по 300–800 токенов с перекрытием, векторизуют сторонней моделью эмбеддингов (в Claude API её нет) и складывают в индекс.

Ищут гибридно, вектора плюс BM25 по словам: артикулы, коды ошибок и фамилии вектора ловят плохо. Топ-20 прогоняют через реранкер и отдают модели пять-десять лучших; промахов меньше, если перед векторизацией дописать к фрагменту, из какого документа и раздела он взят. Источники передавайте блоками document с включёнными citations — ответ разобьётся на части с диапазонами исходника: символы для текста, страницы для PDF. Учтите: citations и output_config.format вместе дают 400, а в system нужно правило «нет данных — так и скажи».

Потоковая передача и кэширование промптов

Стриминг включается флагом stream и приходит потоком SSE-событий: message_start, серия content_block_delta с кусочками текста, message_delta с итоговыми stop_reason и usage, message_stop. В интерфейсе это разница между «зависло на двадцать секунд» и «печатает», а технически — способ не упереться в HTTP-таймаут на длинном ответе. В SDK для этого есть метод stream и хелпер, собирающий финальное сообщение.

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

Агенты, воркфлоу и жизнь в проде

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

Деньги считаются по цене за миллион токенов, отдельно на вход и на выход: Opus 5 — 5 и 25 долларов, Sonnet 5 — 3 и 15, Haiku 4.5 — 1 и 5; прайс меняется, сверяйтесь с консолью. Вызов на 5000 входных и 1000 выходных токенов стоит на Sonnet около трёх центов, на Opus — около пяти. Экономят кэш, Batch API со скидкой 50 процентов, Haiku на массовой рутине и /v1/messages/count_tokens, считающий объём промпта до отправки.

Лимиты выставляются на организацию: запросы и токены в минуту, числа зависят от тира. В коде опирайтесь на заголовки ответа с остатком лимита и retry-after при 429, повторы делайте с экспоненциальной паузой и разбросом. Ошибки различайте по коду, а не по тексту: повторять имеет смысл 429, 500, 529 и сетевые обрывы, 400 и 401 — бессмысленно. Отказ модели приходит со stop_reason refusal и кодом 200, ошибки серверных инструментов — тоже с 200 и error_code внутри блока результата.

• 400 — некорректный запрос: схема, лишний параметр, превышен контекст
• 401 и 403 — ключ неверный или нет прав на модель
• 413 — тело запроса слишком большое
• 429 — упёрлись в лимит, читайте retry-after
• 500 и 529 — сбой или перегрузка на стороне API, повторяйте с паузой

Практика

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

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

Похожие уроки